Sectigo HashiCorp Vault integration

Overview

The Sectigo HashiCorp Vault integration provides a seamless solution for the enrollment, collection, revocation, renewal, and replacement of SSL/TLS and client (S/MIME) certificates issued by the Sectigo Certificate Manager (SCM). This integration is distributed as a custom HashiCorp Vault (Vault) PKI plugin. It provides the following features:

  • RSA 2048, 3072, and 4096-bit private key generation

  • Certificate Signing Request (CSR) creation

  • Storage and state tracking of certificates issued by SCM in Vault

  • Certificate field verification with the profile provided from SCM

The Sectigo Vault integration supports both the management and storage of SSL and client certificates in Vault. The Sectigo Vault PKI plugin supports verifying the validity of certificates that are being read from Vault; certificates that fall within a user-specified certificate expiry window may optionally get automatically renewed.

The types of SSL/TLS and client certificates available to you are based on your account setup.
Integration Diagram

Prerequisites

  • HashiCorp Vault Version 1.2.3, 1.10.0 and 1.11.0

    Vault version 1.2.3 has a known issue with reading the VAULT_CLIENT_TIMEOUT environment variable when executed through the Vault CLI tool. This issue was rectified in Vault 1.3.0. For more information, see Dealing with timeouts and error codes.
  • jq (optional)

  • shasum or equivalent

  • SCM organization with Web API access enabled for SSL or client certificates

  • SSL or client types with associated terms for the organization

  • Supported operating systems:

    • Linux operating systems:

      • Ubuntu Server 16.04 LTS

      • Ubuntu Server 18.04 LTS

      • Ubuntu Server 19.04

      • Ubuntu Server 19.10

      • Ubuntu Server 20.04

      • CentOS 7.3

HashiCorp Vault integration package

The Sectigo HashiCorp Vault integration package contains the following:

  • sectigo-vault-pki:

    • sectigo-vault-pki_<version> (binary): The Sectigo Vault PKI plugin that allows users to store and manage certificates that get generated from SCM on Vault.

    • sample_json_data: Sample JSON files that can be used by the user to interact with the Sectigo Vault PKI plugin.

HashiCorp Vault Folder Path

Understanding the integration

Backend plugins in Vault are essentially separate, standalone applications that Vault executes and communicates with over RPC. Each backend plugin acts as a server and exposes certain API endpoints, which Vault would then interact with.

The Sectigo Vault PKI plugin is a custom secrets backend plugin which makes use of the Sectigo REST API to send HTTP requests to SCM. The plugin exposes its own API endpoints which each correspond to a specific path that builds on top of a starting base path prefix. In this guide, the path prefix sectigo-vault-pki is used.

You can rename this path prefix when you mount the Sectigo Vault PKI plugin into your Vault server.

Components

The Sectigo HashiCorp Vault integration is based on the component Sectigo Vault PKI Plugin, which integrates with Vault and mediates the interaction between the user, Vault, and the Sectigo REST API.

Path endpoints

The Sectigo Vault PKI plugin exposes several paths that users can interact with. Different paths are defined for different use cases. Depending on the applicable functionality, each path accepts different input parameters.

The following table lists all the paths that are supported by the Sectigo Vault PKI plugin and displays the operations that are supported by each path. Sample CLI commands can be found in Interacting with the plugin.

Path

Operation

Write

Read

List

Delete

configs

enroll

certs

revoke

replace

renew

fetch

profile

You can retrieve in-code API help for each individual path in Vault by using the built-in path-help CLI command. For more information on path-help, see HashiCorp’s path-help documentation.

To enroll and manage certificates on Vault through SCM, users must first create a config entry in Vault. This config entry may be used for downloading certificate profiles, and for enrolling and managing multiple certificates that correspond to the same SCM configuration. The following diagram illustrates a typical certificate enrollment scenario using the Sectigo Vault PKI plugin.

HashiCorp Vault Enrollment Scenario

