vault page title Signed SSH Certificates SSH Secrets Engines type an SSH CA signing key is generated or configured at the secrets engine s The signed SSH certificates is the simplest and most powerful in terms of mount layout docs setup complexity and in terms of being platform agnostic When using this

Answer:
---
layout: docs
page_title: Signed SSH Certificates - SSH - Secrets Engines
description: >-
  The signed SSH certificates is the simplest and most powerful in terms of

  setup complexity and in terms of being platform agnostic. When using this

  type, an SSH CA signing key is generated or configured at the secrets engine's
  mount.

  This key will be used to sign other SSH keys.
---

# Signed SSH certificates

The signed SSH certificates is the simplest and most powerful in terms of setup
complexity and in terms of being platform agnostic. By leveraging Vault's
powerful CA capabilities and functionality built into OpenSSH, clients can SSH
into target hosts using their own local SSH keys.

In this section, the term "**client**" refers to the person or machine
performing the SSH operation. The "**host**" refers to the target machine. If
this is confusing, substitute "client" with "user".

This page will show a quick start for this secrets engine. For detailed documentation
on every path, use `vault path-help` after mounting the secrets engine.

## Client key signing

Before a client can request their SSH key be signed, the Vault SSH secrets engine must
be configured. Usually a Vault administrator or security team performs these
steps. It is also possible to automate these actions using a configuration
management tool like Chef, Puppet, Ansible, or Salt.

### Signing key & role configuration

The following steps are performed in advance by a Vault administrator, security
team, or configuration management tooling.

1.  Mount the secrets engine. Like all secrets engines in Vault, the SSH secrets engine
    must be mounted before use.

    ```text
    $ vault secrets enable -path=ssh-client-signer ssh
    Successfully mounted 'ssh' at 'ssh-client-signer'!
    ```

    This enables the SSH secrets engine at the path "ssh-client-signer". It is
    possible to mount the same secrets engine multiple times using different
    `-path` arguments. The name "ssh-client-signer" is not special - it can be
    any name, but this documentation will assume "ssh-client-signer".

1.  Configure Vault with a CA for signing client keys using the `/config/ca`
    endpoint. If you do not have an internal CA, Vault can generate a keypair for
    you.

    ```text
    $ vault write ssh-client-signer/config/ca generate_signing_key=true
    Key             Value
    ---             -----
    public_key      ssh-rsa AAAAB3NzaC1yc2EA...
    ```

    If you already have a keypair, specify the public and private key parts as
    part of the payload:

    ```text
    $ vault write ssh-client-signer/config/ca \
        private_key="..." \
        public_key="..."
    ```

    Regardless of whether it is generated or uploaded, the client signer public
    key is accessible via the API at the `/public_key` endpoint or the CLI (see next step).

1.  Add the public key to all target host's SSH configuration. This process can
    be manual or automated using a configuration management tool. The public key is
    accessible via the API and does not require authentication.

    ```text
    $ curl -o /etc/ssh/trusted-user-ca-keys.pem http://127.0.0.1:8200/v1/ssh-client-signer/public_key
    ```

    ```text
    $ vault read -field=public_key ssh-client-signer/config/ca > /etc/ssh/trusted-user-ca-keys.pem
    ```

    Add the path where the public key contents are stored to the SSH
    configuration file as the `TrustedUserCAKeys` option.

    ```text
    # /etc/ssh/sshd_config
    # ...
    TrustedUserCAKeys /etc/ssh/trusted-user-ca-keys.pem
    ```

    Restart the SSH service to pick up the changes.

1.  Create a named Vault role for signing client keys.

    ~> **IMPORTANT NOTE:** Prior to Vault-1.9, if `"allowed_extensions"` is either empty or not specified in the role,
    Vault will assume permissive defaults: any user assigned to the role may specify any arbitrary
    extension values as part of the certificate request to the Vault server.
    This may have significant impact on third-party systems that rely on an `extensions` field for security-critical information.
    In those cases, consider using a template to specify default extensions, and explicitly setting
    `"allowed_extensions"` to an arbitrary, non-empty string if the field is empty or not set.

    Because of the way some SSH certificate features are implemented, options
    are passed as a map. The following example adds the `permit-pty` extension
    to the certificate, and allows the user to specify their own values for `permit-pty` and `permit-port-forwarding`
    when requesting the certificate.

    ```text
    $ vault write ssh-client-signer/roles/my-role -<<"EOH"
    {
      "algorithm_signer": "rsa-sha2-256",
      "allow_user_certificates": true,
      "allowed_users": "*",
      "allowed_extensions": "permit-pty,permit-port-forwarding",
      "default_extensions": {
        "permit-pty": ""
      },
      "key_type": "ca",
      "default_user": "ubuntu",
      "ttl": "30m0s"
    }
    EOH
    ```

### Client SSH authentication

The following steps are performed by the client (user) that wants to
authenticate to machines managed by Vault. These commands are usually run from
the client's local workstation.

1.  Locate or generate the SSH public key. Usually this is `~/.ssh/id_rsa.pub`.
    If you do not have an SSH keypair, generate one:

    ```text
    $ ssh-keygen -t rsa -C "user@example.com"
    ```

1.  Ask Vault to sign your **public key**. This file usually ends in `.pub` and
    the contents begin with `ssh-rsa ...`.

    ```text
    $ vault write ssh-client-signer/sign/my-role \
        public_key=@$HOME/.ssh/id_rsa.pub

    Key             Value
    ---             -----
    serial_number   c73f26d2340276aa
    signed_key      ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1...
    ```

    The result will include the serial and the signed key. This signed key is
    another public key.

    To customize the signing options, use a JSON payload:

    ```text
    $ vault write ssh-client-signer/sign/my-role -<<"EOH"
    {
      "public_key": "ssh-rsa AAA...",
      "valid_principals": "my-user",
      "key_id": "custom-prefix",
      "extensions": {
        "permit-pty": "",
        "permit-port-forwarding": ""
      }
    }
    EOH
    ```

1.  Save the resulting signed, public key to disk. Limit permissions as needed.

    ```text
    $ vault write -field=signed_key ssh-client-signer/sign/my-role \
        public_key=@$HOME/.ssh/id_rsa.pub > signed-cert.pub
    ```

    If you are saving the certificate directly beside your SSH keypair, suffix
    the name with `-cert.pub` (`~/.ssh/id_rsa-cert.pub`). With this naming
    scheme, OpenSSH will automatically use it during authentication.

1.  (Optional) View enabled extensions, principals, and metadata of the signed
    key.

    ```text
    $ ssh-keygen -Lf ~/.ssh/signed-cert.pub
    ```

1.  SSH into the host machine using the signed key. You must supply both the
    signed public key from Vault **and** the corresponding private key as
    authentication to the SSH call.

    ```text
    $ ssh -i signed-cert.pub -i ~/.ssh/id_rsa username@10.0.23.5
    ```

## Host key signing

For an added layer of security, we recommend enabling host key signing. This is
used in conjunction with client key signing to provide an additional integrity
layer. When enabled, the SSH agent will verify the target host is valid and
trusted before attempting to SSH. This will reduce the probability of a user
accidentally SSHing into an unmanaged or malicious machine.

### Signing key configuration

1.  Mount the secrets engine. For the most security, mount at a different path from the
    client signer.

    ```text
    $ vault secrets enable -path=ssh-host-signer ssh
    Successfully mounted 'ssh' at 'ssh-host-signer'!
    ```

1.  Configure Vault with a CA for signing host keys using the `/config/ca`
    endpoint. If you do not have an internal CA, Vault can generate a keypair for
    you.

    ```text
    $ vault write ssh-host-signer/config/ca generate_signing_key=true
    Key             Value
    ---             -----
    public_key      ssh-rsa AAAAB3NzaC1yc2EA...
    ```

    If you already have a keypair, specify the public and private key parts as
    part of the payload:

    ```text
    $ vault write ssh-host-signer/config/ca \
        private_key="..." \
        public_key="..."
    ```

    Regardless of whether it is generated or uploaded, the host signer public
    key is accessible via the API at the `/public_key` endpoint.

1.  Extend host key certificate TTLs.

    ```text
    $ vault secrets tune -max-lease-ttl=87600h ssh-host-signer
    ```

1.  Create a role for signing host keys. Be sure to fill in the list of allowed
    domains, set `allow_bare_domains`, or both.

    ```text
    $ vault write ssh-host-signer/roles/hostrole \
        key_type=ca \
        algorithm_signer=rsa-sha2-256 \
        ttl=87600h \
        allow_host_certificates=true \
        allowed_domains="localdomain,example.com" \
        allow_subdomains=true
    ```

1.  Sign the host's SSH public key.

    ```text
    $ vault write ssh-host-signer/sign/hostrole \
        cert_type=host \
        public_key=@/etc/ssh/ssh_host_rsa_key.pub
    Key             Value
    ---             -----
    serial_number   3746eb17371540d9
    signed_key      ssh-rsa-cert-v01@openssh.com AAAAHHNzaC1y...
    ```

1.  Set the resulting signed certificate as `HostCertificate` in the SSH
    configuration on the host machine.

    ```text
    $ vault write -field=signed_key ssh-host-signer/sign/hostrole \
        cert_type=host \
        public_key=@/etc/ssh/ssh_host_rsa_key.pub > /etc/ssh/ssh_host_rsa_key-cert.pub
    ```

    Set permissions on the certificate to be `0640`:

    ```text
    $ chmod 0640 /etc/ssh/ssh_host_rsa_key-cert.pub
    ```

    Add host key and host certificate to the SSH configuration file.

    ```text
    # /etc/ssh/sshd_config
    # ...

    # For client keys
    TrustedUserCAKeys /etc/ssh/trusted-user-ca-keys.pem

    # For host keys
    HostKey /etc/ssh/ssh_host_rsa_key
    HostCertificate /etc/ssh/ssh_host_rsa_key-cert.pub
    ```

    Restart the SSH service to pick up the changes.

### Client-Side host verification

1.  Retrieve the host signing CA public key to validate the host signature of
    target machines.

    ```text
    $ curl http://127.0.0.1:8200/v1/ssh-host-signer/public_key
    ```

    ```text
    $ vault read -field=public_key ssh-host-signer/config/ca
    ```

1.  Add the resulting public key to the `known_hosts` file with authority.

    ```text
    # ~/.ssh/known_hosts
    @cert-authority *.example.com ssh-rsa AAAAB3NzaC1yc2EAAA...
    ```

1.  SSH into target machines as usual.

## Troubleshooting

When initially configuring this type of key signing, enable `VERBOSE` SSH
logging to help annotate any errors in the log.

```text
# /etc/ssh/sshd_config
# ...
LogLevel VERBOSE
```

Restart SSH after making these changes.

By default, SSH logs to `/var/log/auth.log`, but so do many other things. To
extract just the SSH logs, use the following:

```shell-session
$ tail -f /var/log/auth.log | grep --line-buffered "sshd"
```

