vault port page title TCP Listeners Configuration tcp listener layout docs The TCP listener configures Vault to listen on the specified TCP address and

Answer:
---
layout: docs
page_title: TCP - Listeners - Configuration
description: >-
  The TCP listener configures Vault to listen on the specified TCP address and
  port.
---

# `tcp` listener

@include 'alerts/ipv6-compliance.mdx'

The TCP listener configures Vault to listen on a TCP address/port.

```hcl
listener "tcp" {
  address = "127.0.0.1:8200"
}
```

The `listener` stanza may be specified more than once to make Vault listen on
multiple interfaces. If you configure multiple listeners you also need to
specify [`api_addr`][api-addr] and [`cluster_addr`][cluster-addr] so Vault will
advertise the correct address to other nodes.

## Sensitive data redaction for unauthenticated endpoints

Unauthenticated API endpoints may return the following sensitive information:

* Vault version number
* Vault binary build date
* Vault cluster name
* IP address of nodes in the cluster

Vault offers the ability to configure each `tcp` `listener` stanza such that,
when appropriate, these values are redacted from responses.

The following API endpoints support redaction based on `listener` stanza configuration:

* [`/sys/health`](/vault/api-docs/system/health)
* [`/sys/leader`](/vault/api-docs/system/leader)
* [`/sys/seal-status`](/vault/api-docs/system/seal-status)

Vault replaces redacted information with an empty string (`""`). Some Vault APIs
also omit keys from the response when the corresponding value is empty (`""`).

<Note title="Redacting values affects responses to all API clients">
  The Vault CLI and UI consume Vault API responses. As a result, your redaction
  settings will apply to CLI and UI output in addition to direct API calls.
</Note>

## Default TLS configuration

By default, Vault TCP listeners only accept TLS 1.2 or 1.3 connections and will
drop connection requests from clients using TLS 1.0 or 1.1.

Vault uses the following ciphersuites by default:

- **TLS 1.3** - `TLS_AES_128_GCM_SHA256`, `TLS_AES_256_GCM_SHA384`, or `TLS_CHACHA20_POLY1305_SHA256`.
- **TLS 1.2** - depends on whether you configure Vault with a RSA or ECDSA certificate.