Understanding the configurations

Parameter descriptions

The Sectigo Vault PKI plugin can handle many parameters. The required parameters depend on the specific use case and can be passed to Vault in two principal ways:

  • Bundled together in a JSON file when interacting with Vault through a Vault CLI tool or through cURL commands.

  • Individually as key/value pairs when interacting with Vault through the Vault CLI tool.

Configuration and user-specific parameters

Parameter Type Description

sectigo_cm_user

Mandatory

The user ID to access your URL

sectigo_cm_password

Mandatory

The password to access your URL

sectigo_config_type

Mandatory

The configuration type for your Vault-specific config entry. The value can either be ssl_cert or client_cert.

sectigo_cm_uri

Mandatory

Your Sectigo URI

sectigo_cm_org_id

Mandatory

Your Organization ID (numeric)

sectigo_cm_base_url

Mandatory

The base url of the Sectigo Certificate Authority

CSR parameters

Parameter Type Description

sectigo_csr_domain

Conditional

A single value for a domain which is included in the certificate Common Name (CN) field.

Required if sectigo_csr is not provided.

sectigo_csr_country

Conditional

The country name which is included in the certificate Country (C) field.

Required if sectigo_csr is not provided.

sectigo_csr_state

Conditional

The state/private name which is included in the certificate State (ST) field.

Required if sectigo_csr is not provided.

sectigo_csr_location

Conditional

The location name which is included in the certificate Location (L) field.

Required if sectigo_csr is not provided.

sectigo_csr_organization

Conditional

The organization name which is included in the certificate Organization (O) field.

Required if sectigo_csr is not provided.

sectigo_csr_organization_unit

Conditional

The organization unit which is included in the certificate Organization Unit (OU) field.

Required if sectigo_csr is not provided.

sectigo_csr_email_address

Conditional

The email address which is included in the certificate emailAddress field.

Required if sectigo_csr is not provided.

sectigo_csr_key_algo

Conditional

The private key algorithm used to generate the private key. Default: RSA.

Required if sectigo_csr is not provided.

sectigo_csr_key_size

Conditional

The size of the SSL/TLS keys to generate. The possible values are:

  • 2048: for 2048-bit (default)

  • 3072: for 3072-bit

  • 4096: for 4096-bit

Required if sectigo_csr is not provided.

sectigo_csr

Conditional

A certificate signing request in PEM format that users can optionally provide if they don’t want to generate a new one.

sectigo_private_key

Conditional

A private key in PEM format that users can optionally provide if they want to generate a CSR by using it.

Certificate issuance and collection parameters

Parameter Type Description

Common

sectigo_max_timeout

Optional

The maximum time in seconds before a certificate download attempt will time out. The default value is 600 seconds.

sectigo_loop_period

Optional

The time in seconds between each attempt to download the issued certificate. The default value is 30 seconds.

sectigo_expiry_window

Optional

The period of days prior to expiration that a new certificate enrollment process will be initiated. The default value is 7 days.

sectigo_auto_renew

Optional

A flag to determine whether certificates that fall within the expiry window should get automatically renewed. The default value is true. If you do not want to automatically renew certificates, you must specify false for this parameter.

sectigo_read_renewed_cert

Optional

When this flag is set to true (default) and you attempt to read a certificate from Vault, if the certificate has the Renewed state, the newer certificate is returned instead of the requested one.

If you set this flag to false, then even if the certificate had already been renewed, the requested certificate is returned. Specifying false may help avoid unwanted renewals.

SSL certificates

sectigo_ssl_cert_type

Mandatory

The type of the SSL certificate (numeric). This is the ID of the SSL certificate type.

sectigo_ssl_cert_validity

Mandatory

The certificate validity period in days (numeric). The values available are dependent on the selected sectigo_ssl_cert_type.

sectigo_ssl_cert_external_requester

Optional

A comma-separated list of emails

sectigo_ssl_cert_format_type

