Update docs for Infisical KMS

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.
-
-<div align="center">
-```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
-```
-</div>
-
 ## Concept
 
-At a high-level, Infisical generates a KMS key when requested, returning the `keyId` to the client. This `keyId` can then be used
+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.
-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/<key-id>/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/<key-id>/decrypt` endpoint.
-4. Infisical returns the decrypted `plaintext` data (base64 encoded).
 
 <Note>
-    Your keys will never be used or viewable outside of Infisical KMS.
+  Keys managed in KMS are not extractable from the platform. Additionally, data
-    In addition, no data is stored when performing cryptographic operations.
+  is never stored when performing cryptographic operations.
+</Note>
+
+## 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>
+  Note that this workflow can be executed via the Infisical UI or manually such
+  as via API.
 </Note>
 
 ## 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.
 
 <Tabs>
     <Tab title="Infisical UI">
         <Steps>
-            <Step title="Creating a key">
+            <Step title="Creating a KMS key">
-                Navigate to Project > Key Management and tap on the Add Key button.
+                Navigate to Project > Key Management and tap on the **Add Key** button.
                 ![kms add key button](/images/platform/kms/infisical-kms/kms-add-key.png)
 
                 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
+                - Type: The encryption algorithm associated with the key (e.g. `AES-GCM-256`).
-                selected,
+                - Description: An optional description of what the intended usage is for the key.
-                but
-                Infisical will continue to add more options down the road.
-                - Description: An optional description of what this key is used for.
 
                 ![kms add key modal](/images/platform/kms/infisical-kms/kms-add-key-modal.png)
             </Step>
-            <Step title="Encrypting your data">
+            <Step title="Encrypting data with the KMS key">
                 Once your key is generated, open the options menu for the newly created key and select encrypt data.
                 ![kms key options](/images/platform/kms/infisical-kms/kms-key-options.png)
 
@@ -88,7 +64,7 @@ In the following steps, we'll explore how to generate a cryptographic key and en
     </Tab>
     <Tab title="API">
         <Steps>
-            <Step title="Creating a key">
+            <Step title="Creating a KMS key">
                 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
                 }
                 ```
             </Step>
-            <Step title="Encrypting data">
+            <Step title="Encrypting data with the KMS key">
                 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
             </Step>
         </Steps>
     </Tab>
+
 </Tabs>
 
 ## 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.
 
 <Tabs>
     <Tab title="Infisical UI">
@@ -168,7 +145,6 @@ In the following steps, we'll explore how to decrypt data.
                 you want to decrypt.
                 ![kms key options](/images/platform/kms/infisical-kms/kms-decrypt-options.png)
 
-
             </Step>
             <Step title="Decrypting your data">
                 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.
         </Steps>
 
     </Tab>
+
 </Tabs>
 
 ## FAQ
 
 <AccordionGroup>
-    <Accordion title="Is my data stored in Infisical KMS?">
+  <Accordion title="Is my data stored in Infisical KMS?">
-        No. Infisical's KMS only provides cryptographic services and does not store any encrypted or decrypted data.
+    No. Infisical's KMS only provides cryptographic services and does not store
-    </Accordion>
+    any encrypted or decrypted data.
-    <Accordion title="Can key material be accessed outside of Infisical KMS?">
+  </Accordion>
-        No. Infisical's KMS will never expose your keys, encrypted or decrypted, to external sources.
+  <Accordion title="Can key material be accessed outside of Infisical KMS?">
-    </Accordion>
+    No. Infisical's KMS will never expose your keys, encrypted or decrypted, to
-    <Accordion title="What algorithms does Infisical KMS support?">
+    external sources.
-        Currently, Infisical only supports AES-128-GCM and AES-256-GCM for encryption operations. We anticipate
+  </Accordion>
-        supporting more algorithms and cryptographic operations in the coming months.
+  <Accordion title="What algorithms does Infisical KMS support?">
-    </Accordion>
+    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.
+  </Accordion>
 </AccordionGroup>