cfssl.txt

THE CFSSL PROGRAM

The CFSSL program is a TLS / PKI tool that provides command line
tools for

      * bundling certificates
      * create private keys, certificate signing requests, and certificates
      * signing certificate signing requests
      * scanning a host to evaluate its TLS security
      * signing OCSP requests
      * running a CA server
      * running an OCSP server

The cfssl server can be used either as a standalone server or as a set
of locally-running instances that talk to a remote CA. For example, a
set of servers might run the cfssl program locally to facilitate
generating certificates for services on the server. These local
servers can be configured to send their certificate signing requests
to a remote cfssl or multirootca server that actually contains the
signing key(s).


CONFIGURATION

The configuration file for cfssl is a JSON dictionary with keys for
signing profiles, OCSP configuration, authentication, and remote
servers.

AUTHENTICATION

See also: authentication.txt

Authentication is used to restrict access to the signing keys when
cfssl is run as a server. A client making a request generates an
authentication token for their request, submitting this token
alongside the request. The authentication section is used to tell
cfssl that authentication is required and how to authenticate.

This section consists of a dictionary of authenticators under the key
"auth_keys"; each authenticator should have the keys "type" and "key",
both strings. For example, to use the standard authenticator with the
(hex-encoded) key "0123456789ABCDEF0123456789ABCDEF" as the "primary"
authenticator, the "auth_keys" section might look like

    "auth_keys": {
        "primary": {
            "type":"standard",
            "key":"0123456789ABCDEF0123456789ABCDEF"
	}
    }

The authentication documentation covers available authenticators and
their key formats.


REMOTE SIGNERS

A local cfssl instance can forward signing requests to another
instance; this might be useful where the CA keys should remain on only
one machine.

A remote is specified as a host:port, or as a comma-separated list of
host:ports. If the remote is a comma-separated list, each server will
be tried in sequence until one succeeds. That is, if the list is

   "ca1.example.org:8888, ca2.example.org:8888, ca3.example.org:8888"

each signing request will first go to ca1, falling back to ca2 if this
fails, and finally falling back to ca3.


SIGNING PROFILES

CFSSL supports different profiles for generating various types of
certificates, as well as a default profile to be used when no profile
is given.

A signing profile may contain the following fields, requiring at a
minimum the expiry field. Fields that are not required may be left
blank.

    + expiry: This should contain a time duration in the form
      understood by Go's time package[1]. This unfortunately means
      that the maximum unit of time that can be used here is the hour.

    + usages: strings of key usages. The following are acceptable key
      usages:

	+ Key Usages
		+ signing
		+ digital signature
		+ content commitment
		+ key encipherment
		+ key agreement
		+ data encipherment
		+ cert sign
		+ crl sign
		+ encipher only
		+ decipher only
		
	+ Ext Key Usages
		+ any
		+ server auth
		+ client auth
		+ code signing
		+ email protection
		+ s/mime
		+ ipsec end system
		+ ipsec tunnel
		+ ipsec user
		+ timestamping
		+ ocsp signing
		+ microsoft sgc
		+ netscape sgc

    + issuer_urls: a list of Authority Information Access (RFC 5280
      4.2.2.1) URLs pointing to the issuer certificate.

    + ocsp_url: the URL of the OCSP server that should be used to
      check the certificate's status.

    + crl_url: the URL of the CRL server for this CA.

    + ca_constraint: this object controls the CA bit and CA pathlen
      constraint of the returned certificates. For example, in order
      to issue a intermediate CA certificate with pathlen = 1, we put
      {"is_ca": true, "max_path_len":1}. For another example, to
      issue an intermediate CA certificate with pathlen = 0, we put
      {"is_ca": true, "max_path_len":0, "max_path_len_zero": true}.
      Notice the extra "max_path_len_zero" field: Without it, the
      intermediate CA certificate will have no pathlen constraint.

    + ocsp_no_check: this should be true if the id-pkix-ocsp-nocheck
      extension should be used (RFC 2560 4.2.2.2.1).

    + backdate: this is a time duration (the same used for the expiry
      field) that specifies an amount of backdating to be applied to
      new certificates.

    + auth_key: this should contain the name of an authentication key
      specified in the authentication portion of the configuration
      file. This key should be used by clients using the authentication
      scheme described in 'authentication.txt'.

    + remote: this should contain the name of a remote signer as
      specified in the remote signer section of the configuration
      file. This is used for unauthenticated CFSSL remotes.

    + auth_remote: this is an object containing an "auth_key" and
      "remote" key. This is an entry for an authenticated remote
      signer. The "auth_key" should contain the name of an
      authentication key specified in the authentication portion of
      the configuration file, and "remote" should contain the name of
      a remote signer as specified in the remote signer section of the
      configuration file.

    + not_before: if provided, this specifies an override for the Not
      Before date in certificates signed by the CA.

    + not_after: if provided, this specifies an override for the Not
      After date in certificates signed by the CA.

    + name_whitelist: if provided, this should be a regular expression
      for permitted SANs.

The signing profiles reside in the "signing" dictionary. This may
contain a "default" field which contains the profile to use by default
for requests, and a "profiles" dictionary mapping profile names to
their profile. If the default profile isn't present, the following
default profile is used:

   {
	"usages": ["signing", "key encipherment", "server auth", "client auth"],
	"expiry": "8760h"
   }

The expiration time of 8760h is equivalent to one year.

A minimal configuration file might look like:

    {
	    "signing": {
		    "profiles": {
			    "CA": {
				    "usages": ["cert sign"],
				    "expiry": "720h",
				    "auth_key": "ca-auth",
				    "remote": "localhost"
			    },
			    "email": {
				    "usages": ["s/mime"],
				    "expiry": "720h"
			    }
		    },
		    "default": {
			    "usages": ["digital signature", "email protection"],
			    "expiry": "8000h"
		    }
	    },
	    "auth_keys": {
		    "ca-auth": {
			    "type":"standard",
			    "key":"0123456789ABCDEF0123456789ABCDEF"
		    }
	    },
	    "remotes": {
		    "localhost": "127.0.0.1:8888"
	    }
    }


[1] https://golang.org/pkg/time/#ParseDuration