EST Certificate Lifecycle Operations

EST Enrollment

Horizon Client is able to use the EST module of Horizon to enroll certificates. The following enrollment modes are supported:

  • Static and authorized user/password in decentralized mode

  • Static and authorized user/password in centralized mode

  • Challenge password in decentralized mode

  • Challenge password in centralized mode

  • Certificate swap in decentralized mode

  • Certificate swap in centralized mode

Static and authorized user

In this enrollment mode, a local user account is created in Horizon for Horizon Client, and the EST profile on Horizon is configured in "authorized" mode thus a static username and password can be provided to Horizon Client for enrollment. They need to be set in general configuration as APIID and APIKEY.

horizon-cli est enroll --mode=static --profile=test --cn=TestCN [data parameters] [key and certificate parameters]

Challenge password

In this enrollment mode, the EST profile on Horizon is set to "challenge" mode. A request must then be made on Horizon in order to retrieve the one-time password "challenge" to be used to authenticate the EST request. No APIID nor APIKEY need to be set.

horizon-cli est enroll --mode=<challenge> --profile=test --cn=TestCN [data parameters] [key and certificate parameters]

Certificate swap

In this enrollment mode, the EST profile on Horizon is set to "x509" mode. The client is then able to make a request to Horizon by authenticating with an existing certificate. This certificate can be specified either:

  • by using the --key and --cert parameters, respectively pointing at the key and the certificate to be used to authenticate

  • by using the --win-store-auth parameter (Windows only), that will look into the "MY" certificate store (user by default, unless --win-machine-store is specified) for a non-expired certificate whose CN matches the Common Name specified in --cn parameter

horizon-cli est enroll --mode=cert --profile=test --key=/path/to/key --cert=/path/to/cert --cn=TestCN [data parameters] [key and certificate parameters]

horizon-cli est enroll --mode=cert --profile=test ---win-store-auth --cn=TestCN [data parameters] [key and certificate parameters]

Decentralized mode

In decentralized mode, which is the default mode, Horizon Client generates a private key and a CSR. The CSR is generated according to Data parameters, and the private key and the retrieved certificate are then stored according to the Key and Certificate parameters

Centralized mode

In Centralized mode, triggered by adding the “--centralized” parameter to the command line, Horizon Client generates a fake private key and a CSR. The CSR is generated according to Data parameters. The private key generated by Horizon Client is discarded. A random password is generated and inserted into the CSR. If the enrollment is successful, Horizon generates a private key and a certificate and sends them back to Horizon Client as PKCS#12, which Horizon Client decodes using the randomly generated password. The retrieved private key and the retrieved certificate are then stored according to the Key and Certificate parameters

The random password generated has 16 characters, letters and numbers. If a password policy is enforced on Horizon side for the centralized mode in the considered EST profile, ensure that it is compatible with such characteristics.

EST Renewal

The certificate renewal is performed by using the “renew” command. It works the same way as the Certificate swap mode, except that:

  • it is designed to renew a certificate already issued by Horizon on the same profile.

  • it can be scheduled as a periodic task (cron or Scheduled Task), that will perform the renewal only when the certificate is N days before its expiration. N can be specified using the “--renewal-interval” parameter, and defaults to 30.

horizon-cli est renew --profile=test --in-cert=/path/to/cert/to/renew --key=/path/to/key --cert=/path/to/cert [key and certificate parameters]

horizon-cli est renew --profile=test --win-store-auth --cn=TestCN --win-store-save [key and certificate parameters]

Data parameters

These parameters are used to be inserted in the Certificate Signing Request sent to Horizon in Enroll mode.

Table 1. CSR data parameters
Parameter Description

--cn

Requested subject Common Name, single value, and mandatory.

--ou

Requested subject OU. Can contain multiple values. Optional.

--dnsnames

Requested subject alternative name DNS entries. Can contain multiple values. Optional.

--emails

Requested subject alternative name RFC822Name entries. Can contain multiple values. Optional.

Key and Certificate parameters

These parameters define how to store the retrieved certificate and its associated private key. The following alternatives are available:

  • Key and certificate stored separately in two files, in PEM format. This is typically used to be used by Apache or NGINX web servers;

  • Key and certificate stored together in a PKCS#12 file. This is typically used by Tomcat application server;

  • Key and certificate stored together in Windows certificate store. This is typically used by IIS web server.

