CFSSL Commands

CloudFlare's PKI toolkit for building and managing certificate authorities with JSON-based configuration.

Certificate Signing

Sign CSR with CA

Sign a certificate signing request:

cfssl sign -ca ca.pem -ca-key ca-key.pem \
  -config config.json \
  request.csr | cfssljson -bare signed

Sign with profile

Use specific signing profile from config:

cfssl sign -ca ca.pem -ca-key ca-key.pem \
  -config config.json \
  -profile server \
  request.csr | cfssljson -bare server-cert

Generate and sign in one step

Create certificate from JSON spec:

cfssl gencert -ca ca.pem -ca-key ca-key.pem \
  -config config.json \
  -profile server \
  server-csr.json | cfssljson -bare server

Certificate Authority Setup

Initialize new CA

Create root CA certificate and key:

cfssl gencert -initca ca-csr.json | cfssljson -bare ca

CA CSR JSON example

Sample CA certificate request JSON:

{
  "CN": "Internal CA",
  "key": {
    "algo": "ecdsa",
    "size": 384
  },
  "names": [
    {
      "C": "US",
      "ST": "California",
      "L": "San Francisco",
      "O": "Example Inc",
      "OU": "Security"
    }
  ],
  "ca": {
    "expiry": "87600h"
  }
}

Create intermediate CA

Generate intermediate CA signed by root:

cfssl gencert -ca root-ca.pem -ca-key root-ca-key.pem \
  -config config.json \
  -profile intermediate \
  intermediate-ca-csr.json | cfssljson -bare intermediate-ca

Certificate Generation

Server certificate JSON

Example server certificate request:

{
  "CN": "server.example.com",
  "hosts": [
    "server.example.com",
    "www.example.com",
    "192.168.1.100"
  ],
  "key": {
    "algo": "ecdsa",
    "size": 256
  },
  "names": [
    {
      "C": "US",
      "ST": "California",
      "L": "San Francisco",
      "O": "Example Inc"
    }
  ]
}

Client certificate

Generate client authentication certificate:

cfssl gencert -ca ca.pem -ca-key ca-key.pem \
  -config config.json \
  -profile client \
  client-csr.json | cfssljson -bare client

Wildcard certificate

Create certificate with wildcard domain:

{
  "CN": "*.example.com",
  "hosts": [
    "*.example.com",
    "example.com"
  ],
  "key": {
    "algo": "rsa",
    "size": 2048
  }
}

Signing Configuration

Example config.json

Comprehensive signing configuration:

{
  "signing": {
    "default": {
      "expiry": "8760h"
    },
    "profiles": {
      "server": {
        "usages": [
          "signing",
          "key encipherment",
          "server auth"
        ],
        "expiry": "8760h"
      },
      "client": {
        "usages": [
          "signing",
          "key encipherment",
          "client auth"
        ],
        "expiry": "8760h"
      },
      "intermediate": {
        "usages": [
          "cert sign",
          "crl sign"
        ],
        "expiry": "43800h",
        "ca_constraint": {
          "is_ca": true,
          "max_path_len": 0
        }
      }
    }
  }
}

Custom key usages

Available key usage values:

# Key Usages:
- signing
- digital signature
- key encipherment
- data encipherment
- key agreement
- cert sign
- crl sign

# Extended Key Usages:
- server auth
- client auth
- code signing
- email protection
- timestamping
- ocsp signing

Certificate Operations

Bundle certificate chain

Create full certificate chain bundle:

cfssl bundle -cert server.pem \
  -ca-bundle ca-bundle.pem | cfssljson -bare bundled

Get certificate info

Display certificate details in JSON:

cfssl certinfo -cert server.pem

Scan remote certificate

Analyze TLS configuration of remote server:

cfssl scan example.com:443

Scan with specific checks

Run targeted security scans:

# Check certificate validity
cfssl scan -family cert example.com:443

# Check cipher suites
cfssl scan -family cipher example.com:443

# Check for vulnerabilities
cfssl scan -family broad example.com:443

OCSP Operations

Run OCSP responder

Start OCSP responder service:

cfssl ocspserve -port 8080 \
  -ca ca.pem \
  -responder-cert ocsp-responder.pem \
  -responder-key ocsp-responder-key.pem \
  -db-config db-config.json

Dump OCSP responses

Generate OCSP response file:

cfssl ocspdump \
  -db-config db-config.json \
  -ca ca.pem \
  -responder-cert ocsp-responder.pem \
  -responder-key ocsp-responder-key.pem

CFSSL API Server

Start API server

Run cfssl as signing service:

cfssl serve -address 0.0.0.0 -port 8888 \
  -ca ca.pem \
  -ca-key ca-key.pem \
  -config config.json

Request certificate via API

Use API endpoint to sign certificate:

curl -X POST http://localhost:8888/api/v1/cfssl/sign \
  -d '{"certificate_request": "'"$(cat request.csr)"'"}' | \
  cfssljson -bare signed

Health check endpoint

Check API server health:

curl http://localhost:8888/api/v1/cfssl/health

Info endpoint

Get CA certificate and available profiles:

curl http://localhost:8888/api/v1/cfssl/info

Multi-Root CA Support

Configure multiple CAs

Manage multiple certificate authorities:

# multiroot-config.json
{
  "internal": {
    "private": "internal-ca-key.pem",
    "certificate": "internal-ca.pem",
    "config": "internal-config.json"
  },
  "external": {
    "private": "external-ca-key.pem",
    "certificate": "external-ca.pem",
    "config": "external-config.json"
  }
}

Start multirootca server

Run server with multiple CA support:

multirootca -roots multiroot-config.json \
  -address 0.0.0.0 \
  -port 8888

Sign with specific CA

Request signature from specific CA:

curl -X POST http://localhost:8888/api/v1/cfssl/sign \
  -d '{
    "certificate_request": "'"$(cat request.csr)"'",
    "label": "internal"
  }' | cfssljson -bare signed

Important Notes

Installation:

Install via: go install github.com/cloudflare/cfssl/cmd/...@latest or download binaries from GitHub releases.

JSON-Centric:

CFSSL uses JSON for all inputs and outputs. Use cfssljson to extract PEM files from JSON responses.

Database Backend:

For production CA deployments, configure PostgreSQL or MySQL backend for certificate tracking and OCSP.

API First:

CFSSL is designed as an API-first CA. The CLI wraps API calls - consider running cfssl serve for production use.

Security:

Protect CA private keys with file permissions (600). Consider hardware security modules (HSM) for production CAs.

Profiles:

Use signing profiles to enforce consistent certificate policies - separate profiles for servers, clients, code signing, etc.

CloudFlare Origin:

Originally built for CloudFlare's internal PKI. Battle-tested at massive scale.

Documentation:

Official docs: github.com/cloudflare/cfssl - includes API specification and configuration examples.