WebRA Certificate Lifecycle Operations

The Horizon Client can perform post-validated lifecycle operations using the WebRA protocol. This includes certificate enrollment, renewal and revocation.

WebRA operations validation

Like SCEP and EST, WebRA operations requires the intervention of a third party to validate the request. Unlike SCEP and EST though, it is a post-validation protocol, meaning that no challenge is produced before the operation, instead a request is created and sent to the WebRA server, which will need to be validated or cancelled by an operator with the appropriate rights on the web app.

This means the Horizon Client performs enrollment and renewal operations in two steps:

Create the request
Once the request is validated, retrieve the certificate

Depending on the time it takes for the request to be validated, the Horizon Client can be configured to either enter a blocking loop and wait for the request to be validated, or merely create the request and exit.

If the latter is chosen, the Horizon Client will keep in its internal database the pending request, and will check for its validation each time the horizon-cli automate routine command is executed. If the request is validated, the certificate will be retrieved and stored in the appropriate location. If it is denied, the request will be removed from the database. In some cases you would want to configure a crontab or scheduled task to perform this check periodically. You can use the command horizon-cli automate create-periodic-task <period> to help you in the process, or create it manually.

By default, the behavior is to create the request and exit. If you wish for the client to enter a blocking loop until the request is validated, specify the --now flag.

WebRA Enrollment

General enrollment parameters

Table 1. General parameters
Parameter	Description
`--profile`	Horizon’s technical name of the profile to enroll on. Mandatory
`--now`	Start a blocking loop to wait for request approval
`--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
`--ms-guid`	Requested Microsoft GUID. Single value
`--ms-sid`	Requested Microsoft SID. Single value

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

WebRA Renewal

The webra renew command is designed to work similarly to the webra enroll command, except that it will enroll a certificate based on the --in-cert parameter (or similar, see below) instead of the content parameters.

General renewal parameters

Table 7. General parameters
Parameter	Description
`--key-type`	Key-type of the certificate. See key types for more details
`--now`	Start a blocking loop to wait for request approval
`--discovery`	Horizon’s discovery campaign name to use in order to report the certificate to Horizon after renewal
`--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

WebRA Import

The `webra import`command is designed to import a certificate and its key on a profile.

Import parameters

Table 11. WebRA import parameters
Parameter	Description
`--profile`	Existing profile on which to import

Table 12. Metadata parameters
Parameter	Description
`--owner`	Owner of the request. Single value
`--team`	Team of the request. Single value
`--contact-email`	Contact email of the request. Single value
`--labels`	Labels of the request. Can contain multiple values
`--metadata`	Technical metadata of the imported certificate, in key:value form

Input parameters

These parameters define how to find the certificate to import. 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 13. WebRA input certificate parameters
`--in-cert`	Path to the Certificate to import (PEM file, PKCS#12 file, JKS file) or cert thumbprint for Windows certificate store entries
`--in-key`	Path to the private key of the certificate to import if it is not included in the certificate file
`--in-pfx-pwd`	Password for the PKCS#12 file to import
`--in-jks-pwd`	Password for the JKS file to import
`--in-jks-alias`	Alias for the certificate to import in the JKS file
`--in-jks-alias-pwd`	Alias password for the JKS file to import

WebRA Revocation

The webra revoke command takes the following parameters:

Revocation parameters

Define how to revoke this certificate:

Table 14. WebRA revocation parameters
Parameter	Description
`--reason`	Reason for revocation (unspecified, keycompromise, cacompromise, affiliationchanged, superseded, cessationofoperation)

Input parameters

These parameters define how to find the certificate to revoke. 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 15. WebRA input certificate parameters
`--in-cert`	Path to the Certificate to revoke (PEM file, PKCS#12 file, JKS file) or cert thumbprint for Windows certificate store entries
`--in-key`	Path to the private key of the certificate to revoke if it is not included in the certificate file
`--in-pfx-pwd`	Password for the PKCS#12 file to revoke
`--in-jks-pwd`	Password for the JKS file to revoke
`--in-jks-alias`	Alias for the certificate to revoke in the JKS file
`--in-jks-alias-pwd`	Alias password for the JKS file to revoke

For a revocation operation, the --now flag is unavailable, and the automate routine command will not track the revocation status, as no actions are to be performed after the revocation is complete. This command thus merely creates the revocation request and exits.

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 WebRA enrollment in various context

Enrollment with output as key and certificate, waiting for the certificate to be issued

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

Enrollment with lots of metadata, output as PKCS#12 and no blocking loop

horizon-cli webra enroll \
  --profile=<profile> \
  --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>

after this command, run periodically:

horizon-cli automate routine > /path/to/my/logfile

Renewal with output as key and certificate, waiting for the certificate to be issued

horizon-cli webra renew --in-cert /path/to/old/cert --in-key /path/to/old/key --cert /path/to/cert --key /path/to/key --now

Revocation of a certificate

horizon-cli webra revoke --in-cert /path/to/cert --in-key /path/to/key