Overview

The Sectigo HashiCorp Vault connector ("the connector" or "the plugin") provides a seamless solution for the enrollment, collection, revocation, renewal, and replacement of SSL/TLS and client (S/MIME) certificates issued through Sectigo Certificate Manager (SCM). It also 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.

The connector is distributed as a custom HashiCorp Vault (Vault) PKI plugin. It provides the following features:

  • Supported key types:

    • RSA 2048, 3072, and 4096-bit

    • ECDSA P256, P384, and P521

  • 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

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 then interacts 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.

Additional resources

Architecture

Integration Diagram

Path endpoints

The connector 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. The 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 Using the Vault CLI.

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 Vault documentation.

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
    "keyTypes": {
      "EC": [
        "P-384"
      ],
      "RSA": [
        "2048",
        "3072",
        "4096",
        "8192"
      ]
    },
    "terms": [
      365,
      730,
      1095
    ],

Package contents

The Sectigo HashiCorp Vault connector package contains the following:

  • sectigo-vault-pki:

    • sectigo-vault-pki_<version>: The Sectigo Vault PKI plugin (binary file) 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