Optional

The format type of the SSL certificate. The supported values are:

  • x509: X509, Base64 encoded (default)

  • x509CO: X509 Certificate only, Base64 encoded

  • x509IO: X509 Intermediates/Root only, Base64 encoded

  • base64: PKCS#7 Base64 encoded

  • bin: PKCS#7 Bin encoded

  • x509OR: X509 Intermediates/Root only Reverse, Base64 encoded

sectigo_ssl_cert_comments

Optional

Comments for certificate enrollment

sectigo_ssl_cert_num_servers

Conditional

The number of server licenses (numeric)

sectigo_ssl_cert_server_type

Optional

The server type ID (numeric)

sectigo_ssl_cert_subject_alt_names

Optional

A comma-separated list of subject alternative names (SAN)

sectigo_ssl_cert_custom_fields

Optional

The custom fields to be applied to the requested certificate. The expected format for custom fields is the following: [{"name":"custom_field_1","value":"value_1"},{"name":"custom_field_2","value":"value_2"}]. If you are providing this input in a JSON string, make sure that the internal double quotes are escaped properly using backslash (\).

Client certificates

sectigo_client_cert_type

Mandatory

The type of the client certificate (numeric). This is the ID of the client certificate type.

sectigo_client_cert_validity

Mandatory

The certificate validity period in days (numeric). The values available are dependent on the selected sectigo_client_cert_type.

sectigo_client_cert_email

Mandatory

A valid user email that is less than 256 characters.

sectigo_client_cert_first_name

Conditional

The user’s first name

sectigo_client_cert_middle_name

Conditional

The user’s middle name

sectigo_client_cert_last_name

Conditional

The user’s last name.

The combined length of the first, middle, and last name fields cannot exceed 64 characters.

sectigo_client_cert_custom_fields

Optional

The custom fields to be applied to the requested certificate. The expected format for custom fields is the following: [{"name":"custom_field_1","value":"value_1"},{"name":"custom_field_2","value":"value_2"}]. If you are providing this input in a JSON string, make sure that the internal double quotes are escaped properly using backslash (\).

Other parameters

Parameter Type Description

Common

sectigo_cert_unique_id

Conditional

The unique certificate ID is used as the main identifier for certificates that are stored in Vault.

For SSL certificates, the unique cert ID is <ssl_id>_<customer_uri>.

For client certificates, the unique cert ID is <order_number>_<customer_uri>.

sectigo_reason

Mandatory

The reason why an action is being taken. The possible actions are either revoke or replace. Indicate why the certificate is being revoked or replaced.

sectigo_profile_unique_id

Conditional

Used in path profile. The unique profile ID is used as the main identifier for profiles that are stored in Vault.

SSL certificates

sectigo_common_name

Conditional

Used in path replace. A single value for a domain that is included in the certificate Common Name (CN) field.

Client certificates

sectigo_client_cert_revoke_on_replace

Mandatory

Used in path replace. The flag to determine whether a replaced certificate should be revoked.

Using the Sectigo Vault PKI plugin

Configuring the plugin directory

Vault servers in development mode can use -dev-plugin-dir to specify the path to the plugin. Otherwise, the Vault server must be configured to use a plugin directory with the plugin_directory field pointing to the path of your plugins directory in a configuration file with HCL or JSON format. For the Sectigo Vault PKI plugin, you must place the custom sectigo-vault-pki_<version> binary in the configured Vault plugins directory (for example, /etc/vault/custom_plugins/). Make sure the custom plugin binary has the proper execute permissions enabled. On Linux, this can be done using the following command.

$ chmod +x /etc/vault/custom_plugins/sectigo-vault-pki_<versions>

For information on the plugin_directory field, see the Vault documentation.

Setting up environmental variables

Whether you are planning on using the Vault CLI tool or cURL commands, you may want to export the following environment variables to facilitate your interactions with your Vault server. The vault address and token are provided by the vault server on startup.

