View mode

AWS KMS - Bring Your Own Key (BYOK)¶

Cosmian KMS provides an aws byok command in its CLI (also available in the ui) to facilitate the import of an AWS wrapping key (KEK) in Cosmian KMS, and the export of the wrapped keys for direct import in AWS KMS. To use the AWS KMS terminology, the key that will be created in the Cosmian KMS will be called the external key material as stated in the AWS KMS docs.

The key material refers to the actual cryptographic key bytes that form the basis of a KMS key. While AWS KMS keys include additional metadata, policies, and access controls, the BYOK process allows Cosmian KMS users to maintain full control over key generation while leveraging AWS KMS’s infrastructure for other usages.

Table of Contents¶

AWS KMS - Bring Your Own Key (BYOK)

Overview¶

Since AWS KMS is a managed service where private key material never leaves AWS HSMs, the key import process requires:

Creating a KMS key with EXTERNAL origin (no key material)
Download the wrapping public key and import token from AWS
Wrap your key material using Cosmian KMS
Import the wrapped key material into AWS KMS

Supported wrapping algorithms:

Wrapping Algorithm	Description	Supported Key Material Types
RSAES_OAEP_SHA_256 RSAES_OAEP_SHA_1	The RSA encryption algorithm with Optimal Asymmetric Encryption Padding (OAEP) with SHA-256 or SHA-1 hash function.	• 256-bit AES Symmetric keys • HMAC keys • Asymmetric ECC private keys*
RSA_AES_KEY_WRAP_SHA_256 RSA_AES_KEY_WRAP_SHA_1	Hybrid wrapping (RSA + AES Key Wrap) with SHA-256 or SHA-1 hash function.	• Asymmetric RSA private keys • Asymmetric ECC private keys

Wrapping Key Specs:

RSA_2048 (Note: cannot be used to wrap ECC_NIST_P521 keys with RSAES_OAEP_SHA*_)
RSA_3072
RSA_4096

⚠️ WARNING: Invalid combinations of wrapping algorithms, key material types may lead to errors. Ensure that your selected key material type is supported by the chosen wrapping algorithm and that the wrapping key spec is compatible with both.

Prerequisites¶

An active AWS account
Either: AWS CLI installed and configured on your machine (recommended) or an access to AWS Management Console and open the AWS Key Management Service (AWS KMS) console at https://console.aws.amazon.com/kms.
A running Cosmian KMS instance.
Either: Cosmian KMS CLI installed and configured on your machine or an access to the Cosmian KMS UI of your deployed KMS instance.
Any tool to convert base64 values to their binary counterparts (e.g. openssl, python, etc).

Creating an AES key and importing it using the AWS CLI and the Cosmian CLI :¶

1. Create a KMS key with `EXTERNAL` origin¶

To use the AWS KMS API to create a symmetric encryption KMS key with no key material, send a CreateKey request with the Origin parameter set to EXTERNAL :

    aws kms create-key --origin EXTERNAL

If successful, the output should look like :

{
    "KeyMetadata": {
        "AWSAccountId": "447182645454",
        "KeyId": "350e35ef-ac51-4dbb-82a4-9bc50b0ea42b",
        "Arn": "arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b",
        "CreationDate": "2026-02-18T15:05:59.358000+01:00",
        "Enabled": false,
        "Description": "",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "KeyState": "PendingImport",
        "Origin": "EXTERNAL",
        "KeyManager": "CUSTOMER",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ],
        "MultiRegion": false
    }
}

Copy the key ARN, you will need it in the next step. In this example, the key ARN is arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b.

Note: If no key spec is specified, a symmetric key is created by default. To create a different key, pass the key-spec argument like below for an ECC_NIST_P384 key :

    aws kms create-key \
        --origin EXTERNAL \
        --key-spec ECC_NIST_P384 \
        --description "External NIST-P384 key for signing"

2. Create a symmetric key in Cosmian KMS¶

./cosmian kms sym keys create symmetric_key_test1

Response:

The symmetric key was successfully generated.
        Unique identifier: symmetric_key_test1

3. Download wrapping public key and import token from AWS¶

After you create a AWS KMS key with no key material, download a wrapping public key and an import token for that KMS key by using the AWS KMS console or the GetParametersForImport API. The wrapping public key and import token are an indivisible set that must be used together.

A very detailed example on how to do this is detailed on this page, please refer to it for more info.

The command you should use is the following :

aws kms get-parameters-for-import \
    --key-id arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b \
    --wrapping-algorithm RSAES_OAEP_SHA_256 \
    --wrapping-key-spec RSA_4096

Response:

{
    "KeyId": "arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b",
    "ImportToken": "<YourBase64EncodedToken>",
    "PublicKey": "<YourBase64EncodedPublicKey>",
    "ParametersValidTo": "2026-02-19T15:07:13.227000+01:00"
}

As mentioned in the AWS documentation for importing key material, you will have to convert the base64 values to their binary counterparts before importing them. This can be done with the method of your choice, the most straightforward method (If you have openssl on your cli), would be to copy the token and paste it with the following command to get the file token.bin :

echo -n "<YourBase64EncodedToken>" | openssl enc -d -base64 -A -out token.bin

In a similar manner, you can use the command if you want to keep your public key as a binary blob :

echo -n "<YourBase64EncodedPublicKey>" | openssl enc -d -base64 -A -out kek.bin

4. Import the AWS KEK into Cosmian KMS¶

