CFSSL

The whitelist package provides mechanisms to permit or deny access based on IP addresses. The core interface is the ACL type, which features a Permitted(net.IP) bool method to check if an address is whitelisted.

There are two primary specialized types:

• HostACL: Manages individual IP addresses using Add(net.IP) and Remove(net.IP).
• NetACL: Manages network ranges using Add(*net.IPNet) and Remove(*net.IPNet).

Available implementations:

• Basic: A host-based whitelister using a map[string]bool and sync.Mutex.
• BasicNet: A network-based whitelister. Note that BasicNet requires exact network matches for Add and Remove; it does not detect subsets or supersets (e.g., removing a subnet will not remove a larger network that contains it).
• HostStub and NetStub: Stand-in implementations that always permit access and log warnings.

Providing a database configuration enables advanced certificate management features.

Enhanced Command Behavior:

• sign and gencert: Automatically add a signed certificate to the certdb.
• serve: Enables database-backed functionality for the sign and revoke endpoints.

Required Database Commands:

• revoke: Marks certificates as revoked in the database with an optional reason.
• ocsprefresh: Refreshes the table of cached OCSP responses.
• ocspdump: Outputs cached OCSP responses in a concatenated base64-encoded format.

The maserver is a mutually authenticated server. It requires a server.json configuration file in its directory. You can specify a custom configuration file using the -f flag. Use the -a flag to specify the address and port to listen on.

cd maserver/
go run server.go -a 127.0.0.1:9876

You can install CFSSL by building from source or using prebuilt binaries.

Building from source: Requires Go 1.20+. Note that on some Linux distributions (like RHEL-based ones), you should install Go manually from the official website rather than using the distribution's repository to ensure all necessary algorithms are available.

Using Go install: This command installs all utility programs including cfssl, cfssljson, and mkbundle.

Prebuilt binaries: Available on the GitHub releases page.

# Build from source
git clone git@github.com:cloudflare/cfssl.git
cd cfssl
make
make install

# Or install via go
go install github.com/cloudflare/cfssl/cmd/...@latest

CFSSL uses goose for database migrations. You can use the goose CLI to apply or revert migrations for MySQL, PostgreSQL, or SQLite backends.

Note: This assumes the target databases are already created and access control is configured.

# Install goose
goose -path certdb/mysql up

# MySQL migrations
goose -path certdb/mysql up
goose -path certdb/mysql down

# PostgreSQL migrations
goose -path certdb/pg up
goose -path certdb/pg down

# SQLite migrations
goose -path certdb/sqlite up
goose -path certdb/sqlite down

To build the CFSSL binary from source and run the server command, use the Go toolchain to build the command directory and then execute the resulting binary with the serve argument.

go build ./cmd/cfssl/...
./cfssl serve

The maclient connects to the server and sends messages. It requires a client.json configuration file in its directory. You can specify a custom configuration file using the -f flag.

go run client.go

If you are developing the CFSSL server and need to update the embedded static files, use the esc tool to compile the static directory into a Go file. This allows the server to serve updated static assets without manual re-embedding.

go install github.com/mjibson/esc

# Compile changes to static files 
esc -pkg serve -prefix cli/serve/static cli/serve/static > cli/serve/static.go

Several CFSSL commands accept a -db-config flag. This flag requires a path to a JSON file containing a dictionary that specifies the database driver and the data source connection string.

Supported drivers include sqlite3, postgres, and mysql.