diff --git a/docs/documentation/platform/kms/aws-hsm.mdx b/docs/documentation/platform/kms/aws-hsm.mdx
new file mode 100644
index 000000000..e7bd03fd1
--- /dev/null
+++ b/docs/documentation/platform/kms/aws-hsm.mdx
@@ -0,0 +1,82 @@
+---
+title: "AWS CloudHSM"
+description: "Learn how to manage encryption using AWS CloudHSM"
+---
+
+This guide provides instructions on securing Infisical project secrets using AWS CloudHSM.
+Integration with AWS CloudHSM is achieved by configuring it as a custom key store for AWS KMS.
+Follow the steps below to set up AWS KMS with AWS CloudHSM as the custom key store.
+
+## Prepare AWS CloudHSM Cluster
+
+Before you get started, you'll need to configure a AWS CloudHSM cluster which meets the following criteria:
+
+- The cluster must be active.
+- The cluster must not be associated with any other AWS KMS custom key store.
+- The cluster must be configured with private subnets in at least two Availability Zones in the Region.
+- The security group for the cluster must include inbound and outbound rules that allow TCP traffic on ports 2223-2225.
+- The cluster must contain at least two active HSMs in different Availability Zones.
+
+For more details on setting up your cluster, refer to the following [AWS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/create-keystore.html#before-keystore).
+
+## Set Up AWS KMS Custom Key Store
+
+To set up an AWS KMS custom key store with AWS CloudHSM, you will need the following:
+
+- The trust anchor certificate of your AWS CloudHSM cluster.
+- A `kmsuser` user in the AWS CloudHSM cluster with the crypto-user role.
+
+
+
+ In the AWS console, head over to `AWS KMS` > `AWS CloudHSM key stores` and click **Create key store**.
+
+
+ Input the custom key store name. 
+
+
+ Select the AWS CloudHSM cluster. You should be able to select the cluster if it meets the required criteria mentioned above.
+ 
+
+
+ Upload your CloudHSM's cluster trust anchor certificate file.
+ 
+
+
+ Input the password of the `kmsuser` crypto-user in your cluster.
+ 
+
+
+ Proceed with creating the AWS CloudHSM key store.
+
+
+
+For more details, refer to the following [AWS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/create-keystore.html#create-keystore-console).
+
+## Create AWS KMS Key
+Next, you'll need to create a AWS KMS key where you will set the key store you created previously.
+
+
+
+ In your AWS console, proceed to `AWS KMS` > `Customer managed keys` and click **Create**.
+
+
+ Set Key type to `Symmetric` and Key usage to `Encrypt and decrypt`.
+ 
+
+
+ In the advanced options, for the Key material origin field, select `AWS CloudHSM key store`. Then, click next.
+ 
+
+
+ Select the AWS CloudHSM key store you created earlier.
+ 
+
+
+ Proceed with creating the AWS KMS Key.
+
+
+
+## Connect Infisical to AWS KMS Key
+
+You should now have an AWS KMS that has a custom key store set to AWS CloudHSM.
+To secure project resources, you will need to add this AWS KMS to your Infisical organization. To learn how, refer to the documentation [here](./aws-kms).
\ No newline at end of file
diff --git a/docs/documentation/platform/kms/aws-kms.mdx b/docs/documentation/platform/kms/aws-kms.mdx
index 0bf33bb0d..14769f301 100644
--- a/docs/documentation/platform/kms/aws-kms.mdx
+++ b/docs/documentation/platform/kms/aws-kms.mdx
@@ -1,24 +1,26 @@
---
-title: "AWS Key Management Service (KMS)"
+title: "AWS Key Management Service"
description: "Learn how to manage encryption using AWS KMS"
---
-You can configure your projects to use AWS KMS keys for encryption, enhancing the security and management of your secrets.
+To enhance the security of your Infisical projects, you can now encrypt your secrets using an external Key Management Service (KMS).
+When external KMS is configured for your project, all encryption and decryption operations will be handled by the chosen KMS.
+This guide will walk you through the steps needed to configure external KMS support with AWS KMS.
## Prerequisites
-Depending on the AWS Authentication Method you intend to use, you will have to do either of the following:
+Before you begin, you'll first need to choose a method of authentication with AWS from below.
-
+
1. Navigate to the [Create IAM Role](https://console.aws.amazon.com/iamv2/home#/roles/create?step=selectEntities) page in your AWS Console.
2. Select **AWS Account** as the **Trusted Entity Type**.
- 3. Choose **Another AWS Account** and enter **381492033652** (Infisical AWS Account ID). This restricts the role to be assumed only by Infisical. If self-hosting, provide your AWS account number instead.
- 4. Optionally, enable **Require external ID** and enter your **project ID** to further enhance security.
+ 3. Choose **Another AWS Account** and enter **381492033652** (Infisical AWS Account ID). This restricts the role to be assumed only by Infisical. If you are self-hosting, provide the AWS account number where Infisical is hosted.
+ 4. Optionally, enable **Require external ID** and enter your Infisical **project ID** to further enhance security.
Use the following custom policy to grant the minimum permissions required by Infisical to integrate with AWS KMS
@@ -44,7 +46,7 @@ Depending on the AWS Authentication Method you intend to use, you will have to d
-
+
Navigate to your IAM user and add a policy to grant the following permissions:
```json
{
@@ -68,10 +70,10 @@ Depending on the AWS Authentication Method you intend to use, you will have to d
## Setup AWS KMS in the Organization Settings
-Follow these steps to set up AWS KMS for your organization:
+Next, you will need to follow the steps listed below to add AWS KMS for your organization.
-
+
@@ -83,7 +85,8 @@ Follow these steps to set up AWS KMS for your organization:
Choose 'AWS KMS' from the list of encryption providers.
- Fill in the required details for AWS KMS:
+ Selecting AWS as the provider will require you input the following fields.
+
Name for referencing the AWS KMS key within the organization.
@@ -96,7 +99,7 @@ Follow these steps to set up AWS KMS for your organization:
Authentication mode for AWS, either "AWS Assume Role" or "Access Key".
-
+
ARN of the AWS role to assume for providing Infisical access to the AWS KMS Key (required if Authentication Mode is "AWS Assume Role")
@@ -104,11 +107,11 @@ Follow these steps to set up AWS KMS for your organization:
Custom identifier for additional validation during role assumption.
-
+
AWS IAM Access Key ID for authentication (required if Authentication Mode is "Access Key").
-
+
AWS IAM Secret Access Key for authentication (required if Authentication Mode is "Access Key").
@@ -126,14 +129,14 @@ Follow these steps to set up AWS KMS for your organization:
-You now have an AWS KMS Key configured at the organization level. You can assign these keys to existing projects via the Project Settings page.
+You now have an AWS KMS Key configured at the organization level. You can assign these AWS KMS keys to existing Infisical projects by visiting the 'Project Settings' page.
## Assign AWS KMS Key to an Existing Project
-Follow these steps to assign an AWS KMS key to a project:
+To assign the AWS KMS key you added to your organization, follow the steps below.
-
+
@@ -143,6 +146,6 @@ Follow these steps to assign an AWS KMS key to a project:
Choose the AWS KMS key you configured earlier.
- Save the changes to apply the new encryption settings to your project.
+ Once you have selected the KMS of choice, click save.
diff --git a/docs/images/platform/kms/aws-hsm/create-key-store-cert.png b/docs/images/platform/kms/aws-hsm/create-key-store-cert.png
new file mode 100644
index 000000000..c07c2a895
Binary files /dev/null and b/docs/images/platform/kms/aws-hsm/create-key-store-cert.png differ
diff --git a/docs/images/platform/kms/aws-hsm/create-key-store-cluster.png b/docs/images/platform/kms/aws-hsm/create-key-store-cluster.png
new file mode 100644
index 000000000..245b11d98
Binary files /dev/null and b/docs/images/platform/kms/aws-hsm/create-key-store-cluster.png differ
diff --git a/docs/images/platform/kms/aws-hsm/create-key-store-name.png b/docs/images/platform/kms/aws-hsm/create-key-store-name.png
new file mode 100644
index 000000000..1b47604b8
Binary files /dev/null and b/docs/images/platform/kms/aws-hsm/create-key-store-name.png differ
diff --git a/docs/images/platform/kms/aws-hsm/create-key-store-password.png b/docs/images/platform/kms/aws-hsm/create-key-store-password.png
new file mode 100644
index 000000000..5ae84394d
Binary files /dev/null and b/docs/images/platform/kms/aws-hsm/create-key-store-password.png differ
diff --git a/docs/images/platform/kms/aws-hsm/create-kms-key-1.png b/docs/images/platform/kms/aws-hsm/create-kms-key-1.png
new file mode 100644
index 000000000..a5bb700c9
Binary files /dev/null and b/docs/images/platform/kms/aws-hsm/create-kms-key-1.png differ
diff --git a/docs/images/platform/kms/aws-hsm/create-kms-key-2.png b/docs/images/platform/kms/aws-hsm/create-kms-key-2.png
new file mode 100644
index 000000000..78f3926d8
Binary files /dev/null and b/docs/images/platform/kms/aws-hsm/create-kms-key-2.png differ
diff --git a/docs/images/platform/kms/aws-hsm/create-kms-select-hsm.png b/docs/images/platform/kms/aws-hsm/create-kms-select-hsm.png
new file mode 100644
index 000000000..925bf6928
Binary files /dev/null and b/docs/images/platform/kms/aws-hsm/create-kms-select-hsm.png differ
diff --git a/docs/mint.json b/docs/mint.json
index 5c7012745..f6bc0e5e9 100644
--- a/docs/mint.json
+++ b/docs/mint.json
@@ -158,7 +158,8 @@
"group": "Key Management",
"pages": [
"documentation/platform/kms/overview",
- "documentation/platform/kms/aws-kms"
+ "documentation/platform/kms/aws-kms",
+ "documentation/platform/kms/aws-hsm"
]
},
"documentation/platform/secret-sharing"