EST Certificate Lifecycle Operations

EST Enrollment

Horizon Client is able to use the EST module of Horizon to enroll certificates.

Enrollment modes

The following enrollment modes are supported:

  • Authorized user/password in decentralized mode

  • 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

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 --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.

Use the --challenge option.

horizon-cli est enroll --challenge=<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

Use the --in-cert, --win-user-store-auth or --win-computer-store-auth option.

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

horizon-cli est enroll --win-user-store-auth --profile=test --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 the given certificate parameters, and the private key and the retrieved certificate are then stored according to the output 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 certificate 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 output 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.

General enrollment parameters

Table 1. General parameters

Parameter

Description

--profile

Horizon’s technical name of the profile to enroll on. Mandatory

--challenge

Challenge generated on Horizon on the profile. Mandatory in challenge mode

--discovery

Horizon’s discovery campaign name to use in order to report the certificate to Horizon after enrollment

--centralized

Switches to centralized enrollment

--script

Path to the script to execute after enrollment. See script for more details

Input certificate parameters (x509 mode)

These parameters define how to find the certificate to swap in x509 mode. It can be stored in the following formats:

  • Key and certificate stored separately in two files, in PEM format (--in-cert & --in-key)

  • Key and certificate stored together in a PKCS#12 file (--in-cert & --in-pfx-pwd)

  • Key and certificate stored together in a JKS file (--in-cert & --in-jks-pwd & --in-jks-alias & --in-jks-alias-pwd)

  • Key and certificate stored together in Windows certificate store:

    • Using certificate thumbprint, available in the details tab of windows certificate explorer or in certutil (--in-cert)

    • Using the certificate CN (see Windows parameters)

Table 2. Input certificate parameters

Parameter

Description

--in-cert

Path to the certificate to renew (PEM file, PKCS#12 file, JKS file) or certificate thumbprint for Windows certificate store entries

--in-key

Path to the private key of the certificate to renew if --in-cert is a PEM file

--in-pfx-pwd

Password for the PKCS#12 file to renew

--in-jks-pwd

Password for the JKS file to renew

--in-jks-alias

Alias for the JKS file to renew

--in-jks-alias-pwd

Alias password for the JKS file to renew

Certificate parameters

Table 3. Data parameters

Parameter

Description

--cn

Requested subject Common Name. Single value

--ou

Requested subject OU. Can contain multiple values

--dnsnames

Requested subject alternative name DNS entries. Can contain multiple values

--ip

Requested subject alternative name IP entries. Can contain multiple values

--emails

Requested subject alternative name RFC822Name entries. Can contain multiple values
Table 4. Metadata parameters

Parameter

Description

--contact-email

Contact email of the request. Single value

--owner

Owner of the request. Single value

--team

Team of the request. Single value

--labels

Labels of the request. Can contain multiple values
Table 5. Crypto parameters

Parameter

Description

--key-type

Key-type of the certificate. See key types for more details

Output 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 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 (see Windows parameters)

Table 6. Output parameters

Parameter

Description

--cert

Path to the certificate to store

--key

Path to the private key to store

--ca-chain

Path to the chain to store

--pfx

Path to write the PKCS#12 output

--pfx-pwd

Password for the PKCS#12 output. Mandatory if --pfx is set

--pfx-aes

Enable AES encryption for PKCS#12, compatible with openssl v3

--jks

Path to write the JKS output

--jks-pwd

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

--jks-alias

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

--jks-alias-pwd

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

--overwrite

Always overwrite existing files

Windows parameters

These parameters define how to integrate with the Windows certificate store:

Table 7. Windows parameters

Parameter

Description

--win-user-store-auth

Triggers the use of Windows current user certificate store for certificate authentication. Most recent valid certificate with matching CN will be used

--win-computer-store-auth

Triggers the use of Windows local machine certificate store for certificate authentication. Most recent valid certificate with matching CN will be used

--win-user-store-save

Triggers the use of user Windows certificate store to save the certificate after enrollment

--win-computer-store-save

Triggers the use of computer Windows certificate store to save the certificate after enrollment

--win-store-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

--win-store-use-legacy

Triggers the ability to store the certificate in the legacy Microsoft Enhanced Cryptographic Provider v1.0 CSP. If not specified, the Microsoft Software Key Storage Provider KSP will be used

--win-store-set-exportable

Marks the key as exportable from the Windows certificate store. If not specified, the key is not exportable

EST Renewal

The certificate renewal is performed by using the “renew” command.

  • 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 and certificate parameters]

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

