• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Vault
  • Install
  • Tutorials
  • Documentation
  • API
  • Integrations
  • Try Cloud(opens in new tab)
  • Sign up
Vault Home

Documentation

Skip to main content
  • Documentation
  • What is Vault?
  • Use Cases

  • Browser Support
  • Installing Vault

    • Overview
    • Active Directory
    • AliCloud
    • AWS
    • Azure
    • Consul
    • Cubbyhole
    • Google Cloud
    • Google Cloud KMS
    • KMIP
      ENTERPRISEENTERPRISE
    • Kubernetes
    • MongoDB Atlas
    • Nomad
    • LDAP
      • Overview
      • Setup and Usage
      • Quick Start - Root CA Setup
      • Quick Start - Intermediate CA Setup
      • Considerations
      • Rotation Primitives
    • RabbitMQ
    • Terraform Cloud
    • TOTP
    • Venafi (Certificates)
  • Vault Integration Program
  • Vault Interoperability Matrix
  • Troubleshoot






  • Glossary


  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Vault
  3. Documentation
  4. Secrets Engines
  5. PKI (Certificates)
  6. Setup and Usage
  • Vault
  • v1.11.x
  • v1.10.x
  • v1.9.x
  • v1.8.x
  • v1.7.x
  • v1.6.x
  • v1.5.x
  • v1.4.x

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

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

  2. Increase the TTL by tuning the secrets engine. The default value of 30 days may be too short, so increase it to 1 year:

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

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

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

  4. Update the CRL location and issuing certificates. These values can be updated in the future.

    $ 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
    
  5. 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:

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

    $ 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) guide for a step-by-step tutorial.

Have a look at the PKI Secrets Engine with Managed Keys 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 for more details.

Edit this page on GitHub

On this page

  1. PKI Secrets Engine - Setup and Usage
  2. Setup
  3. Usage
  4. Tutorial
  5. API
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)