open-vault/website/content/docs/secrets/venafi.mdx

---
layout: docs
page_title: Venafi - Secrets Engines
sidebar_title: Venafi (Certificates)
description: The Venafi integrated secrets engine for Vault.
---

# Venafi Secrets Engine for HashiCorp Vault

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](https://www.venafi.com/platform/trust-protection-platform)
or [Venafi Cloud](https://www.venafi.com/venaficloud) 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](/docs/internals/plugins)
and Venafi's [VCert Client SDK](https://github.com/Venafi/vcert). 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](https://github.com/Venafi/vault-pki-backend-venafi) 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](https://docs.venafi.cloud/help/Default.htm).
- Create a project and zone that identifies the template and other information.
  To learn more, search for "Projects" in the
  [Venafi Cloud Help system](https://docs.venafi.cloud/help/Default.htm).

## Setup

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

1. Create the [directory](/docs/internals/plugins#plugin-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.

1. Download the latest `vault-pki-backend-venafi`
   [release package](https://github.com/Venafi/vault-pki-backend-venafi/releases/latest)
   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.

   ```text
   $ wget https://github.com/Venafi/vault-pki-backend-venafi/releases/download/v0.0.1/venafi-pki-backend_v0.0.1+1_linux.zip
   $ unzip venafi-pki-backend_v0.0.1+1_linux.zip
   $ mv venafi-pki-backend /etc/vault/vault_plugins
   ```

1. Update the Vault [server configuration](/docs/configuration/)
   to specify the plugin directory:

   ```text
   plugin_directory = "/etc/vault/vault_plugins"
   ```

1. Start your Vault using the [server command](/docs/commands/server).

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

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

1. Register the `venafi-pki-backend` plugin in the Vault
   [system catalog](/docs/internals/plugins#plugin-catalog):

   ```text
   $ vault write sys/plugins/catalog/secret/venafi-pki-backend \
       sha_256="${SHA256}" command="venafi-pki-backend"
   Success! Data written to: sys/plugins/catalog/secret/venafi-pki-backend
   ```

1. Enable the Venafi secrets engine:

   ```text
   $ vault secrets enable -path=venafi-pki -plugin-name=venafi-pki-backend plugin
   Success! Enabled the pki-backend-venafi secrets engine at: venafi-pki/
   ```

1. Configure a Venafi secret that maps a name in Vault to connection and authentication
   settings for enrolling certificate 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](https://github.com/Venafi/vcert/blob/master/README-CLI-PLATFORM.md#obtaining-an-authorization-token)
   (`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"
   Success! Data written to: venafi-pki/venafi/tpp
   ```

   **Venafi Cloud**:

   ```
   $ vault write venafi-pki/venafi/cloud \
       apikey="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
       zone="zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
   Success! Data written to: venafi-pki/roles/cloud
   ```

1. Lastly, configure a [role](/docs/secrets/pki)
   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**:

   ```text
   $ vault write venafi-pki/roles/tpp \
       venafi_secret=tpp \
       store_by=serial store_pkey=true \
       allowed_domains=example.com \
       allow_subdomains=true
   Success! Data written to: venafi-pki/roles/tpp
   ```

   **Venafi Cloud**:

   ```text
   $ vault write venafi-pki/roles/cloud \
       venafi_secret=cloud \
       store_by=serial store_pkey=true \
       allowed_domains=example.com \
       allow_subdomains=true
   Success! Data written to: venafi-pki/roles/cloud
   ```

## 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`.

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

   **Trust Protection Platform**:

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

   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**:

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

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

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

   **Trust Protection Platform**:

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

   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**:

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

   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](/api/secret/pki)
as the built-in PKI secrets engine. Some methods, such as those for
managing certificate authorities, do not apply.