vault/website/content/docs/secrets/pki/est.mdx

---
layout: docs
page_title: Enrollment over Secure Transport (EST) within Vault | PKI - Secrets Engines
description: An overview of the Enrollment over Secure Transport protocol implementation within Vault.
---

# PKI secrets engine - Enrollment over Secure Transport (EST) <EnterpriseAlert inline="true" />

This document covers configuration and limitations of Vault's PKI Secrets Engine
implementation of the [EST protocol](https://datatracker.ietf.org/doc/html/rfc7030) <EnterpriseAlert inline="true" />.

## What is Enrollment over Secure Transport (EST)?

The EST protocol is an IETF standardized protocol, [RFC 7030](https://datatracker.ietf.org/doc/html/rfc7030),
that allows clients to acquire client certificates and associated
Certificate Authority (CA) certificates.

## Enabling EST support on a Vault PKI mount

The following is a list of steps required to configure an existing PKI
mount to serve EST clients. Each of which can be broken down within three main
categories.

 1. [Authentication mechanisms](#configuring-est-authentication)
 1. [Updating PKI tunable parameters](#updating-the-pki-mount-tunable-parameters)
 1. [PKI EST configuration](#pki-est-configuration)

### Configuring EST Authentication

The EST protocol specifies a few different authentication mechanisms, of which
Vault supports two.

 1. [HTTP-Based Client authentication](/vault/docs/auth/userpass)
 1. [Certificate TLS authentication](/vault/docs/auth/cert)

Both of these authentication mechanisms leverage a separate Vault authentication
mount, within the same namespace, to validate the client provided credentials
along with the client's ACL policy to enforce. While both authentication
schemes can be enabled at once, only a single mount will be used to authenticate
a client based on the way credentials were provided through EST. If an EST client sends
HTTP-Based authentication credentials, they will be preferred over TLS client
certificates.

For proper accounting, mounts supporting EST authentication should be
dedicated to this purpose, not shared with other workflows.  In other words,
create a new auth mount for EST even if you already have one of the same
type for other purposes.

When setting up the authentication mount for EST clients, the token type must
be configured to return [batch tokens](/vault/docs/concepts/tokens#batch-tokens).
Batch tokens are required to avoid an excessive amount of leases being generated
and persisted as every EST incoming request needs to be authenticated.

The path within an ACL policy, must match the internal redirected path including
the mount and not the `.well-known/est/` URI the client is initially using.
The path to use within the plugin depends on the path policy that is in configured
for the EST label being used by the client.

If using the `sign-verbatim` as a path policy, the following
ACL policy will allow an authenticated client access the required PKI EST paths.
```
path “pki/est/simpleenroll” {
  capabilities=[“update”, “create”]
}
path “pki/est/simplereenroll” {
  capabilities=[“update”, “create”]
}
```

For a role base path policy, this sample policy can be used
```
path “pki/roles/my-role-name/est/simpleenroll” {
  capabilities=[“update”, “create”]
}
path “pki/roles/my-role-name/est/simplereenroll” {
  capabilities=[“update”, “create”]
}
```

#### Updating the PKI mount tunable parameters

Once the authentication mount has been created and configured, the authentication mount's accessor
will need to be captured and added within the PKI mount's [delegated auth accessors](/vault/api-docs/system/mounts#delegated_auth_accessors).

To get an authentication mount's accessor field, the following command can be used.

```shell-session
$ vault read -field=accessor sys/auth/auth/userpass
```

For EST to work within certain clients, a few response headers need to be explicitly allowed
along with configuring the list of accessors the mount can delegate authentication towards.
The following will grant the required response headers, you will need to replace the values for the `delegated-auth-accessors`
to match your values.

```shell-session
$ vault secrets tune \
  -allowed-response-headers="Content-Transfer-Encoding" \
  -allowed-response-headers="Content-Length" \
  -allowed-response-headers="WWW-Authenticate" \
  -delegated-auth-accessors="auth_userpass_e2f4f6d5" \
  -delegated-auth-accessors="auth_cert_4088ac2d" \
  pki
```

#### PKI EST configuration

The EST protocol specifies that an EST server must support a URI path-prefix of
`.well-known/est/` as defined in [RFC-5785](https://datatracker.ietf.org/doc/html/rfc5785).
EST client's normally don't provide any sort of configuration for different path-prefixes, and will
default to hitting the host on the path `https://<hostname>:<port>/.well-known/est/`.

Some clients allow a single label, sometimes referred to as `additional path segment`,
to accommodate different issuers. This label will be added to the path after
the est path such as `https://<hostname>:<port>/.well-known/est/<label>/`.

To provide different restrictions around usage (defaults, an issuer or role),
for EST protocol endpoints, a path policy is associated with the EST
label.

@include 'pki-est-default-policy.mdx'

Within the Vault [EST configuration API](/vault/api-docs/secret/pki/issuance#set-est-configuration), a PKI
mount can be specified as the default mount by enabling [default_mount](/vault/api-docs/secret/pki/issuance#default_mount)
to true, or provide a mapping of a label within [label_to_path_policy](/vault/api-docs/secret/pki/issuance#label_to_path_policy)

As an example of a complete EST configuration, that would enable the pki mount
to register the .well-known/est default label, along with two additional labels
of test-label and sign-all.

The test-label would use the existing est-clients PKI role for restrictions and defaults,
leveraging the issuer specified within the role. The other two labels, default and sign-all will
leverage a sign-verbatim type role, allowing any identifier to be issued using the default
issuer.

```shell-session
vault write pki/config/est -<<EOC
{
  "enabled": true,
  "default_mount": true,
  "default_path_policy": "sign-verbatim",
  "label_to_path_policy": {
    "test-label": "role:est-clients",
    "sign-all": "sign-verbatim"
  },
  "authenticators": {
    "cert": {
      "accessor": "auth_cert_4088ac2d"
    },
    "userpass": {
      "accessor": "auth_userpass_e2f4f6d5"
    }
  }
}
EOC
```

## Limitations

### EST API Support

The initial implementation covers solely the required API endpoints of the EST protocol.
The following optional features from the specification are not currently supported.

 - [Full CMC](https://datatracker.ietf.org/doc/html/rfc7030#section-4.3)
 - [Server-side key generation](https://datatracker.ietf.org/doc/html/rfc7030#section-4.4)
 - [CSR attribute endpoints](https://datatracker.ietf.org/doc/html/rfc7030#section-4.5)

### Well Known redirections

The EST configuration parameters `default_mount` and/or `label_to_path_policy` can be used to register
paths within the .well-known path space. The following limitations apply:

 - Only a single PKI mount, across all namespaces, can be enabled as the `default_mount`.
 - Labels within `label_to_path_policy` must also be unique across all PKI mounts regardless of namespace.
 - Care must be taken if enabling EST on a [local](/vault/docs/commands/secrets/enable#local) PKI mount on
   performance secondary clusters. Vault cannot guarantee the configured EST labels do
   not conflict across different PKI mounts in this use-case. This can lead to
   different issuers being used across clusters for the same EST labels.

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