title	html_title	description
Configuring `step-ca`	Configuring open source step-ca	Learn how to configure step-ca

When the step ca init command sets up your PKI, it creates an initial configuration file for your CA and stores it in $(step path)/config/ca.json.

This document describes how to configure every aspect of step-ca. You'll learn how to configure your CA to:

bind to a non-default address
generate ACME certificates
adjust the default lifetime of certificates
store certificates in memory, on the file system, or in a database
set the root and intermediate PKI chain used to sign new certificates
and much more

Overview

Specify a Configuration File
Environment Variables
Basic Configuration Options
Provisioners
Certificate Issuance Policies
Certificate Templates
Databases
- Badger
- BoltDB
- MySQL
- PostgreSQL
- Schema

Specify a Configuration File

When you run step-ca, you must provide a path to a configuration file (ca.json). It is the only required argument. After you've run step ca init to create a default configuration, use step path to discover the path to ca.json:

$ step-ca $(step path)/config/ca.json

The output of step path varies based on the $STEPPATH environment variable, and whether you use the step command with multiple CAs.

For non-interactive use (eg. as a systemd service), the --password-file flag accepts the name of a file containing the password for the CA's keys.

Environment Variables

STEPDEBUG When set to 1, step-ca provides extra diagnostic information for debugging. This variable can also be used with step.

Basic Configuration Options

Example Configuration

{
  "root": "examples/pki/secrets/root_ca.crt",
  "federatedRoots": ["examples/pki/secrets/federated_root_ca.crt"],
  "crt": "examples/pki/secrets/intermediate_ca.crt",
  "key": "examples/pki/secrets/intermediate_ca_key",
  "address": ":9000",
  "dnsNames": [
    "localhost"
  ],
  "logger": {
    "format": "text"
  },
  "ssh": {
    "hostKey": "/examples/pki/secrets/secrets.host.key",
    "userKey": "/examples/pki/secrets/secrets.user.key"
  },
  "db": {
    "type": "badgerv2",
    "dataSource": "/Users/carl/.step/authorities/config-example/db"
  }, 
  "crl": {
    "enabled": false
  }, 
  "authority": {
    "claims": {
      "minTLSCertDuration": "5m",
      "maxTLSCertDuration": "24h",
      "defaultTLSCertDuration": "24h",
      "disableRenewal": false,
      "allowRenewalAfterExpiry": false,
      "minHostSSHCertDuration": "5m",
      "maxHostSSHCertDuration": "1680h",
      "defaultHostSSHCertDuration": "720h",
      "minUserSSHCertDuration": "5m",
      "maxUserSSHCertDuration": "24h",
      "defaultUserSSHCertDuration": "16h"
    },
    "policy": {
      "x509": {
        "allow": {
          "dns": ["*.local"]
        }
      },
      "ssh": {
        "user": {
          "allow": {
            "email": ["@local"]
          }
        },
        "host": {
          "allow": {
            "dns": ["*.local"]
          }
        }
      }
    },
    "provisioners": [
      {
        "type": "jwk",
        "name": "mike@smallstep.com",
        "key": {
          "use": "sig",
          "kty": "EC",
          "kid": "YYNxZ0rq0WsT2MlqLCWvgme3jszkmt99KjoGEJJwAKs",
          "crv": "P-256",
          "alg": "ES256",
          "x": "LsI8nHBflc-mrCbRqhl8d3hSl5sYuSM1AbXBmRfznyg",
          "y": "F99LoOvi7z-ZkumsgoHIhodP8q9brXe4bhF3szK-c_w"
        },
        "encryptedKey": "eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJjdHkiOiJqd2sranNvbiIsImVuYyI6IkEyNTZHQ00iLCJwMmMiOjEwMDAwMCwicDJzIjoiVERQS2dzcEItTUR4ZDJxTGo0VlpwdyJ9.2_j0cZgTm2eFkZ-hrtr1hBIvLxN0w3TZhbX0Jrrq7vBMaywhgFcGTA.mCasZCbZJ-JT7vjA.bW052WDKSf_ueEXq1dyxLq0n3qXWRO-LXr7OzBLdUKWKSBGQrzqS5KJWqdUCPoMIHTqpwYvm-iD6uFlcxKBYxnsAG_hoq_V3icvvwNQQSd_q7Thxr2_KtPIDJWNuX1t5qXp11hkgb-8d5HO93CmN7xNDG89pzSUepT6RYXOZ483mP5fre9qzkfnrjx3oPROCnf3SnIVUvqk7fwfXuniNsg3NrNqncHYUQNReiq3e9I1R60w0ZQTvIReY7-zfiq7iPgVqmu5I7XGgFK4iBv0L7UOEora65b4hRWeLxg5t7OCfUqrS9yxAk8FdjFb9sEfjopWViPRepB0dYPH8dVI.fb6-7XWqp0j6CR9Li0NI-Q",
        "claims": {
          "minTLSCertDuration": "1m0s",
          "defaultTLSCertDuration": "2m0s"
        },
        "options": {
          "x509": {
            "templateFile": "templates/certs/x509/default.tpl"
          },
          "ssh": {
            "templateFile": "templates/certs/ssh/default.tpl"
          }
        }
      },
      {
        "type": "OIDC",
        "name": "Google",
        "clientID": "1087160488420-8qt7bavg3qesdhs6it824mhnfgcfe8il.apps.googleusercontent.com",
        "clientSecret": "udTrOT3gzrO7W9fDPgZQLfYJ",
        "configurationEndpoint": "https://accounts.google.com/.well-known/openid-configuration",
        "admins": ["you@smallstep.com"],
        "domains": ["smallstep.com"],
        "listenAddress": ":10000",
        "claims": {
          "maxTLSCertDuration": "8h",
          "defaultTLSCertDuration": "2h",
          "enableSSHCA": true,
          "disableRenewal": true
        },
        "options": {
          "x509": {
            "templateFile": "templates/certs/x509/default.tpl"
          },
          "ssh": {
            "templateFile": "templates/certs/ssh/default.tpl"
          }
        }
      },
      {
        "type": "SSHPOP",
        "name": "sshpop-smallstep",
        "claims": {
          "enableSSHCA": true
        }
      },
      {
        "type": "ACME",
        "name": "my-acme-provisioner"
      }
    ]
  },
  "tls": {
    "cipherSuites": [
      "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256",
      "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
    ],
    "minVersion": 1.2,
    "maxVersion": 1.3,
    "renegotiation": false
  },
  "password": "p@55w0rd"
}

