121 lines
4 KiB
Plaintext
121 lines
4 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: 'PKI - Secrets Engines: Setup and Usage'
|
|
description: The PKI secrets engine for Vault generates TLS certificates.
|
|
---
|
|
|
|
# PKI Secrets Engine - Setup and Usage
|
|
|
|
This document provides a brief overview of the setup and usage of the PKI
|
|
Secrets Engine.
|
|
|
|
## Setup
|
|
|
|
Most secrets engines must be configured in advance before they can perform their
|
|
functions. These steps are usually completed by an operator or configuration
|
|
management tool.
|
|
|
|
1. Enable the PKI secrets engine:
|
|
|
|
```text
|
|
$ vault secrets enable pki
|
|
Success! Enabled the pki secrets engine at: pki/
|
|
```
|
|
|
|
By default, the secrets engine will mount at the name of the engine. To
|
|
enable the secrets engine at a different path, use the `-path` argument.
|
|
|
|
1. Increase the TTL by tuning the secrets engine. The default value of 30 days may be too short, so increase it to 1 year:
|
|
|
|
```text
|
|
$ vault secrets tune -max-lease-ttl=8760h pki
|
|
Success! Tuned the secrets engine at: pki/
|
|
```
|
|
|
|
Note that individual roles can restrict this value to be shorter on a
|
|
per-certificate basis. This just configures the global maximum for this
|
|
secrets engine.
|
|
|
|
1. Configure a CA certificate and private key. Vault can accept an existing key
|
|
pair, or it can generate its own self-signed root. In general, we recommend
|
|
maintaining your root CA outside of Vault and providing Vault a signed
|
|
intermediate CA.
|
|
|
|
```text
|
|
$ vault write pki/root/generate/internal \
|
|
common_name=my-website.com \
|
|
ttl=8760h
|
|
|
|
Key Value
|
|
--- -----
|
|
certificate -----BEGIN CERTIFICATE-----...
|
|
expiration 1536807433
|
|
issuing_ca -----BEGIN CERTIFICATE-----...
|
|
serial_number 7c:f1:fb:2c:6e:4d:99:0e:82:1b:08:0a:81:ed:61:3e:1d:fa:f5:29
|
|
```
|
|
|
|
The returned certificate is purely informative. The private key is safely
|
|
stored internally in Vault.
|
|
|
|
1. Update the CRL location and issuing certificates. These values can be updated
|
|
in the future.
|
|
|
|
```text
|
|
$ vault write pki/config/urls \
|
|
issuing_certificates="http://127.0.0.1:8200/v1/pki/ca" \
|
|
crl_distribution_points="http://127.0.0.1:8200/v1/pki/crl"
|
|
Success! Data written to: pki/config/urls
|
|
```
|
|
|
|
1. Configure a role that maps a name in Vault to a procedure for generating a
|
|
certificate. When users or machines generate credentials, they are generated
|
|
against this role:
|
|
|
|
```text
|
|
$ vault write pki/roles/example-dot-com \
|
|
allowed_domains=my-website.com \
|
|
allow_subdomains=true \
|
|
max_ttl=72h
|
|
Success! Data written to: pki/roles/example-dot-com
|
|
```
|
|
|
|
## Usage
|
|
|
|
After the secrets engine is configured and a user/machine has a Vault token with
|
|
the proper permission, it can generate credentials.
|
|
|
|
1. Generate a new credential by writing to the `/issue` endpoint with the name
|
|
of the role:
|
|
|
|
```text
|
|
$ vault write pki/issue/example-dot-com \
|
|
common_name=www.my-website.com
|
|
|
|
Key Value
|
|
--- -----
|
|
certificate -----BEGIN CERTIFICATE-----...
|
|
issuing_ca -----BEGIN CERTIFICATE-----...
|
|
private_key -----BEGIN RSA PRIVATE KEY-----...
|
|
private_key_type rsa
|
|
serial_number 1d:2e:c6:06:45:18:60:0e:23:d6:c5:17:43:c0:fe:46:ed:d1:50:be
|
|
```
|
|
|
|
The output will include a dynamically generated private key and certificate
|
|
which corresponds to the given role and expires in 72h (as dictated by our
|
|
role definition). The issuing CA and trust chain is also returned for
|
|
automation simplicity.
|
|
|
|
## Tutorial
|
|
|
|
Refer to the [Build Your Own Certificate Authority (CA)](https://learn.hashicorp.com/vault/secrets-management/sm-pki-engine)
|
|
guide for a step-by-step tutorial.
|
|
|
|
Have a look at the [PKI Secrets Engine with Managed Keys](https://learn.hashicorp.com/tutorials/vault/managed-key-pki?in=vault/enterprise)
|
|
for more about how to use externally managed keys with PKI.
|
|
|
|
## API
|
|
|
|
The PKI secrets engine has a full HTTP API. Please see the
|
|
[PKI secrets engine API](/api-docs/secret/pki) for more
|
|
details.
|