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:

  1. Create the request

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

Content Parameters

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

Table 1. WebRA enrollment content parameters
Parameter Description

--profile

WebRA Profile to use

--discovery

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

--contact-email

Contact email

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

--ms-guid

SAN MS GUID of the certificate to request

--ms-sid

SAN MS SID of the certificate to request

--key-type

Select a key type for your enrollment other than the default one of the profile

--owner

Certificate owner

--team

Certificate owning team

--labels

Labels, in the form key:value

--cert

path to the cert file to be created

--key

path to the key file to be created

--ca-chain

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

--pfx

Path to write the PKCS#12 output to be created

--pfx-pwd

Password for the PKCS#12 output, mandatory if pfx is set

--jks

Path to write the JKS output to be created

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

Overwrite existing files

--win-store-save

[Windows Only] Triggers the use of Windows certificate store to save the certificate after enrollment

--win-machine-store

[Windows Only] Triggers the use of local machine store on Windows

--win-use-tpm

[Windows Only] Triggers the use of the Microsoft Platform Crypto Provider for certificate store save. Used only with win-store-save.

--script

Execute bash or powershell script upon enrollment or renewal completion

--now

If user has only "request enroll" permission, start a blocking loop until review, instead of waiting for the next routine execution

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.

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

Table 2. WebRA input certificate parameters
Parameter Description

--discovery

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

--in-cert

Path to the Certificate to renew (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 renew if it is not included in the certificate 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 certificate to renew in the JKS file

--in-jks-alias-pwd

Alias password for the JKS file to renew

--key-type

The key type to use for the renewed certificate

--cert

Path to the cert file to be created

--key

Path to the key file to be created

--ca-chain

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

--overwrite

Overwrite existing files

--pfx

Path to write the PKCS#12 output to be created

--pfx-pwd

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

--jks

Path to write the JKS output to be created

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

Overwrite existing files

--win-store-save

[Windows Only] Triggers the use of Windows certificate store to save the certificate after enrollment

--win-machine-store

[Windows Only] Triggers the use of local machine store on Windows

--win-use-tpm

[Windows Only] Triggers the use of the Microsoft Platform Crypto Provider for certificate store save. Used only with win-store-save.

--script

Execute bash or powershell script upon enrollment or renewal completion

--now

If user has only "request enroll" permission, start a blocking loop until review, instead of waiting for the next routine execution

--renewal-interval

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

WebRA Revocation

The webra revoke command takes the following parameters:

Table 3. WebRA revocation parameters
Parameter Description

--discovery

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

--cert

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

--key

Path to the private key of the certificate to revoke if it is not included in the certificate file

--pfx-pwd

Password for the PKCS#12 file to revoke

--jks-pwd

Password for the JKS file to revoke

--jks-alias

Alias for the certificate to revoke in the JKS file

--jks-alias-pwd

Alias password for the JKS file to revoke

--reason

Reason for revocation (unspecified, keycompromise, cacompromise, affiliationchanged, superseded, cessationofoperation)

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.

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 4. Platform-independent output parameters
Parameter Description

--cert

Path to the certificate to store

--key

Path to the private key 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
Table 5. Windows-only output 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.

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

  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 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> --key=/path/to/key --cert=/path/to/cert --cn=test.example.com --dnsnames=test.example.com,www.test.example.com --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 \
  --pfxpwd=<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-key /path/to/old/key --in-cert /path/to/old/cert --key /path/to/key --cert /path/to/cert --now

Revocation of a certificate

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