AWS KMS¶

The AWS Key Management Service is a cloud based KMS available in the AWS cloud. Here is 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 am asymmetric key in AWS KMS. You can for example 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 will use 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, you will need to provide the --kms and --key flags.

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

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-03-12T13:07: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 can be stored without extra protection.

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

Tip

If you need help crafting the subject template, you can use the TRC script builder. It will generate 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, you will need to create signatures for the TRC payload. To do this, you can use the scion-pki trc sign command with the --kms flag.

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

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

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

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

Note

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