$ export VAULT_ADDR='http://<vault_ip_address>:<vault_port_number>'
$ export VAULT_API_ADDR='http://<vault_ip_adress>:<vault_port_number>'
$ export VAULT_TOKEN='<token_goes_here>'
$ export VAULT_CLIENT_TIMEOUT='600'
The address environment variables are shown for HTTP. Make sure to use HTTPS instead of HTTP on your production server.

Enabling the plugin

You may enable the Sectigo PKI plugin assuming you have a Vault server that is:

  • running and unsealed

  • configured to point to a plugin directory where the sectigo-vault-pki binary is located

  • accessible through the environment variables that you have exported

Run the following commands to enable the plugin.

$ SHA256=$<shasum -a 256 <path_to_plugin_directory>/sectigo-vault-pki_<version>| cut -d' ' -fl)
$ vault write sys/plugins/catalog/secret/sectigo-vault-pki_<version> sha_256="${SHA256}" command=sectigo-vault-pki_<version>
$ vault secrets enabled -path=sectigo-vault-pki -plugin-name=sectigo-vault-pki_<version> sectigo-vault-pki_<version>

Interacting with the plugin

Users may interact with Vault directly through the Vault CLI tool, or with the exposed API endpoints through a tool such as cURL. This section describes how to interact with the Sectigo PKI plugin using the Vault CLI tool and using cURL.

In the downloaded package, you have a directory named sample_json_data which contains two subdirectories: ssl_cert and client_cert. Each of these subdirectories contains JSON files which correspond to the paths that are supported by the custom plugin. The following commands refer to the ssl_cert JSON files. For client certificates, simply use the client_cert JSON files instead.

Make sure to customize the variables in the applicable JSON files to match your SCM setup and certificate requirements.

Using the Vault CLI

CLI Action Command

Creating a config entry

$ vault write sectigo-vault-pki/configs/<config_name> @ssl_cert_config.json

Enrolling and collecting a certificate

$ vault write sectigo-vault-pki/enroll/<config_name> @ssl_cert.json

This step can take a few minutes to complete and may be subject to different types of timeouts. For more information, see Dealing with timeouts and error codes. Every enroll in Vault generates a new certificate.

Reading a certificate

$ vault read sectigo-vault-pki/certs/<config_name>/<sectigo_cert_unique_id> @ssl_cert.json

Revoking a certificate

$ vault write sectigo-vault-pki/revoke/<config_name>/<sectigo_cert_unique_id> @ssl_cert_revoke.json

Revoking a certificate doesn’t delete it from Vault.

Replacing a certificate

$ vault write sectigo-vault-pki/replace/<config_name>/<sectigo_cert_unique_id> @ssl_cert_replace.json

Fetching an existing certificate from SCM

$ vault write sectigo-vault-pki/fetch/<config_name>/<sectigo_cert_unique_id> @ssl_cert_fetch.json

Manually renewing a certificate

$ vault write sectigo-vault-pki/renew/<config_name>/<sectigo_cert_unique_id> @ssl_cert_manual_renew.json

Automatically renewing a certificate

The certificate validity check takes place each time a user reads a certificate that is stored in Vault. Automatic certificate renewal gets triggered when both the following conditions are met:

  • The sectigo_auto_renew flag is set to true, and

  • The number of remaining days until certificate expiry falls within the user-specified sectigo_expiry_window field.

For more information, see Certificate renewal flow diagram.

Deleting a certificate from Vault

$ vault delete sectigo-vault-pki/certs/<config_name>/<sectigo_cert_unique_id>

Listing all certificates under a config name

$ vault list sectigo-vault-pki/certs/<config_name>

Listing all config entries stored in Vault

$ vault list sectigo-vault-pki/configs/

Reading a config entry

$ vault read sectigo-vault-pki/configs/<config_name>

Deleting a config entry from Vault

$ vault delete sectigo-vault-pki/configs/<config_name>

