Azure Key Vault¶

The Azure Key Vault is a cloud based KMS available in the Azure cloud. Here is 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. You can for example use the Azure CLI or Azure GUI.

Tip

Use meaningful names for the key vault and the keys. Consider whether you want to maintain multiple vaults 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, do not 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. You can 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. You can 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, 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 '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 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 Azure Key Vault.

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

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

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.