type: required. one of awskms, cloudkms, pkcs11, or yubikey
uri: this field can be used to specify other fields in this section, and its value will take precedence over those values. See cryptographic protection for examples.
region: for awskms, the AWS region
profile: for awskms, the AWS profile
credentialsFile: for cloudkms, the path to a Google Cloud Platform credentials JSON file for a role that can access cloudkms
pin: for yubikey, the PIN of the YubiKey PIV application
password: optionally store the password for decrypting the intermediate private key (this should be the same password you chose during PKI initialization). If the value is not stored in configuration then you will be prompted for it when starting the CA.
address: ex. 127.0.0.1:8080 - address and port on which the CA will bind and respond to requests.
dnsNames: comma separated list of DNS name(s) for the CA.
logger: the default logging format for the CA is text. The other option is json.
ssh: enables the provisioning of SSH certificates by the CA. Add this section to an existing ca.json to enable SSH for an existing CA. SSH keys can be created by running
step crypto keypair host.pub host.key and step crypto keypair user.pub user.key.
userKey: the signing key for user SSH certificates.
hostKey: the signing key for host SSH certificates.
dataSource: string that can be interpreted differently depending on the type of the database. Usually a path to where the data is stored. See the database configuration docs for more info.
database: name of the database. Used for back-ends that may have multiple databases. e.g. MySQL and PostgreSQL
valueDir: directory to store the value log in (Badger specific).
tls: settings for negotiating communication with the CA; includes acceptable ciphersuites, min/max TLS version, etc.
authority: controls the request authorization and signature processes.
type: the type of backing CA service that issues certificates for this step-ca instance. The default is an internal certificate authority service.
Other options can turn step-ca into a Registration Authority: stepcas uses a remote step-ca instance as the backend, cloudcas uses Google CloudCAS, vaultcas uses Hashicorp Vault.
template: default ASN1DN values for new certificates.
claims: default validation for requested attributes in the certificate request. Can be overridden by similar claims objects defined by individual provisioners.
minTLSCertDuration: do not allow certificates with a duration less than this value.
maxTLSCertDuration: do not allow certificates with a duration greater than this value.
defaultTLSCertDuration: if no certificate validity period is specified, use this value.
disableRenewal: do not allow any certificates to be renewed. The default is false.
allowRenewalAfterExpiry: ☠️ allow expired certificates to be renewed. The default is false. This option adds security risk; proceed with caution and consider alternatives.
minUserSSHCertDuration: do not allow certificates with a duration less than this value.
maxUserSSHCertDuration: do not allow certificates with a duration greater than this value.
defaultUserSSHCertDuration: if no certificate validity period is specified, use this value.
minHostSSHCertDuration: do not allow certificates with a duration less than this value.
maxHostSSHCertDuration: do not allow certificates with a duration greater than this value.
defaultHostSSHCertDuration: if no certificate validity period is specified, use this value.
enableSSHCA: enable this provisioner to generate SSH Certificates. The default value is false.
disableIssuedAtCheck: ☠️ disable a check verifying that provisioning tokens must be issued after the CA has booted. This claim is one prevention
against token reuse. The default value is false. Do not change this unless you know what you are doing.
provisioners: list of provisioners. Each provisioner has a name, associated authentication attributes, and an optional claims attribute that will override any values set in the global claims directly underneath authority. The step ca provisioner command group can be used to add, modify, and remove provisioners. See the provisioner documentation for details.
claims: Each provisioner can define an optional claims attribute. The settings in this attribute override any settings in the global claims attribute in the authority configuration. See the authority's claims section above for a complete list of options.
options: Each provisioner can define an optional options attribute. This attribute allows an operator to set templates that will be applied to all X.509 or SSH certificates generated using the provisioner. See the templates documentation for details.
password: ☠️ plain text password for starting the CA. Used to decrypt the intermediate private key.
We do not recommend storing the password plain text in your ca.json. The recommended option is to use the --password-file flag when running step-ca. This attribute is a convenience that should be avoided in production.
Provisioners are people or entities that are registered with the certificate authority and
authorized to issue certificates. Visit the step-ca provisioners page to learn about the
different provisioners, their target use cases, and how to add, remove, and configure them.
Certificate issuance policies can be used to enforce which Subjects, SANs and Principals the CA is allowed to sign.
They can be configured for X.509 certificates as well as SSH user and host certificates.
Policies are evaluated before a certificate is signed.
Some examples of policies you can configure are:
A dns rule for www.example.com, only matching the domain www.example.com
A dns rule for *.internal.example.com, matching all subdomains of internal.example.com.
An ip rule for the 192.168.0.0/24 CIDR, matching all IPs in the range from 192.168.0.0-192.168.0.255.
An email rule for @devops, matching all SSH user principals in the @devops domain.
A uri rule for *.example.com, matching all URIs for subdomains of example.com, ignoring the URI scheme.
Visit the step-ca policy page to learn how certificate issuance policies work and how they can be configured.
step-ca uses a simple key-value interface over popular database
implementations to store persistent certificate management meta-data. Our
recommended default database implementation is nosql-Badger, a NoSQL interface
over the popular Badger database. As a
first pass, the database layer will store every certificate (along with
metadata surrounding the provisioning of the certificate) and
revocation data that will be used to enforce passive revocation.
Configuring step-ca to use a database is as simple as adding a top-level db
stanza to your ca.json file. Below users can find documentation and examples
for supported databases:
badger: currently refers to Badger V1. However, as Badger V1 is deprecated, this will refer to Badger V2 starting with a the next major version release.
badgerV1: explicitly select Badger V1.
badgerV2: explicitly select Badger V2. Anyone looking to use Badger V2 will need to set it explicitly until it becomes the default.
dataSource: path, database directory.
valueDir [optional]: path, value directory, only if different from dataSource.
badgerFileLoadingMode [optional]: can be set to FileIO (instead of the default MemoryMap) to avoid memory-mapping log files. This can be useful in environments with low RAM. Make sure to use badgerV2 as the database type if using this option.
FileIO: This can be useful in environments with low RAM.
The database driver will look for a file with root CAs to trust in $HOME/.postgresql/root.crt, but will use the system CA trust store if that file is not found.
Similarly, $HOME/.postgresql/postgresql.crt and the corresponding $HOME/.postgresql/postgresql.key will be used for mutual TLS authentication if these files exist and if the server requests a client certificate.
It is also possible to override the locations for these files by providing them in the DSN:
The behavior of the PostgreSQL database driver mimics that of libpq and also encompasses handling of other default settings and environment variables.
More info about TLS options and the DSN query parameters for libpq can be found at https://www.postgresql.org/docs/current/libpq-ssl.html.
As the interface is a key-value store, the schema is very simple. We support tables, keys, and values. An entry in the database is a byte value that is indexed by byte table and byte key.
At this time step-ca does not have any API or interface for easily exporting data. Because the data is stored in a noSQL like manner, it is difficult to explore the data even when using a SQL backend like MySQL. We do have a scripted example for accessing the DB to give users a jumping off point for writing their own reporting and logging tools.
Note that some DBs, like Badger and BoltDB, cannot have multiple processes accessing them simultaneously. You'll need to stop the step-ca process in order to run a export script against those DBs.
Cloud KMS is Google's cloud-hosted KMS that allows you to store the cryptographic keys and sign certificates using their infrastructure. Cloud KMS supports two different protection levels: SOFTWARE and HSM.
To configure Cloud KMS in your certificate authority, add the kms object to your ca.json file and replace the property key with the Cloud KMS key name of your intermediate key:
Currently, step does not provide an automatic way to initialize the public key infrastructure (PKI) using Cloud KMS. Still, an experimental tool named step-cloudkms-init addresses this use case. This tool generates the public certificates root_ca.crt and intermediate_ca.crt for inclusion in ca.json and prints the intermediate key name for use in the key property. In a future release, this tool will be integrated into step.
When using Azure Key Vault with step-ca, you will first need to authenticate to Azure.
Authentication to Azure is handled via environment variables;
we recommend using either file-based authentication via the AZURE_AUTH_LOCATION environment variable,
or creating a service principal
and setting the AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET variables when starting step-ca.
See Option 1 under Authentication Methods for Azure SDK for Go for examples of authentication methods and environment variables.
For local development and testing, Azure CLI credentials will be used if no authentication environment variables are set.
Initialize a PKI
To initialize a PKI backed by Azure Key Vault, start by authenticating to Azure using one of the above approaches.
Set the environment variables necessary for authentication to your tenant.
$ step ca init --kms azurekms
You will be walked through the process of creating root and intermediate CA signing keys in Key Vault, and configuring the CA to use them.
If you're creating an SSH CA, SSH host and user CA keys will be created in Key Vault as well.
To configure an existing CA for Azure Key Vault, or to import an existing Azure Key Vault signing key, add the kms object to your ca.json, and replace the key properties with the key name, vault name, and version of your intermediate (signing) key in Azure Key Vault:
In the key URI, the name and vault refer to the key name and vault name of your intermediate key in Azure Key Vault.
In the key URI, the version is the version of the Azure Key Vault key name. Though it is optional, we recommend setting this value explicitly. If omitted, the latest version will be used.
In the key URI, the optional hsm property can be set to true if HSM protection is desired. This is only used when the key is being created by step-ca. The default is to use software-protected (non-HSM-backed) keys. See Key Vault's About Keys page for more details.
In kms, an optional uri property can be added to provide client credentials (eg. azurekms:client-id=fooo;client-secret=bar;tenant-id=9de53416-4431-4181-7a8b-23af3EXAMPLE) instead of using the environment variables described above.
AWS KMS is Amazon's managed encryption and key management service. It creates and stores the cryptographic keys and uses AWS infrastructure for signing operations. Amazon KMS operations are always backed by HSMs.
To configure AWS KMS in your certificate authority, add the kms object to ca.json and replace the key property with the AWS KMS key name of your intermediate key:
By default, step-ca uses the credentials stored in ~/.aws/credentials. Use the credentials-file option to override. The region and profile options specify the AWS region and configuration profiles respectively. These options can also be configured using environment variables as described in the AWS SDK for Go session documentation.
In similar manner, to configure SSH certificate signing, replace the SSH keys with the keys from AWS KMS:
step-ca can also accept just the Amazon Key ID or the ARN as key options, but using the format based on the RFC7512 will allow more flexibility for future step releases.
Currently, step does not provide an automatic way to initialize the public key infrastructure (PKI) using AWS KMS, but an experimental tool named step-awskms-init addresses this use case. This tool generates the public certificates root_ca.crt and intermediate_ca.crt for inclusion in ca.json and prints the intermediate key name for use in the key property. In a future release, this tool will be integrated into step.
You can use the YubiKey for X.509 and SSH CAs; however, the step-yubikey-init utility only supports X.509 at this time. For SSH support, you must manually generate and configure SSH CA keys on the YubiKey.
The initialization of the public key infrastructure (PKI) for YubiKeys is not currently integrated into step, but an experimental tool named step-yubikey-init addresses this use case. In a future release, this tool will be integrated into step.
What is the YubiKey PIN?:
Creating PKI ...
✔ Root Key: yubikey:slot-id=9a
✔ Root Certificate: root_ca.crt
✔ Intermediate Key: yubikey:slot-id=9c
✔ Intermediate Certificate: intermediate_ca.crt
Run the step-yubikey-init --help command for more options.
Finally, to enable it in ca.json, point the root and crt options to the generated certificates, replace the key option with the YubiKey URI generated in the previous part, and configure the kms option with the appropriate type and pin.
This feature is not enabled by default. To enable support, you will need to build step-ca yourself, using CGO support. See Building From Source Using CGO.
A Hardware Security Module (HSM) is a specialized piece of hardware that is designed to generate and store private keys, and sign messages using those keys.
The private keys on an HSM cannot be exported from the device.
One can only run signing operations using the key.
This is an excellent way to protect private keys for a Certificate Authority,
which in normal operation simply needs to be able to sign Certificate Signing Requests.
Your HSM or TPM2 may need to be prepared before you can initialize a PKI on it.
Preparation steps depend on the device and are beyond the scope of this documentation.
With YubiHSM2, you will need to create an authentication key with appropriate capabiliites.
With TPM2, you will need to initialize the TPM and create a PKCS#11 token on it.
You'll also want to consider how you will backup and restore your CA keys, for offline storage.
1. Initialize your PKI using the step-pkcs11-init tool.
The step-pkcs11-init tool will create or import CA keys and/or certificates onto your HSM, for use with step-ca.
It is configured to work with the YubiHSM2 by default, but you can provide a different PKCS #11 URI by using the --kms flag.
Here are some examples of PKCS #11 URIs for accessing various devices in Linux:
You'll need to substitute $HSM_USER and $HSM_PASSWORD with your own values.
In this URI,
module-path points to your PKCS #11 .dll, .so, or .dylib library file,
token is the label (CKA_LABEL) of the HSM you're using,
pin-value contains hardcoded HSM credentials. It may be a PIN, username and password, password, or a filename. The YubiHSM2 is special in that the PIN value is the concatenation of the four-digit authorization key ID (eg. 0001) and the PIN.
Or, pin-source is a filename containing HSM credentials.
Once the utility creates your PKI, it will output a few paths for your keys and certificates before exiting.
You'll need these for step 2.
2. Configure the CA to use PKCS #11
One you've created your PKI on the HSM using step-pkcs11-init, you'll need to configure step-ca to use the HSM.