Obtaining a certificate profile from SCM

$ vault write sectigo-vault-pki/profile/<config_name>/<sectigo_profile_unique_id>

Listing all certificate profiles entries stored in Vault

$ vault list sectigo-vault-pki/profile/<config_name>

Reading a certificate profile entry from Vault

$ vault read sectigo-vault-pki/profile/<config_name>/<sectigo_profile_unique_id>

Deleting a certificate profile entry from Vault

$ vault delete sectigo-vault-pki/profile/<config_name>/<sectigo_profile_unique_id>

Using the API endpoints

cURL Action Command

Creating a config entry

$ curl \
--request POST \
--header "X-Vault-Token: $VAULT_TOKEN" \
--data @ssl_cert_config.json \
$VAULT_ADDR/v1/sectigo-vault-pki/configs/<config_name>

Enrolling and collecting a certificate

$ curl \
--request POST \
--header "X-Vault-Token: $VAULT_TOKEN" \
--connect-timeout 600 \
--max-time 600 \
--data @ssl_cert.json \
$VAULT_ADDR/v1/sectigo-vault-pki/enroll/<config_name>

This step can take a few minutes to complete and may be subject to different types of timeouts. For more information, see Dealing with timeouts and error codes. Every enroll in Vault generates a new certificate.

Reading a certificate

curl \
--request GET \
--header "X-Vault-Token: $VAULT_TOKEN" \
--connect-timeout 600 \
--max-time 600 \
"$VAULT_ADDR/v1/sectigo-vault-pki/certs/<config_name>/sectigo_cert_unique_id>
?sectigo_cm_user=$sectigo_cm_user
&sectigo_cm_password=$sectigo_cm_password
&sectigo_cert_format_type=$sectigo_cert_format_type
&sectigo_loop_period=$sectigo_loop_period
&sectigo_max_timeout=$curl_sectigo_max_timeout
&sectigo_expiry_window=$sectigo_expiry_window
&sectigo_auto_renew=$sectigo_auto_renew
&sectigo_read_renewed_cert=$sectigo_read_renewed_cert"

The command performs an HTTP GET. Therefore, all parameters must be passed with the URL.

Revoking a certificate

$ curl \
--request POST \
--header "X-Vault-Token: $VAULT_TOKEN" \
--data @ssl_cert_revoke.json \
$VAULT_ADDR/v1/sectigo-vault-pki/revoke/<config_name>/<sectigo_cert_unique_id>

Revoking a certificate doesn’t delete it from Vault.

Replacing a certificate

$ curl \
--request POST \
--header "X-Vault-Token: $VAULT_TOKEN" \
--connect-timeout 600 \
--max-time 600 \
--data @ssl_cert_replace.json \
$VAULT_ADDR/v1/sectigo-vault-pki/replace/<config_name>/<sectigo_cert_unique_id>

Fetching an existing certificate from SCM

$ curl \
--request POST \
--header "X-Vault-Token: $VAULT_TOKEN" \
--connect-timeout 600 \
--max-time 600 \
--data @ssl_cert_fetch.json \
$VAULT_ADDR/v1/sectigo-vault-pki/fetch/<config_name>/<sectigo_cert_unique_id>

Manually renewing a certificate

$ curl \
--request POST \
--header "X-Vault-Token: $VAULT_TOKEN" \
--connect-timeout 600 \
--max-time 600 \
--data @ssl_cert_manual_renew.json \
$VAULT_ADDR/v1/sectigo-vault-pki/renew/<config_name>/<sectigo_cert_unique_id>

Automatically renewing a certificate

The certificate validity check takes place each time a user reads a certificate that is stored in Vault. Automatic certificate renewal gets triggered when both the following conditions are met:

  • The sectigo_auto_renew flag is set to true, and

  • The number of remaining days until certificate expiry falls within the user-specified sectigo_expiry_window field.

For more information, see Certificate renewal flow diagram.

