Deploy the AWS KMS XKS proxy

Clone the AWS samples Git repository

The AWS Samples GitHub repository provides essential resources for AWS KMS External Key Store (XKS) integrations, including the XKS proxy API specification. In addition, it contains a reference implementation of an XKS proxy and a test client that can be used to validate compliance with the API specification. For more information, see the AWS Samples repository: https://github.com/aws/aws-kms-xksproxy-api-spec.

  1. Install Git on the AWS EC2 instance:

    $ sudo dnf install -y git
Amazon Linux 2023 repository                                                                   69 MB/s |  69 MB     00:00
Amazon Linux 2023 Kernel Livepatch repository                                                 427 kB/s |  55 kB     00:00
...
	Complete!

  2. Create a directory for Git repositories:

    $ sudo mkdir /opt/git

  3. Change to the newly created directory and clone the AWS Samples repository:

    $ cd /opt/git

$ sudo git clone https://github.com/aws-samples/aws-kms-xks-proxy/
Cloning into 'aws-kms-xks-proxy'...
remote: Enumerating objects: 451, done.
remote: Counting objects: 100% (180/180), done.
remote: Compressing objects: 100% (108/108), done.
remote: Total 451 (delta 105), reused 104 (delta 72), pack-reused 271 (from 1)
Receiving objects: 100% (451/451), 248.80 KiB | 16.59 MiB/s, done.
Resolving deltas: 100% (228/228), done.

Configure the XKS proxy

The configuration file is located at /opt/git/aws-kms-xks-proxy/xks-axum/configuration/settings_nshield.toml.

  1. Edit the [server] section as shown below. Set ip to the private IP of the AWS EC2 instance. Do not use the public IP. Set port to 443. Leave all other settings at their default values.

    For example:

    [server]
ip = "10.0.7.200"
port = 443
region = "us-east-1"
service = "kms-xks-proxy"

  2. Edit the [security] section as shown below:

    [security]
is_sigv4_auth_enabled = true
is_tls_enabled = true
is_mtls_enabled = false

  3. Edit the [external_key_stores] section as shown below. Specify values for sigv4_access_key_id and sigv4_secret_access_key. These values are shared secrets used to authenticate requests between AWS KMS and the nShield XKS proxy. They are not AWS IAM access keys and must not be derived from IAM user credentials. Generate these values as shown in the following table.

    For example:

    Parameter Value

    uri_path_prefix

    "/nshield/xks"

    sigv4_access_key_id

    Generate yourself or run tr -dc 'A-Z2-7' </dev/urandom

    sigv4_secret_access_key

    Generate yourself or run openssl rand -base64 32

    xks_key_id_set

    "plainname" of the PKCS #11 key generated in Generate a PKCS #11 key in the nShield HSM
    xks_key_id_set can contain multiple keys. When specifying multiple keys, separate them with commas. 
    $ tr -dc 'A-Z2-7' </dev/urandom | head -c 24 ; echo
U4B.....................

$ openssl rand -base64 32
Ja4.........................................
    [[external_key_stores]]
uri_path_prefix = "/nshield/xks"
sigv4_access_key_id = "U4B....................."
sigv4_secret_access_key = "Ja4........................................."
xks_key_id_set = ["nshield-xks-hsm-key"]

  4. Delete any other [external_key_stores] sections.

  5. Copy the key generated in Obtain a publicly trusted TLS certificate to /opt/git/aws-kms-xks-proxy/xks-axum/tls.

    For example:

    $ ls -al /opt/git/aws-kms-xks-proxy/xks-axum/tls/nshield-xks-private.key
-rw-------. 1 root root 3268 Jul  9 15:42 /opt/git/aws-kms-xks-proxy/xks-axum/tls/nshield-xks-private.key

  6. Copy the signed certificate obtained in Obtain a publicly trusted TLS certificate to /opt/git/aws-kms-xks-proxy/xks-axum/tls.

    For example:

    $ ls -al /opt/git/aws-kms-xks-proxy/xks-axum/tls/nshield-xks_entrust_com.pem
-rwx------. 1 root root 7505 Jul  9 16:28 /opt/git/aws-kms-xks-proxy/xks-axum/tls/nshield-xks_entrust_com.pem

  7. Edit the [tls] section as shown below. Set tls_cert_pem and tls_key_pem to the paths of the certificate and private key files copied in the previous steps.

    [tls]
tls_cert_pem = "tls/nshield-xks_entrust_com.pem"
tls_key_pem = "tls/nshield-xks-private.key"
mtls_client_ca_pem = ""
mtls_client_dns_name = ""

  8. Leave all other settings at their default values, and then save the file.

Start the nShield XKS proxy

This section demonstrates one method of building and deploying the XKS proxy using Rust Cargo. Alternative build and deployment methods are available. Select the approach that best aligns with your organization’s requirements, operational practices, and toolset.

  1. Install Rust and Cargo on the AWS EC2 instance.

    $ sudo dnf install -y rust cargo
Last metadata expiration check: 3:50:49 ago on Tue Jul  7 14:42:39 2026.
Dependencies resolved.
...
Complete!

  2. Build the XKS proxy using Cargo. This process may take several minutes to complete, depending on the EC2 instance type and available system resources.

    cd /opt/git/aws-kms-xks-proxy/xks-axum

$ sudo cargo build --release
Updating crates.io index
...
   Compiling toml v0.7.8
   Compiling axum-macros v0.3.8
   Compiling xks-proxy v3.1.2 (/opt/git/aws-kms-xks-proxy/xks-axum)
    Finished `release` profile [optimized] target(s) in 4m 29s

  3. Create the following executable script:

    $ cat nshield-xks-run
cd /opt/git/aws-kms-xks-proxy/xks-axum
XKS_PROXY_SETTINGS_TOML=configuration/settings_nshield.toml cargo run

$ sudo chmod +x ~/nshield-xks-run

  4. Run the XKS proxy executable. After it starts successfully, the XKS proxy displays initialization and configuration information in the console, indicating that it is ready to accept requests.

    $ nohup sudo ./nshield-xks-run > xks.log 2>&1 &
[1] 1619760

$ cat xks.log
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 3m 58s
     Running `target/debug/xks-proxy`
2026-07-09T18:44:33.743964Z  INFO main xks_proxy: 276: Tracing level="DEBUG" is_file_writer_enabled=true
2026-07-09T18:44:33.744161Z  INFO main xks_proxy: 278: Tracing file rotation_kind="HOURLY"
...

The nShield XKS proxy is now running and ready to process AWS KMS cryptographic operations.