»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 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 been granted REST API (WebSDK) access.

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

  1. 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.

  2. 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.

    $ 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
    
  3. Update the Vault server configuration to specify the plugin directory:

    plugin_directory = "/etc/vault/vault_plugins"
    
  4. Start your Vault using the server command.

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

    $ SHA256=$(sha256sum /etc/vault/vault_plugins/venafi-pki-backend| cut -d' ' -f1)
    
  6. Register the vault-pki-backend-venafi plugin in the Vault system catalog:

    $ vault write sys/plugins/catalog/secret/venafi-pki-backend \
        sha_256="${SHA256}" command="venafi-pki-backend"
    Success! Data written to: sys/plugins/catalog/secret/pki-backend-venafi
    
  7. Enable the Venafi secrets engine:

    $ vault secrets enable -path=venafi-pki -plugin-name=venafi-pki-backend plugin
    Success! Enabled the pki-backend-venafi secrets engine at: venafi-pki/
    
  8. Configure a role that maps a name in Vault to a procedure for enrolling certificate using Venafi. The zone is a policy folder for Trust Protection Platform or a DevOps project zone for Venafi Cloud. Avoid setting both store_by_serial and store_by_cn to true. To see other available options for the role after it is created, use vault path-help venafi-pki/roles/:name.

    Trust Protection Platform:

    $ vault write venafi-pki/roles/tpp \
        tpp_url="https://tpp.venafi.example/vedsdk" \
        tpp_user="local:admin" tpp_password="password" \
        zone="DevOps\\HashiCorp Vault" \
        trust_bundle_file="/opt/venafi/bundle.pem" \
        generate_lease=true store_by_serial=true store_pkey=true \
        allowed_domains=example.com \
        allow_subdomains=true
    Success! Data written to: venafi-pki/roles/tpp
    

    Venafi Cloud:

    $ vault write venafi-pki/roles/cloud \
        apikey="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
        zone="zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz" \
        generate_lease=true store_by_serial=true 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.

  1. 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"
    
    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"
    
    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
    
  2. 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
    
    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
    
    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.