Configuring the plugin

This page describes how to configure the the Sectigo Vault PKI plugin.

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.

Configuring the plugin directory

Vault servers in development mode can use -dev-plugin-dir to specify the path to the plugin. For example:

vault server -dev -dev-plugin-dir="/etc/vault/plugins"

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='<vault_token>'

$ 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' ' -f1)

$ vault write sys/plugins/catalog/secret/sectigo-vault-pki_<version> sha_256="${SHA256}" command=sectigo-vault-pki_<version>

$ vault secrets enable -path=sectigo-vault-pki -plugin-name=sectigo-vault-pki_<version> sectigo-vault-pki_<version>

Configuration parameters

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.

The sectigo_cm_user and sectigo_cm_password parameters are now supported in both the config and profile JSON files. If specified in both files, the profile file will override.

Config parameters

Parameter Type Description

sectigo_cm_user

Mandatory

The user ID to access your URL. This parameter is supported in both the config and profile JSON files.

sectigo_cm_password

Mandatory

The password to access your URL. This parameter is supported in both the config and profile JSON files.

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

sectigo_cm_base_url

Mandatory

The base url of the Sectigo Certificate Authority

Profile 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/province 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.

The possible values are RSA or ECDSA. The default value is 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 (default)

  • 3072

  • 4096

Required if sectigo_csr_key_algo is RSA.

Required if sectigo_csr is not provided.

sectigo_csr_curve_length

Conditional

The elliptical curve cipher (ECC) of the SSL/TLS keys to generate. The possible values are:

  • P256

  • P384

  • P251

Required if sectigo_csr_key_algo is ECDSA.

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.

Profile 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 don’t 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. This is the ID of the SSL certificate type.

sectigo_ssl_cert_validity

Mandatory

The certificate validity period in days. 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

sectigo_ssl_cert_server_type

Optional

The server type ID

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. This is the ID of the client certificate type.

sectigo_client_cert_validity

Mandatory

The certificate validity period in days. 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 <client_cert_id>_<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.