Azure Key Vault

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

Type	Description
Basic Concepts	Explanation of the basic concepts and terminology of Azure Key Vault.
Best Practices	Guidance on how to use Azure Key Vault securely and efficiently.
RBAC Permission Model	Guidance on how to provide access to Azure Key Vault using the RBAC permission model.
Azure CLI Service Principals	Tutorial on how to create a service principal in Azure CLI.
step-kms-plugin	Guidance by the step-kms-plugin on how to use Azure Key Vault with the plugin.

Key creation

There are multiple ways to create an asymmetric key in Azure Key Vault. Use the Azure CLI or Azure portal.

tip

Use meaningful names for the key vault and the keys. Consider whether you want to maintain multiple vaults to grant different access to different users.

important

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 Azure Key Vault in the step-kms-plugin.

When using the default Azure CLI credentials, you are not required to set any environment variables. The plugin will automatically use the credentials from the Azure CLI. This requires that you are logged in and have the correct permissions to access the Key Vault. Refer to using developer accounts for some hints on how to set this up.

When using service principals, set the AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET variables. Refer to using service principals for some hints on how to set this up.

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 Azure Key Vault, 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 'azurekms' \
    --key 'azurekms:vault=<vault-name>;name=<key-name>' \
    --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 Azure Key Vault.

Example: Create dummy payload

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

Example: Sign dummy payload with Azure Key Vault

scion-pki trc sign /tmp/dummy.pld <certificate> \
    'azurekms:vault=<vault-name>;name=<key-name>' \
    --kms 'azurekms' \
    --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