aws-kms-xksproxy-test-client

This package provides a sample curl based utility to test external key store proxy implementations for compliance against the AWS KMS External Keystore (XKS) Proxy API Specification.

Version

1.1.0

Dependencies

awk
base64
bash 4.2+
cat
curl 7.75+ (i.e. with sigv4 support)
dd
echo
env
head
jq 1.5+
mktemp
printf
read
rm
sed
sh
sha256sum
tr
uuidgen
xxd

Examples

# Change this to your XKS Proxy endpoint to test.
export XKS_PROXY_HOST="localhost"
# Change this to the URI_PREFIX of a logical keystore supported by your XKS Proxy.
export URI_PREFIX="example/uri/path/prefix"
# Change this to the Access key ID for request authentication to your logical keystore.
# Valid characters are a-z, A-Z, 0-9, /, - (hyphen), and _ (underscore)
export SIGV4_ACCESS_KEY_ID="BETWEEN2TENAND3TENCHARACTERS"
# Change this to the Secret access key for request authentication to your logical keystore.
# 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"
# Change this to a test key id supported by your logical keystore.
export KEY_ID="foo"

# Run the tests
./test-xks-proxy

# Run all the tests including the use of encrypt-only key, decrypt-only key and
# key that can neither encrypt nor decrypt. You can specify the respective key id's with
# the environment variables ENCRYPT_ONLY_KEY_ID, DECRYPT_ONLY_KEY_ID and IMPOTENT_KEY_ID.
./test-xks-proxy -a

Using Docker

If you have Docker installed, you can build this client into a Docker image and run the tests via the Docker container. This has the benefit of automatically getting all the necessary versions of dependencies such as curl, jq, etc.

# Build docker image named test-xks-proxy
make docker

# Then run everything in the same way as you would with "test-xks-proxy",
# but replacing "test-xks-proxy" with "test-xks-proxy-via-docker".
# For example, to get help,
./test-xks-proxy-via-docker -h

Examples of running in other modes

# Do not include the curl HTTP response headers in the output
VERBOSE= ./test-xks-proxy

# To make curl verbose
VERBOSE=-v ./test-xks-proxy

# To make curl verbose and include the HTTP response headers in the output
VERBOSE=-iv ./test-xks-proxy

# To enable debugging output to stderr, including the actual curl command being run
DEBUG=1 ./test-xks-proxy

# To enable all of the above
VERBOSE=-iv DEBUG=1 ./test-xks-proxy

# To test against the endpoint http:://xks-proxy.mydomain.com
# XKS_PROXY_HOST=xks-proxy.mydomain.com \
#     SCHEME= \
#     ./test-xks-proxy

# To enable mTLS, a client side SSL key and certificate would need to be specified.
# The command to run the tests would be something like:
# XKS_PROXY_HOST=xks-proxy_with_mtls_enabled.mydomain.com \
#    MTLS="--key client_key.pem --cert client_cert.pem" \
#    ./test-xks-proxy

Environment variables

The following environment variables can be used to override the default settings.

SIGV4_ACCESS_KEY_ID - Access key ID for request authentication to your logical keystore. Valid characters are a-z, A-Z, 0-9, /, - (hyphen), and _ (underscore)
- Default to "BETWEEN2TENAND3TENCHARACTERS"
SIGV4_SECRET_ACCESS_KEY - (Required) Secret access key for request authentication to your logical keystore. Secret access key must have between 43 and 64 characters. Valid characters are a-z, A-Z, 0-9, /, +, and =
- Default to "PleaseReplaceThisWithSomeSecretOfLength43To64"
XKS_PROXY_HOST - the xks-proxy endpoint
- Default to "localhost"
URI_PREFIX - the xks-proxy URI prefix
- Default to "example/uri/path/prefix"
REGION - the region used for SigV4 authentication
- Default to "us-east-1"
VERBOSE - verbosity
- Default to "-i"
- Can be set to "-i" to include the curl HTTP response headers in the output
- Can be set to "-v" to make curl verbose
- Can be set to "-iv" to do both
KEY_ID - the HSM key id
- Default to "foo"
ENCRYPT_ONLY_KEY_ID - the HSM key id for an encrypt-only key
- Default to "encrypt_only_key"
DECRYPT_ONLY_KEY_ID - the HSM key id for an decrypt-only key
- Default to "decrypt_only_key"
IMPOTENT_KEY_ID - the HSM key id for a key that can neither encrypt nor decrypt
- Default to "impotent_key"
SCHEME - used to select whether TLS is used over http
- Default to "https://"
- Can be set to blank to use http instead
SECURE - (TLS) By default, every SSL connection curl makes is verified to be secure. This option allows curl to proceed and operate even for server connections otherwise considered insecure.
- Default to blank, which means, SSL connection is verified if https is in use
- Can be set to "--insecure" to disable SSL connection verification if https is in use
MTLS - used to specify both a client-side SSL private key and SSL certifcate for performing mutual TLS with the xks-proxy.
- Default to not using mTLS.
DEBUG - used to toggle debugging output to stderr
- Default to 0 to disable debugging output
- Can be set to 1 to enable debugging output, printing the actual curl command being run
ANSI_ESCAPE - used to toggle the use of ANSI Escape codes in the output
- Default to 1 to enable the use of ANSI Escape codes in the output
- Can be set to 0 to disable the use of ANSI Escape codes in the output

Notes

The sha256sum command can be installed on OSX via

brew install coreutils

and is typically pre-installed in a Linux distribution.

Change log

Wed Oct 5 2022 Hanson Char [email protected] - 1.1.0
- Fix typo, changing "ASCII_ESCAPE" to "ANSI_ESCAPE"
Wed Sep 28 2022 Hanson Char [email protected] - 1.0.6
- Fix "Segmentation fault: 11" when run on OSX
Mon Sep 26 2022 Hanson Char [email protected] - 1.0.5
- Supports ANSI_ESCAPE to toggle the use of ANSI Escape codes in the output
Mon Sep 26 2022 Hanson Char [email protected] - 1.0.4
- Make scripts work when run in AWS Lambda
Mon Sep 5 2022 Hanson Char [email protected] - 1.0.3
- Initial release

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.

hansonchar / aws-kms-xksproxy-test-client Goto Github PK