1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
|
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
|