./cosmian kms aws byok import \
    --kek-base64 "<YourBase64EncodedPublicKey>" \
    --wrapping-algorithm RSAES_OAEP_SHA_256 \
    --key-arn "<YourKeyArn>" \
    --key-id aws_kek_1

Feel free to change the key id to whatever you want, we will call the kek aws_kek_1 in this example.

Alternative : importing the kek as file¶

./cosmian kms aws byok import \
    --kek-file kek.bin \
    --wrapping-algorithm RSAES_OAEP_SHA_256 \
    --key-arn arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b \
    --key-id aws_kek_1

Response:

The PublicKey in file /tmp/ca9f45ad-8596-45a6-bc57-5591e662cb61 was successfully imported with id: aws_kek_1.
        Unique identifier: aws_kek_1
        Tags:
                - aws
                - wrapping_algorithm:RsaesOaepSha256
                - key_arn:arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b

5. Export the wrapped key material from Cosmian KMS¶

# Provide token file simply to display the correct AWS CLI command for import
# If the output file is not specified, the CLI returns base64 encoded encrypted key material
./cosmian kms aws byok export \
    symmetric_key_test1 \
    kek_test1 \
    token.bin \
    EncryptedKeyMaterial.bin

Response:

The encrypted key material was successfully written to 512 for key symmetric_key_test1.

To import into AWS KMS using the API, run:
aws kms import-key-material \
--key-id arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b \
--encrypted-key-material fileb://EncryptedKeyMaterial.bin \
--import-token fileb://token.bin \
--expiration-model KEY_MATERIAL_DOES_NOT_EXPIRE

6. Import the wrapped key material into AWS KMS¶

If you have filled all the fields on the previous step, you can directly use the command that the Cosmian CLI automatically generated for you:

aws kms import-key-material \
    --key-id arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b \
    --encrypted-key-material fileb://EncryptedKeyMaterial.bin \
    --import-token fileb://token.bin \
    --expiration-model KEY_MATERIAL_DOES_NOT_EXPIRE

Response:

{
    "KeyId": "arn:aws:kms:eu-west-3:447182645454:key/350e35ef-ac51-4dbb-82a4-9bc50b0ea42b",
    "KeyMaterialId": "60a5374a2457941eaf5c26b75fea0236bcdc5ddbe70c4aa15046e6fdda49e334"
}

Receiving this response means that the key material has been successfully imported into AWS KMS.

Creating an RSA key and importing it using the AWS CLI and the Cosmian CLI¶

For this example, we will create an 2048 bits RSA key material, wrapped using a 4096 kek with RSAES_OAEP_SHA_256.

First, Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at https://console.aws.amazon.com/kms and complete the necessary steps to create a KMS key with external key material. Be mindful to provide the correct key spec - otherwise the console will expect a symmetric key by default. For this example, we will use RSA_2048.

The next step is to download the wrapping public key and import token. Be mindful that an RSA_AES_KEY_WRAP_SHA_* wrapping algorithm is required for wrapping RSA private key material (except in China Regions). Choosing RSAES_OAEP_SHA_256 will work for this example.

Once this is done, create your key on the cosmian KMS like follow, we call it rsa_key_material :

Figure 1: Create an RSA key in Cosmian KMS

Then, navigate to the AWS - Import Kek section and fill with the adequate data. In this example, we paste the kek in the base64 format for convenience, and call it aws_kek_2.

Figure 2: Import the AWS KEK into Cosmian KMS

Finally, export the wrapped key material from Cosmian KMS to import it into AWS KMS.

We named the file to export EncryptedKeyMaterial.bin. You can import the wrapped key material using the AWS CLI or the AWS Management Console.

An in depth explanation of the import process can be found in the AWS documentation to Import key material (console).

Automated BYOK Scripts¶

To facilitate testing and automating the BYOK flow, we provide ready-to-use Bash scripts that demonstrate the end-to-end process of creating an AWS KMS key, generating the corresponding key material using the Cosmian CLI, and performing the import/export procedures.

The following scripts are available for download:

RSA BYOK Script: Automates the import of RSA private key material. Supports RSA key sizes: 2048, 3072, and 4096. 📥 Download run_rsa_byok.sh
ECC BYOK Script: Automates the import of Elliptic Curve private key material. Supports NIST curves: p256, p384, and p521. 📥 Download run_ecc_byok.sh
AES BYOK Script: Automates the import of 256-bit AES symmetric key material. 📥 Download run_aes_byok.sh

Usage¶

Each script requires the cosmian CLI to be available either in your PATH, the current directory, or specified via the COSMIAN_KMS_CLI environment variable. Also, ensure the aws CLI is available in your PATH, authenticated, and configured.

Example usage:

# Make the script executable
chmod +x run_rsa_byok.sh

# Run the script with the desired key size and an optional description
./run_rsa_byok.sh 2048 "My RSA External Key"

AWS KMS - Bring Your Own Key (BYOK)¶

Table of Contents¶

Overview¶

Prerequisites¶

Creating an AES key and importing it using the AWS CLI and the Cosmian CLI :¶

1. Create a KMS key with EXTERNAL origin¶

2. Create a symmetric key in Cosmian KMS¶

3. Download wrapping public key and import token from AWS¶

4. Import the AWS KEK into Cosmian KMS¶

Alternative : importing the kek as file¶

5. Export the wrapped key material from Cosmian KMS¶

6. Import the wrapped key material into AWS KMS¶

Creating an RSA key and importing it using the AWS CLI and the Cosmian CLI¶

Automated BYOK Scripts¶

Usage¶

1. Create a KMS key with `EXTERNAL` origin¶