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.

Validation

Get a SCEP challenge password from the Horizon web app or REST API. You can then provide it with the --challenge parameter to the enroll command.

Content Parameters

You can customize the contents of the CSR using the following parameters:

Table 1. SCEP enrollment content parameters
Parameter Description

--profile

SCEP Profile to use

--challenge

SCEP pre-validated request challenge

--cert

Path to the certificate file to be written

--key

Path to the key file to be written

--cn

Common Name of the certificate to request

--ou

Organizational Units of the certificate to request

--dnsnames

SAN DNS Names of the certificate to request

--ip

SAN IP Addresses of the certificate to request

--emails

SAN RFC822 Names of the certificate to request

--contact-email

Contact email

--owner

Certificate owner

--team

Certificate owning team

--labels

Labels, in the form key:value

--ca-chain

Path to write the CA Chain to be written, as a PEM Bundle

--pfx

Path to write the PKCS#12 output to be written

--pfx-pwd

Password for the PKCS#12 output

--key-type

Type and size of the key to generate (defaults to rsa-2048)

--script

Bash or powershell script to execute upon enrollment completion. See script section

--discovery

Discovery profile to use in order to report the certificate to Horizon after enrollment

--jks

Path to write the JKS output to be written

--jks-pwd

Password for the JKS output

--jks-alias

Alias for the JKS output

--jks-alias-pwd

Password for the alias in the JKS output

--overwrite

Overwrite existing files

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

The following input parameters can be used to specify the certificate to renew:

Table 2. SCEP input certificate parameters
Parameter Description

--profile

SCEP Profile to use

--key-type

Key type

--contact-email

Contact email

--owner

Certificate owner

--team

Certificate owning team

--labels

Labels, in the form key:value

--discovery

Discovery profile to use in order to report the certificate to Horizon after renewal

--in-cert

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

--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 certificate to renew in the JKS file

--in-jks-alias-pwd

Alias password for the JKS file to renew

--cert

Path to the Certificate to save as a PEM file

--key

Path to the Key to save as a PEM file

--ca-chain

Path to the Chain to save as a PEM file

--pfx

Path to write the PKCS#12 output

--pfx-pwd

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

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

--script

Execute bash or powershell script upon enrollment or renewal completion. See script section

--renewal-interval

Number of days before expiration to trigger the renewal. Optional, renewal modeonly

Output Parameters

Choose how the created certificate and its associated private key are stored. 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 or JKS 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 3. Platform-independent output 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

--jks-pwd

Password used to encrypt the JKS file specified in the --jks parameter

--jks-alias

Alias of the private key entry within the JKS

--jks-key-pwd

Password of the private key entry within the JKS

Metadata parameters

Each certificate enrolled via horizon must have a profile, specified with the --profile flag. You can add extra metadata according to your needs using the following parameters:

Table 4. SCEP metadata parameters
Parameter Description

--owner

Owner of the certificate

--contact-email

Contact email of the certificate owner

--team

Team owning the certificate

--labels

Labels to attach to the certificate, in the form key:value

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