General renewal parameters

Table 8. General parameters

Parameter

Description

--profile

Horizon’s technical name of the profile to enroll on. Mandatory

--discovery

Horizon’s discovery campaign name to use in order to report the certificate to Horizon after renewal

--centralized

Switches to centralized enrollment

--key-type

Key-type of the certificate. See key types for more details

--script

Path to the script to execute after renewal. See script for more details

--renewal-interval

Number of days before expiration to trigger the renewal. Defaults to 30

Input certificate parameters

These parameters define how to find the certificate to renew. It can be stored in the following formats:

  • Key and certificate stored separately in two files, in PEM format (--in-cert & --in-key)

  • Key and certificate stored together in a PKCS#12 file (--in-cert & --in-pfx-pwd)

  • Key and certificate stored together in a JKS file (--in-cert & --in-jks-pwd & --in-jks-alias & --in-jks-alias-pwd)

  • Key and certificate stored together in Windows certificate store:

    • Using certificate thumbprint, available in the details tab of windows certificate explorer or in certutil (--in-cert)

    • Using the certificate CN (see Windows parameters)

Table 9. Input certificate parameters

Parameter

Description

--in-cert

Path to the certificate to renew (PEM file, PKCS#12 file, JKS file) or certificate thumbprint for Windows certificate store entries

--in-key

Path to the private key of the certificate to renew if --in-cert is a PEM file

--in-pfx-pwd

Password for the PKCS#12 file to renew

--in-jks-pwd

Password for the JKS file to renew

--in-jks-alias

Alias for the JKS file to renew

--in-jks-alias-pwd

Alias password for the JKS file to renew

Output 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 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 (see Windows parameters)

Table 10. Output parameters

Parameter

Description

--cert

Path to the certificate to store

--key

Path to the private key to store

--ca-chain

Path to the chain to store

--pfx

Path to write the PKCS#12 output

--pfx-pwd

Password for the PKCS#12 output. Mandatory if --pfx is set

--pfx-aes

Enable AES encryption for PKCS#12, compatible with openssl v3

--jks

Path to write the JKS output

--jks-pwd

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

--jks-alias

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

--jks-alias-pwd

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

--overwrite

Always overwrite existing files

Windows parameters

These parameters define how to integrate with the Windows certificate store:

Table 11. Windows parameters

Parameter

Description

--cn

CN of the certificate to renew in the Windows certificate store. Use with --win-store-auth

--win-user-store-auth

Triggers the use of Windows current user certificate store for certificate authentication. Most recent valid certificate with matching CN will be used

--win-computer-store-auth

Triggers the use of Windows local machine certificate store for certificate authentication. Most recent valid certificate with matching CN will be used

--win-user-store-save

Triggers the use of user Windows certificate store to save the certificate after enrollment

--win-computer-store-save

Triggers the use of computer Windows certificate store to save the certificate after enrollment

--win-store-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

--win-store-use-legacy

Triggers the ability to store the certificate in the legacy Microsoft Enhanced Cryptographic Provider v1.0 CSP. If not specified, the Microsoft Software Key Storage Provider KSP will be used

--win-store-set-exportable

Marks the key as exportable from the Windows certificate store. If not specified, the key is not exportable

Key Types

Depending on your Horizon version, the following key types are supported:

RSA

To add a RSA key type, the following syntax must be used.

rsa-<key-size>

rsa-2048, rsa-3072, rsa-4096

ECDSA

To add a ECDSA key type, the following syntax must be used.

ec-<curve>

The following curves are supported:

  • secp256r1

  • secp384r1

  • secp521r1

ec-secp256r1, ec-secp384r1

EDDSA

To add a EDDSA key type, the following syntax must be used.

ed-<curve>

The following curves are supported:

  • Ed25519

ed-Ed25519

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 - windows store thumbprint)

  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 --challenge=<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 --challenge=<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 --centralized --challenge=<challenge> --profile=<profile> --cn=test.example.com --dnsnames=test.example.com,www.test.example.com --cert=/path/to/cert --key=/path/to/key

Centralized enrollment with challenge, output as PKCS#12

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

Decentralized enrollment with challenge, output in machine windows store

horizon-cli est enroll --challenge=<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 --cert=/path/to/new/cert --key=/path/to/new/key

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

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

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