--- layout: docs page_title: Venafi - Secrets Engines 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.