awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-09-22 13:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update docs for Infisical KMS

Browse Source
This commit is contained in:
Tuan Dang
2024-10-03 14:29:26 -07:00
parent 2c93561a3b
commit 724e2b3692
1 changed files with 40 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
docs/documentation/platform/kms.mdx
View File

@@ -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
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).
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.
<Note>
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.
</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">
Navigate to Project > Key Management and tap on the Add Key button.
<Step title="Creating a KMS key">
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
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.
![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?">
No. Infisical's KMS only provides cryptographic services and does not store any encrypted or decrypted data.
</Accordion>
<Accordion title="Can key material be accessed outside of Infisical KMS?">
No. Infisical's KMS will never expose your keys, encrypted or decrypted, to external sources.
</Accordion>
<Accordion title="What algorithms does Infisical KMS support?">
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>
<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.
</Accordion>
<Accordion title="Can key material be accessed outside of Infisical KMS?">
No. Infisical's KMS will never expose your keys, encrypted or decrypted, to
external sources.
</Accordion>
<Accordion title="What algorithms does Infisical KMS support?">
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>