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 it's 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. + usage: a string of key usages. The following are acceptable key usages: + signing + digital signature + content committment + key encipherment + key agreement + data encipherment + cert sign + crl sign + encipher only + decipher only + 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 a 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: { "usage": ["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