github/infisical
1
0
Fork 0
mirror of https://github.com/Infisical/infisical.git synced 2026-01-07 22:53:55 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
9f389081fbde70d2ce37b50a9d7380960c719dbc
infisical/docs/documentation/platform/kms/overview.mdx

442 lines
20 KiB
Plaintext
Raw Blame History

---
title: "Key Management Service (KMS)"
sidebarTitle: "Overview"
description: "Learn how to manage and use cryptographic keys with Infisical."
---
## Concept
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.
By default your Infisical data such as projects and the data within them are encrypted at rest using Infisical's own KMS. This ensures that your data is secure and protected from unauthorized access.
If you are on-premise, your KMS root key will be created at random with the `ROOT_ENCRYPTION_KEY` environment variable. You can also use a Hardware Security Module (HSM), to create the root key. Read more about [HSM](/documentation/platform/kms/hsm-integration).
<Note>
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>
## Encryption
### Guide to Encrypting 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 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.
- Key Usage: The type of key to create (e.g `Encrypt/Decrypt` for encryption, and `Sign/Verify` for signing).
- Algorithm: 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 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)
Populate the text area with your data and tap on the Encrypt button.
![kms encrypt data](/images/platform/kms/infisical-kms/kms-encrypt-data.png)
<Note>
If your data is already Base64 encoded make sure to toggle the respective switch on to avoid
redundant encoding.
</Note>
Copy and store the encrypted data.
![kms encrypted data](/images/platform/kms/infisical-kms/kms-encrypted-data.png)
</Step>
</Steps>
</Tab>
<Tab title="API">
<Steps>
<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.
### Sample request
```bash Request
curl --request POST \
--url https://app.infisical.com/api/v1/kms/keys \
--header 'Content-Type: application/json' \
--data '{
"projectId": "<project-id>",
"name": "my-secret-key",
"description": "...",
"encryptionAlgorithm": "aes-256-gcm"
}'
```
### Sample response
```bash Response
{
"key": {
"id": "<key-id>",
"description": "...",
"isDisabled": false,
"isReserved": false,
"orgId": "<org-id>",
"name": "my-secret-key",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"projectId": "<project-id>"
}
}
```
</Step>
<Step title="Encrypting data with the KMS key">
To encrypt data, make an API request to the [Encrypt
Data](/api-reference/endpoints/kms/encryption/encrypt) API endpoint,
specifying the key to use.
<Note>
Make sure your data is Base64 encoded
</Note>
### Sample request
```bash Request
curl --request POST \
--url https://app.infisical.com/api/v1/kms/keys/<key-id>/encrypt \
--header 'Content-Type: application/json' \
--data '{
"plaintext": "lUFHM5Ggwo6TOfpuN1S==" // base64 encoded plaintext
}'
```
### Sample response
```bash Response
{
"ciphertext": "HwFHwSFHwlMF6TOfp==" // base64 encoded ciphertext
}
```
</Step>
</Steps>
</Tab>
</Tabs>
### Guide to Decrypting Data
In the following steps, we explore how to use decrypt data using an existing key in Infisical KMS.
<Tabs>
<Tab title="Infisical UI">
<Steps>
<Step title="Accessing your key">
Navigate to Project > Key Management and open the options menu for the key used to encrypt the 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
originally plain text, enable the decode Base64 switch.
![kms decrypt data](/images/platform/kms/infisical-kms/kms-decrypt-data.png)
Your decrypted data will be displayed and can be copied for use.
![kms decrypted data](/images/platform/kms/infisical-kms/kms-decrypted-data.png)
</Step>
</Steps>
</Tab>
<Tab title="API">
<Steps>
<Step title="Decrypting data">
To decrypt data, make an API request to the [Decrypt
Data](/api-reference/endpoints/kms/encryption/decrypt) API endpoint,
specifying the key to use.
### Sample request
```bash Request
curl --request POST \
--url https://app.infisical.com/api/v1/kms/keys/<key-id>/decrypt \
--header 'Content-Type: application/json' \
--data '{
"ciphertext": "HwFHwSFHwlMF6TOfp==" // base64 encoded ciphertext
}'
```
### Sample response
```bash Response
{
"plaintext": "lUFHM5Ggwo6TOfpuN1S==" // base64 encoded plaintext
}
```
</Step>
</Steps>
</Tab>
</Tabs>
## Signing
### Guide to Signing Data
In the following steps, we explore how to generate a key and use it to sign data.
<Tabs>
<Tab title="Infisical UI">
<Steps>
<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.
- Key Usage: The type of key to create (e.g `Encrypt/Decrypt` for encryption, and `Sign/Verify` for signing).
- Algorithm: The signing algorithm associated with the key (e.g. `RSA_4096`).
- Description: An optional description of what the intended usage is for the key.
![kms add key modal](/images/platform/kms/infisical-kms/signing/add-new-rsa-key.png)
</Step>
<Step title="Signing data with the KMS key">
Once your key is generated, open the options menu for the newly created key and select sign data.
![kms key options](/images/platform/kms/infisical-kms/signing/sign-options.png)
Populate the text area with your data and tap on the Sign button.
![kms sign data](/images/platform/kms/infisical-kms/signing/sign-data-modal.png)
Make sure to select the appropriate signing algorithm that will be used to sign the data.
Supported signing algorithms are:
**For RSA keys:**
- `RSASSA PSS SHA 512`: Not deterministic, and includes random salt.
- `RSASSA PSS SHA 384`: Not deterministic, and includes random salt.
- `RSASSA PSS SHA 256`: Not deterministic, and includes random salt.
- `RSASSA PKCS1 V1.5 SHA 512`: Deterministic, and does not include randomness.
- `RSASSA PKCS1 V1.5 SHA 384`: Deterministic, and does not include randomness.
- `RSASSA PKCS1 V1.5 SHA 256`: Deterministic, and does not include randomness.
**For ECC keys:**
- `ECDSA SHA 512`: Not deterministic, and includes randomness.
- `ECDSA SHA 384`: Not deterministic, and includes randomness.
- `ECDSA SHA 256`: Not deterministic, and includes randomness.
In this example, we'll use the `RSASSA PSS SHA 512` signing algorithm.
<Note>
If your data is already Base64 encoded make sure to toggle the respective switch on to avoid
redundant encoding.
</Note>
Copy and store the signature of your data.
![kms signed data](/images/platform/kms/infisical-kms/signing/copy-signature.png)
</Step>
</Steps>
</Tab>
<Tab title="API">
<Steps>
<Step title="Signing data">
To sign data, make an API request to the [Sign
Data](/api-reference/endpoints/kms/signing/sign) API endpoint,
specifying the key to use.
### Sample request
```bash Request
curl --request POST \
--url https://app.infisical.com/api/v1/kms/keys/<key-id>/sign \
--header 'Content-Type: application/json' \
--data '{
"data": "SGVsbG8sIFdvcmxkIQ==", // base64 encoded data
"signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512",
}'
```
### Sample response
```bash Response
{
"signature": "JYuiBt1Ta9pbqFIW9Ou6qzBsFhjYbMJp9k4dP87ILrO+F2MPnp85g3nOlXK1ttZmRoGWsWnLNDRn9W3rf5VtkeaixPqUW/KvY/fM3CxdMyIV3BuxlGgDksjL8X34Eqkrz4CCPo9hjB5uT+rBCOxCgZqRbOdATPipAneUapI9npseNquEeh3jPklwviBix83PJHV9PW2t03AGGUXuMY55ZaFEIMv+IrI1WYdnPVIXDyIitYsS3y+/6KRfhVeTcPNJ5Rw+FE9y1eZzDEZtTNpxOfUT3QIoXmpZlYL4HbhRuJBZ+Yx54C7uPiUIN9U69XbyXt+Kkynykw2HPaagwuCZxiqCU5sFfLnrVbc3dmZxQcX2yRrs2gmFamzBx+uVbi648H4mb7WuE5UPTBjjA11jRsBjCY0YS2T4Vgfe1RlzlPQkZgjP/bnCCGDqXa3/VZAlZX1nTI51X995bPHBQI0rq2sNDlIXenwiAy1wJSITbSI8DbUx09Cr83xCEaYAE6R6PUfog/tbIUXi0VbrYsCVkAGCK446Wb1vW6q7HR8jrjXNwmXlqN9eLbSVWqdWj7N7fieeTYSrECtUaAjxtUYTIVsH2bfT6FOEM9gMWKffOpFowVzzr3B9bNQLIhnEEwebxBw947i4OcxyVIcEUuumWxoKvcbSPxzJ8v1M3SoBBh4=", // base64 encoded signature
"keyId": "62b2c14e-58af-4199-9842-02995c63edf9",
"signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512",
}
```
<Note>
To sign predigested data, you can pass `"isDigest": true` in the request body. This requires the data to be a base64 encoded digest of the data you wish to sign.
It's important that the digest is created using the same hashing algorithm as the signing algorithm. As an example, you would create the digest with `SHA512` if you are using the `RSASSA_PKCS1_V1_5_SHA_512` signing algorithm.
</Note>
</Step>
</Steps>
</Tab>
</Tabs>
### Guide to Verifying Data
In the following steps, we explore how to verify data using an existing key in Infisical KMS.
<Tabs>
<Tab title="Infisical UI">
<Steps>
<Step title="Accessing your key">
Navigate to Project > Key Management and open the options menu for the key used to sign the data
you want to verify.
![kms key options](/images/platform/kms/infisical-kms/signing/sign-options.png)
</Step>
<Step title="Verifying data with the KMS key">
Paste your signature and data into the text areas and tap on the Verify button.
![kms verify data](/images/platform/kms/infisical-kms/signing/verify-data-modal.png)
Your verification result will be displayed and can be copied for use.
![kms verified data](/images/platform/kms/infisical-kms/signing/signature-verified.png)
If the signature is invalid, you'll see an error message indicating that the signature is invalid, and the "Signature Status" field will be `Invalid`.
</Step>
</Steps>
</Tab>
<Tab title="API">
<Steps>
<Step title="Verifying data">
To verify data, make an API request to the [Verify
Data](/api-reference/endpoints/kms/signing/verify) API endpoint,
specifying the key to use.
### Sample request
```bash Request
curl --request POST \
--url https://app.infisical.com/api/v1/kms/keys/<key-id>/verify \
--header 'Content-Type: application/json' \
--data '{
"data": "SGVsbG8sIFdvcmxkIQ==", // base64 encoded data
"signature": "JYuiBt1Ta9pbqFIW9Ou6qzBsFhjYbMJp9k4dP87ILrO+F2MPnp85g3nOlXK1ttZmRoGWsWnLNDRn9W3rf5VtkeaixPqUW/KvY/fM3CxdMyIV3BuxlGgDksjL8X34Eqkrz4CCPo9hjB5uT+rBCOxCgZqRbOdATPipAneUapI9npseNquEeh3jPklwviBix83PJHV9PW2t03AGGUXuMY55ZaFEIMv+IrI1WYdnPVIXDyIitYsS3y+/6KRfhVeTcPNJ5Rw+FE9y1eZzDEZtTNpxOfUT3QIoXmpZlYL4HbhRuJBZ+Yx54C7uPiUIN9U69XbyXt+Kkynykw2HPaagwuCZxiqCU5sFfLnrVbc3dmZxQcX2yRrs2gmFamzBx+uVbi648H4mb7WuE5UPTBjjA11jRsBjCY0YS2T4Vgfe1RlzlPQkZgjP/bnCCGDqXa3/VZAlZX1nTI51X995bPHBQI0rq2sNDlIXenwiAy1wJSITbSI8DbUx09Cr83xCEaYAE6R6PUfog/tbIUXi0VbrYsCVkAGCK446Wb1vW6q7HR8jrjXNwmXlqN9eLbSVWqdWj7N7fieeTYSrECtUaAjxtUYTIVsH2bfT6FOEM9gMWKffOpFowVzzr3B9bNQLIhnEEwebxBw947i4OcxyVIcEUuumWxoKvcbSPxzJ8v1M3SoBBh4=", // base64 encoded signature
"signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512"
}'
```
### Sample response
```bash Response
{
"signatureValid": true,
"keyId": "62b2c14e-58af-4199-9842-02995c63edf9",
"signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512"
}
```
<Note>
To verify predigested data, you can pass `"isDigest": true` in the request body. This requires the data to be a base64 encoded digest of the data you wish to verify.
It's important that the digest is created using the same hashing algorithm as the signing algorithm. As an example, you would create the digest with `SHA512` if you are using the `RSASSA_PKCS1_V1_5_SHA_512` signing algorithm.
</Note>
</Step>
</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 supports 4 different key algorithms with different purposes:
- `RSA_4096`: For signing and verifying data.
- `ECC_NIST_P256`: For signing and verifying data.
- `AES-256-GCM`: For encryption and decryption operations.
- `AES-128-GCM`: For encryption and decryption operations.
We anticipate to further expand our supported algorithms and support cryptographic operations in the future.
</Accordion>
<Accordion title="How do I sign and verify a digest using the Infisical KMS?">
To sign and verify a digest using the Infisical KMS, you can use the `Sign` and `Verify` endpoints respectively.
You will need to pass `"isDigest": true` in the request body to indicate that you are signing or verifying a digest.
The data you are signing or verifying will need to be a base64 encoded digest of the data you wish to sign or verify.
It's important that the digest is created using the same hashing algorithm as the signing algorithm. As an example, you would create the digest with `SHA512` if you are using the `RSASSA_PKCS1_V1_5_SHA_512` signing algorithm.
To create a SHA512 digest of your data, you can use the following command with OpenSSL:
```bash
echo -n "Hello, World" | openssl dgst -sha512 -binary | openssl base64
```
### Sample request for signing a digest
```bash Request
curl --request POST \
--url https://app.infisical.com/api/v1/kms/keys/<key-id>/sign \
--header 'Content-Type: application/json' \
--data '{
"data": <digest-output-of-openssl-command>,
"signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512",
"isDigest": true
}'
```
### Sample response for signing a digest
```bash Response
{
"signature": <base64-encoded-signature>,
"keyId": <key-id>,
"signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512"
}
```
### Sample request for verifying a digest
```bash Request
curl --request POST \
--url https://app.infisical.com/api/v1/kms/keys/<key-id>/verify \
--header 'Content-Type: application/json' \
--data '{
"data": <digest-output-of-openssl-command>,
"signature": <base64-encoded-signature>,
"signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512",
"isDigest": true
}'
```
### Sample response for verifying a digest
```bash Response
{
"signatureValid": true,
"keyId": <key-id>,
"signingAlgorithm": "RSASSA_PKCS1_V1_5_SHA_512"
}
```
<Note>
Please note that `RSA PSS` signing algorithms are not supported for digest signing and verification. Please use `RSA PKCS1 V1.5` signing algorithms for digest signing and verification, or `ECDSA` if you're using an ECC key.
</Note>
</Accordion>
</AccordionGroup>
Reference in New Issue View Git Blame Copy Permalink