diff --git a/docs/documentation/platform/kms.mdx b/docs/documentation/platform/kms.mdx
index 77a410352..eb4479597 100644
--- a/docs/documentation/platform/kms.mdx
+++ b/docs/documentation/platform/kms.mdx
@@ -4,72 +4,48 @@ sidebarTitle: "Key Management (KMS)"
description: "Learn how to manage and use cryptographic keys with Infisical."
---
-## Diagram
-
-The following sequence diagram illustrates the KMS workflow for creating and using a cryptographic key.
-
-
-```mermaid
-sequenceDiagram
- participant Client as Client
- participant Infis as Infisical
-
- Note over Client,Infis: Step 1: Create KMS Key
- Client->>Infis: create key request
- Infis->>Client: keyId
-
- Note over Client,Infis: Step 2: Encrypt Data
- Client->>Infis: plaintext and keyId
- Infis->>Client: ciphertext
-
- Note over Client,Infis: Step 3: Decrypt Data
- Client->>Infis: ciphertext and keyId
- Infis->>Client: plaintext
-```
-
-
## Concept
-At a high-level, Infisical generates a KMS key when requested, returning the `keyId` to the client. This `keyId` can then be used
-to perform cryptographic operations such as encrypting and decrypting data.
-
-To be more specific:
-
-1. The client requests to create a key using the `/api/v1/kms/keys` endpoint.
-2. Infisical generates a KMS key and returns the `keyId` to the client.
-3. The client requests to encrypt `plaintext` data (base64 encoded) with the specified `keyId` using the `/api/v1/kms/keys//encrypt` endpoint.
-4. Infisical returns the encrypted data or `ciphertext` (base64 encoded).
-3. The client requests to decrypt the `ciphertext` data with the original `keyId` using the `/api/v1/kms/keys//decrypt` endpoint.
-4. Infisical returns the decrypted `plaintext` data (base64 encoded).
+Infisical can be used as a Key Management System (KMS), referred to as Infisical KMS, to centralize management of keys to be used for cryptographic operations like encryption/decryption.
- Your keys will never be used or viewable outside of Infisical KMS.
- In addition, no data is stored when performing cryptographic operations.
+ Keys managed in KMS are not extractable from the platform. Additionally, data
+ is never stored when performing cryptographic operations.
+
+
+## Workflow
+
+The typical workflow for using Infisical KMS consists of the following steps:
+
+1. Creating a KMS key. As part of this step, you specify a name for the key and the encryption algorithm meant to be used for it (e.g. `AES-GCM-128`, `AES-GCM-256`).
+2. Encryption: To encrypt data, you would make a request to the Infisical KMS API endpoint, specifying the base64-encoded plaintext and the intended key to use for encryption; the API would return the base64-encoded ciphertext.
+3. Decryption: To decrypt data, you would make a request to the Infisical KMS API endpoint, specifying the base64-encoded ciphertext and the intended key to use for decryption; the API would return the base64-encoded plaintext.
+
+
+ Note that this workflow can be executed via the Infisical UI or manually such
+ as via API.
## Guide to Encrypting Data
-In the following steps, we'll explore how to generate a cryptographic key and encrypt data.
+In the following steps, we explore how to generate a key and use it to encrypt data.
-
- Navigate to Project > Key Management and tap on the Add Key button.
+
+ Navigate to Project > Key Management and tap on the **Add Key** button.
Specify your key details. Here's some guidance on each field:
- Name: A slug-friendly name for the key.
- - Type: The encryption algorithm associated with this key. By default symmetric `AES-GCM-256` is
- selected,
- but
- Infisical will continue to add more options down the road.
- - Description: An optional description of what this key is used for.
+ - Type: The encryption algorithm associated with the key (e.g. `AES-GCM-256`).
+ - Description: An optional description of what the intended usage is for the key.
-
+
Once your key is generated, open the options menu for the newly created key and select encrypt data.
@@ -88,7 +64,7 @@ In the following steps, we'll explore how to generate a cryptographic key and en
-
+
To create a cryptographic key, make an API request to the [Create KMS
Key](/api-reference/endpoints/kms/keys/create) API endpoint.
@@ -124,7 +100,7 @@ In the following steps, we'll explore how to generate a cryptographic key and en
}
```
-
+
To encrypt data, make an API request to the [Encrypt
Data](/api-reference/endpoints/kms/keys/encrypt) API endpoint,
specifying the key to use.
@@ -154,11 +130,12 @@ In the following steps, we'll explore how to generate a cryptographic key and en
+
## Guide to Decrypting Data
-In the following steps, we'll explore how to decrypt data.
+In the following steps, we explore how to use decrypt data using an existing key in Infisical KMS.
@@ -168,7 +145,6 @@ In the following steps, we'll explore how to decrypt data.
you want to decrypt.
-
Paste your encrypted data into the text area and tap on the Decrypt button. Optionally, if your data was
@@ -210,19 +186,23 @@ In the following steps, we'll explore how to decrypt data.
+
## FAQ
-
- No. Infisical's KMS only provides cryptographic services and does not store any encrypted or decrypted data.
-
-
- No. Infisical's KMS will never expose your keys, encrypted or decrypted, to external sources.
-
-
- Currently, Infisical only supports AES-128-GCM and AES-256-GCM for encryption operations. We anticipate
- supporting more algorithms and cryptographic operations in the coming months.
-
+
+ No. Infisical's KMS only provides cryptographic services and does not store
+ any encrypted or decrypted data.
+
+
+ No. Infisical's KMS will never expose your keys, encrypted or decrypted, to
+ external sources.
+
+
+ Currently, Infisical only supports `AES-128-GCM` and `AES-256-GCM` for
+ encryption operations. We anticipate supporting more algorithms and
+ cryptographic operations in the coming months.
+