Integration of CFSSL with the Lemur Certificate Manager

Author: Ahmad

In the previous article on Lemur certificate manager, we have not used any third party root Certification Authority (CA) for the client certificates. Therefore, in this tutorial, PKI will be set up using CFSSL (Cloudflare's SSL) and integrated with the Lemur project. Currently, there is no document which helps the user to integrate CFSSL with the Lemur setup.

Note: As we are using CFSSL as a 3rd party root authority, so first we have to setup it on a separate machine ( however we set up it on the same Lemur box) and after that change the lemur conf file to use CFSSL for the signing the certificate.

Installing CFSSL

The CloudFlare SSL is implemented using "Go" programming language so installation of "go" package is required on the machine. The following command will install the required package on the machine.

1. Install Go

The Go package will be installed from source code.

wget https://dl.google.com/go/go1.10.1.linux-amd64.tar.gz

Extract the downloaded archive and install it to the desired location on the system. We are installing it under /usr/local directory. You can also put this under the desired location on the system.

tar -xzvf go1.10.1.linux-amd64.tar.gz

mv go /usr/local

After the installation of the Go package, it is also required to set an environment variable for the Go binary. (You can add it in the user profile so make it permanent setting). Commonly you need to set 3 environment variables as GOROOT, GOPATH and PATH.

GOROOT is the location where Go package is installed on your system.

export GOROOT=/usr/local/go

GOPATH is the location of your work directory.

export GOPATH=$HOME/go

Now set the PATH variable to access go binary system-wide.

export PATH=$PATH:$GOROOT/bin:$GOPATH/bin

2. Test Go command

Now type "go" command in the terminal. It will show the output like the following screenshot.

go

3. Install CFSSL

We have to install CFSSL on this Ubuntu platform. When the required environment variables for GO are set properly, then CFSSL installation process will be easy.

a. The following command will download the CFSSL utility and build it in the $GOPATH/bin/ path.

go get -u github.com/cloudflare/cfssl/cmd/cfssl

b. The following command will install the json plugin of CFSSL package.It is required because CFSSL handles JSON requests.

 go get -u github.com/cloudflare/cfssl/cmd/cfssljson

c. simply install all of the programs of CFSSL using below given command. This command will download, build, and install all of the utility programs (including cfssl, cfssljson, and mkbundle among others) into the $GOPATH/bin/ directory.

go get -u github.com/cloudflare/cfssl/cmd/...

As shown below, Run "cfssl" command in the terminal and it will show all the operation supported by the CFSSL PKI.

CFSSL's PKI Setup

Now, cfssl application will be used to setup PKI for the Lemur project. The configuration files "CSR_configuration" and "signing_configuration" are important in CFSSL setup. The "CSR" configuration file contains the configuration for the key pair you’re about to create and the "Signing" configuration as the name goes, sets up the configuration rules.

Create ROOT CA

For the root CA, check the following CSR configuration file (which we’ll call csr_ROOT_CA.json):

csr_ROOT_CA.json

 {
 "CN": "MY-ROOT-CA",
 "key": {
    "algo": "ecdsa",
    "size": 256
 },
 "names": [
 {
    "C": "UK",
    "L": "London",
    "O": "My Organisation",
    "OU": "My Organisational Unit Inside My Organisation"
 }
 ],
 "ca": {
    "expiry": "262800h"
 }
}

A brief explanation of the different fields is given below.

The configuration file follows the X.509 naming scheme, so the following fields are required:
- CN (Common Name) – The name of the entity. On the Root CA case, it’s the Root CA Name;
- C (Country)
- L (Location)
- O (Organisation)
- OU (Organisational Unit)
Now, a number of specific fields are specific to CFSSL:
- KEY – Defines the keys characteristics:
  - Algo – Specifies the algorithm. Can be ‘rsa’ or ‘ecdsa’, for RSA or ECDSA algorithms, respectively. Now, ECDSA is always recommended if legacy devices are not relevant, but this only applies to devices less than two or three years old. RSA shall be used otherwise.
  - size – Specifies the key size. 256 shall be used for ecdsa key. For RSA keys, 2048 or 4096 are the recommended values.
- ca – Defines the CA characteristics and in this case the key validity, in hours, yes, in hours. In this case it’s 30 years (24x356x30), as the root authority shall last as long as you foreseen the security of the root key.

Now, run the following command to actually create the Root CA for the Lemur.

cfssl gencert -initca csr_ROOT_CA.json | cfssljson -bare root_ca

The above command will create the following files on the machine.

root_ca.csr – The root ca certificate sign request, which doesn’t make sense for the root ca, and therefore will never be used. As the root CA is self-signed.
root_ca.pem – The Root CA certificate. This is the file you and to distribute as much as possible.
root_ca.key – This is the root CA Key. Keep this file safe and secured, as if your life depends on it. For a public Root CA this is actually the truth.

The Root CA is self-signed, so move on to the next step for the generation of an intermediate CA.

Intermediate CA

The generation of Intermediate CA is not mandatory but corresponds to a best practice. The end goal of having an intermediate CA, is to have an intermediate step in terms of security. Usually. the Root CA key is kept in an offline machine, and only used when you need to sign an intermediate CA certificate.

The configuration file "csr_INTERMEDIATE_CA.json" is required to create an intermediate CA.

csr_INTERMEDIATE_CA.json – The certificate sign request for the Intermediate CA

{
 "CN": "My-Intermediate-CA",
 "key": {
    "algo": "ecdsa",
    "size": 256
 },
 "names": [
 {
    "C": "UK",
    "L": "London",
    "O": "My Organisation",
    "OU": "My Organisational Unit Inside My Organisation"
 }
 ],
 "ca": {
    "expiry": "42720h"
 }
}

The "root_to_intermediate_ca.json" file contains the Root CA signing configuration.

{ 
"signing": {
 "default": {
 "usages": ["digital signature","cert sign","crl sign","signing"],
 "expiry": "262800h",
 "ca_constraint": {"is_ca": true, "max_path_len":0, "max_path_len_zero": true}
 }
 }
}

This file contains the most relevant parameters for a certificate.

usages – Which usages are allowed to be performed by the certificate being signed. Options supported by CFSSL are the following:
- “digital signature”,
- “cert sign”,
- “crl sign”,
- “signing”
- etc
is_ca – this field is only applicable to generate intermedia CAs certificates, and allows the generated certificate to sign other certificates. If you leave this field on an end device certificate it will be rejected by most common browsers and operative systems.

The following command will create an Intermediate CA against the above-mentioned configuration.

cfssl gencert -initca csr_INTERMEDIATE_CA.json | cfssljson -bare intermediate_ca

The above command will create the following files of the Intermediate CA.

intermediate_ca.csr – The Intermediate CA certificate sign request.
intermediate_ca.pem – The Intermediate CA certificate, not signed by anyone, and therefore useless.
intermediate_ca.key – This is the Intermediate CA Key. Keep this file safe and secured.

The following command shows the signing of Intermediate CA certificate by the Root CA.

cfssl sign -ca root_ca.pem -ca-key root_ca-key.pem -config root_to_intermediate_ca.json intermediate_ca.csr | cfssljson -bare intermediate_ca

The above command will sign the intermediate_ca.pem file. Now the setting of the Root and Intermediate CA is complete. It is important to keep Root CA Keys and configurations files safe and secure. Next step is to create a certificate for client device or customer. Here, we will integrate the CFSSL setup with the Lemur project and the client's certificate will be generated.

Run CFSSL's PKI

To run the CFSSL based PKI, go inside the certs directory and run following command.

cfssl serve -address 192.168.10.151 -ca root_ca.pem -ca-key root_ca-key.pem -port 8888

The output of the above command will be following.

root@test-vm:/home/john/Desktop/certs# cfssl serve -address 192.168.10.151 -ca root_ca.pem -ca-key root_ca-key.pem -port 8888
2018/05/20 16:35:18 [INFO] Initializing signer
2018/05/20 16:35:19 [WARNING] couldn't initialize ocsp signer: open : no such file or directory
2018/05/20 16:35:19 [INFO] endpoint '/api/v1/cfssl/scaninfo' is enabled
2018/05/20 16:35:19 [WARNING] endpoint 'ocspsign' is disabled: signer not initialized
2018/05/20 16:35:19 [INFO] endpoint '/' is enabled
2018/05/20 16:35:19 [INFO] endpoint '/api/v1/cfssl/info' is enabled
2018/05/20 16:35:19 [INFO] endpoint '/api/v1/cfssl/gencrl' is enabled
2018/05/20 16:35:19 [INFO] endpoint '/api/v1/cfssl/scan' is enabled
2018/05/20 16:35:19 [WARNING] endpoint 'crl' is disabled: cert db not configured (missing -db-config)
2018/05/20 16:35:19 [INFO] endpoint '/api/v1/cfssl/certinfo' is enabled
2018/05/20 16:35:19 [WARNING] endpoint 'revoke' is disabled: cert db not configured (missing -db-config)
2018/05/20 16:35:19 [INFO] bundler API ready
2018/05/20 16:35:19 [INFO] endpoint '/api/v1/cfssl/bundle' is enabled
2018/05/20 16:35:19 [INFO] setting up key / CSR generator
2018/05/20 16:35:19 [INFO] endpoint '/api/v1/cfssl/newkey' is enabled
2018/05/20 16:35:19 [INFO] endpoint '/api/v1/cfssl/init_ca' is enabled
2018/05/20 16:35:19 [INFO] endpoint '/api/v1/cfssl/sign' is enabled
2018/05/20 16:35:19 [WARNING] endpoint 'authsign' is disabled: {"code":5200,"message":"Invalid or unknown policy"}
2018/05/20 16:35:19 [INFO] endpoint '/api/v1/cfssl/newcert' is enabled
2018/05/20 16:35:19 [INFO] Handler set up complete.
2018/05/20 16:35:19 [INFO] Now listening on 192.168.10.151:8888

The ip address of the machine is 192.168.10.151 and port is 8888. Allow this port in the firewall to use the CFSSL.

NOTE: The following command is just guiding to use the cfssl utility.

{ 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] }