Configuration Options

root: location of the root certificate PEM file on the filesystem. The root certificate is used to mutually authenticate all API clients of the CA. This can be a string containing one root PEM file, or an array containing multiple root CA files (useful for root rotation).
federatedRoots: location of the federated root certificates on the filesystem. The federated roots are used to authenticate client and servers using TLS certificates from multiple CAs.
crt: location of the intermediate certificate on the filesystem. The intermediate certificate is returned alongside each new certificate, allowing the client to complete the certificate chain. Multiple intermediates are allowed here. When multiple intermediates are supplied, the first certificate in the PEM bundle must be the one used for signing.
key: location of the intermediate private key on the filesystem. The intermediate key signs all new certificates generated by the CA.
kms: enables and configures cryptographic protection using cloud key management services or hardware security modules. See Cryptographic Protection.
- type: required. one of azurekms, awskms, cloudkms, pkcs11, or yubikey
- uri: this field can be used to specify other fields in this section, and its value takes 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
address: ex. 127.0.0.1:8080 - address and port on which the CA 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.
db: data persistence layer. See databases, below.
crl: Certificate Revocation List (CRL) settings. (experimental)
- enabled: enables CRL generation (true to generate, false to disable). Default is false.
- generateOnRevoke: a revoke will generate a new CRL if the crl is enabled. Default is false.
- cacheDuration: the duration until next update of the CRL. Defaults to 24h.
- renewPeriod: the time between CRL regeneration. Defaults to ~2/3 of the cacheDuration.
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. See Templates.
- 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 certificate Provisioners. Each provisioner has a name, associated authentication attributes, and an optional claims attribute that overrides any values set in the global claims directly underneath authority. The step ca provisioner command group can add, modify, and remove provisioners. See Provisioners.
  - claims: Each provisioner can override the authority-wide claims settings. See the authority's claims section above for a complete list of options.
  - options: This optional attribute allows an operator to set templates applied to all X.509 or SSH certificates generated using the provisioner. See Templates.
- password: ☠️ plain text password for starting the CA. Used to decrypt the intermediate CA private key.
  
  In production, do not store a plain text password in your ca.json. Use the --password-file flag when running step-ca. This attribute is a convenience that should be avoided in production.

Provisioners

Provisioners offer many ways to issue certificates to endpoints and people. By default, step ca init creates a JWK provisioner, for administrative use.

step-ca supports ACME, SCEP, X.509, OpenID, and several other provisioner types.

See Provisioners to learn more.

Policy

Policies can be used to enforce which Subjects, SANs and Principals the CA is allowed to issue a certificate for. They can be configured for X.509 certificates, SSH user, and SSH host certificates. Policies are evaluated before a certificate is signed. Some examples of policies 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, path, query and fragment parts.

See Policies to learn more.

Need more control?

A self-hosted step-ca instance can be configured with a policy on the authority level only. In a free hosted smallstep Certificate Manager authority, policies can be configured on the authority, on each provisioner, and on every ACME account.

