aws-kms-xks-proxy

This package provides a sample implementation of the AWS KMS External Keystore (XKS) Proxy API for reference by external customers against any Hardware Security Module (HSM) that supports PKCS#11 v2.40.

The current implementation is written in Rust and is known to work with the following types of HSM:

• LunaSA 7.4.0 (via Thales eLab)
• Luna 7 Network HSM (hardware device)
• SoftHSMv2
• AWS CloudHSM

Quick Start

Build xks-proxy into a Docker image to serve http traffic, with SoftHSMv2 pre-installed and pre-generated with a single AES key named foo:

docker build -t xks-proxy:latest .

Run xks-proxy as a Docker container:

docker run --rm --name xks-proxy -d -p 0.0.0.0:80:80 xks-proxy:latest

Verify the server is up and running:

curl localhost/ping

You should see the response:

pong from xks-proxy v3.1.2-unknown

which indicates the server is now up and running. You can monitor the logs with:

docker logs -f xks-proxy

Using another terminal, download a curl based client and cd to it:

git clone https://github.com/aws-samples/aws-kms-xksproxy-test-client.git
cd aws-kms-xksproxy-test-client

(Note you'd need to have curl 7.75+ installed for the following.)

Run tests locally against the xks-proxy:

export XKS_PROXY_HOST="localhost"
export URI_PREFIX="example/uri/path/prefix"
# Access key ID must have between 20 and 30 characters. Valid characters are uppercase A-Z and 2-7
export SIGV4_ACCESS_KEY_ID="BETWEEN2TENAND3TENCHARACTERS"
# Secret access key must have between 43 and 64 characters. Valid characters are a-z, A-Z, 0-9, /, +, and =
export SIGV4_SECRET_ACCESS_KEY="PleaseReplaceThisWithSomeSecretOfLength43To64"
export KEY_ID="foo"
export SCHEME=
./test-xks-proxy

You should see All 35 tests PASSED at the end.

To stop the Docker container running xks-proxy:

docker container stop xks-proxy

More information about the use of docker can be found at docker/README.md.

Details

The XKS Proxy API spec assumes you have already set up the vendor specific HSM with the necessary cryptographic keys created. Once that is done, set up a configuration file at /var/local/xks-proxy/.secret/settings.toml. A number of sample configuration files for different types of HSM's can be found under the xks-axum/configuration folder.

Then, to run the XKS Proxy server for debugging purposes:

# Under the xks-axum directory
XKS_PROXY_SETTINGS_TOML=/var/local/xks-proxy/.secret/settings.toml cargo run

Unit tests

To run the unit tests, type

# Under the xks-axum directory
cargo test

Generate RPM for Centos Linux

To generate the RPM for xks-proxy for installation on a Centos Linux x86_64 platform, type:

# Under the root directory
make

Install via RPM

To install the generated RPM on a Centos Linux x86_64 platform:

# For example
sudo yum install -y xks-proxy-3.1.2-0.el7.x86_64.rpm

Configuration

Specify the configuration file path, such as /var/local/xks-proxy/.secret/settings.toml, by setting the environment variable XKS_PROXY_SETTINGS_TOML.

See the xks-axum/configuration folders for some sample configuraions for various HSM's such as Thales Luna HSM, AWS CloudHSM and SoftHSMv2.

Manage xks-proxy as a systemd unit

Once the xks-proxy RPM has been installed, you can manage it as a systemd unit. For example

# Show the backing file
sudo systemctl cat xks-proxy

# Display the status
systemctl status xks-proxy

# The default systemd unit configuration for xks-proxy can be found at /etc/systemd/system/xks-proxy.service.
# To override the configuration:
sudo systemctl edit xks-proxy

# To start xks-proxy
sudo systemctl start xks-proxy

# To stop
sudo systemctl stop xks-proxy

# Display the system journal log
sudo journalctl -xef --unit xks-proxy

Clean logs via xks-proxy_cleanlogs.timer

If you choose to output logging of xks-proxy to a file (with is_file_writer_enabled = true in settings.toml), you can have the log files automatically removed perodically via a systemd timer.

# Show the backing file for the timer
sudo systemctl cat xks-proxy_cleanlogs.timer

# Display the status of the cleaning service driven by the timer
systemctl status xks-proxy_cleanlogs

# Display the status of the timer
systemctl status xks-proxy_cleanlogs.timer

# The default systemd unit configuration for the timer can be found at /etc/systemd/system/xks-proxy_cleanlogs.timer.
# To override the (default hourly timer) configuration:
sudo systemctl edit xks-proxy_cleanlogs.timer

# To start the timer
sudo systemctl start xks-proxy_cleanlogs.timer

# Display the system journal log of the cleaning service
sudo journalctl -xef --unit xks-proxy_cleanlogs

# Display the system journal log of the timer
sudo journalctl -xef --unit xks-proxy_cleanlogs.timer

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.