Now, the configuration of the CFSSL is complete and it is running on the machine. The next step is the integration of CFSSL with Lemur.

Lemur configuration for CFSSL's PKI

Now, the configuration file "lemur.conf.py" of the Lemur will be modified ( such as URL, ROOT, and Intermediate keys). The configuration file will include the information about the CFSSL. The path of the lemur configuration file is "/home/lemur/.lemur/lemur.conf.py".

CFSSL_URL ="http://192.168.10.151:8888"

CFSSL_ROOT ="""-----BEGIN CERTIFICATE-----
MIICcjCCAhegAwIBAgIUahfYPc4RpK92G1ZHhu3q9URvf+8wCgYIKoZIzj0EAwIw
9UmEM4IEd2j8/w4WdTYaBE5EzwIhAN3oW9iAmjcyzC/7BPIY/Sr+twig/+XwnQ8T
hKXP2OHd
-----END CERTIFICATE-----"""

CFSSL_INTERMEDIATE ="""-----BEGIN CERTIFICATE-----
MIICfDCCAiKgAwIBAgIUEeb8Duel8wySG61vCM2UEUD15XQwCgYIKoZIzj0EAwIw
qM9lE82tku/b6SMxAlBByQ==
-----END CERTIFICATE-----"""

Now, run the "lemur start" command to use the lemur.conf.py with CFSSL setting.

Create certificates using CFSSL

By following our previous article on the Lemur, access the dashboard to create client Certificates using Root CA of CFSSL. First of all, create new Certification Authority and select plugin CFSSL as Root CA.

1. setting different parameters of the new authority.

2. select newly setup CFSSL Plugin as a Root CA.

After setting up the new Certification Authority in the Lemur, the next step is to generate a certificate using the newly setup CFSSL plugin.

Integration of CFSSL with the Lemur Certificate Manager