No Description

Nicky Semenza d6d030a38b Merge pull request #1368 from cloudflare/dependabot/go_modules/github.com/google/certificate-transparency-go-1.1.8 1 month ago
.github f19cf511ff build(deps): bump golangci/golangci-lint-action from 3 to 4 2 months ago
api 6ea8605b55 Merge pull request #1063 from izolight/sha256-digest 10 months ago
auth 2bc4f21a8c auth: replace uses of deprecated io/ioutil 1 year ago
bundler 50f8789003 Merge pull request #1304 from testwill/master 10 months ago
certdb 8d25f25515 certdb/sql: remove uses of github.com/stretchr/testify/require 8 months ago
certinfo 7c1b3588da certinfo: replace uses of deprecated io/ioutil 1 year ago
cli 123abe0b8f Merge pull request #1187 from jonathanio/improve-ocspserve-ipv6-handling 1 year ago
cmd 9a0778d6d8 Add support for generating ed25519 keys and certs (#1061) 10 months ago
config 5e37590af1 code optimization 10 months ago
crl 31652f3d0c crl: replace uses of deprecated io/ioutil 1 year ago
crypto d90536d543 all: gofmt for go1.18 (fixes missing build-tags) 1 year ago
csr 6619c79a5b Add DER support for gernerating and parsing CSR 9 months ago
doc 6ea8605b55 Merge pull request #1063 from izolight/sha256-digest 10 months ago
errors 9a0778d6d8 Add support for generating ed25519 keys and certs (#1061) 10 months ago
helpers 6619c79a5b Add DER support for gernerating and parsing CSR 9 months ago
info 71299729be Clean up some of the structures around info. 9 years ago
initca 50f8789003 Merge pull request #1304 from testwill/master 10 months ago
log e5661b7acb remove flag definition in init() 8 years ago
multiroot 9d4d8c6779 multiroot: replace uses of deprecated io/ioutil 1 year ago
ocsp 5b8919c197 ocsp: replace uses of deprecated io/ioutil 1 year ago
revoke cfd0e9ab2a Merge pull request #1255 from thaJeztah/update_gomod 1 year ago
scan 9a0778d6d8 Add support for generating ed25519 keys and certs (#1061) 10 months ago
selfsign 5ac7cd977a Add unit test for custom extension supt 2 months ago
signer 8d25f25515 certdb/sql: remove uses of github.com/stretchr/testify/require 8 months ago
testdata c797d34f6a Add field to API docs and testdata. 8 years ago
transport 9a0778d6d8 Add support for generating ed25519 keys and certs (#1061) 10 months ago
ubiquity cfd0e9ab2a Merge pull request #1255 from thaJeztah/update_gomod 1 year ago
vendor a421aee837 build(deps): bump github.com/google/certificate-transparency-go 1 month ago
whitelist c9e5b44932 whitelist: replace uses of deprecated io/ioutil 1 year ago
.dockerignore 055a97a5da build to the dist folder 8 years ago
.gitignore bba3a2015c update release make target to use go 1.18 1 year ago
.golangci.yaml 23c92b07d6 add github Actions to replace travis 1 year ago
.goreleaser.yml b946db1ac1 reenable vcs stamping with docker image that supports it 11 months ago
CHANGELOG 23e784e12c Adding a CHANGELOG. 8 years ago
Dockerfile 7f58e9c9ad Build images on base image for target platform 1 month ago
Dockerfile.alpine 3d2d3b5209 update Dockerfiles to use go 1.16 1 year ago
LICENSE edc6592652 Initial import. 9 years ago
Makefile b946db1ac1 reenable vcs stamping with docker image that supports it 11 months ago
README.md 51a7fa85be Make api intro.txt references links 1 year ago
go.mod a421aee837 build(deps): bump github.com/google/certificate-transparency-go 1 month ago
go.sum a421aee837 build(deps): bump github.com/google/certificate-transparency-go 1 month ago
test.sh 23c92b07d6 add github Actions to replace travis 1 year ago
tools.go 1c31e687d9 remove deprecated golint (golang.org/x/lint) 1 year ago

README.md

CFSSL

Build Status Coverage Status GoDoc

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.16+ 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 the cfssl and multirootca programs and writes certificates, keys, CSRs, and bundles to disk.

Building

Building cfssl requires a working Go 1.16+ installation.

$ git clone git@github.com:cloudflare/cfssl.git
$ cd cfssl
$ make

The resulting binaries will be in the bin folder:

$ tree bin
bin
├── cfssl
├── cfssl-bundle
├── cfssl-certinfo
├── cfssl-newkey
├── cfssl-scan
├── cfssljson
├── mkbundle
└── multirootca

0 directories, 8 files

Cross Compilation

You can set the GOOS and GOARCH environment variables to have Go cross compile for alternative platforms; however, cfssl requires cgo, and cgo requires a working compiler toolchain for the target platform.

Installation

Installation requires a working Go 1.16+ installation. Alternatively, prebuilt binaries are available

$ go get github.com/cloudflare/cfssl/cmd/cfssl

will download, build, and install the CFSSL tool.

To install any of the other utility programs that are in this repo (for instance cfssljson in this case):

$ go get github.com/cloudflare/cfssl/cmd/cfssljson

This will download, build, and install the CFSSLJSON tool.

And to simply install all of the programs in this repo:

$ go get github.com/cloudflare/cfssl/cmd/...

if you are above go 1.18:

$ go install github.com/cloudflare/cfssl/cmd/...@latest

This will download, build, and install all of the utility programs (including cfssl, cfssljson, and mkbundle among others).

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",
        "https://www.example.com",
        "jdoe@example.com",
        "127.0.0.1"
    ],
    "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 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.

Additional Documentation

Additional documentation can be found in the "doc" directory: