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