If you are unable to make a connection to the host, the SSH server logs may
provide guidance and insights.

### Name is not a listed principal

If the `auth.log` displays the following messages:

```text
# /var/log/auth.log
key_cert_check_authority: invalid certificate
Certificate invalid: name is not a listed principal
```

The certificate does not permit the username as a listed principal for
authenticating to the system. This is most likely due to an OpenSSH bug (see
[known issues](#known-issues) for more information). This bug does not respect
the `allowed_users` option value of "\*". Here are ways to work around this
issue:

1.  Set `default_user` in the role. If you are always authenticating as the same
    user, set the `default_user` in the role to the username you are SSHing into the
    target machine:

    ```text
    $ vault write ssh/roles/my-role -<<"EOH"
    {
      "default_user": "YOUR_USER",
      // ...
    }
    EOH
    ```

1.  Set `valid_principals` during signing. In situations where multiple users may
    be authenticating to SSH via Vault, set the list of valid principles during key
    signing to include the current username:

    ```text
    $ vault write ssh-client-signer/sign/my-role -<<"EOH"
    {
      "valid_principals": "my-user"
      // ...
    }
    EOH
    ```

### No prompt after login

If you do not see a prompt after authenticating to the host machine, the signed
certificate may not have the `permit-pty` extension. There are two ways to add
this extension to the signed certificate.

- As part of the role creation

  ```text
  $ vault write ssh-client-signer/roles/my-role -<<"EOH"
  {
    "default_extensions": {
      "permit-pty": ""
    }
    // ...
  }
  EOH
  ```

- As part of the signing operation itself:

  ```text
  $ vault write ssh-client-signer/sign/my-role -<<"EOH"
  {
    "extensions": {
      "permit-pty": ""
    }
    // ...
  }
  EOH
  ```

### No port forwarding

If port forwarding from the guest to the host is not working, the signed
certificate may not have the `permit-port-forwarding` extension. Add the
extension as part of the role creation or signing process to enable port
forwarding. See [no prompt after login](#no-prompt-after-login) for examples.

```json
{
  "default_extensions": {
    "permit-port-forwarding": ""
  }
}
```

### No x11 forwarding

If X11 forwarding from the guest to the host is not working, the signed
certificate may not have the `permit-X11-forwarding` extension. Add the
extension as part of the role creation or signing process to enable X11
forwarding. See [no prompt after login](#no-prompt-after-login) for examples.

```json
{
  "default_extensions": {
    "permit-X11-forwarding": ""
  }
}
```

### No agent forwarding

If agent forwarding from the guest to the host is not working, the signed
certificate may not have the `permit-agent-forwarding` extension. Add the
extension as part of the role creation or signing process to enable agent
forwarding. See [no prompt after login](#no-prompt-after-login) for examples.

```json
{
  "default_extensions": {
    "permit-agent-forwarding": ""
  }
}
```

### Key comments
There are additional steps needed to preserve [comment attributes](https://www.rfc-editor.org/rfc/rfc4716#section-3.3.2)
in keys which ought to be considered if they are required. Private and public
key may have comments applied to them and for example where `ssh-keygen` is used
with its `-C` parameter - similar to:

```shell-session
ssh-keygen -C "...Comments" -N "" -t rsa -b 4096 -f host-ca
```

Adapted key values containing comments must be provided with the key related
parameters as per the Vault CLI and API steps demonstrated below.

```shell-extension
# Using CLI:
vault secrets enable -path=hosts-ca ssh
KEY_PRI=$(cat ~/.ssh/id_rsa | sed -z 's/\n/\\n/g')
KEY_PUB=$(cat ~/.ssh/id_rsa.pub | sed -z 's/\n/\\n/g')
# Create / update keypair in Vault
vault write ssh-client-signer/config/ca \
  generate_signing_key=false \
  private_key="${KEY_PRI}" \
  public_key="${KEY_PUB}"
```

```shell-extension
# Using API:
curl -X POST -H "X-Vault-Token: ..." -d '{"type":"ssh"}' http://127.0.0.1:8200/v1/sys/mounts/hosts-ca
KEY_PRI=$(cat ~/.ssh/id_rsa | sed -z 's/\n/\\n/g')
KEY_PUB=$(cat ~/.ssh/id_rsa.pub | sed -z 's/\n/\\n/g')
tee payload.json <<EOF
{
  "generate_signing_key" : false,
  "private_key"          : "${KEY_PRI}",
  "public_key"           : "${KEY_PUB}"
}
EOF
# Create / update keypair in Vault
curl -X POST -H "X-Vault-Token: ..." -d @payload.json http://127.0.0.1:8200/v1/hosts-ca/config/ca
```

~> **IMPORTANT:** Do NOT add a private key password since Vault can't decrypt it.
Destroy the keypair and `payload.json` from your hosts immediately after they have been confirmed as successfully uploaded.

### Known issues
- On SELinux-enforcing systems, you may need to adjust related types so that the
  SSH daemon is able to read it. For example, adjust the signed host certificate
  to be an `sshd_key_t` type.

- On some versions of SSH, you may get the following error:

  ```text
  no separate private key for certificate
  ```

  This is a bug introduced in OpenSSH version 7.2 and fixed in 7.5. See
  [OpenSSH bug 2617](https://bugzilla.mindrot.org/show_bug.cgi?id=2617) for
  details.

- On some versions of SSH, you may get the following error on target host:

  ```text
  userauth_pubkey: certificate signature algorithm ssh-rsa: signature algorithm not supported [preauth]
  ```
  Fix is to add below line to /etc/ssh/sshd_config
  ```text
  CASignatureAlgorithms ^ssh-rsa
  ```
  The ssh-rsa algorithm is no longer supported in [OpenSSH 8.2](https://www.openssh.com/txt/release-8.2)

## API

The SSH secrets engine has a full HTTP API. Please see the
[SSH secrets engine API](/vault/api-docs/secret/ssh) for more
details.

layout  docs page title  Signed SSH Certificates   SSH   Secrets Engines description       The signed SSH certificates is the simplest and most powerful in terms of    setup complexity and in terms of being platform agnostic  When using this    type  an SSH CA signing key is generated or configured at the secrets engine s   mount     This key will be used to sign other SSH keys         Signed SSH certificates  The signed SSH certificates is the simplest and most powerful in terms of setup complexity and in terms of being platform agnostic  By leveraging Vault s powerful CA capabilities and functionality built into OpenSSH  clients can SSH into target hosts using their own local SSH keys   In this section  the term    client    refers to the person or machine performing the SSH operation  The    host    refers to the target machine  If this is confusing  substitute  client  with  user    This page will show a quick start for this secrets engine  For detailed documentation on every path  use  vault path help  after mounting the secrets engine      Client key signing  Before a client can request their SSH key be signed  the Vault SSH secrets engine must be configured  Usually a Vault administrator or security team performs these steps  It is also possible to automate these actions using a configuration management tool like Chef  Puppet  Ansible  or Salt       Signing key  amp  role configuration  The following steps are performed in advance by a Vault administrator  security team  or configuration management tooling   1   Mount the secrets engine  Like all secrets engines in Vault  the SSH secrets engine     must be mounted before use          text       vault secrets enable  path ssh client signer ssh     Successfully mounted  ssh  at  ssh client signer                This enables the SSH secrets engine at the path  ssh client signer   It is     possible to mount the same secrets engine multiple times using different       path  arguments  The name  ssh client signer  is not special   it can be     any name  but this documentation will assume  ssh client signer    1   Configure Vault with a CA for signing client keys using the   config ca      endpoint  If you do not have an internal CA  Vault can generate a keypair for     you          text       vault write ssh client signer config ca generate signing key true     Key             Value                               public key      ssh rsa AAAAB3NzaC1yc2EA                 If you already have a keypair  specify the public and private key parts as     part of the payload          text       vault write ssh client signer config ca           private key                 public key                    Regardless of whether it is generated or uploaded  the client signer public     key is accessible via the API at the   public key  endpoint or the CLI  see next step    1   Add the public key to all target host s SSH configuration  This process can     be manual or automated using a configuration management tool  The public key is     accessible via the API and does not require authentication          text       curl  o  etc ssh trusted user ca keys pem http   127 0 0 1 8200 v1 ssh client signer public key                 text       vault read  field public key ssh client signer config ca    etc ssh trusted user ca keys pem              Add the path where the public key contents are stored to the SSH     configuration file as the  TrustedUserCAKeys  option          text        etc ssh sshd config               TrustedUserCAKeys  etc ssh trusted user ca keys pem              Restart the SSH service to pick up the changes   1   Create a named Vault role for signing client keys            IMPORTANT NOTE    Prior to Vault 1 9  if   allowed extensions   is either empty or not specified in the role      Vault will assume permissive defaults  any user assigned to the role may specify any arbitrary     extension values as part of the certificate request to the Vault server      This may have significant impact on third party systems that rely on an  extensions  field for security critical information      In those cases  consider using a template to specify default extensions  and explicitly setting       allowed extensions   to an arbitrary  non empty string if the field is empty or not set       Because of the way some SSH certificate features are implemented  options     are passed as a map  The following example adds the  permit pty  extension     to the certificate  and allows the user to specify their own values for  permit pty  and  permit port forwarding      when requesting the certificate          text       vault write ssh client signer roles my role     EOH               algorithm signer    rsa sha2 256          allow user certificates   true         allowed users               allowed extensions    permit pty permit port forwarding          default extensions              permit pty                      key type    ca          default user    ubuntu          ttl    30m0s            EOH              Client SSH authentication  The following steps are performed by the client  user  that wants to authenticate to machines managed by Vault  These commands are usually run from the client s local workstation   1   Locate or generate the SSH public key  Usually this is     ssh id rsa pub       If you do not have an SSH keypair  generate one          text       ssh keygen  t rsa  C  user example com           1   Ask Vault to sign your   public key    This file usually ends in   pub  and     the contents begin with  ssh rsa               text       vault write ssh client signer sign my role           public key   HOME  ssh id rsa pub      Key             Value                               serial number   c73f26d2340276aa     signed key      ssh rsa cert v01 openssh com AAAAHHNzaC1                 The result will include the serial and the signed key  This signed key is     another public key       To customize the signing options  use a JSON payload          text       vault write ssh client signer sign my role     EOH               public key    ssh rsa AAA             valid principals    my user          key id    custom prefix          extensions              permit pty                permit port forwarding                        EOH          1   Save the resulting signed  public key to disk  Limit permissions as needed          text       vault write  field signed key ssh client signer sign my role           public key   HOME  ssh id rsa pub   signed cert pub              If you are saving the certificate directly beside your SSH keypair  suffix     the name with   cert pub       ssh id rsa cert pub    With this naming     scheme  OpenSSH will automatically use it during authentication   1    Optional  View enabled extensions  principals  and metadata of the signed     key          text       ssh keygen  Lf    ssh signed cert pub          1   SSH into the host machine using the signed key  You must supply both the     signed public key from Vault   and   the corresponding private key as     authentication to the SSH call          text       ssh  i signed cert pub  i    ssh id rsa username 10 0 23 5             Host key signing  For an added layer of security  we recommend enabling host key signing  This is used in conjunction with client key signing to provide an additional integrity layer  When enabled  the SSH agent will verify the target host is valid and trusted before attempting to SSH  This will reduce the probability of a user accidentally SSHing into an unmanaged or malicious machine       Signing key configuration  1   Mount the secrets engine  For the most security  mount at a different path from the     client signer          text       vault secrets enable  path ssh host signer ssh     Successfully mounted  ssh  at  ssh host signer            1   Configure Vault with a CA for signing host keys using the   config ca      endpoint  If you do not have an internal CA  Vault can generate a keypair for     you          text       vault write ssh host signer config ca generate signing key true     Key             Value                               public key      ssh rsa AAAAB3NzaC1yc2EA                 If you already have a keypair  specify the public and private key parts as     part of the payload          text       vault write ssh host signer config ca           private key                 public key                    Regardless of whether it is generated or uploaded  the host signer public     key is accessible via the API at the   public key  endpoint   1   Extend host key certificate TTLs          text       vault secrets tune  max lease ttl 87600h ssh host signer          1   Create a role for signing host keys  Be sure to fill in the list of allowed     domains  set  allow bare domains   or both          text       vault write ssh host signer roles hostrole           key type ca           algorithm signer rsa sha2 256           ttl 87600h           allow host certificates true           allowed domains  localdomain example com            allow subdomains true          1   Sign the host s SSH public key          text       vault write ssh host signer sign hostrole           cert type host           public key   etc ssh ssh host rsa key pub     Key             Value                               serial number   3746eb17371540d9     signed key      ssh rsa cert v01 openssh com AAAAHHNzaC1y             1   Set the resulting signed certificate as  HostCertificate  in the SSH     configuration on the host machine          text       vault write  field signed key ssh host signer sign hostrole           cert type host           public key   etc ssh ssh host rsa key pub    etc ssh ssh host rsa key cert pub              Set permissions on the certificate to be  0640           text       chmod 0640  etc ssh ssh host rsa key cert pub              Add host key and host certificate to the SSH configuration file          text        etc ssh sshd config                  For client keys     TrustedUserCAKeys  etc ssh trusted user ca keys pem        For host keys     HostKey  etc ssh ssh host rsa key     HostCertificate  etc ssh ssh host rsa key cert pub              Restart the SSH service to pick up the changes       Client Side host verification  1   Retrieve the host signing CA public key to validate the host signature of     target machines          text       curl http   127 0 0 1 8200 v1 ssh host signer public key                 text       vault read  field public key ssh host signer config ca          1   Add the resulting public key to the  known hosts  file with authority          text          ssh known hosts      cert authority   example com ssh rsa AAAAB3NzaC1yc2EAAA             1   SSH into target machines as usual      Troubleshooting  When initially configuring this type of key signing  enable  VERBOSE  SSH logging to help annotate any errors in the log      text    etc ssh sshd config       LogLevel VERBOSE      Restart SSH after making these changes   By default  SSH logs to   var log auth log   but so do many other things  To extract just the SSH logs  use the following      shell session   tail  f  var log auth log   grep   line buffered  sshd       If you are unable to make a connection to the host  the SSH server logs may provide guidance and insights       Name is not a listed principal  If the  auth log  displays the following messages      text    var log auth log key cert check authority  invalid certificate Certificate invalid  name is not a listed principal      The certificate does not permit the username as a listed principal for authenticating to the system  This is most likely due to an OpenSSH bug  see  known issues   known issues  for more information   This bug does not respect the  allowed users  option value of       Here are ways to work around this issue   1   Set  default user  in the role  If you are always authenticating as the same     user  set the  default user  in the role to the username you are SSHing into the     target machine          text       vault write ssh roles my role     EOH               default user    YOUR USER                          EOH          1   Set  valid principals  during signing  In situations where multiple users may     be authenticating to SSH via Vault  set the list of valid principles during key     signing to include the current username          text       vault write ssh client signer sign my role     EOH               valid principals    my user                         EOH              No prompt after login  If you do not see a prompt after authenticating to the host machine  the signed certificate may not have the  permit pty  extension  There are two ways to add this extension to the signed certificate     As part of the role creation       text     vault write ssh client signer roles my role     EOH           default extensions            permit pty                             EOH          As part of the signing operation itself        text     vault write ssh client signer sign my role     EOH           extensions            permit pty                             EOH            No port forwarding  If port forwarding from the guest to the host is not working  the signed certificate may not have the  permit port forwarding  extension  Add the extension as part of the role creation or signing process to enable port forwarding  See  no prompt after login   no prompt after login  for examples      json      default extensions          permit port forwarding                     No x11 forwarding  If X11 forwarding from the guest to the host is not working  the signed certificate may not have the  permit X11 forwarding  extension  Add the extension as part of the role creation or signing process to enable X11 forwarding  See  no prompt after login   no prompt after login  for examples      json      default extensions          permit X11 forwarding                     No agent forwarding  If agent forwarding from the guest to the host is not working  the signed certificate may not have the  permit agent forwarding  extension  Add the extension as part of the role creation or signing process to enable agent forwarding  See  no prompt after login   no prompt after login  for examples      json      default extensions          permit agent forwarding                     Key comments There are additional steps needed to preserve  comment attributes  https   www rfc editor org rfc rfc4716 section 3 3 2  in keys which ought to be considered if they are required  Private and public  key may have comments applied to them and for example where  ssh keygen  is used  with its   C  parameter   similar to      shell session ssh keygen  C     Comments   N     t rsa  b 4096  f host ca      Adapted key values containing comments must be provided with the key related  parameters as per the Vault CLI and API steps demonstrated below       shell extension   Using CLI  vault secrets enable  path hosts ca ssh KEY PRI   cat    ssh id rsa   sed  z  s  n   n g   KEY PUB   cat    ssh id rsa pub   sed  z  s  n   n g     Create   update keypair in Vault vault write ssh client signer config ca     generate signing key false     private key    KEY PRI       public key    KEY PUB           shell extension   Using API  curl  X POST  H  X Vault Token        d    type   ssh    http   127 0 0 1 8200 v1 sys mounts hosts ca KEY PRI   cat    ssh id rsa   sed  z  s  n   n g   KEY PUB   cat    ssh id rsa pub   sed  z  s  n   n g   tee payload json   EOF      generate signing key    false     private key                KEY PRI       public key                 KEY PUB     EOF   Create   update keypair in Vault curl  X POST  H  X Vault Token        d  payload json http   127 0 0 1 8200 v1 hosts ca config ca           IMPORTANT    Do NOT add a private key password since Vault can t decrypt it  Destroy the keypair and  payload json  from your hosts immediately after they have been confirmed as successfully uploaded       Known issues   On SELinux enforcing systems  you may need to adjust related types so that the   SSH daemon is able to read it  For example  adjust the signed host certificate   to be an  sshd key t  type     On some versions of SSH  you may get the following error        text   no separate private key for certificate          This is a bug introduced in OpenSSH version 7 2 and fixed in 7 5  See    OpenSSH bug 2617  https   bugzilla mindrot org show bug cgi id 2617  for   details     On some versions of SSH  you may get the following error on target host        text   userauth pubkey  certificate signature algorithm ssh rsa  signature algorithm not supported  preauth          Fix is to add below line to  etc ssh sshd config      text   CASignatureAlgorithms  ssh rsa         The ssh rsa algorithm is no longer supported in  OpenSSH 8 2  https   www openssh com txt release 8 2      API  The SSH secrets engine has a full HTTP API  Please see the  SSH secrets engine API   vault api docs secret ssh  for more details


vault More information on the Tokenization transform Not to be confused with Vault tokens Tokenization exchanges a page title Transform Secrets Engines Tokenization layout docs Tokenization transform

Answer:
---
layout: docs
page_title: Transform - Secrets Engines - Tokenization
description: >-
  More information on the Tokenization transform.
---

# Tokenization transform

Not to be confused with Vault tokens, Tokenization exchanges a
sensitive value for an unrelated value called a _token_. The original sensitive
value cannot be recovered from a token alone, they are irreversible. Instead,
unlike format preserving encryption, tokenization is stateful. To decode the
original value, the token must be submitted to Vault where it is
retrieved from a cryptographic mapping in storage.

## Operation

On encode, Vault generates a random, signed token and stores a mapping of a
version of that token to encrypted versions of the plaintext and metadata, as
well as a fingerprint of the original plaintext which facilitates the `tokenized`
endpoint that lets one query whether a plaintext exists in the system.

Depending on the mapping mode, the plaintext may be decoded only with possession
of the distributed token, or may be recoverable in the export operation. See
[Security Considerations](#security-considerations) for more.
Tokenization's cryptosystem uses AES256-GCM96 for encryption of its token
store, with keys derived from the token and a tokenization root key.

### Convergence

By default, tokenization produces a unique token for every encode operation.
This makes the resulting token fully independent of its plaintext and expiration.
Sometimes, though, it may be beneficial if the tokenization of a plaintext/expiration
pair tokenizes consistently to the same value.  For example if one wants to
do a statistical analysis of the tokens as they relate to some other field
in a database (without decoding the token), or if one needed to tokenize
in two different systems but be able relate the results.  In this case,
one can create a tokenization transformation that is *convergent*.

When enabled at transformation creation time, Vault alters the calculation so that
encoding a plaintext and expiration tokenizes to the same value every time, and
storage keeps only a single entry of that token.  Like the exportable mapping
mode, convergence should only be enabled if needed.  Convergent tokenization
has a small performance penalty in external stores and a larger one in the
built in store due to the need to avoid duplicate entries and to update
metadata when convergently encoding.  It is recommended that if one has some
use cases that require convergence and some that do not, one should create two
different tokenization transforms with convergence enabled on only one.

### Token lookup

Some use cases may want to lookup the value of a token given its plaintext.  Ordinarily
this is contrary to the nature of tokenization where we want to prevent the ability
of an attacker to determine that a token corresponds to a plaintext value (a known
plaintext attack).  But for use cases that require it, the
[token lookup](/vault/api-docs/secret/transform#token-lookup)
operation is supported, but only in some configurations of the tokenization
transformation.  Token lookup is supported when convergence is enabled, or
if the mapping mode is exportable *and* the storage backend is external.

## Performance considerations

### Builtin (Internal) store

As tokenization is stateful, the encode operation necessarily writes values to
storage. By default, that storage is the Vault backend store itself. This
differs from some secret engines in that the encode and decode operations require
an access of storage per operation. Other engines use storage for configuration
but can process operations largely without accessing any storage.

Since these operations involve writes to storage, and therefore must be performed
on primary nodes, the scalability of the encode operation is limited by the
primary's storage performance.

Additionally, using internal storage, since writes must be performed on primary
nodes, the scalability of the encode operation will be limited by the performance
of the primary and its storage subsystem. All other operations can be performed
on secondaries.

Finally, due to replication, writes to the primary may take some time to reach
secondaries, so other read operations like decode or metadata may not succeed on
the secondaries until this happens. In other words, tokenization is eventually
consistent.

### External storage

All nodes (except DRs) can participate in all operations using external storage,
but one must take care to monitor and scale the external storage for the level of
traffic experienced. The storage schema is simple however and well known approaches
should be effective.

## Security considerations

The goal of Tokenization is to let end users' devices store the token rather than
their sensitive values (such as credit card numbers) and still participate in
transactions where the token is a stand-in for the sensitive value. For this reason
the token Vault generates is completely unrelated (e.g. irreversible) to the
sensitive value.

Furthermore, the Tokenization transform is designed to resist a number of attacks
on the values produced during encode. In particular it is designed so that
attackers cannot recover plaintext even if they steal the tokenization values
from Vault itself. In the default mapping mode,
even stealing the underlying transform key does not allow them to recover
the plaintext without also possessing the encoded token. An attacker must have
gotten access to all values in the construct.

In the `exportable` mapping mode however, the plaintext values are encrypted
in a way that can be decrypted within Vault. If the attacker possesses the
transform key and the tokenization mapping values, the plaintext can be
recovered. This mode is available for the case where operators prioritize the
ability to export all of the plaintext values in an emergency, via the
`export-decoded` operation.

### Metadata

Since tokenization isn't format preserving and requires storage, one can associate
arbitrary metadata with a token. Metadata is considered less sensitive than the
original plaintext value. As it has it's own retrieval endpoint, operators can
configure policies that may allow access to the metadata of a token but not
its decoded value to enable workflows that operate just on the metadata.

## TTLs and tidying

By default, tokens are long lived, and the storage for them will be maintained
indefinitely. Where there is a concept of time-to-live, it is strongly encouraged
that the tokens be generated with a TTL. For example, as credit cards
have an expiration date, it is recommended that tokenizing a credit card
primary account number (PAN) be done with a TTL that corresponds to the time
after which the PAN is invalid.

This allows such values to be _tidied_ and removed from storage once expired.
Tokens themselves encode the expiration time, so decode and other operations
can immediately reject the operation when presented with an expired token.

## Storage

### External SQL stores

Currently the PostgreSQL, MySQL, and MSSQL relational databases are supported as
external storage backends for tokenization.
The [Schema Endpoint](/vault/api-docs/secret/transform#create-update-store-schema)
may be used to initialize and upgrade the necessary database tables. Vault uses
a schema versioning table to determine if it needs to create or modify the
tables when using that endpoint. If you make changes to those tables yourself,
the automatic schema management may become out of sync and may fail in the future.

External stores may often be preferred due to their ability to achieve a much
higher scale of performance, especially when used with batch operations.

### Snapshot/Restore

Snapshot allows one to iteratively retrieve the tokenization state, for
backup or migration purposes. The resulting data can be fed to the restore
endpoint of the same or a different tokenization store. Note that the state
is only useable by the tokenization transform that created it, as state is
encrypted via keys in that configured transform.

### Export decoded

For stores configured with the `exportable` mapping mode, the export decoded
endpoint allows operators to retrieve the _decoded_ contents of tokenization
state, which includes tokens and their decoded, sensitive values. The
`exportable` mode is only recommended if this use case is required, as the default
cannot be decoded by attackers even if they gain access to Vault's storage and
keys.

### Migration

Tokenization stores are configured separately from the tokenization transform,
and the transform can point to multiple stores. The primary use case for this
one-to-many relationship is to facilitate migration between two tokenization
stores.

When multiple stores are configured, Vault writes new tokenization state to all
configured stores, and reads from each store in the order they were configured.
Thus, one can use multiple configured stores along with the snapshot/restore
functionality to perform a zero-downtime migration to a new store:

1. Configure the new tokenization store in the API.
1. Modify the existing tokenization transform to use both the existing and new
   store.
1. Snapshot the old store.
1. Restore the snapshot to the new store.
1. Perform any desired validations.
1. Modify the tokenization transform to use only the new store.

## Key management

Tokenization supports key rotation. Keys are tied to transforms, so key
names are the same as the name of the corresponding tokenization transform.
Keys can be rotated to a new version, with backward compatibility for
decoding. Encoding is always performed with the newest key version. Keys versions
can be tidied as well. Keys may also be rotated automatically on a user-defined
time interval, specified by the `auto_rotate_field` of the key config. For more
information, see the [transform api docs](/vault/api-docs/secret/transform).

## Tutorial

Refer to [Tokenize Data with Transform Secrets
Engine](/vault/tutorials/adp/tokenization) for a
step-by-step tutorial.

layout  docs page title  Transform   Secrets Engines   Tokenization description       More information on the Tokenization transform         Tokenization transform  Not to be confused with Vault tokens  Tokenization exchanges a sensitive value for an unrelated value called a  token   The original sensitive value cannot be recovered from a token alone  they are irreversible  Instead  unlike format preserving encryption  tokenization is stateful  To decode the original value  the token must be submitted to Vault where it is retrieved from a cryptographic mapping in storage      Operation  On encode  Vault generates a random  signed token and stores a mapping of a version of that token to encrypted versions of the plaintext and metadata  as well as a fingerprint of the original plaintext which facilitates the  tokenized  endpoint that lets one query whether a plaintext exists in the system   Depending on the mapping mode  the plaintext may be decoded only with possession of the distributed token  or may be recoverable in the export operation  See  Security Considerations   security considerations  for more   Tokenization s cryptosystem uses AES256 GCM96 for encryption of its token store  with keys derived from the token and a tokenization root key       Convergence  By default  tokenization produces a unique token for every encode operation   This makes the resulting token fully independent of its plaintext and expiration   Sometimes  though  it may be beneficial if the tokenization of a plaintext expiration pair tokenizes consistently to the same value   For example if one wants to  do a statistical analysis of the tokens as they relate to some other field in a database  without decoding the token   or if one needed to tokenize in two different systems but be able relate the results   In this case  one can create a tokenization transformation that is  convergent      When enabled at transformation creation time  Vault alters the calculation so that encoding a plaintext and expiration tokenizes to the same value every time  and storage keeps only a single entry of that token   Like the exportable mapping mode  convergence should only be enabled if needed   Convergent tokenization has a small performance penalty in external stores and a larger one in the built in store due to the need to avoid duplicate entries and to update metadata when convergently encoding   It is recommended that if one has some use cases that require convergence and some that do not  one should create two different tokenization transforms with convergence enabled on only one        Token lookup  Some use cases may want to lookup the value of a token given its plaintext   Ordinarily this is contrary to the nature of tokenization where we want to prevent the ability of an attacker to determine that a token corresponds to a plaintext value  a known plaintext attack    But for use cases that require it  the   token lookup   vault api docs secret transform token lookup  operation is supported  but only in some configurations of the tokenization transformation   Token lookup is supported when convergence is enabled  or if the mapping mode is exportable  and  the storage backend is external      Performance considerations      Builtin  Internal  store  As tokenization is stateful  the encode operation necessarily writes values to storage  By default  that storage is the Vault backend store itself  This differs from some secret engines in that the encode and decode operations require an access of storage per operation  Other engines use storage for configuration but can process operations largely without accessing any storage   Since these operations involve writes to storage  and therefore must be performed on primary nodes  the scalability of the encode operation is limited by the primary s storage performance   Additionally  using internal storage  since writes must be performed on primary nodes  the scalability of the encode operation will be limited by the performance of the primary and its storage subsystem  All other operations can be performed on secondaries   Finally  due to replication  writes to the primary may take some time to reach secondaries  so other read operations like decode or metadata may not succeed on the secondaries until this happens  In other words  tokenization is eventually consistent       External storage  All nodes  except DRs  can participate in all operations using external storage  but one must take care to monitor and scale the external storage for the level of traffic experienced  The storage schema is simple however and well known approaches should be effective      Security considerations  The goal of Tokenization is to let end users  devices store the token rather than their sensitive values  such as credit card numbers  and still participate in transactions where the token is a stand in for the sensitive value  For this reason the token Vault generates is completely unrelated  e g  irreversible  to the sensitive value   Furthermore  the Tokenization transform is designed to resist a number of attacks on the values produced during encode  In particular it is designed so that attackers cannot recover plaintext even if they steal the tokenization values from Vault itself  In the default mapping mode  even stealing the underlying transform key does not allow them to recover the plaintext without also possessing the encoded token  An attacker must have gotten access to all values in the construct   In the  exportable  mapping mode however  the plaintext values are encrypted in a way that can be decrypted within Vault  If the attacker possesses the transform key and the tokenization mapping values  the plaintext can be recovered  This mode is available for the case where operators prioritize the ability to export all of the plaintext values in an emergency  via the  export decoded  operation       Metadata  Since tokenization isn t format preserving and requires storage  one can associate arbitrary metadata with a token  Metadata is considered less sensitive than the original plaintext value  As it has it s own retrieval endpoint  operators can configure policies that may allow access to the metadata of a token but not its decoded value to enable workflows that operate just on the metadata      TTLs and tidying  By default  tokens are long lived  and the storage for them will be maintained indefinitely  Where there is a concept of time to live  it is strongly encouraged that the tokens be generated with a TTL  For example  as credit cards have an expiration date  it is recommended that tokenizing a credit card primary account number  PAN  be done with a TTL that corresponds to the time after which the PAN is invalid   This allows such values to be  tidied  and removed from storage once expired  Tokens themselves encode the expiration time  so decode and other operations can immediately reject the operation when presented with an expired token      Storage      External SQL stores  Currently the PostgreSQL  MySQL  and MSSQL relational databases are supported as external storage backends for tokenization  The  Schema Endpoint   vault api docs secret transform create update store schema  may be used to initialize and upgrade the necessary database tables  Vault uses a schema versioning table to determine if it needs to create or modify the tables when using that endpoint  If you make changes to those tables yourself  the automatic schema management may become out of sync and may fail in the future   External stores may often be preferred due to their ability to achieve a much higher scale of performance  especially when used with batch operations       Snapshot Restore  Snapshot allows one to iteratively retrieve the tokenization state  for backup or migration purposes  The resulting data can be fed to the restore endpoint of the same or a different tokenization store  Note that the state is only useable by the tokenization transform that created it  as state is encrypted via keys in that configured transform       Export decoded  For stores configured with the  exportable  mapping mode  the export decoded endpoint allows operators to retrieve the  decoded  contents of tokenization state  which includes tokens and their decoded  sensitive values  The  exportable  mode is only recommended if this use case is required  as the default cannot be decoded by attackers even if they gain access to Vault s storage and keys       Migration  Tokenization stores are configured separately from the tokenization transform  and the transform can point to multiple stores  The primary use case for this one to many relationship is to facilitate migration between two tokenization stores   When multiple stores are configured  Vault writes new tokenization state to all configured stores  and reads from each store in the order they were configured  Thus  one can use multiple configured stores along with the snapshot restore functionality to perform a zero downtime migration to a new store   1  Configure the new tokenization store in the API  1  Modify the existing tokenization transform to use both the existing and new    store  1  Snapshot the old store  1  Restore the snapshot to the new store  1  Perform any desired validations  1  Modify the tokenization transform to use only the new store      Key management  Tokenization supports key rotation  Keys are tied to transforms  so key names are the same as the name of the corresponding tokenization transform  Keys can be rotated to a new version  with backward compatibility for decoding  Encoding is always performed with the newest key version  Keys versions can be tidied as well  Keys may also be rotated automatically on a user defined time interval  specified by the  auto rotate field  of the key config  For more information  see the  transform api docs   vault api docs secret transform       Tutorial  Refer to  Tokenize Data with Transform Secrets Engine   vault tutorials adp tokenization  for a step by step tutorial


vault include alerts enterprise and hcp mdx page title Transform Secrets Engines layout docs Transform secrets engine The Transform secrets engine for Vault performs secure data transformation

Answer:
---
layout: docs
page_title: Transform - Secrets Engines
description: >-
  The Transform secrets engine for Vault performs secure data transformation.
---

# Transform secrets engine

@include 'alerts/enterprise-and-hcp.mdx'

Transform secrets engine requires [Vault
Enterprise](https://www.hashicorp.com/products/vault/pricing) with the Advanced Data
Protection Transform (ADP-Transform) module.

The Transform secrets engine handles secure data transformation and tokenization
against provided input value. Transformation methods may encompass NIST vetted
cryptographic standards such as [format-preserving encryption
(FPE)](https://en.wikipedia.org/wiki/Format-preserving_encryption) via
[FF3-1](https://csrc.nist.gov/publications/detail/sp/800-38g/rev-1/draft), but
can also be pseudonymous transformations of the data through other means, such
as masking.

The secret engine currently supports `fpe`, `masking`, and `tokenization` as
data transformation types.

## 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 Transform secrets engine:

   ```text
   $ vault secrets enable transform
   Success! Enabled the transform secrets engine at: transform/
   ```

   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. Create a named role:

   ```text
   $ vault write transform/role/payments transformations=ccn-fpe
   Success! Data written to: transform/role/payments
   ```

1. Create a transformation:

   ```text
   $ vault write transform/transformations/fpe/ccn-fpe \
     template=ccn \
     tweak_source=internal \
     allowed_roles=payments
   Success! Data written to: transform/transformations/fpe/ccn-fpe
   ```

1. Optionally, create a template:

   ```text
   $ vault write transform/template/ccn \
     type=regex \
     pattern='(\d{4})[- ](\d{4})[- ](\d{4})[- ](\d{4})' \
     encode_format='$1-$2-$3-$4' \
     decode_formats=last-four='$4' \
     alphabet=numerics
   Success! Data written to: transform/template/ccn
   ```

1. Optionally, create an alphabet:

   ```text
   $ vault write transform/alphabet/numerics \
       alphabet="0123456789"
   Success! Data written to: transform/alphabet/numerics
   ```

## Usage

After the secrets engine is configured and a user/machine has a Vault token with
the proper permission, it can use this secrets engine to encode and decode input
values.

1. Encode some input value using the `/encode` endpoint with a named role:

   ```text
   $ vault write transform/encode/payments value=1111-2222-3333-4444
   Key              Value
   ---              -----
   encoded_value    9300-3376-4943-8903
   ```

   A transformation must be provided if the role contains more than one
   transformation. A tweak must be provided if the tweak source for the
   transformation is "supplied".

1. Decode some input value using the `/decode` endpoint with a named role:

   ```text
   $ vault write transform/decode/payments value=9300-3376-4943-8903
   Key              Value
   ---              -----
   decoded_value    1111-2222-3333-4444
   ```

   A transformation must be provided if the role contains more than one
   transformation. A tweak must be provided if the tweak source for the
   transformation is "supplied" or "generated".

1. Decode some input value using the `/decode` endpoint with a named role and decode format:

   ```text
   $ vault write transform/decode/payments/last-four value=9300-3376-4943-8903
   Key              Value
   ---              -----
   decoded_value    4444
   ```

   A transformation must be provided if the role contains more than one
   transformation. A tweak must be provided if the tweak source for the
   transformation is "supplied" or "generated". A decode format can optionally
   be provided. If one isn't provided, the decoded output will be formatted to
   match the template's pattern as in the previous example.

## Roles, transformations, templates, and alphabets

The Transform secrets engine contains several types of resources that
encapsulate different aspects of the information required in order to perform
data transformation.

- **Roles** are the basic high-level construct that holds the set of
  transformation that it is allowed to performed. The role name is provided when
  performing encode and decode operations.

- **Transformations** hold information about a particular transformation. It
  contains information about the type of transformation that we want to perform,
  the template that it should use for value detection, and other
  transformation-specific values such as the tweak source or the masking character
  to use.

- **Templates** allow us to determine what and how to capture the value that we
  want to transform.

- **Alphabets** provide the set of valid UTF-8 character contained within both
  the input and transformed value on FPE transformations.

## Transformations

### Format preserving encryption

Format Preserving Encryption (FPE) performs cryptographically secure
transformation via FF3-1 to encode input values while maintaining its data
format and length.  FF3-1 is a construction that uses AES-256 for
encryption.

#### Tweak and tweak source

FF3-1 uses a non-confidential parameter called the tweak along with the
ciphertext when performing encryption and decryption operations. The tweak
is precisely a 7-byte value. The secret engine consumes a base64 encoded string
of this value for its encode and decode operation whenever this input is
required.

In order to simplify the flow of encoding and decoding operations, transformation
creation can take care of generating and associating a tweak value. This allows
applications to provide a single value without having the need to generate or
store any other metadata.

In cases where more granularity is required, a tweak value can be generated by
Vault and returned, or it may be independently generated and provided.

In summary, there are three ways in which the tweak value may be sourced:

- `supplied`: This is the default behavior for FPE transformations. The tweak
  value must be generated externally, and supplied into the on encode and decode
  operations.
- `generated`: The secret engine will take care of generating the tweak value
  on encode operations and return this back as part of the response along
  with the encoded value. It is up to the application to store this value
  so that it can be provided back when decoding the encoded value.
- `internal`: The secret engine will generate an internal tweak value per
  transformation. This value is not returned on encode or decode operations
  since it gets re-used for all encode and decode operations for the
  transformation. Depending on the uniqueness of the dataset, this mode may
  introduce higher risks, but provides the most convenience since the value does
  not need to be stored separately. This mode should only be used if the values
  being encoded are sufficiently unique.

Your team and organization should weigh the trade-offs when it comes to
choosing the proper tweak source to use. For `supplied` and `internal`
sourcing, please see [FF3-1 Tweak Usage Details](/vault/docs/secrets/transform/ff3-tweak-details)

#### Input limits

FF3-1 specifies both minimum and maximum limits on the length of an input.
These limits are driven by the security goals, making sure that for a given
alphabet the input size does not leave the input guessable by brute force.

Given an alphabet of length A, an input length L is valid if:

- L >= 2,
- AL >= 1,000,000
- and L <= 2 \* floor(logA(296)).

As a concrete example, for handling credit card numbers, A is 10, L is 16, so
valid input lengths would be between 6 and 56 characters. This is because
106=1,000,000 (already greater than 2), and 2 \* floor(log10(296)) = 56.

Of course, in the case of credit card numbers valid input would always be
between 12 and 19 decimal digits.

#### Output limitations

After transformation and formatting by the template, the value is an encrypted
version of the input with the format preserved. However, the value itself may
be _invalid_ with respect to other standards. For example the output credit card
number may not validate (it likely won't create a valid check digit).

So one must consider when the outputs are stored whether validation in storage
may reject them.

### Masking

Masking performs replacement of matched characters on the input value with a
desired character. This form of transformation is non-reversible and thus does
not support retrieving the original value back using the decode operation.

### Tokenization

[Tokenization](/vault/docs/secrets/transform/tokenization) exchanges a
sensitive value for an unrelated value called a _token_. The original sensitive
value cannot be recovered from a token alone, they are irreversible.

#### Inputs

Tokenization inputs are not processed by templates or alphabets, as they do not
preserve any of the contents or format of the input.

#### Outputs

Tokenization is not format preserving. The token output is a Base58 encoded
string value of unrelated length, and is not rendered by a template.

The decoded value is returned verbatim as it was before encoding.

#### Metadata

As tokenization isn't format preserving and is stateful, the input values can be
any length, subject to other limits in Vault's request processing. In addition,
non-sensitive _metadata_ can be encoded alongside the value, and retrieved either
with or independently of the original value.

#### Operations

In addition to encode and decode, as tokenization is stateful, it provides two
additional operations:

- Retrieve metadata given a token.
- Check whether an input value has a valid, unexpired token.
- For some configurations, retrieve a previously encoded token for a plaintext
  input.

#### Stores

Tokenization is stateful. Tokenized state can be stored internally (the
default) or in an external store. Currently only PostgreSQL, MySQL, and MSSQL are supported
for external storage.

#### Mapping modes

[Tokenization](/vault/docs/secrets/transform/tokenization) stores the results of an encode operation
in storage using a cryptographic construct that enhances the safety of its values.
In the `default` mapping mode, the token itself is transformed via a one way
function involving the transform key and elements of the token. As Vault does
not store the token, the values in Vault storage themselves cannot be used to
retrieve original input.

A second mapping mode, `exportable` is provided for cases where
operators may need to recover the full set of decoded inputs in an emergency via
the export operation. It is strongly recommended that one use the `default` mode if
possible, as it is resistant to more types of attack.

#### Convergent tokenization

~> **Note:** Convergent tokenization is not supported for transformations with
imported keys.

In addition, tokenization transformations may be configured as *convergent*, meaning
that tokenizing a plaintext and expiration more than once results in the
same token value.  Enabling convergence has performance and security
[considerations](/vault/docs/secrets/transform/tokenization#convergence).

## Deletion behavior

The deletion of resources, aside from roles, is guarded by checking whether any
other related resources are currently using it in order to avoid accidental data
loss of any encoded value that may depend on these bits of information to
decode and reconstruct the original value. Role deletion can be safely done
since the information related to the transformation itself is contained within
transformation object and its related resources.

The following rules applies when it comes to deleting a resource:

- A transformation cannot be deleted if it's in use by a role.
- A template or store cannot be deleted if it's in use by a transformation.
- An alphabet cannot be deleted if it's in use by a template.

## Provided builtin resources

The secret engine provides a set of builtin templates and alphabets that are
considered common. Builtin templates cannot be deleted, and the prefix
"builtin/" on template and alphabet names is a reserved keyword.

### Templates

The following builtin templates are available for use in the secret engine:

- builtin/creditcardnumber
- builtin/socialsecuritynumber

Note that these templates only check for the matching pattern(s), and not the
validity of the value itself. For instance, the builtin credit card number
template can determine whether the provided value is in the format of commonly
issued credit cards, but not whether the credit card is a valid number from a
particular issuer.

Templates currently only accept regular expressions as the matching pattern
type. It uses Go's standard library for the regexp engine, which supports
[the RE2 syntax](https://github.com/google/re2/wiki/Syntax).

**Note**: The `builtin/any` template is only valid and is the default for the tokenization
transform.

### Alphabets

The following builtin alphabets are available for use in the secret engine:

- builtin/numeric
- builtin/alphalower
- builtin/alphaupper
- builtin/alphanumericlower
- builtin/alphanumericupper
- builtin/alphanumeric

Custom alphabets must contain between 2 and 65536 unique characters.

### Stores

The following builtin store is available (and is the default) for tokenization
transformations:

- builtin/internal

## Tutorial

Refer to the [Transform Secrets Engine](/vault/tutorials/adp/transform) tutorial to learn how to use the Transform secrets engine to handle secure data transmission and tokenization against provided secrets.

## Bring your own key (BYOK)

~> **Note:** Key import functionality supports cases where there is a need to bring
in an existing key from an HSM or other outside systems. It is more secure to
have Transform generate and manage a key within Vault.

### Via the Command Line

The Vault command line tool [includes a helper](/vault/docs/commands/transform/) to perform the steps described
in Manual below.

### Via the API

First, the wrapping key needs to be read from the transform secrets engine:

```text
$ vault read transform/wrapping_key
```

The wrapping key will be a 4096-bit RSA public key.

Then, the wrapping key is used to create the ciphertext input for the `import` endpoint,
as described below. The target key refers to the key being imported.

### HSM

If the key is being imported from an HSM that supports PKCS#11, there are
two possible scenarios:

- If the HSM supports the CKM_RSA_AES_KEY_WRAP mechanism, it can be used to wrap the
target key using the wrapping key.

- Otherwise, two mechanisms can be combined to wrap the target key. First, a 256-bit AES key is
generated and then used to wrap the target key using the CKM_AES_KEY_WRAP_KWP mechanism.
Then the AES key should be wrapped under the wrapping key using the CKM_RSA_PKCS_OAEP mechanism
using MGF1 and either SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512.

The ciphertext is constructed by appending the wrapped target key to the wrapped AES key.

The ciphertext bytes should be base64-encoded.

### Manual process

If the target key is not stored in an HSM or KMS, the following steps can be used to construct
the ciphertext for the input of the `import` endpoint:

1. Generate an ephemeral 256-bit AES key.

2. Wrap the target key using the ephemeral AES key with AES-KWP.

3. Wrap the AES key under the Vault wrapping key using RSAES-OAEP with MGF1 and
either SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512.

4. Delete the ephemeral AES key.

5. Append the wrapped target key to the wrapped AES key.

6. Base64 encode the result.

For more details on the key wrapping process, see the [key wrapping guide](/vault/docs/secrets/transit/key-wrapping-guide)
(be sure to use the transform wrapping key when wrapping a key for import into the transform secrets engine).

## API

The Transform secrets engine has a full HTTP API. Please see the
[Transform secrets engine API](/vault/api-docs/secret/transform) for more
details.

layout  docs page title  Transform   Secrets Engines description       The Transform secrets engine for Vault performs secure data transformation         Transform secrets engine   include  alerts enterprise and hcp mdx   Transform secrets engine requires  Vault Enterprise  https   www hashicorp com products vault pricing  with the Advanced Data Protection Transform  ADP Transform  module   The Transform secrets engine handles secure data transformation and tokenization against provided input value  Transformation methods may encompass NIST vetted cryptographic standards such as  format preserving encryption  FPE   https   en wikipedia org wiki Format preserving encryption  via  FF3 1  https   csrc nist gov publications detail sp 800 38g rev 1 draft   but can also be pseudonymous transformations of the data through other means  such as masking   The secret engine currently supports  fpe    masking   and  tokenization  as data transformation types      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 Transform secrets engine         text      vault secrets enable transform    Success  Enabled the transform secrets engine at  transform             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  Create a named role         text      vault write transform role payments transformations ccn fpe    Success  Data written to  transform role payments         1  Create a transformation         text      vault write transform transformations fpe ccn fpe        template ccn        tweak source internal        allowed roles payments    Success  Data written to  transform transformations fpe ccn fpe         1  Optionally  create a template         text      vault write transform template ccn        type regex        pattern    d 4        d 4        d 4        d 4           encode format   1  2  3  4         decode formats last four   4         alphabet numerics    Success  Data written to  transform template ccn         1  Optionally  create an alphabet         text      vault write transform alphabet numerics          alphabet  0123456789     Success  Data written to  transform alphabet numerics            Usage  After the secrets engine is configured and a user machine has a Vault token with the proper permission  it can use this secrets engine to encode and decode input values   1  Encode some input value using the   encode  endpoint with a named role         text      vault write transform encode payments value 1111 2222 3333 4444    Key              Value                              encoded value    9300 3376 4943 8903            A transformation must be provided if the role contains more than one    transformation  A tweak must be provided if the tweak source for the    transformation is  supplied    1  Decode some input value using the   decode  endpoint with a named role         text      vault write transform decode payments value 9300 3376 4943 8903    Key              Value                              decoded value    1111 2222 3333 4444            A transformation must be provided if the role contains more than one    transformation  A tweak must be provided if the tweak source for the    transformation is  supplied  or  generated    1  Decode some input value using the   decode  endpoint with a named role and decode format         text      vault write transform decode payments last four value 9300 3376 4943 8903    Key              Value                              decoded value    4444            A transformation must be provided if the role contains more than one    transformation  A tweak must be provided if the tweak source for the    transformation is  supplied  or  generated   A decode format can optionally    be provided  If one isn t provided  the decoded output will be formatted to    match the template s pattern as in the previous example      Roles  transformations  templates  and alphabets  The Transform secrets engine contains several types of resources that encapsulate different aspects of the information required in order to perform data transformation       Roles   are the basic high level construct that holds the set of   transformation that it is allowed to performed  The role name is provided when   performing encode and decode operations       Transformations   hold information about a particular transformation  It   contains information about the type of transformation that we want to perform    the template that it should use for value detection  and other   transformation specific values such as the tweak source or the masking character   to use       Templates   allow us to determine what and how to capture the value that we   want to transform       Alphabets   provide the set of valid UTF 8 character contained within both   the input and transformed value on FPE transformations      Transformations      Format preserving encryption  Format Preserving Encryption  FPE  performs cryptographically secure transformation via FF3 1 to encode input values while maintaining its data format and length   FF3 1 is a construction that uses AES 256 for encryption        Tweak and tweak source  FF3 1 uses a non confidential parameter called the tweak along with the ciphertext when performing encryption and decryption operations  The tweak is precisely a 7 byte value  The secret engine consumes a base64 encoded string of this value for its encode and decode operation whenever this input is required   In order to simplify the flow of encoding and decoding operations  transformation creation can take care of generating and associating a tweak value  This allows applications to provide a single value without having the need to generate or store any other metadata   In cases where more granularity is required  a tweak value can be generated by Vault and returned  or it may be independently generated and provided   In summary  there are three ways in which the tweak value may be sourced      supplied   This is the default behavior for FPE transformations  The tweak   value must be generated externally  and supplied into the on encode and decode   operations     generated   The secret engine will take care of generating the tweak value   on encode operations and return this back as part of the response along   with the encoded value  It is up to the application to store this value   so that it can be provided back when decoding the encoded value     internal   The secret engine will generate an internal tweak value per   transformation  This value is not returned on encode or decode operations   since it gets re used for all encode and decode operations for the   transformation  Depending on the uniqueness of the dataset  this mode may   introduce higher risks  but provides the most convenience since the value does   not need to be stored separately  This mode should only be used if the values   being encoded are sufficiently unique   Your team and organization should weigh the trade offs when it comes to choosing the proper tweak source to use  For  supplied  and  internal  sourcing  please see  FF3 1 Tweak Usage Details   vault docs secrets transform ff3 tweak details        Input limits  FF3 1 specifies both minimum and maximum limits on the length of an input  These limits are driven by the security goals  making sure that for a given alphabet the input size does not leave the input guessable by brute force   Given an alphabet of length A  an input length L is valid if     L    2    A sup L  sup     1 000 000   and L    2    floor log sub A  sub  2 sup 96  sup      As a concrete example  for handling credit card numbers  A is 10  L is 16  so valid input lengths would be between 6 and 56 characters  This is because 10 sup 6  sup  1 000 000  already greater than 2   and 2    floor log sub 10  sub  2 sup 96  sup      56   Of course  in the case of credit card numbers valid input would always be between 12 and 19 decimal digits        Output limitations  After transformation and formatting by the template  the value is an encrypted version of the input with the format preserved  However  the value itself may be  invalid  with respect to other standards  For example the output credit card number may not validate  it likely won t create a valid check digit    So one must consider when the outputs are stored whether validation in storage may reject them       Masking  Masking performs replacement of matched characters on the input value with a desired character  This form of transformation is non reversible and thus does not support retrieving the original value back using the decode operation       Tokenization   Tokenization   vault docs secrets transform tokenization  exchanges a sensitive value for an unrelated value called a  token   The original sensitive value cannot be recovered from a token alone  they are irreversible        Inputs  Tokenization inputs are not processed by templates or alphabets  as they do not preserve any of the contents or format of the input        Outputs  Tokenization is not format preserving  The token output is a Base58 encoded string value of unrelated length  and is not rendered by a template   The decoded value is returned verbatim as it was before encoding        Metadata  As tokenization isn t format preserving and is stateful  the input values can be any length  subject to other limits in Vault s request processing  In addition  non sensitive  metadata  can be encoded alongside the value  and retrieved either with or independently of the original value        Operations  In addition to encode and decode  as tokenization is stateful  it provides two additional operations     Retrieve metadata given a token    Check whether an input value has a valid  unexpired token    For some configurations  retrieve a previously encoded token for a plaintext   input        Stores  Tokenization is stateful  Tokenized state can be stored internally  the default  or in an external store  Currently only PostgreSQL  MySQL  and MSSQL are supported for external storage        Mapping modes   Tokenization   vault docs secrets transform tokenization  stores the results of an encode operation in storage using a cryptographic construct that enhances the safety of its values  In the  default  mapping mode  the token itself is transformed via a one way function involving the transform key and elements of the token  As Vault does not store the token  the values in Vault storage themselves cannot be used to retrieve original input   A second mapping mode   exportable  is provided for cases where operators may need to recover the full set of decoded inputs in an emergency via the export operation  It is strongly recommended that one use the  default  mode if possible  as it is resistant to more types of attack        Convergent tokenization       Note    Convergent tokenization is not supported for transformations with imported keys   In addition  tokenization transformations may be configured as  convergent   meaning that tokenizing a plaintext and expiration more than once results in the same token value   Enabling convergence has performance and security  considerations   vault docs secrets transform tokenization convergence       Deletion behavior  The deletion of resources  aside from roles  is guarded by checking whether any other related resources are currently using it in order to avoid accidental data loss of any encoded value that may depend on these bits of information to decode and reconstruct the original value  Role deletion can be safely done since the information related to the transformation itself is contained within transformation object and its related resources   The following rules applies when it comes to deleting a resource     A transformation cannot be deleted if it s in use by a role    A template or store cannot be deleted if it s in use by a transformation    An alphabet cannot be deleted if it s in use by a template      Provided builtin resources  The secret engine provides a set of builtin templates and alphabets that are considered common  Builtin templates cannot be deleted  and the prefix  builtin   on template and alphabet names is a reserved keyword       Templates  The following builtin templates are available for use in the secret engine     builtin creditcardnumber   builtin socialsecuritynumber  Note that these templates only check for the matching pattern s   and not the validity of the value itself  For instance  the builtin credit card number template can determine whether the provided value is in the format of commonly issued credit cards  but not whether the credit card is a valid number from a particular issuer   Templates currently only accept regular expressions as the matching pattern type  It uses Go s standard library for the regexp engine  which supports  the RE2 syntax  https   github com google re2 wiki Syntax      Note    The  builtin any  template is only valid and is the default for the tokenization transform       Alphabets  The following builtin alphabets are available for use in the secret engine     builtin numeric   builtin alphalower   builtin alphaupper   builtin alphanumericlower   builtin alphanumericupper   builtin alphanumeric  Custom alphabets must contain between 2 and 65536 unique characters       Stores  The following builtin store is available  and is the default  for tokenization transformations     builtin internal     Tutorial  Refer to the  Transform Secrets Engine   vault tutorials adp transform  tutorial to learn how to use the Transform secrets engine to handle secure data transmission and tokenization against provided secrets      Bring your own key  BYOK        Note    Key import functionality supports cases where there is a need to bring in an existing key from an HSM or other outside systems  It is more secure to have Transform generate and manage a key within Vault       Via the Command Line  The Vault command line tool  includes a helper   vault docs commands transform   to perform the steps described in Manual below        Via the API  First  the wrapping key needs to be read from the transform secrets engine      text   vault read transform wrapping key      The wrapping key will be a 4096 bit RSA public key   Then  the wrapping key is used to create the ciphertext input for the  import  endpoint  as described below  The target key refers to the key being imported       HSM  If the key is being imported from an HSM that supports PKCS 11  there are two possible scenarios     If the HSM supports the CKM RSA AES KEY WRAP mechanism  it can be used to wrap the target key using the wrapping key     Otherwise  two mechanisms can be combined to wrap the target key  First  a 256 bit AES key is generated and then used to wrap the target key using the CKM AES KEY WRAP KWP mechanism  Then the AES key should be wrapped under the wrapping key using the CKM RSA PKCS OAEP mechanism using MGF1 and either SHA 1  SHA 224  SHA 256  SHA 384  or SHA 512   The ciphertext is constructed by appending the wrapped target key to the wrapped AES key   The ciphertext bytes should be base64 encoded       Manual process  If the target key is not stored in an HSM or KMS  the following steps can be used to construct the ciphertext for the input of the  import  endpoint   1  Generate an ephemeral 256 bit AES key   2  Wrap the target key using the ephemeral AES key with AES KWP   3  Wrap the AES key under the Vault wrapping key using RSAES OAEP with MGF1 and either SHA 1  SHA 224  SHA 256  SHA 384  or SHA 512   4  Delete the ephemeral AES key   5  Append the wrapped target key to the wrapped AES key   6  Base64 encode the result   For more details on the key wrapping process  see the  key wrapping guide   vault docs secrets transit key wrapping guide   be sure to use the transform wrapping key when wrapping a key for import into the transform secrets engine       API  The Transform secrets engine has a full HTTP API  Please see the  Transform secrets engine API   vault api docs secret transform  for more details


vault PKI secrets engine quick start root CA setup This document provides a brief overview of setting up a Vault PKI Secrets The PKI secrets engine for Vault generates TLS certificates layout docs Engine with a Root CA certificate page title PKI Secrets Engines Quick Start Root CA Setup

layout  docs page title   PKI   Secrets Engines  Quick Start  Root CA Setup  description  The PKI secrets engine for Vault generates TLS certificates         PKI secrets engine   quick start   root CA setup  This document provides a brief overview of setting up a Vault PKI Secrets Engine with a Root CA certificate        Mount the backend  The first step to using the PKI backend is to mount it  Unlike the  kv  backend  the  pki  backend is not mounted by default      shell session   vault secrets enable pki Successfully mounted  pki  at  pki             Configure a CA certificate  Next  Vault must be configured with a CA certificate and associated private key  We ll take advantage of the backend s self signed root generation support  but Vault also supports generating an intermediate CA  with a CSR for signing  or setting a PEM encoded certificate and private key bundle directly into the backend   Generally you ll want a root certificate to only be used to sign CA intermediate certificates  but for this example we ll proceed as if you will issue certificates directly from the root  As it s a root  we ll want to set a long maximum life time for the certificate  since it honors the maximum mount TTL  first we adjust that      shell session   vault secrets tune  max lease ttl 87600h pki Successfully tuned mount  pki        That sets the maximum TTL for secrets issued from the mount to 10 years   Note that roles can further restrict the maximum TTL    Now  we generate our root certificate      shell session   vault write pki root generate internal common name myvault com ttl 87600h Key             Value                       certificate          BEGIN CERTIFICATE      MIIDNTCCAh2gAwIBAgIUJqrw 9EDZbp4DExaLjh0vSAHyBgwDQYJKoZIhvcNAQEL BQAwFjEUMBIGA1UEAxMLbXl2YXVsdC5jb20wHhcNMTcxMjA4MTkyMzIwWhcNMjcx MjA2MTkyMzQ5WjAWMRQwEgYDVQQDEwtteXZhdWx0LmNvbTCCASIwDQYJKoZIhvcN AQEBBQADggEPADCCAQoCggEBAKY vJ6sRFym yFYUneoVtDmOCaDKAQiGzQw0IXL wgMBBb82iKpYj5aQjXZGIl VkVnCi M2AQ iYXWZf1kTAdle4A6OC4 VefSIa2b4 eB7R8aiGTce62jB95 s5 YgrfIqk6igfpCSXYLE8ubNDA2  cqvjhku1UzlvKBX2 hIlgWkKlrsnybHN B 3Usw9Km 87rzoDR3OMxLV55YPHiq6 olIfSSwKAPjH8LZm uM1ITLG3WQUl8ARF17Dj wOKqbUG38PduVwKL5 qPksrvNwlmCP7Kmjncc6xnYp6 5lfr7V4DC UezrJYCIb0g SvtxoN1OuqmmvSTKiEE7hVOAcCAwEAAaN7MHkwDgYD VR0PAQH BAQDAgEGMA8GA1UdEwEB wQFMAMBAf8wHQYDVR0OBBYEFECKdYM4gDbM kxRZA2wR4f yNhQUMB8GA1UdIwQYMBaAFECKdYM4gDbMkxRZA2wR4f yNhQUMBYG A1UdEQQPMA2CC215dmF1bHQuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCCJKZPcjjn 7mvD2 sr6lx4DW vJwVSW8eTuLtOLNu6 aFhcgTY OOB8q4n6iHuLrEt8 RV7RJI obRx74SfK9BcOLt4 DHGnFXqu2FNVnhDMOKarj41yGyXlJaQRUPYf6WJJLF ZphN nNsZqHJHBfZtpJpE5Vywx3pah08B5yZHk1ItRPEz7EY3uwBI CJoBb P5Ahk6krc LZ62kFwstkVuFp43o3K7cRNexCIsZGx2tsyZ0nyqDUFsBr66xwUfn3C  1CDc9YL zjq 8nI2ooIrj4ZKZCOm2fKd1KeGN CZD7Ob6uNhXrd0Tjwv00a7nffvYQkl 1V5 BT55jevSPVVu      END CERTIFICATE      expiration      1828121029 issuing ca           BEGIN CERTIFICATE      MIIDNTCCAh2gAwIBAgIUJqrw 9EDZbp4DExaLjh0vSAHyBgwDQYJKoZIhvcNAQEL BQAwFjEUMBIGA1UEAxMLbXl2YXVsdC5jb20wHhcNMTcxMjA4MTkyMzIwWhcNMjcx MjA2MTkyMzQ5WjAWMRQwEgYDVQQDEwtteXZhdWx0LmNvbTCCASIwDQYJKoZIhvcN AQEBBQADggEPADCCAQoCggEBAKY vJ6sRFym yFYUneoVtDmOCaDKAQiGzQw0IXL wgMBBb82iKpYj5aQjXZGIl VkVnCi M2AQ iYXWZf1kTAdle4A6OC4 VefSIa2b4 eB7R8aiGTce62jB95 s5 YgrfIqk6igfpCSXYLE8ubNDA2  cqvjhku1UzlvKBX2 hIlgWkKlrsnybHN B 3Usw9Km 87rzoDR3OMxLV55YPHiq6 olIfSSwKAPjH8LZm uM1ITLG3WQUl8ARF17Dj wOKqbUG38PduVwKL5 qPksrvNwlmCP7Kmjncc6xnYp6 5lfr7V4DC UezrJYCIb0g SvtxoN1OuqmmvSTKiEE7hVOAcCAwEAAaN7MHkwDgYD VR0PAQH BAQDAgEGMA8GA1UdEwEB wQFMAMBAf8wHQYDVR0OBBYEFECKdYM4gDbM kxRZA2wR4f yNhQUMB8GA1UdIwQYMBaAFECKdYM4gDbMkxRZA2wR4f yNhQUMBYG A1UdEQQPMA2CC215dmF1bHQuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCCJKZPcjjn 7mvD2 sr6lx4DW vJwVSW8eTuLtOLNu6 aFhcgTY OOB8q4n6iHuLrEt8 RV7RJI obRx74SfK9BcOLt4 DHGnFXqu2FNVnhDMOKarj41yGyXlJaQRUPYf6WJJLF ZphN nNsZqHJHBfZtpJpE5Vywx3pah08B5yZHk1ItRPEz7EY3uwBI CJoBb P5Ahk6krc LZ62kFwstkVuFp43o3K7cRNexCIsZGx2tsyZ0nyqDUFsBr66xwUfn3C  1CDc9YL zjq 8nI2ooIrj4ZKZCOm2fKd1KeGN CZD7Ob6uNhXrd0Tjwv00a7nffvYQkl 1V5 BT55jevSPVVu      END CERTIFICATE      serial number   26 aa f0 ff d1 03 65 ba 78 0c 4c 5a 2e 38 74 bd 20 07 c8 18      The returned certificate is purely informational  it and its private key are safely stored in the backend mount        Set URL configuration  Generated certificates can have the CRL location and the location of the issuing certificate encoded  These values must be set manually and typically to FQDN associated to the Vault server  but can be changed at any time      shell session   vault write pki config urls issuing certificates  http   vault example com 8200 v1 pki ca  crl distribution points  http   vault example com 8200 v1 pki crl  Success  Data written to  pki ca urls           Configure a role  The next step is to configure a role  A role is a logical name that maps to a policy used to generate those credentials  For example  let s create an  example dot com  role      shell session   vault write pki roles example dot com       allowed domains example com       allow subdomains true max ttl 72h Success  Data written to  pki roles example dot com           Issue certificates  By writing to the  roles example dot com  path we are defining the  example dot com  role  To generate a new certificate  we simply write to the  issue  endpoint with that role name  Vault is now configured to create and manage certificates      shell session   vault write pki issue example dot com       common name blah example com Key                 Value                           certificate              BEGIN CERTIFICATE      MIIDvzCCAqegAwIBAgIUWQuvpMpA2ym36EoiYyf3Os5UeIowDQYJKoZIhvcNAQEL BQAwFjEUMBIGA1UEAxMLbXl2YXVsdC5jb20wHhcNMTcxMjA4MTkyNDA1WhcNMTcx MjExMTkyNDM1WjAbMRkwFwYDVQQDExBibGFoLmV4YW1wbGUuY29tMIIBIjANBgkq hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1CU93lVgcLXGPxRGTRT3GM5wqytCo7Z6 gjfoHyKoPCAqjRdjsYgp1FMvumNQKjUat5KTtr2fypbOnAURDCh4bN omcj7eAqt ldJ8mf8CtKUaaJ1kp3R6RRFY u96BnmKUG8G7oDeEDsKlXuEuRcNbGlGF8DaM O1 HFa57cM 8yFB26Nj5wBoG5Om6ee5 W 14Qee8AB6OJbsf883Z zvhJTaB0QM4ZUq uAMoMVEutWhdI5EFm5OjtMeMu2U iJl2XqqgQ JmLRjRdMn1qd9TzTaVSnjoZ97s jHK444Px1m45einLqKUJ Ia2ljXYkkItJj9Ut6ZSAP9fHlAtX84W3QIDAQABo4H  MIH8MA4GA1UdDwEB wQEAwIDqDAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUH AwIwHQYDVR0OBBYEFH YdObW6T94U0zuU5hBfTfU5pt1MB8GA1UdIwQYMBaAFECK dYM4gDbMkxRZA2wR4f yNhQUMDsGCCsGAQUFBwEBBC8wLTArBggrBgEFBQcwAoYf aHR0cDovLzEyNy4wLjAuMTo4MjAwL3YxL3BraS9jYTAbBgNVHREEFDASghBibGFo LmV4YW1wbGUuY29tMDEGA1UdHwQqMCgwJqAkoCKGIGh0dHA6Ly8xMjcuMC4wLjE6 ODIwMC92MS9wa2kvY3JsMA0GCSqGSIb3DQEBCwUAA4IBAQCDXbHV68VayweB2tkb KDdCaveaTULjCeJUnm9UT 6C0YqC RxTAjdKFrilK49elOA3rAtEL6dmsDP2yH25 ptqi2iU y99HhZgu0zkS p8elYN3 l 0O7pOxayYXBkFf5t0TlEWSTb7cW Etz c MvSqx6vVvspSjB0PsA3eBq0caZnUJv2u TEiUe7PPY0UmrZxp R P kE54yI3nWN 4Cwto6yUwScOPbVR1d3hE2KU2toiVkEoOk17UyXWTokbG8rG0KLj99zu7my Fyre sjV5nWGDSMZODEsGxHOC JgNAC1z3n14 InFNOsHICnA5AnJzQdSQQjvcZHN2NyW  t4f      END CERTIFICATE      issuing ca               BEGIN CERTIFICATE      MIIDNTCCAh2gAwIBAgIUJqrw 9EDZbp4DExaLjh0vSAHyBgwDQYJKoZIhvcNAQEL BQAwFjEUMBIGA1UEAxMLbXl2YXVsdC5jb20wHhcNMTcxMjA4MTkyMzIwWhcNMjcx MjA2MTkyMzQ5WjAWMRQwEgYDVQQDEwtteXZhdWx0LmNvbTCCASIwDQYJKoZIhvcN AQEBBQADggEPADCCAQoCggEBAKY vJ6sRFym yFYUneoVtDmOCaDKAQiGzQw0IXL wgMBBb82iKpYj5aQjXZGIl VkVnCi M2AQ iYXWZf1kTAdle4A6OC4 VefSIa2b4 eB7R8aiGTce62jB95 s5 YgrfIqk6igfpCSXYLE8ubNDA2  cqvjhku1UzlvKBX2 hIlgWkKlrsnybHN B 3Usw9Km 87rzoDR3OMxLV55YPHiq6 olIfSSwKAPjH8LZm uM1ITLG3WQUl8ARF17Dj wOKqbUG38PduVwKL5 qPksrvNwlmCP7Kmjncc6xnYp6 5lfr7V4DC UezrJYCIb0g SvtxoN1OuqmmvSTKiEE7hVOAcCAwEAAaN7MHkwDgYD VR0PAQH BAQDAgEGMA8GA1UdEwEB wQFMAMBAf8wHQYDVR0OBBYEFECKdYM4gDbM kxRZA2wR4f yNhQUMB8GA1UdIwQYMBaAFECKdYM4gDbMkxRZA2wR4f yNhQUMBYG A1UdEQQPMA2CC215dmF1bHQuY29tMA0GCSqGSIb3DQEBCwUAA4IBAQCCJKZPcjjn 7mvD2 sr6lx4DW vJwVSW8eTuLtOLNu6 aFhcgTY OOB8q4n6iHuLrEt8 RV7RJI obRx74SfK9BcOLt4 DHGnFXqu2FNVnhDMOKarj41yGyXlJaQRUPYf6WJJLF ZphN nNsZqHJHBfZtpJpE5Vywx3pah08B5yZHk1ItRPEz7EY3uwBI CJoBb P5Ahk6krc LZ62kFwstkVuFp43o3K7cRNexCIsZGx2tsyZ0nyqDUFsBr66xwUfn3C  1CDc9YL zjq 8nI2ooIrj4ZKZCOm2fKd1KeGN CZD7Ob6uNhXrd0Tjwv00a7nffvYQkl 1V5 BT55jevSPVVu      END CERTIFICATE      private key              BEGIN RSA PRIVATE KEY      MIIEpAIBAAKCAQEA1CU93lVgcLXGPxRGTRT3GM5wqytCo7Z6gjfoHyKoPCAqjRdj sYgp1FMvumNQKjUat5KTtr2fypbOnAURDCh4bN omcj7eAqtldJ8mf8CtKUaaJ1k p3R6RRFY u96BnmKUG8G7oDeEDsKlXuEuRcNbGlGF8DaM O1HFa57cM 8yFB26Nj 5wBoG5Om6ee5 W 14Qee8AB6OJbsf883Z zvhJTaB0QM4ZUquAMoMVEutWhdI5EF m5OjtMeMu2U iJl2XqqgQ JmLRjRdMn1qd9TzTaVSnjoZ97sjHK444Px1m45einL qKUJ Ia2ljXYkkItJj9Ut6ZSAP9fHlAtX84W3QIDAQABAoIBAQCf5YIANfF gkNt   YM6yRi hZJrU2I 1zPETxPW1vaFZR8y4hEoxCEDD8JCRm 9k w1TWoorvxgkEv r1HuDALYbNtwLd 71nCHYCKyH1b2uQpyl07qOAyASlb9r5oVjz4E6eobkd3N9fJA QN0EdK VarN968mLJsD3Hxb8chGdObBCQ LO zdqQLaz JwhfnK98rm6huQtYK3w ccd0OwoVmtZz2eJl11TJkB9fi4WqJyxl4wST7QC80LstB1deR78oDmN5WUKU12 G 4Mrgc1hRwUSm18HTTgAhaA4A3rjPyirBohb5Sf jJxusnnay7tvWeMnIiRI9mqCE dr3tLrcxAoGBAPL jHVUF6sxBqm6RTe8Ewg 8RrGmd69oB71QlVUrLYyC96E2s56 19dcyt5U2z F0u9wlwR1rMb2BJIXbxlNk i87IHmpOjCMS38SPZYWLHKj02eGfvA MjKKqEjNY md9eVAVZIWSEy63c4UcBK1qUH3 5PNlyjk53gCOI 4OXX AoGBAN A Alyd6A pyHWq8WMyAlV18LnzX8XktJ07xrNmjbPGD5sEHp Q9V33NitOZpu3bQL  gCNmcrodrbr9LBV83bkAOVJrf82SPaBesV ATY7ZiWpqvHTmcoS7nglM2XTr uWR Y9JGdpCE9U5QwTc6qfcn7Eqj7yNvvHMrT 1SHwsjAoGBALQyQEbhzYuOF7rV 26N ci z 0A39vNO  b5Se tk0apZlPlgb2NK3LxxR LHevFed9GRzdvbGk F7Se3CyP cxgswdazC6fwGjhX1mOYsG1oIU0V6X7f0FnaqWETrwf1M9yGEO78xzDfgozIazP0 s0fQeR9KXsZcuaotO3TIRxRRAoGAMFIDsLRvDKm1rkL0B0czm hwwDMu KDyr5 R 2M2OS1TB4PjmCgeUFOmyq3A63OWuStxtJboribOK8Qd1dXvWj 3NZtVY z j1P1E Ceq6We0MOZa0Ae4kyi p kbAKPgv VwSoc6cKailRHZPH7quLoJSIt0IgbfRnXC6 ygtcLNMCgYBwiPw2mTYvXDrAcO17NhK r7IL7BEdFdx w8vNJQp Ub4OO3Iw6ARI vXxu6A Qp50jra3UUtnI hIirMS XEeWqJghK1js3ZR6wA ZkYZw5X1RYuPexb 4 6befxmnEuGSbsgvGqYYTf5Z0vgsw4tAHfNS7TqSulYH06CjeG1F8DQ        END RSA PRIVATE KEY      private key type    rsa serial number       59 0b af a4 ca 40 db 29 b7 e8 4a 22 63 27 f7 3a ce 54 78 8a      Vault has now generated a new set of credentials using the  example dot com  role configuration  Here we see the dynamically generated private key and certificate   Using ACLs  it is possible to restrict using the pki backend such that trusted operators can manage the role definitions  and both users and applications are restricted in the credentials they are allowed to read   If you get stuck at any time  simply run  vault path help pki  or with a subpath for interactive help output      Tutorial  Refer to the  Build Your Own Certificate Authority  CA    vault tutorials secrets management pki engine  guide for a step by step tutorial   Have a look at the  PKI Secrets Engine with Managed Keys   vault tutorials enterprise managed key pki  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   vault api docs secret pki  for more details