You can configure Vault with any cipher supported by the
[`tls`](https://pkg.go.dev/crypto/tls) and
[`tlsutil`](https://github.com/hashicorp/go-secure-stdlib/blob/main/tlsutil/tlsutil.go#L31-L57)
Go packages. Vault uses the `tlsutil` package to parse ciphersuite configurations.

<Note title="Sweet32 and 3DES">

  The Go team and HashiCorp believe that the set of cyphers supported by `tls`
  and `tlsutil` is appropriate for modern, secure usage. However, some
  vulnerability scanners may flag issues with your configuration.

  In particular, Sweet32 (CVE-2016-2183) is an attack against 64-bit block size
  ciphers including 3DES that may allow an attacker to break the encryption of
  long lived connections. According to the
  [vulnerability disclosure](https://sweet32.info/), Sweet32 took a
  single HTTPS session with 785 GB of traffic to break the encryption.

  As of May 2024, the Go team does not believe the risk of Sweet32 is sufficient
  to remove existing client compatibility by deprecating 3DES support, however,
  the team did [de-prioritize 3DES](https://github.com/golang/go/issues/45430)
  in favor of AES-based ciphers.

</Note>

Before overriding Vault defaults, we recommend reviewing the recommended Go team
[approach to TLS configuration](https://go.dev/blog/tls-cipher-suites) with
particular attention to their ciphersuite selections.

## Listener's custom response headers

As of version 1.9, Vault supports defining custom HTTP response headers for the root path (`/`) and also on API endpoints (`/v1/*`).
The headers are defined based on the returned status code. For example, a user can define a list of
custom response headers for the `200` status code, and another list of custom response headers for
the `307` status code. There is a `"/sys/config/ui"` [API endpoint](/vault/api-docs/system/config-ui) which allows users
to set `UI` specific custom headers. If a header is configured in a configuration file, it is not allowed
to be reconfigured through the `"/sys/config/ui"` [API endpoint](/vault/api-docs/system/config-ui). In cases where a
custom header value needs to be modified or the custom header needs to be removed, the Vault's configuration file
needs to be modified accordingly, and a `SIGHUP` signal needs to be sent to the Vault process.

If a header is defined in the configuration file and the same header is used by the internal
processes of Vault, the configured header is not accepted. For example, a custom header which has
the `X-Vault-` prefix will not be accepted. A message will be logged in the Vault's logs
upon start up indicating the header with `X-Vault-` prefix is not accepted.

### Order of precedence

If the same header is configured in both the configuration file and
in the `"/sys/config/ui"` [API endpoint](/vault/api-docs/system/config-ui), the header in the configuration file takes precedence.
For example, the `"Content-Security-Policy"` header is defined by default in the
`"/sys/config/ui"` [API endpoint](/vault/api-docs/system/config-ui). If that header is also defined in the configuration file,
the value in the configuration file is set in the response headers instead of the
default value in the `"/sys/config/ui"` [API endpoint](/vault/api-docs/system/config-ui).

## `tcp` listener parameters

- `address` `(string: "127.0.0.1:8200")` – Specifies the address to bind to for
  listening. This can be dynamically defined with a
  [go-sockaddr template](https://pkg.go.dev/github.com/hashicorp/go-sockaddr/template)
  that is resolved at runtime.

- `cluster_address` `(string: "127.0.0.1:8201")` – Specifies the address to bind
  to for cluster server-to-server requests. This defaults to one port higher
  than the value of `address`. This does not usually need to be set, but can be
  useful in case Vault servers are isolated from each other in such a way that
  they need to hop through a TCP load balancer or some other scheme in order to
  talk. This can be dynamically defined with a
  [go-sockaddr template](https://pkg.go.dev/github.com/hashicorp/go-sockaddr/template)
  that is resolved at runtime.

- `chroot_namespace` `(string: "")` – Specifies an alternate top-level namespace
  for the listener. Vault appends namespaces provided in the `X-Vault-Namespace`
  header or the `-namespace` field in a CLI command to the top-level namespace
  to determine the full namespace path for the request. For example, if
  `chroot_namespace` is set to `admin` and the `X-Vault-Namespace` header is
  `ns1`, the full namespace path is `admin/ns1`. Calls to the listener will fail
   with a 4XX error if the top-level namespace provided for `chroot_namespace`
   does not exist.
- `http_idle_timeout` `(string: "5m")` - Specifies the maximum amount of time to
  wait for the next request when keep-alives are enabled. If `http_idle_timeout`
  is zero, the value of `http_read_timeout` is used. If both are zero, the value
  of `http_read_header_timeout` is used. This is specified using a label suffix
  like `"30s"` or `"1h"`.

- `http_read_header_timeout` `(string: "10s")` - Specifies the amount of time
  allowed to read request headers. This is specified using a label suffix like
  `"30s"` or `"1h"`.

- `http_read_timeout` `(string: "30s")` - Specifies the maximum duration for
  reading the entire request, including the body. This is specified using a
  label suffix like `"30s"` or `"1h"`.

- `http_write_timeout` `string: "0")` - Specifies the maximum duration before
  timing out writes of the response and is reset whenever a new request's header
  is read. The default value of `"0"` means infinity. This is specified using a
  label suffix like `"30s"` or `"1h"`.

- `max_request_size` `(int: 33554432)` – Specifies a hard maximum allowed
  request size, in bytes. Defaults to 32 MB if not set or set to `0`.
  Specifying a number less than `0` turns off limiting altogether.

- `max_request_duration` `(string: "90s")` – Specifies the maximum
  request duration allowed before Vault cancels the request. This overrides
  `default_max_request_duration` for this listener.

- `proxy_protocol_behavior` `(string: "")` – When specified, enables a PROXY
  protocol behavior for the listener (version 1 and 2 are both supported).
  Accepted Values:

  - _use_always_ - The client's IP address will always be used.
  - _allow_authorized_ - If the source IP address is in the
    `proxy_protocol_authorized_addrs` list, the client's IP address will be used.
    If the source IP is not in the list, the source IP address will be used.
  - _deny_unauthorized_ - The traffic will be rejected if the source IP
    address is not in the `proxy_protocol_authorized_addrs` list.

- `proxy_protocol_authorized_addrs` `(string: <required-if-enabled> or array: <required-if-enabled> )` –
  Specifies the list of allowed source IP addresses to be used with the PROXY protocol.
  Not required if `proxy_protocol_behavior` is set to `use_always`. Source IPs should
  be comma-delimited if provided as a string. At least one source IP must be provided,
  `proxy_protocol_authorized_addrs` cannot be an empty array or string.

- `redact_addresses` `(bool: false)` - Redacts `leader_address` and `cluster_leader_address` values in applicable API responses when `true`.

- `redact_cluster_name` `(bool: false)` - Redacts `cluster_name` values in applicable API responses when `true`.

- `redact_version` `(bool: false)` - Redacts `version` and `build_date` values in applicable API responses when `true`.

- `tls_disable` `(string: "false")` – Specifies if TLS will be disabled. Vault
  assumes TLS by default, so you must explicitly disable TLS to opt-in to
  insecure communication. Disabling TLS can **disable** some UI functionality. See
  the [Browser Support](/vault/docs/browser-support) page for more details.

- `tls_cert_file` `(string: <required-if-enabled>, reloads-on-SIGHUP)` –
  Specifies the path to the certificate for TLS. It requires a PEM-encoded file.
  To configure the listener to use a CA certificate, concatenate the primary certificate and the CA
  certificate together. The primary certificate should appear first in the
  combined file. On `SIGHUP`, the path set here _at Vault startup_ will be used
  for reloading the certificate; modifying this value while Vault is running
  will have no effect for `SIGHUP`s.

- `tls_key_file` `(string: <required-if-enabled>, reloads-on-SIGHUP)` –
  Specifies the path to the private key for the certificate. It requires a PEM-encoded file.
  If the key file is encrypted, you will be prompted to enter the passphrase on server startup.
  The passphrase must stay the same between key files when reloading your
  configuration using `SIGHUP`. On `SIGHUP`, the path set here _at Vault
  startup_ will be used for reloading the certificate; modifying this value
  while Vault is running will have no effect for `SIGHUP`s.

- `tls_min_version` `(string: "tls12")` – Specifies the minimum supported
  version of TLS. Accepted values are "tls10", "tls11", "tls12" or "tls13".

  ~> **Warning**: TLS 1.1 and lower (`tls10` and `tls11` values for the
  `tls_min_version` and `tls_max_version` parameters) are widely considered
  insecure.

- `tls_max_version` `(string: "tls13")` – Specifies the maximum supported
  version of TLS. Accepted values are "tls10", "tls11", "tls12" or "tls13".

  ~> **Warning**: TLS 1.1 and lower (`tls10` and `tls11` values for the
  `tls_min_version` and `tls_max_version` parameters) are widely considered
  insecure.

- `tls_cipher_suites` `(string: "")` – Specifies the list of supported
  ciphersuites as a comma-separated-list. The list of all available ciphersuites
  is available in the [Golang TLS documentation][golang-tls].

  ~> **Note**: Go only consults the `tls_cipher_suites` list for TLSv1.2 and
  earlier; the order of ciphers is not important. For this parameter to be
  effective, the `tls_max_version` property must be set to `tls12` to prevent
  negotiation of TLSv1.3, which is not recommended. For more information about
  this and other TLS related changes, see the [Go TLS blog post][go-tls-blog].

- `tls_prefer_server_cipher_suites` `(string: "false")` – Specifies to prefer the
  server's ciphersuite over the client ciphersuites.

  ~> **Warning**: The `tls_prefer_server_cipher_suites` parameter is
  deprecated. Setting it has no effect. See the above
  [Go blog post][go-tls-blog] for more information about
  this change.

- `tls_require_and_verify_client_cert` `(string: "false")` – Turns on client
  authentication for this listener; the listener will require a presented
  client cert that successfully validates against system CAs.

- `tls_client_ca_file` `(string: "")` – PEM-encoded Certificate Authority file
  used for checking the authenticity of client.

- `tls_disable_client_certs` `(string: "false")` – Turns off client
  authentication for this listener. The default behavior (when this is false)
  is for Vault to request client authentication certificates when available.

  ~> **Warning**: The `tls_disable_client_certs` and `tls_require_and_verify_client_cert` fields in the listener stanza of the Vault server configuration are mutually exclusive fields. Please ensure they are not both set to true. TLS client verification remains optional with default settings and is not enforced.

- `x_forwarded_for_authorized_addrs` `(string: <required-to-enable>)` –
  Specifies the list of source IP CIDRs for which an X-Forwarded-For header
  will be trusted. Comma-separated list or JSON array. This turns on
  X-Forwarded-For support.  If for example Vault receives connections from the
  load balancer's IP of `1.2.3.4`, adding `1.2.3.4` to `x_forwarded_for_authorized_addrs`
  will result in the `remote_address` field in the audit log being populated with the
  connecting client's IP, for example `3.4.5.6`. Note this requires the load balancer
  to send the connecting client's IP in the `X-Forwarded-For` header.

- `x_forwarded_for_client_cert_header` `(string: "")` –
  Specifies the header that will be used for the client certificate.
  This is required if you use the [TLS Certificates Auth Method](/vault/docs/auth/cert) and your
  vault server is behind a reverse proxy.

- `x_forwarded_for_client_cert_header_decoders` `(string: "")` –
  Comma delimited list that specifies the decoders that will be used to decode the client certificate.
  This is required if you use the [TLS Certificates Auth Method](/vault/docs/auth/cert) and your
  vault server is behind a reverse proxy. The resulting certificate should be in DER format.
  Available Values:

  - BASE64 - Runs Base64 decode
  - DER - Converts a pem certificate to der
  - URL - Runs URL decode

  Known Values:

  - Traefik = "BASE64"
  - NGINX   = "URL,DER"

- `x_forwarded_for_hop_skips` `(string: "0")` – The number of addresses that will be
  skipped from the _rear_ of the set of hops. For instance, for a header value
  of `1.2.3.4, 2.3.4.5, 3.4.5.6, 4.5.6.7`, if this value is set to `"1"`, the address that
  will be used as the originating client IP is `3.4.5.6`.

- `x_forwarded_for_reject_not_authorized` `(string: "true")` – If set false,
  if there is an X-Forwarded-For header in a connection from an unauthorized
  address, the header will be ignored and the client connection used as-is,
  rather than the client connection rejected.

- `x_forwarded_for_reject_not_present` `(string: "true")` – If set false, if
  there is no X-Forwarded-For header or it is empty, the client address will be
  used as-is, rather than the client connection rejected.

- `disable_replication_status_endpoints` `(bool: false)` - Disables replication
  status endpoints for the configured listener when set to `true`.

### `telemetry` parameters

- `unauthenticated_metrics_access` `(bool: false)` - If set to true, allows
  unauthenticated access to the `/v1/sys/metrics` endpoint.

### `profiling` parameters

- `unauthenticated_pprof_access` `(bool: false)` - If set to true, allows
  unauthenticated access to the `/v1/sys/pprof` endpoint.

### `inflight_requests_logging` parameters

- `unauthenticated_in_flight_requests_access` `(bool: false)` - If set to true, allows
  unauthenticated access to the `/v1/sys/in-flight-req` endpoint.

### `custom_response_headers` parameters

- `default` `(key-value-map: {})` - A map of string header names to an array of
  string values. The default headers are set on all endpoints regardless of
  the status code value. For an example, please refer to the
  "Configuring custom http response headers" section.

- `<specific status code>` `(key-value-map: {})` - A map of string header names
  to an array of string values. These headers are set only when the specific status
  code is returned. For example, `"200" = {"Header-A": ["Value1", "Value2"]}`, `"Header-A"`
  is set when the http response status code is `"200"`.

- `<collective status code>` `(key-value-map: {})` - A map of string header names
  to an array of string values. These headers are set only when the response status
  code falls under the collective status code.
  For example, `"2xx" = {"Header-A": ["Value1", "Value2"]}`, `"Header-A"`
  is set when the http response status code is `"200"`, `"204"`, etc.

## `tcp` listener examples

### Configuring TLS

This example shows enabling a TLS listener.

```hcl
listener "tcp" {
  address = "127.0.0.1:8200"
  tls_cert_file = "/etc/certs/vault.crt"
  tls_key_file  = "/etc/certs/vault.key"
}
```

### Listening on multiple interfaces

This example shows Vault listening on a private interface, as well as localhost.

```hcl
listener "tcp" {
  address = "127.0.0.1:8200"
}

listener "tcp" {
  address = "10.0.0.5:8200"
}

# Advertise the non-loopback interface
api_addr = "https://10.0.0.5:8200"
cluster_addr = "https://10.0.0.5:8201"
```

### Configuring unauthenticated metrics access

This example shows enabling unauthenticated metrics access.

```hcl
listener "tcp" {
  telemetry {
    unauthenticated_metrics_access = true
  }
}
```

### Configuring unauthenticated profiling access

This example shows enabling unauthenticated profiling access.

```hcl
listener "tcp" {
  profiling {
    unauthenticated_pprof_access = true
    unauthenticated_in_flight_request_access = true
  }
}
```

### Configuring custom http response headers

Note: Requires Vault version 1.9 or newer. This example shows configuring custom http response headers.
Operators can configure `"custom_response_headers"` sub-stanza in the listener stanza to set custom http
headers appropriate to their applications. Examples of such headers are `"Strict-Transport-Security"`
and `"Content-Security-Policy"` which are known HTTP headers, and could be configured to harden
the security of an application communicating with the Vault endpoints. Note that vulnerability
scans often examine such security related HTTP headers. In addition, application specific
custom headers can also be configured. For example, `"X-Custom-Header"` has been configured
in the example below.

```hcl
listener "tcp" {
  custom_response_headers {
    "default" = {
      "Strict-Transport-Security" = ["max-age=31536000","includeSubDomains"],
      "Content-Security-Policy" = ["connect-src https://clusterA.vault.external/"],
      "X-Custom-Header" = ["Custom Header Default Value"],
    },
    "2xx" = {
      "Content-Security-Policy" = ["connect-src https://clusterB.vault.external/"],
      "X-Custom-Header" = ["Custom Header Value 1", "Custom Header Value 2"],
    },
    "301" = {
      "Strict-Transport-Security" = ["max-age=31536000"],
      "Content-Security-Policy" = ["connect-src https://clusterC.vault.external/"],
    },
  }
}
```

In situations where a header is defined under several status code subsections,
the header matching the most specific response code will be returned. For example,
with the config example below, a `307` response would return `307 Custom header value`,
while a `306` would return `3xx Custom header value`.

```hcl
listener "tcp" {
  custom_response_headers {
    "default" = {
       "X-Custom-Header" = ["default Custom header value"]
    },
    "3xx" = {
       "X-Custom-Header" = ["3xx Custom header value"]
    },
    "307" = {
       "X-Custom-Header" = ["307 Custom header value"]
    }
  }
}
```

### Listening on all IPv6 & IPv4 interfaces

This example shows Vault listening on all IPv4 & IPv6 interfaces including localhost.

```hcl
listener "tcp" {
  address         = "[::]:8200"
  cluster_address = "[::]:8201"
}
```

### Listening to specific IPv6 address

This example shows Vault only using IPv6 and binding to the interface with the IP address: `2001:1c04:90d:1c00:a00:27ff:fefa:58ec`

```hcl
listener "tcp" {
  address         = "[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8200"
  cluster_address = "[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8201"
}

# Advertise the non-loopback interface
api_addr = "https://[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8200"
cluster_addr = "https://[2001:1c04:90d:1c00:a00:27ff:fefa:58ec]:8201"
```

## Redaction examples

Please see redaction settings above, for details on each redaction setting.

Example configuration for the [`tcp`](/vault/docs/configuration/listener/tcp) listener,
enabling [`redact_addresses`](/vault/docs/configuration/listener/tcp#redact_addresses),
[`redact_cluster_name`](/vault/docs/configuration/listener/tcp#redact_cluster_name) and
[`redact_version`](/vault/docs/configuration/listener/tcp#redact_version).

```hcl
ui            = true
cluster_addr  = "https://127.0.0.1:8201"
api_addr      = "https://127.0.0.1:8200"
disable_mlock = true

storage "raft" {
  path = "/path/to/raft/data"
  node_id = "raft_node_1"
}

listener "tcp" {
  address             = "127.0.0.1:8200",
  tls_cert_file = "/path/to/full-chain.pem"
  tls_key_file  = "/path/to/private-key.pem"
  redact_addresses    = "true"
  redact_cluster_name = "true"
  redact_version      = "true"
}

telemetry {
  statsite_address = "127.0.0.1:8125"
  disable_hostname = true
}
```

### API: `/sys/health`
In the following call to `/sys/health/` notice that `cluster_name` and `version`
are both redacted. The `cluster_name` field is fully omitted from the response
and `version` is the empty string (`""`).

```shell-session
$ curl -s https://127.0.0.1:8200/v1/sys/health | jq`:

{
  "initialized": true,
  "sealed": false,
  "standby": true,
  "performance_standby": false,
  "replication_performance_mode": "disabled",
  "replication_dr_mode": "disabled",
  "server_time_utc": 1696598650,
  "version": "",
  "cluster_id": "a1a7a078-0ae1-7fb9-41ec-2f4f583c773e"
}
```

### API: `sys/leader`
In the following call to `/sys/leader/` notice that `leader_address` and `leader_cluster_address`
are both redacted and set to the empty string (`""`).

```shell-session
$ curl -s https://127.0.0.1:8200/v1/sys/leader | jq`:

{
  "ha_enabled": true,
  "is_self": false,
  "active_time": "0001-01-01T00:00:00Z",
  "leader_address": "",
  "leader_cluster_address": "",
  "performance_standby": false,
  "performance_standby_last_remote_wal": 0,
  "raft_committed_index": 164,
  "raft_applied_index": 164
}
```

### API: `sys/seal-status`

In the following call to `/sys/seal-status/` notice that `cluster_name`, `build_date`,
and `version` are all redacted. The `cluster_name` field is fully omitted from
the response while `build_date` and `version` are empty strings (`""`).

```shell-session
$ curl -s https://127.0.0.1:8200/v1/sys/seal-status | jq`:

{
  "type": "shamir",
  "initialized": true,
  "sealed": false,
  "t": 1,
  "n": 1,
  "progress": 0,
  "nonce": "",
  "version": "",
  "build_date": "",
  "migration": false,
  "cluster_id": "a1a7a078-0ae1-7fb9-41ec-2f4f583c773e",
  "recovery_seal": false,
  "storage_type": "raft"
}
```

### CLI: `vault status`

The CLI command `vault status` uses endpoints that support redacting data, so the
output redacts `Version`, `Build Date`, `HA Cluster`, and `Active Node Address`.
`Version`, `Build Date`, `HA Cluster` show `n/a` because the underlying endpoint
returned the empty string, and  `Active Node Address` shows as `<none>` because
it was omitted from the API response.

```shell-session

$ vault status

Key                     Value
---                     -----
Seal Type               shamir
Initialized             true
Sealed                  false
Total Shares            5
Threshold               3
Version                 n/a
Build Date              n/a
Storage Type            raft
HA Enabled              true
HA Cluster              n/a
HA Mode                 standby
Active Node Address     <none>
Raft Committed Index    219
Raft Applied Index      219
```

[golang-tls]: https://golang.org/src/crypto/tls/cipher_suites.go
[api-addr]: /vault/docs/configuration#api_addr
[cluster-addr]: /vault/docs/configuration#cluster_addr
[go-tls-blog]: https://go.dev/blog/tls-cipher-suites

layout  docs page title  TCP   Listeners   Configuration description       The TCP listener configures Vault to listen on the specified TCP address and   port          tcp  listener   include  alerts ipv6 compliance mdx   The TCP listener configures Vault to listen on a TCP address port      hcl listener  tcp      address    127 0 0 1 8200         The  listener  stanza may be specified more than once to make Vault listen on multiple interfaces  If you configure multiple listeners you also need to specify   api addr   api addr  and   cluster addr   cluster addr  so Vault will advertise the correct address to other nodes      Sensitive data redaction for unauthenticated endpoints  Unauthenticated API endpoints may return the following sensitive information     Vault version number   Vault binary build date   Vault cluster name   IP address of nodes in the cluster  Vault offers the ability to configure each  tcp   listener  stanza such that  when appropriate  these values are redacted from responses   The following API endpoints support redaction based on  listener  stanza configuration        sys health    vault api docs system health       sys leader    vault api docs system leader       sys seal status    vault api docs system seal status   Vault replaces redacted information with an empty string         Some Vault APIs also omit keys from the response when the corresponding value is empty           Note title  Redacting values affects responses to all API clients     The Vault CLI and UI consume Vault API responses  As a result  your redaction   settings will apply to CLI and UI output in addition to direct API calls    Note      Default TLS configuration  By default  Vault TCP listeners only accept TLS 1 2 or 1 3 connections and will drop connection requests from clients using TLS 1 0 or 1 1   Vault uses the following ciphersuites by default       TLS 1 3      TLS AES 128 GCM SHA256    TLS AES 256 GCM SHA384   or  TLS CHACHA20 POLY1305 SHA256       TLS 1 2     depends on whether you configure Vault with a RSA or ECDSA certificate   You can configure Vault with any cipher supported by the   tls   https   pkg go dev crypto tls  and   tlsutil   https   github com hashicorp go secure stdlib blob main tlsutil tlsutil go L31 L57  Go packages  Vault uses the  tlsutil  package to parse ciphersuite configurations    Note title  Sweet32 and 3DES      The Go team and HashiCorp believe that the set of cyphers supported by  tls    and  tlsutil  is appropriate for modern  secure usage  However  some   vulnerability scanners may flag issues with your configuration     In particular  Sweet32  CVE 2016 2183  is an attack against 64 bit block size   ciphers including 3DES that may allow an attacker to break the encryption of   long lived connections  According to the    vulnerability disclosure  https   sweet32 info    Sweet32 took a   single HTTPS session with 785 GB of traffic to break the encryption     As of May 2024  the Go team does not believe the risk of Sweet32 is sufficient   to remove existing client compatibility by deprecating 3DES support  however    the team did  de prioritize 3DES  https   github com golang go issues 45430    in favor of AES based ciphers     Note   Before overriding Vault defaults  we recommend reviewing the recommended Go team  approach to TLS configuration  https   go dev blog tls cipher suites  with particular attention to their ciphersuite selections      Listener s custom response headers  As of version 1 9  Vault supports defining custom HTTP response headers for the root path       and also on API endpoints    v1      The headers are defined based on the returned status code  For example  a user can define a list of custom response headers for the  200  status code  and another list of custom response headers for the  307  status code  There is a    sys config ui    API endpoint   vault api docs system config ui  which allows users to set  UI  specific custom headers  If a header is configured in a configuration file  it is not allowed to be reconfigured through the    sys config ui    API endpoint   vault api docs system config ui   In cases where a custom header value needs to be modified or the custom header needs to be removed  the Vault s configuration file needs to be modified accordingly  and a  SIGHUP  signal needs to be sent to the Vault process   If a header is defined in the configuration file and the same header is used by the internal processes of Vault  the configured header is not accepted  For example  a custom header which has the  X Vault   prefix will not be accepted  A message will be logged in the Vault s logs upon start up indicating the header with  X Vault   prefix is not accepted       Order of precedence  If the same header is configured in both the configuration file and in the    sys config ui    API endpoint   vault api docs system config ui   the header in the configuration file takes precedence  For example  the   Content Security Policy   header is defined by default in the    sys config ui    API endpoint   vault api docs system config ui   If that header is also defined in the configuration file  the value in the configuration file is set in the response headers instead of the default value in the    sys config ui    API endpoint   vault api docs system config ui        tcp  listener parameters     address    string   127 0 0 1 8200      Specifies the address to bind to for   listening  This can be dynamically defined with a    go sockaddr template  https   pkg go dev github com hashicorp go sockaddr template    that is resolved at runtime      cluster address    string   127 0 0 1 8201      Specifies the address to bind   to for cluster server to server requests  This defaults to one port higher   than the value of  address   This does not usually need to be set  but can be   useful in case Vault servers are isolated from each other in such a way that   they need to hop through a TCP load balancer or some other scheme in order to   talk  This can be dynamically defined with a    go sockaddr template  https   pkg go dev github com hashicorp go sockaddr template    that is resolved at runtime      chroot namespace    string         Specifies an alternate top level namespace   for the listener  Vault appends namespaces provided in the  X Vault Namespace    header or the   namespace  field in a CLI command to the top level namespace   to determine the full namespace path for the request  For example  if    chroot namespace  is set to  admin  and the  X Vault Namespace  header is    ns1   the full namespace path is  admin ns1   Calls to the listener will fail    with a 4XX error if the top level namespace provided for  chroot namespace     does not exist     http idle timeout    string   5m      Specifies the maximum amount of time to   wait for the next request when keep alives are enabled  If  http idle timeout    is zero  the value of  http read timeout  is used  If both are zero  the value   of  http read header timeout  is used  This is specified using a label suffix   like   30s   or   1h        http read header timeout    string   10s      Specifies the amount of time   allowed to read request headers  This is specified using a label suffix like     30s   or   1h        http read timeout    string   30s      Specifies the maximum duration for   reading the entire request  including the body  This is specified using a   label suffix like   30s   or   1h        http write timeout   string   0      Specifies the maximum duration before   timing out writes of the response and is reset whenever a new request s header   is read  The default value of   0   means infinity  This is specified using a   label suffix like   30s   or   1h        max request size    int  33554432     Specifies a hard maximum allowed   request size  in bytes  Defaults to 32 MB if not set or set to  0     Specifying a number less than  0  turns off limiting altogether      max request duration    string   90s      Specifies the maximum   request duration allowed before Vault cancels the request  This overrides    default max request duration  for this listener      proxy protocol behavior    string         When specified  enables a PROXY   protocol behavior for the listener  version 1 and 2 are both supported     Accepted Values        use always    The client s IP address will always be used       allow authorized    If the source IP address is in the      proxy protocol authorized addrs  list  the client s IP address will be used      If the source IP is not in the list  the source IP address will be used       deny unauthorized    The traffic will be rejected if the source IP     address is not in the  proxy protocol authorized addrs  list      proxy protocol authorized addrs    string   required if enabled  or array   required if enabled         Specifies the list of allowed source IP addresses to be used with the PROXY protocol    Not required if  proxy protocol behavior  is set to  use always   Source IPs should   be comma delimited if provided as a string  At least one source IP must be provided     proxy protocol authorized addrs  cannot be an empty array or string      redact addresses    bool  false     Redacts  leader address  and  cluster leader address  values in applicable API responses when  true       redact cluster name    bool  false     Redacts  cluster name  values in applicable API responses when  true       redact version    bool  false     Redacts  version  and  build date  values in applicable API responses when  true       tls disable    string   false      Specifies if TLS will be disabled  Vault   assumes TLS by default  so you must explicitly disable TLS to opt in to   insecure communication  Disabling TLS can   disable   some UI functionality  See   the  Browser Support   vault docs browser support  page for more details      tls cert file    string   required if enabled   reloads on SIGHUP       Specifies the path to the certificate for TLS  It requires a PEM encoded file    To configure the listener to use a CA certificate  concatenate the primary certificate and the CA   certificate together  The primary certificate should appear first in the   combined file  On  SIGHUP   the path set here  at Vault startup  will be used   for reloading the certificate  modifying this value while Vault is running   will have no effect for  SIGHUP s      tls key file    string   required if enabled   reloads on SIGHUP       Specifies the path to the private key for the certificate  It requires a PEM encoded file    If the key file is encrypted  you will be prompted to enter the passphrase on server startup    The passphrase must stay the same between key files when reloading your   configuration using  SIGHUP   On  SIGHUP   the path set here  at Vault   startup  will be used for reloading the certificate  modifying this value   while Vault is running will have no effect for  SIGHUP s      tls min version    string   tls12      Specifies the minimum supported   version of TLS  Accepted values are  tls10    tls11    tls12  or  tls13           Warning    TLS 1 1 and lower   tls10  and  tls11  values for the    tls min version  and  tls max version  parameters  are widely considered   insecure      tls max version    string   tls13      Specifies the maximum supported   version of TLS  Accepted values are  tls10    tls11    tls12  or  tls13           Warning    TLS 1 1 and lower   tls10  and  tls11  values for the    tls min version  and  tls max version  parameters  are widely considered   insecure      tls cipher suites    string         Specifies the list of supported   ciphersuites as a comma separated list  The list of all available ciphersuites   is available in the  Golang TLS documentation  golang tls           Note    Go only consults the  tls cipher suites  list for TLSv1 2 and   earlier  the order of ciphers is not important  For this parameter to be   effective  the  tls max version  property must be set to  tls12  to prevent   negotiation of TLSv1 3  which is not recommended  For more information about   this and other TLS related changes  see the  Go TLS blog post  go tls blog       tls prefer server cipher suites    string   false      Specifies to prefer the   server s ciphersuite over the client ciphersuites          Warning    The  tls prefer server cipher suites  parameter is   deprecated  Setting it has no effect  See the above    Go blog post  go tls blog  for more information about   this change      tls require and verify client cert    string   false      Turns on client   authentication for this listener  the listener will require a presented   client cert that successfully validates against system CAs      tls client ca file    string         PEM encoded Certificate Authority file   used for checking the authenticity of client      tls disable client certs    string   false      Turns off client   authentication for this listener  The default behavior  when this is false    is for Vault to request client authentication certificates when available          Warning    The  tls disable client certs  and  tls require and verify client cert  fields in the listener stanza of the Vault server configuration are mutually exclusive fields  Please ensure they are not both set to true  TLS client verification remains optional with default settings and is not enforced      x forwarded for authorized addrs    string   required to enable        Specifies the list of source IP CIDRs for which an X Forwarded For header   will be trusted  Comma separated list or JSON array  This turns on   X Forwarded For support   If for example Vault receives connections from the   load balancer s IP of  1 2 3 4   adding  1 2 3 4  to  x forwarded for authorized addrs    will result in the  remote address  field in the audit log being populated with the   connecting client s IP  for example  3 4 5 6   Note this requires the load balancer   to send the connecting client s IP in the  X Forwarded For  header      x forwarded for client cert header    string           Specifies the header that will be used for the client certificate    This is required if you use the  TLS Certificates Auth Method   vault docs auth cert  and your   vault server is behind a reverse proxy      x forwarded for client cert header decoders    string           Comma delimited list that specifies the decoders that will be used to decode the client certificate    This is required if you use the  TLS Certificates Auth Method   vault docs auth cert  and your   vault server is behind a reverse proxy  The resulting certificate should be in DER format    Available Values       BASE64   Runs Base64 decode     DER   Converts a pem certificate to der     URL   Runs URL decode    Known Values       Traefik    BASE64      NGINX      URL DER      x forwarded for hop skips    string   0      The number of addresses that will be   skipped from the  rear  of the set of hops  For instance  for a header value   of  1 2 3 4  2 3 4 5  3 4 5 6  4 5 6 7   if this value is set to   1    the address that   will be used as the originating client IP is  3 4 5 6       x forwarded for reject not authorized    string   true      If set false    if there is an X Forwarded For header in a connection from an unauthorized   address  the header will be ignored and the client connection used as is    rather than the client connection rejected      x forwarded for reject not present    string   true      If set false  if   there is no X Forwarded For header or it is empty  the client address will be   used as is  rather than the client connection rejected      disable replication status endpoints    bool  false     Disables replication   status endpoints for the configured listener when set to  true         telemetry  parameters     unauthenticated metrics access    bool  false     If set to true  allows   unauthenticated access to the   v1 sys metrics  endpoint        profiling  parameters     unauthenticated pprof access    bool  false     If set to true  allows   unauthenticated access to the   v1 sys pprof  endpoint        inflight requests logging  parameters     unauthenticated in flight requests access    bool  false     If set to true  allows   unauthenticated access to the   v1 sys in flight req  endpoint        custom response headers  parameters     default    key value map         A map of string header names to an array of   string values  The default headers are set on all endpoints regardless of   the status code value  For an example  please refer to the    Configuring custom http response headers  section       specific status code     key value map         A map of string header names   to an array of string values  These headers are set only when the specific status   code is returned  For example    200      Header A     Value1    Value2        Header A     is set when the http response status code is   200         collective status code     key value map         A map of string header names   to an array of string values  These headers are set only when the response status   code falls under the collective status code    For example    2xx      Header A     Value1    Value2        Header A     is set when the http response status code is   200      204    etc       tcp  listener examples      Configuring TLS  This example shows enabling a TLS listener      hcl listener  tcp      address    127 0 0 1 8200    tls cert file     etc certs vault crt    tls key file      etc certs vault key             Listening on multiple interfaces  This example shows Vault listening on a private interface  as well as localhost      hcl listener  tcp      address    127 0 0 1 8200     listener  tcp      address    10 0 0 5 8200       Advertise the non loopback interface api addr    https   10 0 0 5 8200  cluster addr    https   10 0 0 5 8201           Configuring unauthenticated metrics access  This example shows enabling unauthenticated metrics access      hcl listener  tcp      telemetry       unauthenticated metrics access   true                Configuring unauthenticated profiling access  This example shows enabling unauthenticated profiling access      hcl listener  tcp      profiling       unauthenticated pprof access   true     unauthenticated in flight request access   true                Configuring custom http response headers  Note  Requires Vault version 1 9 or newer  This example shows configuring custom http response headers  Operators can configure   custom response headers   sub stanza in the listener stanza to set custom http headers appropriate to their applications  Examples of such headers are   Strict Transport Security   and   Content Security Policy   which are known HTTP headers  and could be configured to harden the security of an application communicating with the Vault endpoints  Note that vulnerability scans often examine such security related HTTP headers  In addition  application specific custom headers can also be configured  For example    X Custom Header   has been configured in the example below      hcl listener  tcp      custom response headers        default             Strict Transport Security      max age 31536000   includeSubDomains           Content Security Policy      connect src https   clusterA vault external            X Custom Header      Custom Header Default Value                2xx             Content Security Policy      connect src https   clusterB vault external            X Custom Header      Custom Header Value 1    Custom Header Value 2                301             Strict Transport Security      max age 31536000           Content Security Policy      connect src https   clusterC vault external                       In situations where a header is defined under several status code subsections  the header matching the most specific response code will be returned  For example  with the config example below  a  307  response would return  307 Custom header value   while a  306  would return  3xx Custom header value       hcl listener  tcp      custom response headers        default              X Custom Header      default Custom header value               3xx              X Custom Header      3xx Custom header value               307              X Custom Header      307 Custom header value                        Listening on all IPv6   IPv4 interfaces  This example shows Vault listening on all IPv4   IPv6 interfaces including localhost      hcl listener  tcp      address                 8200    cluster address         8201             Listening to specific IPv6 address  This example shows Vault only using IPv6 and binding to the interface with the IP address   2001 1c04 90d 1c00 a00 27ff fefa 58ec      hcl listener  tcp      address             2001 1c04 90d 1c00 a00 27ff fefa 58ec  8200    cluster address     2001 1c04 90d 1c00 a00 27ff fefa 58ec  8201       Advertise the non loopback interface api addr    https    2001 1c04 90d 1c00 a00 27ff fefa 58ec  8200  cluster addr    https    2001 1c04 90d 1c00 a00 27ff fefa 58ec  8201          Redaction examples  Please see redaction settings above  for details on each redaction setting   Example configuration for the   tcp    vault docs configuration listener tcp  listener  enabling   redact addresses    vault docs configuration listener tcp redact addresses     redact cluster name    vault docs configuration listener tcp redact cluster name  and   redact version    vault docs configuration listener tcp redact version       hcl ui              true cluster addr     https   127 0 0 1 8201  api addr         https   127 0 0 1 8200  disable mlock   true  storage  raft      path     path to raft data    node id    raft node 1     listener  tcp      address                127 0 0 1 8200     tls cert file     path to full chain pem    tls key file      path to private key pem    redact addresses       true    redact cluster name    true    redact version         true     telemetry     statsite address    127 0 0 1 8125    disable hostname   true            API    sys health  In the following call to   sys health   notice that  cluster name  and  version  are both redacted  The  cluster name  field is fully omitted from the response and  version  is the empty string             shell session   curl  s https   127 0 0 1 8200 v1 sys health   jq         initialized   true     sealed   false     standby   true     performance standby   false     replication performance mode    disabled      replication dr mode    disabled      server time utc   1696598650     version          cluster id    a1a7a078 0ae1 7fb9 41ec 2f4f583c773e              API   sys leader  In the following call to   sys leader   notice that  leader address  and  leader cluster address  are both redacted and set to the empty string             shell session   curl  s https   127 0 0 1 8200 v1 sys leader   jq         ha enabled   true     is self   false     active time    0001 01 01T00 00 00Z      leader address          leader cluster address          performance standby   false     performance standby last remote wal   0     raft committed index   164     raft applied index   164             API   sys seal status   In the following call to   sys seal status   notice that  cluster name    build date   and  version  are all redacted  The  cluster name  field is fully omitted from the response while  build date  and  version  are empty strings             shell session   curl  s https   127 0 0 1 8200 v1 sys seal status   jq         type    shamir      initialized   true     sealed   false     t   1     n   1     progress   0     nonce          version          build date          migration   false     cluster id    a1a7a078 0ae1 7fb9 41ec 2f4f583c773e      recovery seal   false     storage type    raft             CLI   vault status   The CLI command  vault status  uses endpoints that support redacting data  so the output redacts  Version    Build Date    HA Cluster   and  Active Node Address    Version    Build Date    HA Cluster  show  n a  because the underlying endpoint returned the empty string  and   Active Node Address  shows as   none   because it was omitted from the API response      shell session    vault status  Key                     Value                               Seal Type               shamir Initialized             true Sealed                  false Total Shares            5 Threshold               3 Version                 n a Build Date              n a Storage Type            raft HA Enabled              true HA Cluster              n a HA Mode                 standby Active Node Address      none  Raft Committed Index    219 Raft Applied Index      219       golang tls   https   golang org src crypto tls cipher suites go  api addr    vault docs configuration api addr  cluster addr    vault docs configuration cluster addr  go tls blog   https   go dev blog tls cipher suites


vault Example TCP listener configuration with TLS encryption You can configure your TCP listener to use specific versions of TLS and specific page title Configure TLS for your Vault TCP listener Configure TLS for your Vault TCP listener layout docs

Answer:
---
layout: docs
page_title: Configure TLS for your Vault TCP listener
description: >-
  Example TCP listener configuration with TLS encryption.
---

# Configure TLS for your Vault TCP listener

You can configure your TCP listener to use specific versions of TLS and specific
ciphersuites.

## Assumptions

- **Your Vault instance is not currently running**. If your Vault cluster is
  running, you must
  [restart the cluster gracefully](https://support.hashicorp.com/hc/en-us/articles/17169701076371-A-Step-by-Step-Guide-to-Restarting-a-Vault-Cluster)
  to apply changes to your TCP listener. SIGHUP will not reload your TLS
  configuration.
- **You have a valid TLS certificate file**.
- **You have a valid TLS key file**.
- **You have a valid CA file (if required)**.

## Example TLS 1.3 configuration

If a reasonably modern set of clients are connecting to a Vault instance, you
can configure the `tcp` listener stanza to only accept TLS 1.3 with the
`tls_min_version` parameter:

<CodeBlockConfig hideClipboard highlight="5">

```plaintext
listener "tcp" {
  address = "127.0.0.1:8200"
  tls_cert_file = "cert.pem"
  tls_key_file  = "key.pem"
  tls_min_version = "tls13"
}
```

</CodeBlockConfig>

Vault does not accept explicit ciphersuite configuration for TLS 1.3 because the
Go team has already designated a select set of ciphers that align with the
broadly-accepted Mozilla Security/Server Side TLS guidance for [modern TLS
configuration](https://wiki.mozilla.org/Security/Server_Side_TLS#Modern_compatibility).

## Example TLS 1.2 configuration

To use TLS 1.2 with a non-default set of ciphersuites, you can set 1.2 as the
minimum and maximum allowed TLS version and explicitly define your preferred
ciphersuites with `tls_ciper_suites` and one or more of the ciphersuite
constants from the ciphersuite configuration parser. For example:

<CodeBlockConfig hideClipboard highlight="5-7">

```plaintext
listener "tcp" {
  address = "127.0.0.1:8200"
  tls_cert_file = "cert.pem"
  tls_key_file  = "key.pem"
  tls_min_version = "tls12"
  tls_max_version = "tls12"
  tls_cipher_suites = "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256"
}
```

</CodeBlockConfig>

You must set the minimum and maximum TLS version to disable TLS 1.3, which does
not support explicit cipher selection. The priority order of the ciphersuites
in `tls_cipher_suites` is determined by the `tls` Go package.

<Note>

  The TLS 1.2 configuration example excludes any 3DES ciphers to avoid potential
  exposure to the Sweet32 attack (CVE-2016-2183). You should customize the
  ciphersuite list as needed to meet your environment-specific security
  requirements.

</Note>

## Verify your TLS configuration

You can verify your TLS configuration using an SSL scanner such as
[`sslscan`](https://github.com/rbsec/sslscan).

<Tabs>
<Tab heading="Example scan with ECDSA certificate">

<CodeBlockConfig hideClipboard>

```shell-session
$ sslscan 127.0.0.1:8200
Version: 2.1.3
OpenSSL 3.2.1 30 Jan 2024

Connected to 127.0.0.1

Testing SSL server 127.0.0.1 on port 8200 using SNI name 127.0.0.1

  SSL/TLS Protocols:
SSLv2     disabled
SSLv3     disabled
TLSv1.0   disabled
TLSv1.1   disabled
TLSv1.2   enabled
TLSv1.3   enabled

  TLS Fallback SCSV:
Server supports TLS Fallback SCSV

  TLS renegotiation:
Session renegotiation not supported

  TLS Compression:
Compression disabled

  Heartbleed:
TLSv1.3 not vulnerable to heartbleed
TLSv1.2 not vulnerable to heartbleed

  Supported Server Cipher(s):
Preferred TLSv1.3  128 bits  TLS_AES_128_GCM_SHA256        Curve 25519 DHE 253
Accepted  TLSv1.3  256 bits  TLS_AES_256_GCM_SHA384        Curve 25519 DHE 253
Accepted  TLSv1.3  256 bits  TLS_CHACHA20_POLY1305_SHA256  Curve 25519 DHE 253
Preferred TLSv1.2  128 bits  ECDHE-ECDSA-AES128-GCM-SHA256 Curve 25519 DHE 253
Accepted  TLSv1.2  256 bits  ECDHE-ECDSA-AES256-GCM-SHA384 Curve 25519 DHE 253
Accepted  TLSv1.2  256 bits  ECDHE-ECDSA-CHACHA20-POLY1305 Curve 25519 DHE 253
Accepted  TLSv1.2  128 bits  ECDHE-ECDSA-AES128-SHA        Curve 25519 DHE 253
Accepted  TLSv1.2  256 bits  ECDHE-ECDSA-AES256-SHA        Curve 25519 DHE 253

  Server Key Exchange Group(s):
TLSv1.3  128 bits  secp256r1 (NIST P-256)
TLSv1.3  192 bits  secp384r1 (NIST P-384)
TLSv1.3  260 bits  secp521r1 (NIST P-521)
TLSv1.3  128 bits  x25519
TLSv1.2  128 bits  secp256r1 (NIST P-256)
TLSv1.2  192 bits  secp384r1 (NIST P-384)
TLSv1.2  260 bits  secp521r1 (NIST P-521)
TLSv1.2  128 bits  x25519

  SSL Certificate:
Signature Algorithm: ecdsa-with-SHA256
ECC Curve Name:      prime256v1
ECC Key Strength:    128

Subject:  localhost
Issuer:   localhost

Not valid before: May 17 17:27:29 2024 GMT
Not valid after:  Jun 16 17:27:29 2024 GMT
```

</CodeBlockConfig>

</Tab>
<Tab heading="Example scan with RSA certificate">

<CodeBlockConfig hideClipboard>

```shell-session
sslscan 127.0.0.1:8200
Testing SSL server 127.0.0.1 on port 8200 using SNI name 127.0.0.1

  SSL/TLS Protocols:
SSLv2     disabled
SSLv3     disabled
TLSv1.0   disabled
TLSv1.1   disabled
TLSv1.2   enabled
TLSv1.3   enabled

  Supported Server Cipher(s):
Preferred TLSv1.3  128 bits  TLS_AES_128_GCM_SHA256        Curve 25519 DHE 253
Accepted  TLSv1.3  256 bits  TLS_AES_256_GCM_SHA384        Curve 25519 DHE 253
Accepted  TLSv1.3  256 bits  TLS_CHACHA20_POLY1305_SHA256  Curve 25519 DHE 253
Preferred TLSv1.2  128 bits  ECDHE-RSA-AES128-GCM-SHA256   Curve 25519 DHE 253
Accepted  TLSv1.2  256 bits  ECDHE-RSA-AES256-GCM-SHA384   Curve 25519 DHE 253
Accepted  TLSv1.2  256 bits  ECDHE-RSA-CHACHA20-POLY1305   Curve 25519 DHE 253
Accepted  TLSv1.2  128 bits  ECDHE-RSA-AES128-SHA          Curve 25519 DHE 253
Accepted  TLSv1.2  256 bits  ECDHE-RSA-AES256-SHA          Curve 25519 DHE 253
Accepted  TLSv1.2  128 bits  AES128-GCM-SHA256
Accepted  TLSv1.2  256 bits  AES256-GCM-SHA384
Accepted  TLSv1.2  128 bits  AES128-SHA
Accepted  TLSv1.2  256 bits  AES256-SHA
Accepted  TLSv1.2  112 bits  TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
Accepted  TLSv1.2  112 bits  TLS_RSA_WITH_3DES_EDE_CBC_SHA

  Server Key Exchange Group(s):
TLSv1.3  128 bits  secp256r1 (NIST P-256)
TLSv1.3  192 bits  secp384r1 (NIST P-384)
TLSv1.3  260 bits  secp521r1 (NIST P-521)
TLSv1.3  128 bits  x25519
TLSv1.2  128 bits  secp256r1 (NIST P-256)
TLSv1.2  192 bits  secp384r1 (NIST P-384)
TLSv1.2  260 bits  secp521r1 (NIST P-521)
TLSv1.2  128 bits  x25519

  SSL Certificate:
Signature Algorithm: sha256WithRSAEncryption
RSA Key Strength:    4096
```

</CodeBlockConfig>

</Tab>
</Tabs>

layout  docs page title  Configure TLS for your Vault TCP listener description       Example TCP listener configuration with TLS encryption         Configure TLS for your Vault TCP listener  You can configure your TCP listener to use specific versions of TLS and specific ciphersuites      Assumptions      Your Vault instance is not currently running    If your Vault cluster is   running  you must    restart the cluster gracefully  https   support hashicorp com hc en us articles 17169701076371 A Step by Step Guide to Restarting a Vault Cluster    to apply changes to your TCP listener  SIGHUP will not reload your TLS   configuration      You have a valid TLS certificate file        You have a valid TLS key file        You have a valid CA file  if required         Example TLS 1 3 configuration  If a reasonably modern set of clients are connecting to a Vault instance  you can configure the  tcp  listener stanza to only accept TLS 1 3 with the  tls min version  parameter    CodeBlockConfig hideClipboard highlight  5       plaintext listener  tcp      address    127 0 0 1 8200    tls cert file    cert pem    tls key file     key pem    tls min version    tls13           CodeBlockConfig   Vault does not accept explicit ciphersuite configuration for TLS 1 3 because the Go team has already designated a select set of ciphers that align with the broadly accepted Mozilla Security Server Side TLS guidance for  modern TLS configuration  https   wiki mozilla org Security Server Side TLS Modern compatibility       Example TLS 1 2 configuration  To use TLS 1 2 with a non default set of ciphersuites  you can set 1 2 as the minimum and maximum allowed TLS version and explicitly define your preferred ciphersuites with  tls ciper suites  and one or more of the ciphersuite constants from the ciphersuite configuration parser  For example    CodeBlockConfig hideClipboard highlight  5 7       plaintext listener  tcp      address    127 0 0 1 8200    tls cert file    cert pem    tls key file     key pem    tls min version    tls12    tls max version    tls12    tls cipher suites    TLS ECDHE ECDSA WITH AES 128 GCM SHA256 TLS ECDHE RSA WITH AES 128 GCM SHA256 TLS ECDHE ECDSA WITH AES 256 GCM SHA384 TLS ECDHE RSA WITH AES 256 GCM SHA384 TLS ECDHE ECDSA WITH CHACHA20 POLY1305 SHA256 TLS ECDHE RSA WITH CHACHA20 POLY1305 SHA256           CodeBlockConfig   You must set the minimum and maximum TLS version to disable TLS 1 3  which does not support explicit cipher selection  The priority order of the ciphersuites in  tls cipher suites  is determined by the  tls  Go package    Note     The TLS 1 2 configuration example excludes any 3DES ciphers to avoid potential   exposure to the Sweet32 attack  CVE 2016 2183   You should customize the   ciphersuite list as needed to meet your environment specific security   requirements     Note      Verify your TLS configuration  You can verify your TLS configuration using an SSL scanner such as   sslscan   https   github com rbsec sslscan      Tabs   Tab heading  Example scan with ECDSA certificate     CodeBlockConfig hideClipboard      shell session   sslscan 127 0 0 1 8200 Version  2 1 3 OpenSSL 3 2 1 30 Jan 2024  Connected to 127 0 0 1  Testing SSL server 127 0 0 1 on port 8200 using SNI name 127 0 0 1    SSL TLS Protocols  SSLv2     disabled SSLv3     disabled TLSv1 0   disabled TLSv1 1   disabled TLSv1 2   enabled TLSv1 3   enabled    TLS Fallback SCSV  Server supports TLS Fallback SCSV    TLS renegotiation  Session renegotiation not supported    TLS Compression  Compression disabled    Heartbleed  TLSv1 3 not vulnerable to heartbleed TLSv1 2 not vulnerable to heartbleed    Supported Server Cipher s   Preferred TLSv1 3  128 bits  TLS AES 128 GCM SHA256        Curve 25519 DHE 253 Accepted  TLSv1 3  256 bits  TLS AES 256 GCM SHA384        Curve 25519 DHE 253 Accepted  TLSv1 3  256 bits  TLS CHACHA20 POLY1305 SHA256  Curve 25519 DHE 253 Preferred TLSv1 2  128 bits  ECDHE ECDSA AES128 GCM SHA256 Curve 25519 DHE 253 Accepted  TLSv1 2  256 bits  ECDHE ECDSA AES256 GCM SHA384 Curve 25519 DHE 253 Accepted  TLSv1 2  256 bits  ECDHE ECDSA CHACHA20 POLY1305 Curve 25519 DHE 253 Accepted  TLSv1 2  128 bits  ECDHE ECDSA AES128 SHA        Curve 25519 DHE 253 Accepted  TLSv1 2  256 bits  ECDHE ECDSA AES256 SHA        Curve 25519 DHE 253    Server Key Exchange Group s   TLSv1 3  128 bits  secp256r1  NIST P 256  TLSv1 3  192 bits  secp384r1  NIST P 384  TLSv1 3  260 bits  secp521r1  NIST P 521  TLSv1 3  128 bits  x25519 TLSv1 2  128 bits  secp256r1  NIST P 256  TLSv1 2  192 bits  secp384r1  NIST P 384  TLSv1 2  260 bits  secp521r1  NIST P 521  TLSv1 2  128 bits  x25519    SSL Certificate  Signature Algorithm  ecdsa with SHA256 ECC Curve Name       prime256v1 ECC Key Strength     128  Subject   localhost Issuer    localhost  Not valid before  May 17 17 27 29 2024 GMT Not valid after   Jun 16 17 27 29 2024 GMT        CodeBlockConfig     Tab   Tab heading  Example scan with RSA certificate     CodeBlockConfig hideClipboard      shell session sslscan 127 0 0 1 8200 Testing SSL server 127 0 0 1 on port 8200 using SNI name 127 0 0 1    SSL TLS Protocols  SSLv2     disabled SSLv3     disabled TLSv1 0   disabled TLSv1 1   disabled TLSv1 2   enabled TLSv1 3   enabled    Supported Server Cipher s   Preferred TLSv1 3  128 bits  TLS AES 128 GCM SHA256        Curve 25519 DHE 253 Accepted  TLSv1 3  256 bits  TLS AES 256 GCM SHA384        Curve 25519 DHE 253 Accepted  TLSv1 3  256 bits  TLS CHACHA20 POLY1305 SHA256  Curve 25519 DHE 253 Preferred TLSv1 2  128 bits  ECDHE RSA AES128 GCM SHA256   Curve 25519 DHE 253 Accepted  TLSv1 2  256 bits  ECDHE RSA AES256 GCM SHA384   Curve 25519 DHE 253 Accepted  TLSv1 2  256 bits  ECDHE RSA CHACHA20 POLY1305   Curve 25519 DHE 253 Accepted  TLSv1 2  128 bits  ECDHE RSA AES128 SHA          Curve 25519 DHE 253 Accepted  TLSv1 2  256 bits  ECDHE RSA AES256 SHA          Curve 25519 DHE 253 Accepted  TLSv1 2  128 bits  AES128 GCM SHA256 Accepted  TLSv1 2  256 bits  AES256 GCM SHA384 Accepted  TLSv1 2  128 bits  AES128 SHA Accepted  TLSv1 2  256 bits  AES256 SHA Accepted  TLSv1 2  112 bits  TLS ECDHE RSA WITH 3DES EDE CBC SHA Accepted  TLSv1 2  112 bits  TLS RSA WITH 3DES EDE CBC SHA    Server Key Exchange Group s   TLSv1 3  128 bits  secp256r1  NIST P 256  TLSv1 3  192 bits  secp384r1  NIST P 384  TLSv1 3  260 bits  secp521r1  NIST P 521  TLSv1 3  128 bits  x25519 TLSv1 2  128 bits  secp256r1  NIST P 256  TLSv1 2  192 bits  secp384r1  NIST P 384  TLSv1 2  260 bits  secp521r1  NIST P 521  TLSv1 2  128 bits  x25519    SSL Certificate  Signature Algorithm  sha256WithRSAEncryption RSA Key Strength     4096        CodeBlockConfig     Tab    Tabs


vault wrapping mechanism layout docs page title PKCS11 Seals Configuration The PKCS11 seal configures Vault to use an HSM with PKCS11 as the seal pkcs11 seal

Answer:
---
layout: docs
page_title: PKCS11 - Seals - Configuration
description: |-
  The PKCS11 seal configures Vault to use an HSM with PKCS11 as the seal
  wrapping mechanism.
---

# `pkcs11` seal

<Note title="Auto-unseal and seal wrapping requires Vault Enterprise">

  Auto-unseal **and** seal wrapping for PKCS11 require Vault Enterprise.

  Vault Enterprise enables seal wrapping by default, which means the KMS service
  must be available at runtime and not just during the unseal process. Refer to
  the [Seal wrap](/vault/docs/enterprise/sealwrap) overview for more
  information.

</Note>

The PKCS11 seal configures Vault to use an HSM with PKCS11 as the seal wrapping
mechanism. Vault Enterprise's HSM PKCS11 support is activated by one of the
following:

- The presence of a `seal "pkcs11"` block in Vault's configuration file
- The presence of the environment variable `VAULT_HSM_LIB` set to the library's
  path as well as `VAULT_SEAL_TYPE` set to `pkcs11`. If enabling via environment
  variable, all other required values (i.e. `VAULT_HSM_SLOT`) must be also
  supplied.

**IMPORTANT**: Having Vault generate its own key is the easiest way to get up
and running, but for security, Vault marks the key as non-exportable. If your
HSM key backup strategy requires the key to be exportable, you should generate
the key yourself. The list of creation attributes that Vault uses to generate
the key are listed at the end of this document.

## Requirements

The following software packages are required for Vault Enterprise HSM:

- PKCS#11 compatible HSM integration library. Vault targets version 2.2 or
  higher of PKCS#11. Depending on any given HSM, some functions (such as key
  generation) may have to be performed manually.
- The [GNU libltdl
  library](https://www.gnu.org/software/libtool/manual/html_node/Using-libltdl.html)
  — ensure that it is installed for the correct architecture of your servers

## `pkcs11` example

This example shows configuring HSM PKCS11 seal through the Vault configuration
file by providing all the required values:

```hcl
seal "pkcs11" {
  lib            = "/usr/vault/lib/libCryptoki2_64.so"
  slot           = "2305843009213693953"
  pin            = "AAAA-BBBB-CCCC-DDDD"
  key_label      = "vault-hsm-key"
  hmac_key_label = "vault-hsm-hmac-key"
}
```

## `pkcs11` parameters

These parameters apply to the `seal` stanza in the Vault configuration file:

- `lib` `(string: <required>)`: The path to the PKCS#11 library shared object
  file. May also be specified by the `VAULT_HSM_LIB` environment variable.

  ~> **Note:** Depending on your HSM, the value of the `lib` parameter may be
  either a binary or a dynamic library, and its use may require other libraries
  depending on which system the Vault binary is currently running on (e.g.: a
  Linux system may require other libraries to interpret Windows .dll files).

- `slot` `(string: <slot or token label required>)`: The slot number to use,
  specified as a string (e.g. `"2305843009213693953"`). May also be specified by
  the `VAULT_HSM_SLOT` environment variable.

  ~> **Note**: Slots are typically listed as hex-decimal values in the OS setup
  utility but this configuration uses their decimal equivalent. For example, using the
  HSM command-line `pkcs11-tool`, a slot listed as `0x2000000000000001`in hex is equal
  to `2305843009213693953` in decimal; these values may be listed shorter or
  differently as determined by the HSM in use.

- `token_label` `(string: <slot or token label required>)`: The slot token label to
  use. May also be specified by the `VAULT_HSM_TOKEN_LABEL` environment variable.

- `pin` `(string: <required>)`: The PIN for login. May also be specified by the
  `VAULT_HSM_PIN` environment variable. _If set via the environment variable,
  it will need to be re-set if Vault is restarted._

- `key_label` `(string: <required>)`: The label of the key to use. If the key
  does not exist and generation is enabled, this is the label that will be given
  to the generated key. May also be specified by the `VAULT_HSM_KEY_LABEL`
  environment variable.

- `default_key_label` `(string: "")`: This is the default key label for decryption
  operations. Prior to 0.10.1, key labels were not stored with the ciphertext.
  Seal entries now track the label used in encryption operations. The default value
  for this field is the `key_label`. If `key_label` is rotated and this value is not
  set, decryption may fail. May also be specified by the `VAULT_HSM_DEFAULT_KEY_LABEL`
  environment variable. This value is ignored in new installations.

- `key_id` `(string: "")`: The ID of the key to use. The value should be a hexadecimal
  string (e.g., "0x33333435363434373537"). May also be specified by the
  `VAULT_HSM_KEY_ID` environment variable.

- `hmac_key_label` `(string: <required>)`: The label of the key to use for
  HMACing. This needs to be a suitable type. If Vault tries to create this it
  will attempt to use CKK_GENERIC_SECRET_KEY. If the key does not exist and
  generation is enabled, this is the label that will be given to the generated
  key. May also be specified by the `VAULT_HSM_HMAC_KEY_LABEL` environment
  variable.

- `default_hmac_key_label` `(string: "")`: This is the default HMAC key label for signing
  operations. Prior to 0.10.1, HMAC key labels were not stored with the signature.
  Seal entries now track the label used in signing operations. The default value
  for this field is the `hmac_key_label`. If `hmac_key_label` is rotated and this
  value is not set, signature verification may fail. May also be specified by the
  `VAULT_HSM_HMAC_DEFAULT_KEY_LABEL` environment variable. This value is ignored in
  new installations.

- `hmac_key_id` `(string: "")`: The ID of the HMAC key to use. The value should be a
  hexadecimal string (e.g., "0x33333435363434373537"). May also be specified by the
  `VAULT_HSM_HMAC_KEY_ID` environment variable.

- `mechanism` `(string: <best available>)`: The encryption/decryption mechanism to use,
  specified as a decimal or hexadecimal (prefixed by `0x`) string. May also be
  specified by the `VAULT_HSM_MECHANISM` environment variable.
  Currently supported mechanisms (in order of precedence):

  - `0x1085` `CKM_AES_CBC_PAD` (HMAC mechanism required)
  - `0x1082` `CKM_AES_CBC` (HMAC mechanism required)
  - `0x1087` `CKM_AES_GCM`
  - `0x0009` `CKM_RSA_PKCS_OAEP`
  - `0x0001` `CKM_RSA_PKCS`

  ~> **Warning**: CKM_RSA_PKCS specifies the PKCS #1 v1.5 padding scheme, which is
  in considered less secure than OAEP. Where possible, use of CKM_RSA_PKCS_OAEP is
  recommended over CKM_RSA_PKCS.

- `hmac_mechanism` `(string: "0x0251")`: The encryption/decryption mechanism to
  use, specified as a decimal or hexadecimal (prefixed by `0x`) string.
  Currently only `0x0251` (corresponding to `CKM_SHA256_HMAC` from the
  specification) is supported. May also be specified by the
  `VAULT_HSM_HMAC_MECHANISM` environment variable. This value is only required
  for specific mechanisms.

- `generate_key` `(string: "false")`: If no existing key with the label
  specified by `key_label` can be found at Vault initialization time, instructs
  Vault to generate a key. This is a boolean expressed as a string (e.g.
  `"true"`). May also be specified by the `VAULT_HSM_GENERATE_KEY` environment
  variable. Vault may not be able to successfully generate keys in all
  circumstances, such as if proprietary vendor extensions are required to
  create keys of a suitable type.

  ~> **NOTE**: Once the initial key creation has occurred post cluster
  initialization, it is advisable to disable this flag to prevent any
  unintended key creation in the future.

- `force_rw_session` `(string: "false")`: Force all operations to open up
  a read-write session to the HSM. This is a boolean expressed as a string (e.g.
  `"true"`). May also be specified by the `VAULT_HSM_FORCE_RW_SESSION` environment
  variable. This key is mainly to work around a limitation within AWS's CloudHSM v5
  pkcs11 implementation.

- `max_parallel` `(int: 1)` - The number of concurrent requests that may be
  in flight to the HSM at any given time.

- `disabled` `(string: "")`: Set this to `true` if Vault is migrating from an auto seal configuration. Otherwise, set to `false`.

Refer to the [Seal Migration](/vault/docs/concepts/seal#seal-migration) documentation for more information about the seal migration process.

### Mechanism specific flags

- `rsa_encrypt_local` `(string: "false")`: For HSMs that do not support encryption
  for RSA keys, perform encryption locally. Available for mechanisms
  `CKM_RSA_PKCS_OAEP` and `CKM_RSA_PKCS`. May also be specified by the
  `VAULT_HSM_RSA_ENCRYPT_LOCAL` environment variable.

- `rsa_oaep_hash` `(string: "sha256")`: Specify the hash algorithm to use for RSA
  with OAEP padding. Valid values are sha1, sha224, sha256, sha384, and sha512.
  Available for mechanism `CKM_RSA_PKCS_OAEP`. May also be specified by the
  `VAULT_HSM_RSA_OAEP_HASH` environment variable.

~> **Note:** Although the configuration file allows you to pass in
`VAULT_HSM_PIN` as part of the seal's parameters, it is _strongly_ recommended
to set this value via environment variables.

## `pkcs11` environment variables

Alternatively, the HSM seal can be activated by providing the following
environment variables:

```text
VAULT_SEAL_TYPE
VAULT_HSM_LIB
VAULT_HSM_SLOT
VAULT_HSM_TOKEN_LABEL
VAULT_HSM_PIN
VAULT_HSM_KEY_LABEL
VAULT_HSM_DEFAULT_KEY_LABEL
VAULT_HSM_KEY_ID
VAULT_HSM_HMAC_KEY_LABEL
VAULT_HSM_HMAC_DEFAULT_KEY_LABEL
VAULT_HSM_HMAC_KEY_ID
VAULT_HSM_MECHANISM
VAULT_HSM_HMAC_MECHANISM
VAULT_HSM_GENERATE_KEY
VAULT_HSM_RSA_ENCRYPT_LOCAL
VAULT_HSM_RSA_OAEP_HASH
VAULT_HSM_FORCE_RW_SESSION
```

## Vault key generation attributes

If Vault generates the HSM key for you, the following is the list of attributes
it uses. These identifiers correspond to official PKCS#11 identifiers.

### AES key

- `CKA_CLASS`: `CKO_SECRET_KEY` (It's a secret key)
- `CKA_KEY_TYPE`: `CKK_AES` (Key type is AES)
- `CKA_VALUE_LEN`: `32` (Key size is 256 bits)
- `CKA_LABEL`: Set to the key label set in Vault's configuration
- `CKA_ID`: Set to a random 32-bit unsigned integer
- `CKA_PRIVATE`: `true` (Key is private to this slot/token)
- `CKA_TOKEN`: `true` (Key persists to the slot/token rather than being for one
  session only)
- `CKA_SENSITIVE`: `true` (Key is a sensitive value)
- `CKA_ENCRYPT`: `true` (Key can be used for encryption)
- `CKA_DECRYPT`: `true` (Key can be used for decryption)
- `CKA_WRAP`: `true` (Key can be used for wrapping)
- `CKA_UNWRAP`: `true` (Key can be used for unwrapping)
- `CKA_EXTRACTABLE`: `false` (Key cannot be exported)

### RSA key

_Public Key_

- `CKA_CLASS`: `CKO_PUBLIC_KEY` (It's a public key)
- `CKA_KEY_TYPE`: `CKK_RSA` (Key type is RSA)
- `CKA_LABEL`: Set to the key label set in Vault's configuration
- `CKA_ID`: Set to a random 32-bit unsigned integer
- `CKA_ENCRYPT`: `true` (Key can be used for encryption)
- `CKA_WRAP`: `true` (Key can be used for wrapping)
- `CKA_MODULUS_BITS`: `2048` (Key size is 2048 bits)
- `CKA_PUBLIC_EXPONENT`: `0x10001` (Public exponent of 65537)
- `CKA_TOKEN`: `true` (Key persists to the slot/token rather than being for one
  session only)

_Private Key_

- `CKA_CLASS`: `CKO_PRIVATE_KEY` (It's a private key)
- `CKA_KEY_TYPE`: `CKK_RSA` (Key type is RSA)
- `CKA_LABEL`: Set to the key label set in Vault's configuration
- `CKA_ID`: Set to a random 32-bit unsigned integer
- `CKA_DECRYPT`: `true` (Key can be used for decryption)
- `CKA_UNWRAP`: `true` (Key can be used for unwrapping)
- `CKA_TOKEN`: `true` (Key persists to the slot/token rather than being for one
  session only)
- `CKA_EXTRACTABLE`: `false` (Key cannot be exported)

### HMAC key

- `CKA_CLASS`: `CKO_SECRET_KEY` (It's a secret key)
- `CKA_KEY_TYPE`: `CKK_GENERIC_SECRET_KEY` (Key type is a generic secret key)
- `CKA_VALUE_LEN`: `32` (Key size is 256 bits)
- `CKA_LABEL`: Set to the HMAC key label set in Vault's configuration
- `CKA_ID`: Set to a random 32-bit unsigned integer
- `CKA_PRIVATE`: `true` (Key is private to this slot/token)
- `CKA_TOKEN`: `true` (Key persists to the slot/token rather than being for one
  session only)
- `CKA_SENSITIVE`: `true` (Key is a sensitive value)
- `CKA_SIGN`: `true` (Key can be used for signing)
- `CKA_VERIFY`: `true` (Key can be used for verifying)
- `CKA_EXTRACTABLE`: `false` (Key cannot be exported)

## Key rotation

This seal supports rotating keys by using different key labels to track key versions. To rotate
the key value, generate a new key in a different key label in the HSM and update Vault's
configuration with the new key label value. Restart your vault instance to pick up the new key
label and all new encryption operations will use the updated key label. Old keys must not be disabled
or deleted and are used to decrypt older data. To disable or delete old keys, Vault needs to
 perform [seal-rewrap](/vault/api-docs/system/sealwrap-rewrap#start-a-seal-rewrap-process)
 so  that data encrypted by the old key can be decrypted using the new key.

**NOTE**: Prior to version 0.10.1, key information was not tracked with the ciphertext. If
rotation is desired for data that was seal wrapped prior to this version must also set
`default_key_label` and `hmac_default_key_label` to allow for decryption of older values.

## Tutorial

Refer to the [HSM Integration - Seal Wrap](/vault/tutorials/auto-unseal/seal-wrap)
tutorial to learn how to enable the Seal Wrap feature to protect your data.

layout  docs page title  PKCS11   Seals   Configuration description       The PKCS11 seal configures Vault to use an HSM with PKCS11 as the seal   wrapping mechanism          pkcs11  seal    Note title  Auto unseal and seal wrapping requires Vault Enterprise      Auto unseal   and   seal wrapping for PKCS11 require Vault Enterprise       Vault Enterprise enables seal wrapping by default  which means the KMS service   must be available at runtime and not just during the unseal process  Refer to   the  Seal wrap   vault docs enterprise sealwrap  overview for more   information     Note   The PKCS11 seal configures Vault to use an HSM with PKCS11 as the seal wrapping mechanism  Vault Enterprise s HSM PKCS11 support is activated by one of the following     The presence of a  seal  pkcs11   block in Vault s configuration file   The presence of the environment variable  VAULT HSM LIB  set to the library s   path as well as  VAULT SEAL TYPE  set to  pkcs11   If enabling via environment   variable  all other required values  i e   VAULT HSM SLOT   must be also   supplied     IMPORTANT    Having Vault generate its own key is the easiest way to get up and running  but for security  Vault marks the key as non exportable  If your HSM key backup strategy requires the key to be exportable  you should generate the key yourself  The list of creation attributes that Vault uses to generate the key are listed at the end of this document      Requirements  The following software packages are required for Vault Enterprise HSM     PKCS 11 compatible HSM integration library  Vault targets version 2 2 or   higher of PKCS 11  Depending on any given HSM  some functions  such as key   generation  may have to be performed manually    The  GNU libltdl   library  https   www gnu org software libtool manual html node Using libltdl html      ensure that it is installed for the correct architecture of your servers      pkcs11  example  This example shows configuring HSM PKCS11 seal through the Vault configuration file by providing all the required values      hcl seal  pkcs11      lib                usr vault lib libCryptoki2 64 so    slot              2305843009213693953    pin               AAAA BBBB CCCC DDDD    key label         vault hsm key    hmac key label    vault hsm hmac key             pkcs11  parameters  These parameters apply to the  seal  stanza in the Vault configuration file      lib    string   required     The path to the PKCS 11 library shared object   file  May also be specified by the  VAULT HSM LIB  environment variable          Note    Depending on your HSM  the value of the  lib  parameter may be   either a binary or a dynamic library  and its use may require other libraries   depending on which system the Vault binary is currently running on  e g   a   Linux system may require other libraries to interpret Windows  dll files       slot    string   slot or token label required     The slot number to use    specified as a string  e g    2305843009213693953     May also be specified by   the  VAULT HSM SLOT  environment variable          Note    Slots are typically listed as hex decimal values in the OS setup   utility but this configuration uses their decimal equivalent  For example  using the   HSM command line  pkcs11 tool   a slot listed as  0x2000000000000001 in hex is equal   to  2305843009213693953  in decimal  these values may be listed shorter or   differently as determined by the HSM in use      token label    string   slot or token label required     The slot token label to   use  May also be specified by the  VAULT HSM TOKEN LABEL  environment variable      pin    string   required     The PIN for login  May also be specified by the    VAULT HSM PIN  environment variable   If set via the environment variable    it will need to be re set if Vault is restarted       key label    string   required     The label of the key to use  If the key   does not exist and generation is enabled  this is the label that will be given   to the generated key  May also be specified by the  VAULT HSM KEY LABEL    environment variable      default key label    string        This is the default key label for decryption   operations  Prior to 0 10 1  key labels were not stored with the ciphertext    Seal entries now track the label used in encryption operations  The default value   for this field is the  key label   If  key label  is rotated and this value is not   set  decryption may fail  May also be specified by the  VAULT HSM DEFAULT KEY LABEL    environment variable  This value is ignored in new installations      key id    string        The ID of the key to use  The value should be a hexadecimal   string  e g    0x33333435363434373537    May also be specified by the    VAULT HSM KEY ID  environment variable      hmac key label    string   required     The label of the key to use for   HMACing  This needs to be a suitable type  If Vault tries to create this it   will attempt to use CKK GENERIC SECRET KEY  If the key does not exist and   generation is enabled  this is the label that will be given to the generated   key  May also be specified by the  VAULT HSM HMAC KEY LABEL  environment   variable      default hmac key label    string        This is the default HMAC key label for signing   operations  Prior to 0 10 1  HMAC key labels were not stored with the signature    Seal entries now track the label used in signing operations  The default value   for this field is the  hmac key label   If  hmac key label  is rotated and this   value is not set  signature verification may fail  May also be specified by the    VAULT HSM HMAC DEFAULT KEY LABEL  environment variable  This value is ignored in   new installations      hmac key id    string        The ID of the HMAC key to use  The value should be a   hexadecimal string  e g    0x33333435363434373537    May also be specified by the    VAULT HSM HMAC KEY ID  environment variable      mechanism    string   best available     The encryption decryption mechanism to use    specified as a decimal or hexadecimal  prefixed by  0x   string  May also be   specified by the  VAULT HSM MECHANISM  environment variable    Currently supported mechanisms  in order of precedence         0x1085   CKM AES CBC PAD   HMAC mechanism required       0x1082   CKM AES CBC   HMAC mechanism required       0x1087   CKM AES GCM       0x0009   CKM RSA PKCS OAEP       0x0001   CKM RSA PKCS          Warning    CKM RSA PKCS specifies the PKCS  1 v1 5 padding scheme  which is   in considered less secure than OAEP  Where possible  use of CKM RSA PKCS OAEP is   recommended over CKM RSA PKCS      hmac mechanism    string   0x0251     The encryption decryption mechanism to   use  specified as a decimal or hexadecimal  prefixed by  0x   string    Currently only  0x0251   corresponding to  CKM SHA256 HMAC  from the   specification  is supported  May also be specified by the    VAULT HSM HMAC MECHANISM  environment variable  This value is only required   for specific mechanisms      generate key    string   false     If no existing key with the label   specified by  key label  can be found at Vault initialization time  instructs   Vault to generate a key  This is a boolean expressed as a string  e g      true     May also be specified by the  VAULT HSM GENERATE KEY  environment   variable  Vault may not be able to successfully generate keys in all   circumstances  such as if proprietary vendor extensions are required to   create keys of a suitable type          NOTE    Once the initial key creation has occurred post cluster   initialization  it is advisable to disable this flag to prevent any   unintended key creation in the future      force rw session    string   false     Force all operations to open up   a read write session to the HSM  This is a boolean expressed as a string  e g      true     May also be specified by the  VAULT HSM FORCE RW SESSION  environment   variable  This key is mainly to work around a limitation within AWS s CloudHSM v5   pkcs11 implementation      max parallel    int  1     The number of concurrent requests that may be   in flight to the HSM at any given time      disabled    string        Set this to  true  if Vault is migrating from an auto seal configuration  Otherwise  set to  false    Refer to the  Seal Migration   vault docs concepts seal seal migration  documentation for more information about the seal migration process         Mechanism specific flags     rsa encrypt local    string   false     For HSMs that do not support encryption   for RSA keys  perform encryption locally  Available for mechanisms    CKM RSA PKCS OAEP  and  CKM RSA PKCS   May also be specified by the    VAULT HSM RSA ENCRYPT LOCAL  environment variable      rsa oaep hash    string   sha256     Specify the hash algorithm to use for RSA   with OAEP padding  Valid values are sha1  sha224  sha256  sha384  and sha512    Available for mechanism  CKM RSA PKCS OAEP   May also be specified by the    VAULT HSM RSA OAEP HASH  environment variable        Note    Although the configuration file allows you to pass in  VAULT HSM PIN  as part of the seal s parameters  it is  strongly  recommended to set this value via environment variables       pkcs11  environment variables  Alternatively  the HSM seal can be activated by providing the following environment variables      text VAULT SEAL TYPE VAULT HSM LIB VAULT HSM SLOT VAULT HSM TOKEN LABEL VAULT HSM PIN VAULT HSM KEY LABEL VAULT HSM DEFAULT KEY LABEL VAULT HSM KEY ID VAULT HSM HMAC KEY LABEL VAULT HSM HMAC DEFAULT KEY LABEL VAULT HSM HMAC KEY ID VAULT HSM MECHANISM VAULT HSM HMAC MECHANISM VAULT HSM GENERATE KEY VAULT HSM RSA ENCRYPT LOCAL VAULT HSM RSA OAEP HASH VAULT HSM FORCE RW SESSION         Vault key generation attributes  If Vault generates the HSM key for you  the following is the list of attributes it uses  These identifiers correspond to official PKCS 11 identifiers       AES key     CKA CLASS    CKO SECRET KEY   It s a secret key     CKA KEY TYPE    CKK AES   Key type is AES     CKA VALUE LEN    32   Key size is 256 bits     CKA LABEL   Set to the key label set in Vault s configuration    CKA ID   Set to a random 32 bit unsigned integer    CKA PRIVATE    true   Key is private to this slot token     CKA TOKEN    true   Key persists to the slot token rather than being for one   session only     CKA SENSITIVE    true   Key is a sensitive value     CKA ENCRYPT    true   Key can be used for encryption     CKA DECRYPT    true   Key can be used for decryption     CKA WRAP    true   Key can be used for wrapping     CKA UNWRAP    true   Key can be used for unwrapping     CKA EXTRACTABLE    false   Key cannot be exported       RSA key   Public Key      CKA CLASS    CKO PUBLIC KEY   It s a public key     CKA KEY TYPE    CKK RSA   Key type is RSA     CKA LABEL   Set to the key label set in Vault s configuration    CKA ID   Set to a random 32 bit unsigned integer    CKA ENCRYPT    true   Key can be used for encryption     CKA WRAP    true   Key can be used for wrapping     CKA MODULUS BITS    2048   Key size is 2048 bits     CKA PUBLIC EXPONENT    0x10001   Public exponent of 65537     CKA TOKEN    true   Key persists to the slot token rather than being for one   session only    Private Key      CKA CLASS    CKO PRIVATE KEY   It s a private key     CKA KEY TYPE    CKK RSA   Key type is RSA     CKA LABEL   Set to the key label set in Vault s configuration    CKA ID   Set to a random 32 bit unsigned integer    CKA DECRYPT    true   Key can be used for decryption     CKA UNWRAP    true   Key can be used for unwrapping     CKA TOKEN    true   Key persists to the slot token rather than being for one   session only     CKA EXTRACTABLE    false   Key cannot be exported       HMAC key     CKA CLASS    CKO SECRET KEY   It s a secret key     CKA KEY TYPE    CKK GENERIC SECRET KEY   Key type is a generic secret key     CKA VALUE LEN    32   Key size is 256 bits     CKA LABEL   Set to the HMAC key label set in Vault s configuration    CKA ID   Set to a random 32 bit unsigned integer    CKA PRIVATE    true   Key is private to this slot token     CKA TOKEN    true   Key persists to the slot token rather than being for one   session only     CKA SENSITIVE    true   Key is a sensitive value     CKA SIGN    true   Key can be used for signing     CKA VERIFY    true   Key can be used for verifying     CKA EXTRACTABLE    false   Key cannot be exported      Key rotation  This seal supports rotating keys by using different key labels to track key versions  To rotate the key value  generate a new key in a different key label in the HSM and update Vault s configuration with the new key label value  Restart your vault instance to pick up the new key label and all new encryption operations will use the updated key label  Old keys must not be disabled or deleted and are used to decrypt older data  To disable or delete old keys  Vault needs to  perform  seal rewrap   vault api docs system sealwrap rewrap start a seal rewrap process   so  that data encrypted by the old key can be decrypted using the new key      NOTE    Prior to version 0 10 1  key information was not tracked with the ciphertext  If rotation is desired for data that was seal wrapped prior to this version must also set  default key label  and  hmac default key label  to allow for decryption of older values      Tutorial  Refer to the  HSM Integration   Seal Wrap   vault tutorials auto unseal seal wrap  tutorial to learn how to enable the Seal Wrap feature to protect your data