AWS KMS

The AWS Key Management Service is a cloud-based KMS available in the AWS cloud. The table below provides a set of useful documentation links to get started with AWS KMS:

Type	Description
Basic Concepts	Explanation of the basic concepts and terminology of AWS KMS.
KMS Access and Permissions	Guidance on the different mechanisms to control access and permissions in AWS KMS.
Specifying Credentials	Guidance on how to specify credentials to access AWS KMS.
step-kms-plugin	Guidance by the step-kms-plugin on how to use AWS KMS with the plugin.

Key creation

There are multiple ways to create an asymmetric key in AWS KMS. You can use the AWS KMS Console or the AWS KMS CLI. For a set-by-step example, refer to the official AWS documentation

tip

Use meaningful aliases and tags for the keys.

important

Create an asymmetric key with the purpose of signing and verifying data. If you are using the CLI, use SIGN_VERIFY.

The SCION Control Plane PKI currently only supports the following EC curves for the private keys: P-256, P-384, and P-521. Make sure to use one of these curves when creating the private keys.

Authentication

There are multiple ways to authenticate to AWS KMS in the step-kms-plugin.

By default, the plugin uses the shared credentials file located at ~/.aws/credentials. You can also specify the credentials in the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to use more specific credentials. Refer to the official specifying credentials documentation for more details.

The method you choose depends on your internal policies and requirements.

Certificate creation

To create a self-signed certificate based on a key stored in AWS KMS, provide the --kms and --key flags.

For example, to create a sensitive voting certificate, you can use the following command:

Example: Create a self-signed certificate

scion-pki certificate create <subject-template-file> <certificate-output> \
    --profile sensitive-voting \
    --kms 'awskms:region=<region>' \
    --key 'awskms:key-id=<key-uuid>' \
    --not-before 2025-04-05T10:16:00.00Z \
    --not-after 5y \
    --common-name "My Common Name"

note

Make sure to use the appropriate validity period and subject (including common name) for the certificate. The certificate is non-sensitive information and access to it does not need to be restricted.

For more information on the scion-pki certificate create command, refer to the the scion-pki reference or the TRC ceremony preparations. You can also use the TRC script builder and amend the commands with the --kms and --key flags.

tip

You can use the TRC script builder. It generates a cat command to create the subject template file based on your input.

For example:

cat << EOF > $WORKDIR/subject.tmpl
{
    "state": "CH",
    "isd_as": "1-ff00:0:110"
}
EOF

TRC signature

During the TRC signing ceremony, create signatures for the TRC payload. Use the scion-pki trc sign command with the --kms flag.

To test the signing process before the ceremony, create a dummy payload using the scion-pki trc payload dummy command and sign it with your private key stored in AWS KMS.

Example: Create dummy payload

scion-pki trc payload dummy > /tmp/dummy.pld

Example: Sign dummy payload with AWS KMS

scion-pki trc sign /tmp/dummy.pld <certificate> \
    'awskms:key-id=<key-uuid>' \
    --kms 'awskms:region=<region>' \
    --out /tmp/dummy.pld.sig

note

Contrary to the certificate creation, the key name is provided as an argument rather than through the --key flag.

Example: Inspect signed payload

scion-pki trc inspect /tmp/dummy.pld.sig