SCEP Certificate Lifecycle Operations

The Horizon Client includes a SCEP client to perform challenge based pre-validated enrollments and renewals. Its usage is similar to that of the EST client in challenge mode.

Usage:

horizon-cli scep [command] [flags]

SCEP Enrollment

The enroll command allows you to perform a SCEP enrollment operation. It will generate a new key pair and a CSR based on the content parameters, and send it to the SCEP server to obtain a certificate.

Enrollment modes

The following enrollment modes are supported:

Authorized user/password in decentralized mode
Challenge password in decentralized mode

Authorized user

In this enrollment mode, a local user account is created in Horizon for Horizon Client, and the SCEP 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 scep enroll --profile=test --cn=TestCN [data parameters] [key and certificate parameters]

Challenge password

In this enrollment mode, the SCEP 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 SCEP request.No APIID nor APIKEY need to be set.

Use the --challenge option.

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

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
`--script`	Path to the script to execute after enrollment. See script for more details

Certificate parameters

Table 2. 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 3. 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 4. 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 5. 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 6. Windows parameters
Parameter	Description
`--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

SCEP Renewal

The renew command is designed to work similarly to the enroll command, but with a few differences:

It will enroll a certificate based on the --in-cert parameter (or similar, see below) instead of the content parameters. Only the --key-type parameter is used to generate a new key pair.
No challenge is needed for a SCEP renewal operation

General renewal parameters

Table 7. 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
`--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)

Table 8. 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 9. 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 10. Windows parameters
Parameter	Description
`--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:

Issued certificate serial number
Issued certificate fingerprint (SHA-1 hash of the certificate in DER format - windows store thumbprint)
Issued certificate Subject DN
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 SCEP enrollment in various context

Enrollment with output as key and certificate

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

Enrollment with lots of metadata and output as PKCS#12

horizon-cli scep enroll \
  --profile=<profile> \
  --challenge=<challenge> \
  --key-type=rsa-2048 \
  --cn=test.example.com \
  --dnsnames=test.example.com,www.test.example.com \
  --owner="John Doe" \
  --ou="IT" \
  --team="IT" \
  --labels="env:prod" \
  --pfx=/path/to/pkcs12 \
  --pfx-pwd=<pkcs12_password>

Renewal with output as key and certificate

horizon-cli scep renew --profile=<profile> --in-cert /path/to/cert --cert=/path/to/cert --key=/path/to/key