Table 2. Platform-independent key and certificate parameters
Parameter Description

--key

Path to the private key to store

--cert

Path to the certificate to store

--pfx

Path to the PKCS#12 file storing the certificate and its key

--pfx-pwd

Password used to encrypt the PKCS#12 file specified in the --pfx parameter

--jks

Path to export the certificate and private key as JKS. Optional, must be used along pfx/pfxpwd options as pfxpwd option is used to protect the JKS

--jks-pwd

Password for the JKS output. Mandatory if --jks is set

--jks-alias

Alias of the private key entry within the JKS. Optional, only used with --jks

--jks-alias-pwd

Password of the private key entry within the JKS. Optional, defaults to pfxpwd, only used with --jks
Table 3. Windows-only key and certificate parameters
Parameter Description

--win-store-save

Triggers the ability to store the certificate and private key into the "MY" certificate store

--win-machine-store

Triggers the ability to store in the Machine store. If not specified, the User store is used. This parameter requires Horizon Client to be executed with appropriate elevated rights.

--win-use-tpm

Triggers the ability to store the certificate in the Microsoft Platform Crypto Provider KSP. If not specified, the Microsoft Software Key Storage Provider KSP will be used.

Discovery parameter

You can chain a certificate enrollment operation with the discovery operation by using the --discovery parameter. It will use the APIID and APIKey defined in the general configuration to authenticate to Horizon and feed it with the enrolled certificate and its discovery metadata.

The --discovery parameter takes a value, which is the name of the Discovery campaign to use to report the certificate to Horizon.

Script parameter

You can tell Horizon Client to launch a script upon successful certificate enrollment or renewal by using the --script parameter, which takes the path to the script as an argument.

The script will receive arguments passed by Horizon Client in the following order:

  1. Issued certificate serial number

  2. Issued certificate fingerprint (SHA-1 hash of the certificate in DER format)

  3. Issued certificate Subject DN

  4. Issued certificate Issuer DN

Below is an example of a very simple bash script:

#!/bin/sh

echo $1
echo $2
echo $3
echo $4

Below is an example of a very simple PowerShell script:

param($serial, $fingerprint, $subject, $issuer)

Write-Output $serial
Write-Output $fingerprint
Write-Output $subject
Write-Output $issuer

Examples

You will find below a few examples detailing how to use the client for EST enrollment in various context

Decentralized enrollment with challenge, output as key and certificate

horizon-cli est enroll --mode=<challenge> --profile=<profile> --key=/path/to/key --cert=/path/to/cert --cn=test.example.com --dnsnames=test.example.com,www.test.example.com

Decentralized enrollment with challenge, output as PKCS#12

horizon-cli est enroll --mode=<challenge> --profile=<profile> --cn=test.example.com --dnsnames=test.example.com,www.test.example.com --pfx=/path/to/pkcs12 --pfx-pwd=<pkcs12_password>

Centralized enrollment with challenge, output as key and certificate

horizon-cli est enroll --mode=<challenge> --profile=<profile> --key=/path/to/key --cert=/path/to/cert --cn=test.example.com --dnsnames=test.example.com,www.test.example.com --centralized

Centralized enrollment with challenge, output as PKCS#12

horizon-cli est enroll --mode=<challenge> --profile=<profile> --cn=test.example.com --dnsnames=test.example.com,www.test.example.com --pfx=/path/to/pkcs12 --pfxpwd=<pkcs12_password> --centralized

Decentralized enrollment with challenge, output in machine windows store

horizon-cli est enroll --mode=<challenge> --profile=<profile> --cn=test.example.com --dnsnames=test.example.com,www.test.example.com --win-store-save --win-machine-store

Decentralized renewal from certificate and key, output as key and certificate

horizon-cli est renew --profile=<profile> --in-cert=/path/to/old/cert --in-key=/path/to/old/key --key=/path/to/new/key --cert=/path/to/new/cert

Decentralized renewal from PKCS#12, output as key and certificate

horizon-cli est renew --profile=<profile> --in-cert=/path/to/old/pkcs12 --key=/path/to/key --cert=/path/to/cert

Decentralized renewal using machine windows store

horizon-cli est renew --profile=<profile> --cn=test.example.com --win-store-auth --win-store-save --win-machine-store