Templates

Using X.509 and SSH certificate templates administrators can configure information that gets processed and added to certificates. These include things like:

Custom SANs or extensions for X.509 certificates
Create longer certificate chains, including multiple intermediate CAs
Embed SSH force-command or source-address extensions
Evaluate basic logic operations on certificate's parameters, and fail if requirements are not met

See Templates to learn more.

Databases

To store state, step-ca uses a simple NoSQL key-value interface over popular database systems.

The database stores things like:

Issued certificates and certificate metadata, to facilitate passive revocation
ACME accounts
Used one-time-use tokens

The database for step-ca is configured in a top-level db stanza in your ca.json.

Badger
BoltDB
MySQL
PostgreSQL

Because Badger and BoltDB are embedded, only MySQL and PostgreSQL are appropriate for load balanced, high availability deployments of step-ca.

Badger

Badger is a key-value database embedded in step-ca.

{
  ...
  "db": {
    "type": "badger",
    "dataSource": "./.step/db",
    "valueDir": "./.step/valuedb",
    "badgerFileLoadingMode": "MemoryMap"
  },
  ...
},

Options

type
- badger: currently refers to Badger V1. This is subject to change.
- badgerV1: explicitly select Badger V1.
- badgerV2: explicitly select Badger V2.
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.
- MemoryMap: default.
- FileIO: This can be useful in environments with low RAM.

BoltDB

Bolt (etcd fork) is a key-value database embedded in step-ca.

{
  ...
  "db": {
    "type": "bbolt",
    "dataSource": "./stepdb"
  },
  ...
}

Options

type: bbolt
dataSource: path, database directory.

MySQL

step-ca uses MySQL as a simple key-value store, not as a relational database.

{
  ...
  "db": {
    "type": "mysql",
    "dataSource": "user:password@tcp(127.0.0.1:3306)/",
    "database": "myDBName"
  },
  ...
},

Options

type: mysql
dataSource: path, database directory.

Extra parameters can be passed in the mysql dataSource name as follows: "dataSource": "user:password@tcp(127.0.0.1:3306)/myDBName?tls=true".

PostgreSQL

step-ca uses PostgreSQL as a simple key-value store, not as a relational database.

{
  ...
  "db": {
    "type": "postgresql",
    "dataSource": "postgresql://user:password@127.0.0.1:5432/",
    "database": "myDBName"
  },
  ...
},

Options

type: postgresql
dataSource: a PostgreSQL DSN.
database: database name. Takes precedence over name in the DSN if provided.

Alternatively, you can use environment variables to configure the PostgreSQL connection. Instead of supplying dataSource and database options, use the standard libpq environment variables when starting step-ca.

Use TLS with PostgreSQL

The PostgreSQL DSN can be used to configure TLS settings for connecting to the server. An example database configuration that enables TLS server hostname verification is shown below:

{
  ...
  "db": {
    "type": "postgresql",
    "dataSource": "postgresql://user:password@127.0.0.1:5432/dbname?sslmode=verify-full"
  },
  ...
},

The database driver looks in $HOME/.postgresql/root.crt for a PEM bundle of root CAs to trust. When that file is not found, it uses the system's default trust store. Similarly, $HOME/.postgresql/postgresql.crt and the corresponding $HOME/.postgresql/postgresql.key is used for mutual TLS authentication if these files exist, and if the PostgreSQL server requests a client certificate. You can override the locations for these files by providing them in the DSN:

{
  ...
  "db": {
    "type": "postgresql",
    "dataSource": "postgresql://user:password@127.0.0.1:5432/dbname?sslmode=verify-full&sslrootcert=/path/to/roots.pem&sslcert=/path/to/client.pem&sslkey=/path/to/client.key"
  },
  ...
},

The behavior of the PostgreSQL database driver mimics that of libpq and also encompasses handling of other default settings and environment variables.

The libpq docs cover TLS options and the DSN query parameters for libpq in more detail.

Schema

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.

Exporting Data

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

configuration.mdx

configuration.mdx

Overview

Specify a Configuration File

Environment Variables

Basic Configuration Options

Example Configuration

Configuration Options

Provisioners

Policy

Templates

Databases

Badger

BoltDB

MySQL

PostgreSQL

Options

Use TLS with PostgreSQL

Schema

Exporting Data

Files

configuration.mdx

Latest commit

History

configuration.mdx

File metadata and controls

Overview

Specify a Configuration File

Environment Variables

Basic Configuration Options

Example Configuration

Configuration Options

Provisioners

Policy

Templates

Databases

Badger

BoltDB

MySQL

PostgreSQL

Options

Use TLS with PostgreSQL

Schema

Exporting Data