Venafi secrets engine

The Venafi Machine Identity Secrets Engine provides applications with the ability to dynamically generate SSL/TLS certificates that serve as machine identities. Using Venafi Trust Protection Platform or Venafi Cloud assures compliance with enterprise policy and consistency with industry standard trust protection. Designed for high performance with the same interface as the built-in PKI secrets engine, services can get certificates without manually generating a private key and CSR, submitting to a certificate authority, and waiting for a verification and signing process to complete. Venafi's certificate authority integrations and policy controls, combined with Vault's built-in authentication and authorization mechanisms, provide the verification functionality.

Like the built-in PKI secrets engine, short-lived certificates for ephemeral workloads are the primary focus of the Venafi secrets engine. As such, revocation is not currently supported.

The Venafi secrets engine makes use of HashiCorp Vault's plugin system and Venafi's VCert Client SDK. If you have questions about the Venafi secrets engine, have an issue to report, or have developed improvements that you want to contribute, visit the GitHub repository.

Considerations

To successfully deploy this secrets engine, there are some important considerations. Before using Venafi secrets engine, you should read every consideration.

Venafi trust protection platform requirements

Your certificate authority (CA) must be able to issue a certificate in under one minute. Microsoft Active Directory Certificate Services (ADCS) is a popular choice. Other CA choices may have slightly different requirements.

Within Trust Protection Platform, configure these settings. For more information see the Venafi Administration Guide.

A user account that has an authentication token for the "Venafi Secrets Engine for HashiCorp Vault" (ID "hashicorp-vault-by-venafi") API Application as of 20.1 (or scope "certificate:manage" for 19.2 through 19.4) or has been granted WebSDK Access (deprecated)
A Policy folder where the user has the following permissions: View, Read, Write, Create.
Enterprise compliant policies applied to the folder including:
- Subject DN values for Organizational Unit (OU), Organization (O), City/Locality (L), State/Province (ST) and Country (C).
- CA Template that Trust Protection Platform will use to enroll general certificate requests.
- Management Type not locked or locked to 'Enrollment'.
- Certificate Signing Request (CSR) Generation unlocked or not locked to 'Service Generated CSR'.
- Generate Key/CSR on Application not locked or locked to 'No'.
- (Recommended) Disable Automatic Renewal set to 'Yes'.
- (Recommended) Key Bit Strength set to 2048 or higher.
- (Recommended) Domain Whitelisting policy appropriately assigned.
NOTE: If you are using Microsoft ACDS, the CRL distribution point and Authority Information Access (AIA) URIs must start with an HTTP URI (non-default configuration). If an LDAP URI appears first in the X509v3 extensions, some applications will fail, such as NGINX ingress controllers. These applications aren't able to retrieve CRL and OCSP information.

Trust between Vault and trust protection platform

The Trust Protection Platform REST API (WebSDK) must be secured with a certificate. Generally, the certificate is issued by a CA that is not publicly trusted so establishing trust is a critical part of your setup.

Two methods can be used to establish trust. Both require the trust anchor (root CA certificate) of the WebSDK certificate. If you have administrative access, you can import the root certificate into the trust store for your operating system. If you don't have administrative access, or prefer not to make changes to your system configuration, save the root certificate to a file in PEM format (e.g. /opt/venafi/bundle.pem) and reference it using the trust_bundle_file parameter whenever you create or update a PKI role in your Vault.

Venafi Cloud requirements

If you are using Venafi Cloud, be sure to set up an issuing template, project, and any other dependencies that appear in the Venafi Cloud documentation.

Set up an issuing template to link Venafi Cloud to your CA. To learn more, search for "Issuing Templates" in the Venafi Cloud Help system.
Create a project and zone that identifies the template and other information. To learn more, search for "Projects" in the Venafi Cloud Help system.

Setup

Before certificates can be issued, you must complete these steps to configure the Venafi secrets engine:

Create the directory where your Vault server will look for plugins (e.g. /etc/vault/vault_plugins). The directory must not be a symbolic link. On macOS, for example, /etc is a link to /private/etc. To avoid errors, choose an alternative directory such as /private/etc/vault/vault_plugins.
Download the latest vault-pki-backend-venafi release package for your operating system. Unzip the binary to the plugin directory. Note that the URL for the zip file, referenced below, changes as new versions of the plugin are released. Replace the version (0.12.0) of the release in the command below to download the desired version.
```
$ wget https://github.com/Venafi/vault-pki-backend-venafi/releases/download/v0.12.0/venafi-pki-backend_v0.12.0_darwin.zip
$ unzip venafi-pki-backend_v0.12.0_darwin.zip
$ mv venafi-pki-backend /etc/vault/vault_plugins
```
Update the Vault server configuration to specify the plugin directory:
```
$ plugin_directory = "/etc/vault/vault_plugins"
```
Start your Vault using the server command.

Get the SHA-256 checksum of the venafi-pki-backend plugin binary:

$ SHA256=$(sha256sum /etc/vault/vault_plugins/venafi-pki-backend| cut -d' ' -f1)

$ vault write sys/plugins/catalog/secret/venafi-pki-backend \
sha_256="${SHA256}" command="venafi-pki-backend"

Enable the Venafi secrets engine:

$ vault secrets enable -path=venafi-pki -plugin-name=venafi-pki-backend plugin

Configure a Venafi secret that maps a name in Vault to connection and authentication settings for enrolling certificates using Venafi. The zone is a policy folder for Trust Protection Platform or a DevOps project zone for Venafi Cloud.
Obtain the access_token and refresh_token for Trust Protection Platform using the VCert CLI (getcred action with --client-id "hashicorp-vault-by-venafi" and --scope "certificate:manage") or the Platform's Authorize REST API method.
To see all options available for venafi secrets, use vault path-help venafi-pki/venafi/:name after creating the secret.
Trust Protection Platform:
```
$ vault write venafi-pki/venafi/tpp \
    url="https://tpp.venafi.example" \
    access_token="tn1PwE1QTZorXmvnTowSyA==" \
    refresh_token="MGxV7DzNnclQi9CkJMCXCg==" \
    zone="DevOps\\HashiCorp Vault" \
    trust_bundle_file="/path-to/bundle.pem"
```
Venafi Cloud:
```
$ vault write venafi-pki/venafi/cloud \
    apikey="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
    zone="zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
```

Lastly, configure a role that maps a name in Vault to a Venafi secret for enrollment. To see all options available for roles, including ttl, max_ttl and issuer_hint (for validity), use vault path-help venafi-pki/roles/:name after creating the role.

Trust Protection Platform:

$ vault write venafi-pki/roles/tpp \
    venafi_secret=tpp \
    store_by=serial store_pkey=true \
    allowed_domains=example.com \
    allow_subdomains=true

Venafi Cloud:

$ vault write venafi-pki/roles/cloud \
    venafi_secret=cloud \
    store_by=serial store_pkey=true \
    allowed_domains=example.com \
    allow_subdomains=true

The Venafi Secrets Engine on HCP Vault Dedicated currently supports Venafi Cloud or Trust Protection Platform instances secured using a certificate from a publicly trusted CA. Support for uploading a certificate signed by a private CA using trust_bundle_file parameter is not available on HCP Vault Dedicated and requires running a self-managed Vault to use.

Before certificates can be issued, you must complete these steps to configure the Venafi secrets engine:

