luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases Activity
open-vault/website/content/docs/secrets/venafi.mdx
Yoko Hyakuna f374938d31
Fix broken links referencing to API docs (#14565) 
* Fix all '/api/' to '/api-docs/'

* Minor fixes

* Undo some of the unintentional changes
2022-03-17 18:14:48 -07:00

306 lines
12 KiB
Plaintext
Raw Blame History

---
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-docs/secret/pki)
as the built-in PKI secrets engine. Some methods, such as those for
managing certificate authorities, do not apply.
Reference in a new issue View git blame Copy permalink