Configuring the Step Certificate Authority

When you generate a new Certificate Authority (CA) using step ca init, the configuration file (ca.json) is generated automatically. It contains settings related to communication and authentication, and default new certificate values for the CA.

Below is a short list of definitions and descriptions of available configuration attributes.

  • root: location of the root certificate on the filesystem. The root certificate is used to mutually authenticate all api clients of the CA.

  • 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.

  • key: location of the intermediate private key on the filesystem. The intermediate key signs all new certificates generated by the CA.

  • 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: e.g. 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.

  • db: data persistence layer. See database documentation for more info.

    • type: badger, bbolt, mysql, etc.

    • 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 backends that may have multiple databases. e.g. MySQL

    • 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.

    • template: default ASN1DN values for new certificates.

    • claims: default validation for requested attributes in the certificate request. Can be overriden 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.

      • disableIssuedAtCheck: disable a check verifying that provisioning tokens must be issued after the CA has booted. This 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 public/private keys, and an optional claims attribute that will override any values set in the global claims directly underneath authority.

Please see ca.json for an example configuration.