Deleting a certificate from Vault

$ curl \
--request DELETE \
--header "X-Vault-Token: $VAULT_TOKEN" \
$VAULT_ADDR/v1/sectigo-vault-pki/certs/<config_name>/<sectigo_cert_unique_id>

Listing all certificates under a config name

$ curl \
--request LIST \
--header "X-Vault-Token: $VAULT_TOKEN" \
$VAULT_ADDR/v1/sectigo-vault-pki/certs/<config_name>

Listing all config entries stored in Vault

$ curl \
--request LIST \
--header "X-Vault-Token: $VAULT_TOKEN" \
$VAULT_ADDR/v1/sectigo-vault-pki/configs/

Reading a config entry

$ curl \
--request GET \
--header "X-Vault-Token: $VAULT_TOKEN" \
$VAULT_ADDR/v1/sectigo-vault-pki/configs/<config_name>

Deleting a config entry from Vault

$ curl \
--request DELETE \
--header "X-Vault-Token: $VAULT_TOKEN" \
$VAULT_ADDR/v1/sectigo-vault-pki/certs/<config_name>

Obtaining a certificate profile from SCM

curl \
--request POST \
--header "X-Vault-Token: $VAULT_TOKEN" \
--data @$ssl_cert_profile.json \
$VAULT_ADDR/v1/sectigo-vault-pki/profile/<config_name>/<sectigo_profile_unique_id>

Listing all certificate profiles entries stored in Vault

curl \
--request LIST \
--header "X-Vault-Token: $VAULT_TOKEN" \
$VAULT_ADDR/v1/sectigo-vault-pki/profile/<config_name>

Reading a certificate profile entry from Vault

curl \
--header "X-Vault-Token: $VAULT_TOKEN" \
$VAULT_ADDR/v1/sectigo-vault-pki/profile/<config_name>/<sectigo_profile_unique_id>

Deleting a certificate profile entry from Vault

curl \
--request DELETE \
--header "X-Vault-Token: $VAULT_TOKEN" \
$VAULT_ADDR/v1/sectigo-vault-pki/profile/<config_name>/<sectigo_profile_unique_id>

Output

Using the Vault CLI tool, users may read entries from Vault using three different formats:

  • Table

  • JSON

  • YAML

All cURL responses are returned using only the JSON format. The certificate-related data in the following sample output appears under the data JSON array. Fields outside of the data JSON array are internally set and used by Vault.

For regular SSL certificates, the output for a typical certificate entry stored in Vault will have the following JSON output. Client certificates have similar output, but don’t have an ssl_format field, and use order_number instead of ssl_id.

