mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-03-03 05:01:30 -05:00
3b3822d770
Signed-off-by: Christian Mesh <christianmesh1@gmail.com> Signed-off-by: ollevche <ollevche@gmail.com> Co-authored-by: ollevche <ollevche@gmail.com>
239 lines
16 KiB
Plaintext
239 lines
16 KiB
Plaintext
---
|
|
description: >-
|
|
Encrypt your state-related data at rest.
|
|
---
|
|
|
|
import Tabs from '@theme/Tabs';
|
|
import TabItem from '@theme/TabItem';
|
|
import CodeBlock from '@theme/CodeBlock';
|
|
import ConfigurationTF from '!!raw-loader!./examples/encryption/configuration.tf'
|
|
import ConfigurationSH from '!!raw-loader!./examples/encryption/configuration.sh'
|
|
import ConfigurationPS1 from '!!raw-loader!./examples/encryption/configuration.ps1'
|
|
import Enforce from '!!raw-loader!./examples/encryption/enforce.tf'
|
|
import AESGCM from '!!raw-loader!./examples/encryption/aes_gcm.tf'
|
|
import PBKDF2 from '!!raw-loader!./examples/encryption/pbkdf2.tf'
|
|
import AWSKMS from '!!raw-loader!./examples/encryption/aws_kms.tf'
|
|
import GCPKMS from '!!raw-loader!./examples/encryption/gcp_kms.tf'
|
|
import OpenBao from '!!raw-loader!./examples/encryption/openbao.tf'
|
|
import Sample from '!!raw-loader!./examples/encryption/sample.tf'
|
|
import Fallback from '!!raw-loader!./examples/encryption/fallback.tf'
|
|
import FallbackFromUnencrypted from '!!raw-loader!./examples/encryption/fallback_from_unencrypted.tf'
|
|
import FallbackToUnencrypted from '!!raw-loader!./examples/encryption/fallback_to_unencrypted.tf'
|
|
import RemoteState from '!!raw-loader!./examples/encryption/terraform_remote_state.tf'
|
|
|
|
# State and Plan Encryption
|
|
|
|
OpenTofu supports encrypting state and plan files at rest, both for local storage and when using a backend. In addition, you can also use encryption with the `terraform_remote_state` data source. This page explains how to set up encryption and what encryption method is suitable for which use case.
|
|
|
|
## General guidance and pitfalls (please read)
|
|
|
|
When you enable encryption, your state and plan files become unrecoverable without the appropriate encryption key. Please make sure you read this section carefully before enabling encryption.
|
|
|
|
### What does encryption protect against?
|
|
|
|
When you enable encryption, OpenTofu will encrypt state data *at rest*. If an attacker were to gain access to your state file, they should not be able to read it and use the sensitive values (e.g. access keys) contained in the state file.
|
|
|
|
However, encryption does not protect against data loss (your state file getting damaged) and it also does not protect against replay attack (an attacker using an older state or plan file and tricking you into running it). Additionally, OpenTofu does not and cannot protect the sensitive values in the state file from the person running the `tofu` command.
|
|
|
|
### What precautions do I need to take?
|
|
|
|
When you enable encryption, consider who needs access to your state file directly. If you have more than a very small number of people with access needs, you may want to consider running your production `plan` and `apply` runs from a continuous integration system to protect both the encryption key and the sensitive values in your state.
|
|
|
|
You will also need to decide what kind of key you would like to use based on your security requirements. You can either opt for a static passphrase or you can choose a key management system. If you opt for a key management system, it is imperative to configure automatic key rotation for some encryption methods. This is particularly crucial if the encryption algorithm you choose has the potential to reach a point of 'key saturation', where the maximum safe usage limit of the key is approached, such as AES-GCM. You can find more information about this in the [encryption methods](#methods) section below.
|
|
|
|
Finally, before enabling encryption, please exercise your disaster recovery plan and make a temporary backup of your unencrypted state file. Also, make sure you have backups of your keys. Once you enable encryption, OpenTofu cannot read your state file without the correct key.
|
|
|
|
|
|
### Migrating from an unencrypted state/plan
|
|
|
|
If you have a pre-existing state file and want to enable encryption, simply enabling encryption is not enough as OpenTofu will refuse to read plain text data. This is a protection mechanism to prevent OpenTofu from reading manipulated, unencrypted data. Please see the [initial setup](#initial-setup) section below for detailed migration instructions.
|
|
|
|
### Compatibility guarantee
|
|
|
|
Research in cryptography can change the state of the art quickly. We will support all key providers and methods as documented for +1 minor version, but may introduce new versions of the same key providers and methods (e.g. `aes_gcm_v2`), or new key providers and methods in any minor version. If we deprecate a key provider or method, you will receive a warning on the console when running `tofu plan` or `tofu apply`. If you receive such a warning, please switch before upgrading to the next version.
|
|
|
|
## Configuration
|
|
|
|
You can configure encryption in OpenTofu either by specifying the configuration in the OpenTofu code, or using the `TF_ENCRYPTION` environment variable. Both solutions are equivalent and if you use both, OpenTofu will merge the two configurations, overriding any code-based settings with the environment ones.
|
|
|
|
The basic configuration structure looks as follows:
|
|
|
|
<Tabs>
|
|
<TabItem value="code" label="Code" default>
|
|
<CodeBlock language={"hcl"}>{ConfigurationTF}</CodeBlock>
|
|
</TabItem>
|
|
<TabItem value="env-sh" label="Environment (Linux/UNIX shell)">
|
|
<CodeBlock language={"shell"}>{ConfigurationSH}</CodeBlock>
|
|
</TabItem>
|
|
<TabItem value="env-ps1" label="Environment (Powershell)">
|
|
<CodeBlock language={"powershell"}>{ConfigurationPS1}</CodeBlock>
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
:::warning
|
|
|
|
Once your data is encrypted, do not rename key providers and methods in your configuration! The encrypted data stored in the backend contains metadata related to their specific names. Instead, use a [fallback block](#key-and-method-rollover) to handle changes to key providers.
|
|
|
|
:::
|
|
|
|
:::tip
|
|
|
|
You can use the [JSON configuration syntax](../../language/syntax/json.mdx) instead of HCL for encryption configuration.
|
|
|
|
:::
|
|
|
|
:::tip
|
|
|
|
If you use environment configuration, you can include the following code configuration to prevent unencrypted data from being written in the absence of an environment variable:
|
|
|
|
<CodeBlock language="hcl">{Enforce}</CodeBlock>
|
|
|
|
:::
|
|
|
|
## Key and method rollover
|
|
|
|
In some cases, you may want to change your encryption configuration. This can include renaming a key provider or method, changing a passphrase for a key provider, or switching key-management systems. OpenTofu supports an automatic rollover of your encryption configuration if you provide your old configuration in a `fallback` block:
|
|
|
|
<CodeBlock language="hcl">{Fallback}</CodeBlock>
|
|
|
|
If OpenTofu fails to **read** your state or plan file with the new method, it will automatically try the fallback method. When OpenTofu **saves** your state or plan file, it will always use the new method and not the fallback.
|
|
|
|
## Initial setup
|
|
|
|
### New project
|
|
|
|
If you are setting up a new project and do not yet have a state file, this sample configuration will get you started with passphrase-based encryption:
|
|
|
|
<CodeBlock language="hcl">{Sample}</CodeBlock>
|
|
|
|
### Pre-existing project
|
|
|
|
When you first configure encryption on an existing project, your state and plan files are unencrypted. OpenTofu, by default, refuses to read them because they could have been manipulated. To enable reading unencrypted data, you have to specify an `unencrypted` method:
|
|
|
|
<CodeBlock language="hcl">{FallbackFromUnencrypted}</CodeBlock>
|
|
|
|
:::note
|
|
Variables and locals can be used in configuration, but may not contain any references to data in the state or provider defined functions. All values must be able to be resolved during `tofu init` before the state is available.
|
|
:::
|
|
|
|
## Rolling back encryption
|
|
|
|
Similar to the initial setup above, migrating to unencrypted state and plan files is also possible by using the `unencrypted` method as follows:
|
|
|
|
<CodeBlock language="hcl">{FallbackToUnencrypted}</CodeBlock>
|
|
|
|
:::warning
|
|
|
|
Do not remove or modify the original encryption method until you have finished the migration.
|
|
|
|
:::
|
|
|
|
## Remote state data sources
|
|
|
|
You can also configure an encryption setup for projects using the `terraform_remote_state` data source. This can be the same encryption setup as your main configuration, but you can also define a separate set of keys and methods. The configuration syntax is as follows:
|
|
|
|
<CodeBlock language="hcl">{RemoteState}</CodeBlock>
|
|
|
|
For specific remote states, you can use the following syntax:
|
|
|
|
- `myname` to target a data source in the main project with the given name.
|
|
- `mymodule.myname` to target a data source in the specified module with the given name.
|
|
- `mymodule.myname[0]` to target the first data source in the specified module with the given name.
|
|
|
|
## Key providers
|
|
|
|
### PBKDF2
|
|
|
|
The PBKDF2 key provider allows you to use a long passphrase as to generate a key for an encryption method such as AES-GCM. You can configure it as follows:
|
|
|
|
<CodeBlock language="hcl">{PBKDF2}</CodeBlock>
|
|
|
|
| Option | Description | Min. | Default |
|
|
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|---------|
|
|
| passphrase *(required)* | Enter a long and complex passphrase. | 16 chars. | - |
|
|
| key_length | Number of bytes to generate as a key. | 1 | 32 |
|
|
| iterations | Number of iterations. See [this document](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2) for recommendations. | 200.000 | 600.000 |
|
|
| salt_length | Length of the salt for the key derivation. | 1 | 32 |
|
|
| hash_function | Specify either `sha256` or `sha512` to use as a hash function. `sha1` is not supported. | N/A | sha512 |
|
|
|
|
### AWS KMS
|
|
|
|
This key provider uses the [Amazon Web Servers Key Management Service](https://aws.amazon.com/kms/) to generate keys. The authentication options are identical to the [S3 backend](../../language/settings/backends/s3.mdx) excluding any deprecated options. In addition, please provide the following options:
|
|
|
|
| Option | Description | Min. | Default |
|
|
|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|------|---------|
|
|
| kms_key_id | [Key ID for AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id). | 1 | - |
|
|
| key_spec | [Key spec for AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-spec). Adapt this to your encryption method (e.g. `AES_256`). | 1 | - |
|
|
|
|
The following example illustrates a minimal configuration:
|
|
|
|
<CodeBlock language="hcl">{AWSKMS}</CodeBlock>
|
|
|
|
### GCP KMS
|
|
|
|
This key provider uses the [Google Cloud Key Management Service](https://cloud.google.com/kms/docs) to generate keys. The authentication options are identical to the [GCS backend](../../language/settings/backends/gcs.mdx) excluding any deprecated options. In addition, please provide the following options:
|
|
|
|
| Option | Description | Min. | Default |
|
|
|---------------------------------------|------------------------------------------------------------------------------------------------------------------|------|---------|
|
|
| kms_encryption_key *(required)* | [Key ID for GCP KMS](https://cloud.google.com/kms/docs/create-key#kms-create-symmetric-encrypt-decrypt-console). | N/A | - |
|
|
| key_length *(required)* | Number of bytes to generate as a key. Must be in range from `1` to `1024` bytes. | 1 | - |
|
|
|
|
The following example illustrates a minimal configuration:
|
|
|
|
<CodeBlock language="hcl">{GCPKMS}</CodeBlock>
|
|
|
|
### OpenBao (experimental)
|
|
|
|
This key provider uses the [OpenBao Transit Secret Engine](https://openbao.org/docs/secrets/transit) to generate data keys. You can configure it as follows:
|
|
|
|
| Option | Description | Min. | Default |
|
|
|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|------------------------|
|
|
| key_name *(required)* | Name of the transit encryption key to use to encrypt/decrypt the datakey. [Pre-configure](https://openbao.org/docs/secrets/transit/#setup) it in your in OpenBao server. | N/A | - |
|
|
| token | [Authorization Token](https://openbao.org/docs/concepts/tokens/) to use when accessing OpenBao API. OpenTofu can read it from the `BAO_TOKEN` environment variable as well. | N/A | - |
|
|
| address | OpenBao server address to access the API. OpenTofu can read it from the `BAO_ADDR` environment variable as well. Your system must trust the TLS certificate of the server. | N/A | https://127.0.0.1:8200 |
|
|
| transit_engine_path | Path at which the Transit Secret Engine is enabled in OpenBao. Customize this if you changed the transit engine path. | N/A | /transit |
|
|
| key_length | Number of bytes to generate as a key. Available options are `16`, `32` or `64` bytes. | 16 | 32 |
|
|
|
|
The following example illustrates a possible configuration:
|
|
|
|
<CodeBlock language="hcl">{OpenBao}</CodeBlock>
|
|
|
|
:::warning
|
|
|
|
The OpenBao key provider is currently experimental because there was no stable release of OpenBao available at the time the OpenTofu release was made.
|
|
|
|
:::
|
|
|
|
:::info
|
|
|
|
The OpenBao key provider is compatible with the last MPL-licensed version of HashiCorp Vault (1.14) but does not support the subsequent BUSL-licensed versions.
|
|
|
|
:::
|
|
|
|
## Methods
|
|
|
|
|
|
### AES-GCM
|
|
|
|
The only currently supported encryption method is AES-GCM. You can configure it in the following way:
|
|
|
|
<CodeBlock language="hcl">{AESGCM}</CodeBlock>
|
|
|
|
:::note
|
|
|
|
The AES-GCM method needs 16, 24, or 32-byte keys. Please configure your key provider to supply keys with this exact length.
|
|
|
|
:::
|
|
|
|
:::warning
|
|
|
|
AES-GCM is a secure, industry-standard encryption algorithm, but suffers from "key saturation". In order to configure a secure setup, you should either use a key-derivation key provider (such as PBKDF2) with a long and complex passphrase, or use a key management system that automatically rotates keys regularly. Using short, static keys will degrade your encryption.
|
|
|
|
:::
|
|
|
|
### Unencrypted
|
|
|
|
The `unencrypted` method is used to provide an explicit migration path to and from encryption. It takes no configuration and can be seen in use above in the [Initial Setup](#initial-setup) block.
|
|
|
|
|