README ¶
CFSSL
CloudFlare's PKI/TLS toolkit
CFSSL is CloudFlare's PKI/TLS swiss army knife. It is both a command line tool and an HTTP API server for signing, verifying, and bundling TLS certificates. It requires Go 1.8+ to build.
Note that certain linux distributions have certain algorithms removed (RHEL-based distributions in particular), so the golang from the official repositories will not work. Users of these distributions should install go manually to install CFSSL.
CFSSL consists of:
- a set of packages useful for building custom TLS PKI tools
- the
cfssl
program, which is the canonical command line utility using the CFSSL packages. - the
multirootca
program, which is a certificate authority server that can use multiple signing keys. - the
mkbundle
program is used to build certificate pool bundles. - the
cfssljson
program, which takes the JSON output from thecfssl
andmultirootca
programs and writes certificates, keys, CSRs, and bundles to disk.
Building
See BUILDING
Installation
Installation requires a
working Go 1.8+ installation and a
properly set GOPATH
.
$ go get -u github.com/cloudflare/cfssl/cmd/cfssl
will download and build the CFSSL tool, installing it in
$GOPATH/bin/cfssl
.
To install any of the other utility programs that are
in this repo (for instance cffsljson
in this case):
$ go get -u github.com/cloudflare/cfssl/cmd/cfssljson
This will download and build the CFSSLJSON tool, installing it in
$GOPATH/bin/
.
And to simply install all of the programs in this repo:
$ go get -u github.com/cloudflare/cfssl/cmd/...
This will download, build, and install all of the utility programs
(including cfssl
, cfssljson
, and mkbundle
among others) into the
$GOPATH/bin/
directory.
Using the Command Line Tool
The cfssl
command line tool takes a command to specify what
operation it should carry out:
sign signs a certificate
bundle build a certificate bundle
genkey generate a private key and a certificate request
gencert generate a private key and a certificate
serve start the API server
version prints out the current version
selfsign generates a self-signed certificate
print-defaults print default configurations
Use cfssl [command] -help
to find out more about a command.
The version
command takes no arguments.
Signing
cfssl sign [-ca cert] [-ca-key key] [-hostname comma,separated,hostnames] csr [subject]
The csr
is the client's certificate request. The -ca
and -ca-key
flags are the CA's certificate and private key, respectively. By
default, they are ca.pem
and ca_key.pem
. The -hostname
is
a comma separated hostname list that overrides the DNS names and
IP address in the certificate SAN extension.
For example, assuming the CA's private key is in
/etc/ssl/private/cfssl_key.pem
and the CA's certificate is in
/etc/ssl/certs/cfssl.pem
, to sign the cloudflare.pem
certificate
for cloudflare.com:
cfssl sign -ca /etc/ssl/certs/cfssl.pem \
-ca-key /etc/ssl/private/cfssl_key.pem \
-hostname cloudflare.com \
./cloudflare.pem
It is also possible to specify CSR with the -csr
flag. By doing so,
flag values take precedence and will overwrite the argument.
The subject is an optional file that contains subject information that should be used in place of the information from the CSR. It should be a JSON file as follows:
{
"CN": "example.com",
"names": [
{
"C": "US",
"L": "San Francisco",
"O": "Internet Widgets, Inc.",
"OU": "WWW",
"ST": "California"
}
]
}
N.B. As of Go 1.7, self-signed certificates will not include the AKI.
Bundling
cfssl bundle [-ca-bundle bundle] [-int-bundle bundle] \
[-metadata metadata_file] [-flavor bundle_flavor] \
-cert certificate_file [-key key_file]
The bundles are used for the root and intermediate certificate
pools. In addition, platform metadata is specified through -metadata
.
The bundle files, metadata file (and auxiliary files) can be
found at:
https://github.com/cloudflare/cfssl_trust
Specify PEM-encoded client certificate and key through -cert
and
-key
respectively. If key is specified, the bundle will be built
and verified with the key. Otherwise the bundle will be built
without a private key. Instead of file path, use -
for reading
certificate PEM from stdin. It is also acceptable that the certificate
file should contain a (partial) certificate bundle.
Specify bundling flavor through -flavor
. There are three flavors:
optimal
to generate a bundle of shortest chain and most advanced
cryptographic algorithms, ubiquitous
to generate a bundle of most
widely acceptance across different browsers and OS platforms, and
force
to find an acceptable bundle which is identical to the
content of the input certificate file.
Alternatively, the client certificate can be pulled directly from
a domain. It is also possible to connect to the remote address
through -ip
.
cfssl bundle [-ca-bundle bundle] [-int-bundle bundle] \
[-metadata metadata_file] [-flavor bundle_flavor] \
-domain domain_name [-ip ip_address]
The bundle output form should follow the example:
{
"bundle": "CERT_BUNDLE_IN_PEM",
"crt": "LEAF_CERT_IN_PEM",
"crl_support": true,
"expires": "2015-12-31T23:59:59Z",
"hostnames": ["example.com"],
"issuer": "ISSUER CERT SUBJECT",
"key": "KEY_IN_PEM",
"key_size": 2048,
"key_type": "2048-bit RSA",
"ocsp": ["http://ocsp.example-ca.com"],
"ocsp_support": true,
"root": "ROOT_CA_CERT_IN_PEM",
"signature": "SHA1WithRSA",
"subject": "LEAF CERT SUBJECT",
"status": {
"rebundled": false,
"expiring_SKIs": [],
"untrusted_root_stores": [],
"messages": [],
"code": 0
}
}
Generating certificate signing request and private key
cfssl genkey csr.json
To generate a private key and corresponding certificate request, specify the key request as a JSON file. This file should follow the form:
{
"hosts": [
"example.com",
"www.example.com"
],
"key": {
"algo": "rsa",
"size": 2048
},
"names": [
{
"C": "US",
"L": "San Francisco",
"O": "Internet Widgets, Inc.",
"OU": "WWW",
"ST": "California"
}
]
}
Generating self-signed root CA certificate and private key
cfssl genkey -initca csr.json | cfssljson -bare ca
To generate a self-signed root CA certificate, specify the key request as a JSON file in the same format as in 'genkey'. Three PEM-encoded entities will appear in the output: the private key, the csr, and the self-signed certificate.
Generating a remote-issued certificate and private key.
cfssl gencert -remote=remote_server [-hostname=comma,separated,hostnames] csr.json
This calls genkey
but has a remote CFSSL server sign and issue
the certificate. You may use -hostname
to override certificate SANs.
Generating a local-issued certificate and private key.
cfssl gencert -ca cert -ca-key key [-hostname=comma,separated,hostnames] csr.json
This generates and issues a certificate and private key from a local CA
via a JSON request. You may use -hostname
to override certificate SANs.
Updating an OCSP responses file with a newly issued certificate
cfssl ocspsign -ca cert -responder key -responder-key key -cert cert \
| cfssljson -bare -stdout >> responses
This will generate an OCSP response for the cert
and add it to the
responses
file. You can then pass responses
to ocspserve
to start an
OCSP server.
Starting the API Server
CFSSL comes with an HTTP-based API server; the endpoints are
documented in doc/api/intro.txt
. The server is started with the serve
command:
cfssl serve [-address address] [-ca cert] [-ca-bundle bundle] \
[-ca-key key] [-int-bundle bundle] [-int-dir dir] [-port port] \
[-metadata file] [-remote remote_host] [-config config] \
[-responder cert] [-responder-key key] [-db-config db-config]
Address and port default to "127.0.0.1:8888". The -ca
and -ca-key
arguments should be the PEM-encoded certificate and private key to use
for signing; by default, they are ca.pem
and ca_key.pem
. The
-ca-bundle
and -int-bundle
should be the certificate bundles used
for the root and intermediate certificate pools, respectively. These
default to ca-bundle.crt
and int-bundle.crt
respectively. If the
-remote
option is specified, all signature operations will be forwarded
to the remote CFSSL.
-int-dir
specifies an intermediates directory. -metadata
is a file for
root certificate presence. The content of the file is a json dictionary
(k,v) such that each key k is an SHA-1 digest of a root certificate while value v
is a list of key store filenames. -config
specifies a path to a configuration
file. -responder
and -responder-key
are the certificate and the
private key for the OCSP responder, respectively.
The amount of logging can be controlled with the -loglevel
option. This
comes after the serve command:
cfssl serve -loglevel 2
The levels are:
- 0 - DEBUG
- 1 - INFO (this is the default level)
- 2 - WARNING
- 3 - ERROR
- 4 - CRITICAL
The multirootca
The cfssl
program can act as an online certificate authority, but it
only uses a single key. If multiple signing keys are needed, the
multirootca
program can be used. It only provides the sign
,
authsign
and info
endpoints. The documentation contains instructions
for configuring and running the CA.
The mkbundle Utility
mkbundle
is used to build the root and intermediate bundles used in
verifying certificates. It can be installed with
go get -u github.com/cloudflare/cfssl/cmd/mkbundle
It takes a collection of certificates, checks for CRL revocation (OCSP
support is planned for the next release) and expired certificates, and
bundles them into one file. It takes directories of certificates and
certificate files (which may contain multiple certificates). For example,
if the directory intermediates
contains a number of intermediate
certificates:
mkbundle -f int-bundle.crt intermediates
will check those certificates and combine valid certificates into a single
int-bundle.crt
file.
The -f
flag specifies an output name; -loglevel
specifies the verbosity
of the logging (using the same loglevels as above), and -nw
controls the
number of revocation-checking workers.
The cfssljson Utility
Most of the output from cfssl
is in JSON. The cfssljson
utility can take
this output and split it out into separate key
, certificate
, CSR
, and
bundle
files as appropriate. The tool takes a single flag, -f
, that
specifies the input file, and an argument that specifies the base name for
the files produced. If the input filename is -
(which is the default),
cfssljson reads from standard input. It maps keys in the JSON file to
filenames in the following way:
- if cert or certificate is specified, basename.pem will be produced.
- if key or private_key is specified, basename-key.pem will be produced.
- if csr or certificate_request is specified, basename.csr will be produced.
- if bundle is specified, basename-bundle.pem will be produced.
- if ocspResponse is specified, basename-response.der will be produced.
Instead of saving to a file, you can pass -stdout
to output the encoded
contents to standard output.
Static Builds
By default, the web assets are accessed from disk, based on their
relative locations. If you wish to distribute a single,
statically-linked, cfssl
binary, you’ll want to embed these resources
before building. This can by done with the
go.rice tool.
pushd cli/serve && rice embed-go && popd
Then building with go build
will use the embedded resources.
Using a PKCS#11 hardware token / HSM
For better security, you may wish to store your private key in an HSM or smartcard. The interface to both of these categories of device is described by the PKCS#11 spec. If you need to do approximately one signing operation per second or fewer, the Yubikey NEO and NEO-n are inexpensive smartcard options:
https://www.yubico.com/products/yubikey-hardware/yubikey-neo/
In general you should look for a product that supports PIV (personal identity verification). If your signing needs are in the hundreds of signatures per second, you will need to purchase an expensive HSM (in the thousands to many thousands of USD).
If you wish to try out the PKCS#11 signing modes without a hardware token, you can use the SoftHSM implementation. Please note that using SoftHSM simply stores your private key in a file on disk and does not increase security.
To get started with your PKCS#11 token you will need to initialize it with a
private key, PIN, and token label. The instructions to do this will be specific
to each hardware device, and you should follow the instructions provided by your
vendor. You will also need to find the path to your module
, a shared object
file (.so). Having initialized your device, you can query it to check your token
label with:
pkcs11-tool --module <module path> --list-token-slots
You'll also want to check the label of the private key you imported (or
generated). Run the following command and look for a Private Key Object
:
pkcs11-tool --module <module path> --pin <pin> \
--list-token-slots --login --list-objects
You now have all the information you need to use your PKCS#11 token with CFSSL.
CFSSL supports PKCS#11 for certificate signing and OCSP signing. To create a
Signer (for certificate signing), import signer/universal
and call NewSigner
with a Root object containing the module, pin, token label and private label
from above, plus a path to your certificate. The structure of the Root object is
documented in universal.go
.
Alternately, you can construct a pkcs11key.Key or pkcs11key.Pool yourself, and pass it to ocsp.NewSigner (for OCSP) or local.NewSigner (for certificate signing). This will be necessary, for example, if you are using a single-session token like the Yubikey and need both OCSP signing and certificate signing at the same time.
Additional Documentation
Additional documentation can be found in the "doc" directory:
api/intro.txt
: documents the API endpointsbootstrap.txt
: a walkthrough from building the package to getting up and running
Directories ¶
Path | Synopsis |
---|---|
Package api implements an HTTP-based API and server for CFSSL.
|
Package api implements an HTTP-based API and server for CFSSL. |
bundle
Package bundle implements the HTTP handler for the bundle command.
|
Package bundle implements the HTTP handler for the bundle command. |
certinfo
Package certinfo implements the HTTP handler for the certinfo command.
|
Package certinfo implements the HTTP handler for the certinfo command. |
client
Package client implements a Go client for CFSSL API commands.
|
Package client implements a Go client for CFSSL API commands. |
crl
Package crl implements the HTTP handler for the crl command.
|
Package crl implements the HTTP handler for the crl command. |
gencrl
Package gencrl implements the HTTP handler for the gencrl commands.
|
Package gencrl implements the HTTP handler for the gencrl commands. |
generator
Package generator implements the HTTP handlers for certificate generation.
|
Package generator implements the HTTP handlers for certificate generation. |
info
Package info implements the HTTP handler for the info command.
|
Package info implements the HTTP handler for the info command. |
initca
Package initca implements the HTTP handler for the CA initialization command
|
Package initca implements the HTTP handler for the CA initialization command |
ocsp
Package ocsp implements the HTTP handler for the ocsp commands.
|
Package ocsp implements the HTTP handler for the ocsp commands. |
revoke
Package revoke implements the HTTP handler for the revoke command
|
Package revoke implements the HTTP handler for the revoke command |
sign
Package sign implements the HTTP handler for the certificate signing command.
|
Package sign implements the HTTP handler for the certificate signing command. |
signhandler
Package signhandler provides the handlers for signers.
|
Package signhandler provides the handlers for signers. |
Package auth implements an interface for providing CFSSL authentication.
|
Package auth implements an interface for providing CFSSL authentication. |
Package bundler implements certificate bundling functionality for CFSSL.
|
Package bundler implements certificate bundling functionality for CFSSL. |
ocspstapling
Package ocspstapling implements OCSP stapling of Signed Certificate Timestamps (SCTs) into OCSP responses in a database.
|
Package ocspstapling implements OCSP stapling of Signed Certificate Timestamps (SCTs) into OCSP responses in a database. |
Package cli provides the template for adding new cfssl commands
|
Package cli provides the template for adding new cfssl commands |
bundle
Package bundle implements the bundle command.
|
Package bundle implements the bundle command. |
certinfo
Package certinfo implements the certinfo command
|
Package certinfo implements the certinfo command |
crl
Package crl implements the crl command
|
Package crl implements the crl command |
gencert
Package gencert implements the gencert command.
|
Package gencert implements the gencert command. |
gencrl
Package gencrl implements the gencrl command
|
Package gencrl implements the gencrl command |
gencsr
Package gencsr implements the gencsr command.
|
Package gencsr implements the gencsr command. |
genkey
Package genkey implements the genkey command.
|
Package genkey implements the genkey command. |
info
Package info implements the info command.
|
Package info implements the info command. |
ocspdump
Package ocspdump implements the ocspdump command.
|
Package ocspdump implements the ocspdump command. |
ocsprefresh
Package ocsprefresh implements the ocsprefresh command.
|
Package ocsprefresh implements the ocsprefresh command. |
ocspserve
Package ocspserve implements the ocspserve function.
|
Package ocspserve implements the ocspserve function. |
ocspsign
Package ocspsign implements the ocspsign command.
|
Package ocspsign implements the ocspsign command. |
revoke
Package revoke implements the revoke command.
|
Package revoke implements the revoke command. |
selfsign
Package selfsign implements the selfsign command.
|
Package selfsign implements the selfsign command. |
serve
Package serve implements the serve command for CFSSL's API.
|
Package serve implements the serve command for CFSSL's API. |
sign
Package sign implements the sign command.
|
Package sign implements the sign command. |
version
Package version implements the version command.
|
Package version implements the version command. |
cmd
|
|
cfssl
cfssl is the command line tool to issue/sign/bundle client certificate.
|
cfssl is the command line tool to issue/sign/bundle client certificate. |
cfssljson
cfssljson splits out JSON with cert, csr, and key fields to separate files.
|
cfssljson splits out JSON with cert, csr, and key fields to separate files. |
mkbundle
mkbundle is a commandline tool for building certificate pool bundles.
|
mkbundle is a commandline tool for building certificate pool bundles. |
Package config contains the configuration logic for CFSSL.
|
Package config contains the configuration logic for CFSSL. |
Package crl exposes Certificate Revocation List generation functionality
|
Package crl exposes Certificate Revocation List generation functionality |
Package crypto contains implementations of crypto.Signer.
|
Package crypto contains implementations of crypto.Signer. |
pkcs7
Package pkcs7 implements the subset of the CMS PKCS #7 datatype that is typically used to package certificates and CRLs.
|
Package pkcs7 implements the subset of the CMS PKCS #7 datatype that is typically used to package certificates and CRLs. |
Package csr implements certificate requests for CFSSL.
|
Package csr implements certificate requests for CFSSL. |
Package errors provides error types returned in CF SSL.
|
Package errors provides error types returned in CF SSL. |
Package helpers implements utility functionality common to many CFSSL packages.
|
Package helpers implements utility functionality common to many CFSSL packages. |
derhelpers
Package derhelpers implements common functionality on DER encoded data
|
Package derhelpers implements common functionality on DER encoded data |
Package info contains the definitions for the info endpoint
|
Package info contains the definitions for the info endpoint |
Package initca contains code to initialise a certificate authority, generating a new root key and certificate.
|
Package initca contains code to initialise a certificate authority, generating a new root key and certificate. |
Package log implements a wrapper around the Go standard library's logging package.
|
Package log implements a wrapper around the Go standard library's logging package. |
multiroot
|
|
config
Package config contains the multi-root configuration file parser.
|
Package config contains the multi-root configuration file parser. |
Package ocsp exposes OCSP signing functionality, much like the signer package does for certificate signing.
|
Package ocsp exposes OCSP signing functionality, much like the signer package does for certificate signing. |
config
Package config in the ocsp directory provides configuration data for an OCSP signer.
|
Package config in the ocsp directory provides configuration data for an OCSP signer. |
Package revoke provides functionality for checking the validity of a cert.
|
Package revoke provides functionality for checking the validity of a cert. |
Package selfsign implements certificate selfsigning.
|
Package selfsign implements certificate selfsigning. |
Package signer implements certificate signature functionality for CFSSL.
|
Package signer implements certificate signature functionality for CFSSL. |
local
Package local implements certificate signature functionality for CFSSL.
|
Package local implements certificate signature functionality for CFSSL. |
universal
Package universal implements a signer that can do remote or local
|
Package universal implements a signer that can do remote or local |
Package transport implements functions for facilitating proper TLS-secured communications for clients and servers.
|
Package transport implements functions for facilitating proper TLS-secured communications for clients and servers. |
ca
Package ca provides the CertificateAuthority interface for the transport package, which provides an interface to get a CSR signed by some certificate authority.
|
Package ca provides the CertificateAuthority interface for the transport package, which provides an interface to get a CSR signed by some certificate authority. |
ca/localca
Package localca implements a localca that is useful for testing the transport package.
|
Package localca implements a localca that is useful for testing the transport package. |
core
Package core contains core definitions for the transport package, the most salient of which is likely the Identity type.
|
Package core contains core definitions for the transport package, the most salient of which is likely the Identity type. |
example/exlib
Package exlib contains common library code for the examples.
|
Package exlib contains common library code for the examples. |
kp
Package kp describes transport key providers and provides a reference implementation.
|
Package kp describes transport key providers and provides a reference implementation. |
roots
Package roots includes support for loading trusted roots from various sources.
|
Package roots includes support for loading trusted roots from various sources. |
Package ubiquity contains the ubiquity scoring logic for CFSSL bundling.
|
Package ubiquity contains the ubiquity scoring logic for CFSSL bundling. |
Package whitelist implements IP whitelisting for various types of connections.
|
Package whitelist implements IP whitelisting for various types of connections. |