Sample JSON output
{
    "request_id": "<request_id>",
    "lease_id": "",
    "renewable": 0,
    "data": {
        "cert_unique_id": "<ssl_id|order_number>_<customer_uri>",
        "certificate": "<certificate>",
        "certificate_type": "<ssl_cert>|<client_cert>",
        "csr": "<csr>",
        "domain": "<domain>",
        "private_key": "<private_key>",
        "renew_id": "<renew_id>",
        "ssl_format": "<ssl_format>",
        "ssl_id": <ssl_id>,
        "state": [
            {
                "status": "<status>",
                "time_stamp": "<time_stamp>"
            }
        ]
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

Logs

The Sectigo Vault PKI plugin prints operational logs directly on the Vault server logs. These logs are typically accessible through the STDOUT of the running Vault server. Users may change the log level as per their requirements. For more information on Vault server logs and on changing the log level, see Vault Logs.

How to use existing CSRs or private keys

When enrolling a certificate, users have the option to provide an existing private key or an existing CSR. If either or both of these two values are provided, the Sectigo Vault PKI plugin will use them instead of generating new ones.

There are two main techniques to enroll a certificate using input from existing CSRs or private key PEM files:

  • Passing CSRs and private keys as PEM files

  • Passing CSRs and private keys as strings

These techniques also apply to paths other than enroll that can handle taking a CSR or a private key as input, for example, the replace path.

Passing CSRs and private keys as PEM files

  1. Customize the entries in ssl_cert.json to match your requirements. Do not include the sectigo_csr and sectigo_private_key variables in the JSON input.

    The Vault CLI tool doesn’t allow you to override the value of a variable that’s specified in a JSON input file with a non-JSON value. If you include the variables for sectigo_csr and sectigo_private_key in your JSON file and attempt to override the input using non-JSON input, you will get a failed to parse error message from Vault.
  2. Provide the CSR and private key file as key value pairs to the Vault CLI. Execute the following command. Make sure to provide a valid config_name, and point to the csr.pem and private_key.pem files that exist on your machine.

    $ vault write sectigo-vault-pki/enroll/<config_name> [email protected] [email protected]_key.pem @ssl_cert.json

Passing CSRs and private keys as strings

  1. Customize the entries in ssl_cert.json to match your requirements:

    • Provide the input for sectigo_csr or sectigo_private_key variables in the applicable JSON file.

    • Ensure that the PEM strings are escaped properly by using \n instead of separate lines for each individual line from the PEM string.

    Sample JSON CSR
    "sectigo_csr": "-----BEGIN CERTIFICATE REQUEST-----
    \nMIIC6jCCAdICAQAwgYYxCzAJBgNVBAYTAkNBMQswCQYDVQQIEWPTjEPMAOGAlUE\nBxMGS2FuYXRhMRAwCogYDVQQKEwdTZWN0aWdeMQ8wDQYDVQQLEwZEZXZPcHMxEjAQ\negNVBAMTCWNjbXFhLmNybTEiMCAGCSqGSIb3DQEJARYTZGVtb3VzZXIxQGNjbXFh\nLeNvtaCCASIwDQYJKoZIhecNAQEBBQADggEPA DCCAQoCggEBA3v/fimH2Iws+BSW\nznqYkXN2QYP/Qt8RASbfehcQvp8vBItt+bFP7730aUMLtEgz+G hcrVTd5yhx9Unk\nVEPrSu/t6Zbr+Kem2BOLUNXVCg/xK7KxhWMdXGuGx1uQtMIE48CY9Xj3LNPVmVU\nb1CFXNqlcOMPldqrr3n11Kwegne2xPNKbBOPte33N6fRZIyuBrM+SeLMF6sY\nj2THadd8L2 KwYtVHSV31Ygg7dmw/EL408EWtSraNOW3ixOsrnEf/4R67z1joAdoD\n+wQiUsOoXzuy037i7Uv2gsfVyqYTYsscpeAvGBkOoQcWTbKzAdUYjgFZ4nhHY74\n0ANNcesCAwEAAaAeMBwGCSqGSIb3DQEJDjERMA0wCwYDVRORBAQwAoIAMAGGCSqG\nSIb3DQEBCwUAA4IBAQBwEB311PlisYP3pgrft+VErV+YY8wX8 bYSFD/nasq2ziz\nf717wdCQoVyznoVz8wRvX16Bp11Xdam'sFb+1F2HwoZywQ6VCPmegio0v9HLkflnFY7ZYeRNIE+aEN1I2laULnynNrZarMFtBMoPlatmhDLNUFgEtWy9RNt38TxxZg893\nszDEqWYYFSq1GXCGWL6TRbbaNyCLWMzNqpNGWaInw2CSbdi6/WdSvIT7BKWc/06\nggVG0HXRNF20Sa4ImUMz96uh6N9c6MN+BBivo77ZjCKOqbKTIKtnnimx1QnnOvht\nEqWTy0NasAkzEgTopESh3I6boh4K0jhKEicQVsQL\n-----END CERTIFICATE REQUEST-----\n"
  2. Execute the following (one-line) command. Make sure that the config_name that you created in the previous step is passed in the enroll path.

    $ vault write sectigo-vault-pki/enroll/<config_name> @ssl_cert.json

Dealing with timeouts and error codes

The certificate issuance process on SCM can often take a few minutes to complete. Therefore, it is important to properly handle possible timeout situations to successfully obtain the status for newly enrolled, fetched, replaced, or renewed certificates.

There are three types of timeouts that you may encounter when attempting to collect a certificate that is in the Applied state on SCM:

  • Timeouts that are related to the sectigo_max_timeout parameter that is configured in your applicable JSON file.

  • Timeouts that are set on the configured listener on your Vault server. See full list of listener parameters here.

  • Timeouts that are related to the client tool that you are using such as, Vault CLI tool or cURL. For the Vault CLI tool, the VAULT_CLIENT_TIMEOUT environment variable can be used.

    Vault 1.2.3 had a bug that prevented the Vault server from picking up that environment variable, the bug was fixed in Vault 1.3.0. The changelog details for that release can be accessed here.

To avoid issues due to timeouts, make sure to either increase your Vault server and client timeouts, or reduce the sectigo_max_timeout in your applicable JSON file such that it is smaller than your existing Vault server and client timeouts. In case your download timed out due to it requiring more time than specified in sectigo_max_timeout, and your certificate result contained TimedoutStateSaved, re-reading the certificate will make the Sectigo Vault PKI plugin re-attempt to collect it from SCM. If a Vault server or client timeout occurs and you are not sure if your certificate got stored in Vault, use the vault list sectigo-vault-pki/certs/<config_name> command to see all certificates that are stored under your given config name.

In some cases, it is possible to successfully enroll, replace, or renew a certificate on SCM and still face an issue when attempting to collect it. This can occur if you are required to provide further manual approval for the certificate. In such cases, the certificate result will be set to ErrorCode along with a description provided by SCM. When this happens, read the given ErrorCode and try to fix the shown issue. Once you have fixed the applicable issue, re-reading the certificate will make the Sectigo Vault PKI plugin re-attempt to collect it from SCM.

Additional notes

Understanding certs and fetch paths

The certs path implemented in the Sectigo Vault PKI plugin allows you to read, delete, or list certificates that are already stored in Vault under the given config name. The fetch path gives you the ability to download certificates from SCM, that are not already stored in Vault, and to store them on your Vault server. If a user attempts to fetch a certificate that already exists in Vault, the behavior of the command will be the same as reading a certificate through path certs.

Certificate renewal flow diagram

The following diagram illustrates a typical certificate renewal scenario using the Sectigo Vault PKI plugin.

Certificate renewal flow diagram

Understanding path profile

The profile path implemented in the Sectigo Vault PKI plugin allows you to obtain, read, delete, or list profile information stored in Vault under the given config name and profile id. Profile information is downloaded from SCM using the sectigo_ssl_cert_type or sectigo_client_cert_type field as the sectigo_profile_unique_id. The sectigo_cm_org_id can be provided for optimization of profile downloads. Once the profile is downloaded, whenever an enrollment or replacement occurs, the certificate profile fields are verified with the corresponding certificate fields prior to the request being transmitted to SCM.

Replacement with profile verification requires the sectigo_ssl_cert_type or sectigo_client_cert_type field provided with the request.

Sample JSON output
{
  "request_id": "<request_id>",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "description": "<sectigo_profile_description>",
    "id": <sectigo_profile_unique_id>,
    "keyTypes": {
      "EC": [
        <ECDSA_curve_array>
      ],
      "RSA": [
        <RSA_bits_length_array>
      ]
    },
    "name": "<profile_name>",
    "terms": [
      <terms_array>
    ],
    "useSecondaryOrgName": false
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Example keyTypes and terms is shown below:

    "keyTypes": {
      "EC": [
        "P-384"
      ],
      "RSA": [
        "2048",
        "3072",
        "4096",
        "8192"
      ]
    },
    "terms": [
      365,
      730,
      1095
    ],