Navigate to your HCP Vault Dedicated cluster's Integrations page within the HCP portal to add the Venafi secrets engine to your cluster.
After the Venafi plugin has been successfully added to your cluster, you can use the Vault CLI to configure the Venafi secrets engine for use.
Enable the Venafi secrets engine:
```
$ vault secrets enable -path=venafi-pki -plugin-name=venafi-pki-backend plugin
```
Configure a Venafi secret that maps a name in Vault to connection and authentication settings for enrolling certificates using Venafi. The zone is a DevOps project zone for Venafi Cloud.
To see all options available for venafi secrets, use vault path-help venafi-pki/venafi/:name after creating the secret.
Venafi Cloud:
```
$ vault write venafi-pki/venafi/cloud \
    apikey="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
    zone="zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
```
Lastly, configure a role that maps a name in Vault to a Venafi secret for enrollment. To see all options available for roles, including ttl, max_ttl and issuer_hint (for validity), use vault path-help venafi-pki/roles/:name after creating the role.
Venafi Cloud:
```
$ vault write venafi-pki/roles/cloud \
    venafi_secret=cloud \
    store_by=serial store_pkey=true \
    allowed_domains=example.com \
    allow_subdomains=true
```

Usage

After the Venafi secrets engine is configured and a user/machine has a Vault token with the proper permission, it can enroll certificates using Venafi. To see all of the options available when requesting a certificate, including ttl (for validity), key_password, and custom_fields, use vault path-help venafi-pki/issue/:role-name and vault path-help venafi-pki/sign/:role-name.

Generate a certificate by writing to the /issue endpoint with the name of the role:

Trust Protection Platform:

$ vault write venafi-pki/issue/tpp common_name="common-name.example.com" \
    alt_names="dns-san-1.example.com,dns-san-2.example.com"

Example output:

Key                  Value
---                  -----
lease_id             venafi-pki/issue/tpp/oLih42SCFzyjntxGc00vqmWH
lease_duration       719h49m55s
lease_renewable      false
certificate          -----BEGIN CERTIFICATE-----
certificate_chain    -----BEGIN CERTIFICATE-----
common_name          common-name.example.com
private_key          -----BEGIN RSA PRIVATE KEY-----
serial_number        1d:bc:a8:3c:00:00:00:05:5c:e8

Venafi Cloud:

$ vault write venafi-pki/issue/cloud common_name="common-name.example.com" \
    alt_names="dns-san-1.example.com,dns-san-2.example.com"

Example output:

Key                  Value
---                  -----
lease_id             venafi-pki/issue/cloud/1WCNvXKiwboWfRRfjzlPAwEi
lease_duration       167h59m58s
lease_renewable      false
certificate          -----BEGIN CERTIFICATE-----
certificate_chain    -----BEGIN CERTIFICATE-----
common_name          common-name.example.com
private_key          -----BEGIN RSA PRIVATE KEY-----
serial_number        17:47:8b:13:90:b8:3d:87:b0:dc:b6:9e:00:2b:87:02:c9:d3:1e:8a

Or sign a CSR from a file by writing to the /sign endpoint with the name of the role:

Trust Protection Platform:

$ vault write venafi-pki/sign/tpp csr=@example.req

Example output:

Key                  Value
---                  -----
lease_id             venafi-pki/sign/tpp/tQq3QNY45e4sJMqTTI9DXEGK
lease_duration       719h49m57s
lease_renewable      false
certificate          -----BEGIN CERTIFICATE-----
certificate_chain    -----BEGIN CERTIFICATE-----
common_name          common-name.example.com
serial_number        1d:c4:07:9a:00:00:00:05:5c:ea

Venafi Cloud:

$ vault write venafi-pki/sign/cloud csr=@example.req

Example output:

Key                  Value
---                  -----
lease_id             venafi-pki/sign/cloud/fF44FdMAjuCdC29w3Ff81hes
lease_duration       167h59m58s
lease_renewable      false
certificate          -----BEGIN CERTIFICATE-----
certificate_chain    -----BEGIN CERTIFICATE-----
common_name          common-name.example.com
serial_number        76:55:e2:14:de:c8:3f:e1:64:4a:fa:37:d4:6e:f5:ef:5e:4c:16:5b

API

Venafi Machine Identity Secrets Engine uses the same Vault API as the built-in PKI secrets engine. Some methods, such as those for managing certificate authorities, do not apply.