Using AWS KMS via the CLI with Elliptic Curve (ECC) Keys

Off the back of local‑kms, I’ve been getting a few questions regarding how to interact with it via the CLI. So here are a few examples of how you can use AWS KMS (or local‑kms) via the CLI.

The examples here focus on demonstrating how to use AWS KMS, not as examples of how to perform ‘good’ encryption. Please don’t use these snippets in production systems unless you know what you’re doing.

What do Elliptic Curve Asymmetric Keys support in KMS?

AWS KMS supports message signing and verification operations using an Elliptic Curve key. You can pick between using National Institute of Standards and Technology (NIST) curves with a key size of 256, 384 or 521 bits. Or the secp256k1 curve, commonly known for its use in Bitcoin.

AWS KMS does not currently support encryption / decryption operations with Elliptic Curve keys.

Using KMS from the CLI

Generating an new ECC CMK

aws kms create-key --key-usage SIGN_VERIFY --customer-master-key-spec ECC_NIST_P256

Note that whilst --key-usage SIGN_VERIFY is the only valid option, it must still be included.

This returns the key details:

{
    "KeyMetadata": {
        "AWSAccountId": "111122223333",
        "KeyId": "024f6b2c-365a-4d86-af2e-9cc5c468afba",
        "Arn": "arn:aws:kms:eu-west-2:111122223333:key/024f6b2c-365a-4d86-af2e-9cc5c468afba",
        "CreationDate": 1590507285,
        "Enabled": true,
        "KeyUsage": "SIGN_VERIFY",
        "KeyState": "Enabled",
        "Origin": "AWS_KMS",
        "KeyManager": "CUSTOMER",
        "CustomerMasterKeySpec": "ECC_NIST_P256",
        "SigningAlgorithms": [
            "ECDSA_SHA_256"
        ]
    }
}

Each ECC Key Spec maps to the following signing algorithm:

  • ECC_NIST_P256 → ECDSA_SHA_256
  • ECC_NIST_P384 → ECDSA_SHA_384
  • ECC_NIST_P521 → ECDSA_SHA_512
  • ECC_SECG_P256K1 → ECDSA_SHA_256

Signing a message

In all cases, when KMS is signing a message, it is in fact always signing the digest of that message, generated via a SHA hash function.

KMS supports two options for generating the digest of a message – you can generate it yourself in advance or, if your message is less than or equal to 4096 bytes, you can have KMS generate the digest for you.

Having KMS generate the digest for you (--message-type RAW)

aws kms sign --key-id 024f6b2c-365a-4d86-af2e-9cc5c468afba --signing-algorithm ECDSA_SHA_256 --message Hello

Generating the digest yourself (--message-type DIGEST)

echo -n Hello | openssl dgst -sha256 -binary > message.sha256

aws kms sign --key-id 024f6b2c-365a-4d86-af2e-9cc5c468afba --signing-algorithm ECDSA_SHA_256 --message-type DIGEST --message fileb://message.sha256

Verifying a message’s signature

aws kms verify --key-id 024f6b2c-365a-4d86-af2e-9cc5c468afba --signing-algorithm ECDSA_SHA_256 --message Hello --signature fileb://signature-raw.sign