Skip to content

Using KMS API to obtain the RSA private key

IAD Server supports receiving private keys from KMS to decrypt payloads. IAD Server receives a key from KMS at startup and then periodically requests key updates. If an error occurs during the call to KMS (if KMS is not available), IAD Server continues to use the previous version of the key. When the server is restarted, the key is reset.

You can use the following environment variables to configure integration with KMS.

Variable Default value Description
IAD_SERVER_DECRYPTION_KEY_PROVIDER_TYPE LOCAL Key provider type, acceptable values: LOCAL, KMS.
LOCAL - keys are downloaded from file system.
KMS - keys are downloaded from KMS.
IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_HTTP_METHOD GET KMS API HTTP method type, acceptable value: GET, POST.
IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_URL Full URL of KMS API method. For example: https://kms-host:443/rsa/private
IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_HTTP_HEADER_NAME KMS API HTTP header name, used to pass KMS Client ID. For example:
-H “kms-client-id:c923ccbd-b36f-40a2-ba6b-2833ef19c287”
In this case, the KMS API HTTP header name is kms-client-id
IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_CLIENT_ID The KMS Client ID that must be passed in the HTTP header on every KMS API call.
IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_SSL_ENABLE false Enable interaction with KMS over HTTPS.
IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_SSL_TRUST_STORE Path to a SSL certificate for interaction with KMS over HTTPS.
IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_SSL_TRUST_STORE_PASSWORD Password for SSL certificate.
IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_CACHE_TTL 300000 The frequency in milliseconds with which IAD Server requests an updated key from KMS.
The default value is 5 minutes (300,000 ms).

Example of running IAD Server in the KMS integration mode:

docker run -d -p 8080:8080 --name=iad \
    -v /path/to/cert_key.p12:/app/cert_key.p12 \
    -e IAD_SERVER_DECRYPTION_KEY_PROVIDER_TYPE=KMS \
    -e IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_URL=https://kms-host:443/rsa/private \
    -e IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_HTTP_HEADER_NAME=kms-client-id \
    -e IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_CLIENT_ID=c923ccbd-b36f-40a2-ba6b-2833ef19c287 \
    -e IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_SSL_ENABLE=true \
    -e IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_SSL_TRUST_STORE_PASSWORD=dummy \
    -e IAD_SERVER_DECRYPTION_KEY_PROVIDER_KMS_SSL_TRUST_STORE=/app/cert_key.p12 \
    367672406076.dkr.ecr.eu-central-1.amazonaws.com/iadproject/iad-server-prod:2.1.0