Skip to main content

transit seal

The Transit seal configures OpenBao to use OpenBao's Transit Secret Engine as the autoseal mechanism. The Transit seal is activated by one of the following:

  • The presence of a seal "transit" block in OpenBao's configuration file
  • The presence of the environment variable VAULT_SEAL_TYPE set to transit.

transit example​

This example shows configuring Transit seal through the OpenBao configuration file by providing all the required values:

seal "transit" {
  address            = "https://openbao:8200"
  token              = "s.Qf1s5zigZ4OX6akYjQXJC1jY"
  disable_renewal    = "false"

  // Key configuration
  key_name           = "transit_key_name"
  mount_path         = "transit/"
  namespace          = "ns1/"

  // TLS Configuration
  tls_ca_cert        = "/etc/openbao/ca_cert.pem"
  tls_client_cert    = "/etc/openbao/client_cert.pem"
  tls_client_key     = "/etc/openbao/ca_cert.pem"
  tls_server_name    = "openbao"
  tls_skip_verify    = "false"
}

transit parameters​

These parameters apply to the seal stanza in the OpenBao configuration file:

  • address (string: <required>): The full address to the OpenBao cluster. This may also be specified by the VAULT_ADDR environment variable.

  • token (string: <required>): The OpenBao token to use. This may also be specified by the VAULT_TOKEN environment variable.

  • key_name (string: <required>): The transit key to use for encryption and decryption. This may also be supplied using the VAULT_TRANSIT_SEAL_KEY_NAME environment variable.

  • mount_path (string: <required>): The mount path to the transit secret engine. This may also be supplied using the VAULT_TRANSIT_SEAL_MOUNT_PATH environment variable.

  • namespace (string: ""): The namespace path to the transit secret engine. This may also be supplied using the VAULT_NAMESPACE environment variable.

  • disable_renewal (string: "false"): Disables the automatic renewal of the token in case the lifecycle of the token is managed with some other mechanism outside of OpenBao, such as OpenBao Agent. This may also be specified using the VAULT_TRANSIT_SEAL_DISABLE_RENEWAL environment variable.

  • tls_ca_cert (string: ""): Specifies the path to the CA certificate file used for communication with the OpenBao server. This may also be specified using the VAULT_CACERT environment variable.

  • tls_client_cert (string: ""): Specifies the path to the client certificate for communication with the OpenBao server. This may also be specified using the VAULT_CLIENT_CERT environment variable.

  • tls_client_key (string: ""): Specifies the path to the private key for communication with the OpenBao server. This may also be specified using the VAULT_CLIENT_KEY environment variable.

  • tls_server_name (string: ""): Name to use as the SNI host when connecting to the OpenBao server via TLS. This may also be specified via the VAULT_TLS_SERVER_NAME environment variable.

  • tls_skip_verify (bool: "false"): Disable verification of TLS certificates. Using this option is highly discouraged and decreases the security of data transmissions to and from the OpenBao server. This may also be specified using the VAULT_SKIP_VERIFY environment variable.

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

Refer to the Seal Migration documentation for more information about the seal migration process.

Authentication​

Authentication-related values must be provided, either as environment variables or as configuration parameters.

warning

Note: Although the configuration file allows you to pass in VAULT_TOKEN as part of the seal's parameters, it is strongly recommended to set these values via environment variables.

The OpenBao token used to authenticate needs the following permissions on the transit key:

path "<mount path>/encrypt/<key name>" {
  capabilities = ["update"]
}

path "<mount path>/decrypt/<key name>" {
  capabilities = ["update"]
}

Other considerations for the token used:

  • it should probably be an orphan token, otherwise when the parent token expires or gets revoked the seal will break.
  • consider making it a periodic token and not setting an explicit max TTL, otherwise at some point it will cease to be renewable.

Key rotation​

This seal supports key rotation using the Transit Secret Engine's key rotation endpoints. See doc. Old keys must not be disabled or deleted and are used to decrypt older data.