Sectigo.com
Shop Enterprise Partners Resources

Using 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

Create a config entry

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

Enroll and collect 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.

Read a certificate

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

Read a certificate from the Vault local storage

 
$ vault read sectigo-vault-pki/readcert/<config_name>/<sectigo_cert_unique_id>

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

Replace a certificate

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

Fetch an existing certificate from SCM

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

Manually renew a certificate

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

Automatically renew 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.

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

Delete a certificate from Vault

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

List all certificates under a config name

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

List all config entries stored in Vault

 
$ vault list sectigo-vault-pki/configs/

Read a config entry

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

Delete a config entry from Vault

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

Obtain a certificate profile from SCM

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

List all certificate profiles entries stored in Vault

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

Read a certificate profile entry from Vault

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

Delete 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

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

Enroll and collect 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.

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

Read a certificate from the Vault local storage

 
curl \
--request GET \
--header "X-Vault-Token: $VAULT_TOKEN" \
--connect-timeout 600 \
--max-time 600 \
$VAULT_ADDR/v1/sectigo-vault-pki/readcert/<config_name>/<sectigo_cert_unique_id> | jq

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

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

Fetch 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 renew 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 renew 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.

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

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

List all certificates under a config name

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

List all config entries stored in Vault

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

Read a config entry

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

Delete a config entry from Vault

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

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

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

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

Delete 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] sectigo_private_key=@private_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.