OpenTofu previews encryption with explicit state migration

Encrypting a state file changes which credentials are sufficient to operate infrastructure. Access to the backend no longer supplies readable state by itself. The process executing the infrastructure tool also needs the encryption configuration and the appropriate key. OpenTofu's first 1.7 alpha makes that separation available for testing, including the migration behavior needed to introduce it without abandoning existing state.

The 1.7.0-alpha1 release, published on 14 March, explicitly excludes production workloads. State encryption is one of its headline additions, alongside declarative removal blocks. The useful detail is in the encryption documentation shipped with this alpha, which explains both the protection and the conditions under which OpenTofu will read older files.

I favor OpenTofu's open source direction because infrastructure configuration benefits from an implementation that can be inspected and extended. Encryption is a concrete example of that development opportunity. Its value depends on a precise threat model and on recoverable key handling, which the alpha documentation makes part of the feature.

The encryption boundary is the CLI

The alpha supports encryption of state and plan files at rest for both local storage and remote backends. It also supports encrypted data accessed through terraform_remote_state. This locates the protection in the infrastructure tool, so the same configuration model can apply even when the storage destination changes.

The documented threat is an attacker obtaining the state file and reading sensitive values such as access keys. With encryption enabled, possessing the stored file should not disclose those values without the appropriate key. This is useful when backend file access and permission to execute infrastructure operations need separate controls. An exported file can retain its encryption even after it leaves the backend where it originated.

The process running tofu must still obtain readable data to do its work. The documentation explicitly says encryption cannot hide state values from the person running the command. It also excludes protection against data loss and against replay of an older state or plan. Those are different properties, and treating encryption as proof of freshness would assign it a guarantee this alpha does not offer.

An encrypted backup therefore needs two forms of recoverability. The state bytes must survive, and a permitted operator must still be able to obtain the key needed to read them. Keeping only one side produces either lost infrastructure records or an unreadable backup. The alpha documentation asks users to exercise recovery and preserve keys before enabling the feature.

Key providers and encryption methods have separate jobs

The tagged changelog lists AES-GCM as the available encryption method. It lists PBKDF2 passphrase derivation and AWS KMS as key providers. Separating these concepts lets a configuration describe where key material comes from independently of the method that encrypts state.

A method references a configured key provider. State and plan settings then select methods for their respective files. That structure gives the configuration distinct places to express key acquisition and file protection. It also means that a configuration naming a method is only part of the setup. The referenced provider must supply usable key material.

For PBKDF2, the alpha documentation specifies a minimum passphrase length of 16 characters and a default derived key length of 32 bytes. It gives 600,000 iterations as the default and supports SHA-256 or SHA-512, with SHA-512 selected by default. These are the settings documented for this prerelease, not a claim that a passphrase of the minimum length has adequate strength for every environment.

The AES-GCM section requires keys of 16, 24 or 32 bytes. It also discusses limits on safe key reuse and the need to account for rotation or derivation in the key setup. This reinforces why choosing an algorithm name is insufficient as an operating design. The key provider's behavior is part of the protection the method can supply.

Configuration can require encryption without storing the key

Encryption settings can live in the OpenTofu configuration or in the TF_ENCRYPTION environment variable. When both exist, the documentation says OpenTofu merges them and gives environment settings precedence. This permits an execution environment to supply details separately from the infrastructure source.

A small configuration can require encryption for both artifact types while the environment supplies the selected methods and keys. The alpha includes this pattern in its enforcement example.

terraform {
  encryption {
    state {
      enforced = true
    }
    plan {
      enforced = true
    }
  }
}

This block is an enforcement policy, not a complete key configuration. Its purpose is to prevent unencrypted writes when the expected environment settings are missing. A run still needs the remaining encryption settings before it can use the encrypted artifacts.

I find that separation useful because a repository can state its persistence requirements without containing the operational key material. It also makes missing execution configuration an explicit failure. A developer or automation process should not silently produce plaintext merely because a variable expected by the workflow was absent.

Fallbacks define the migration

OpenTofu does not automatically accept plaintext files after encryption is configured. The alpha documentation describes this as protection against reading manipulated unencrypted data. An existing plaintext state consequently needs an explicit transition configuration before the encrypted workflow can read it.

For the initial transition, an empty fallback block allows reading unencrypted data while the selected method controls new writes. This is a directional migration. The old representation remains readable for the transition, while subsequent persistence uses the new method. The setting expresses which old input is permitted without choosing that representation for future output.

The same structure supports changes between encryption methods or key configurations. OpenTofu first attempts to read with the new method, then tries the configured fallback if needed. Writes always use the new method. This allows a passphrase change or a key-management change to preserve access to existing files during the transition.

Names in the encryption configuration have persistence consequences. The alpha documentation warns against casually renaming key providers or methods after encrypting data, because the stored metadata refers to those names. A rename therefore needs migration treatment through fallbacks. Refactoring a configuration label can affect readability of existing artifacts even though the label might otherwise appear local to the source.

Encrypted remote state consumers need their own decryption configuration too. The alpha supports settings for remote state data sources and allows selection of specific source names, including sources inside modules. The producer's ability to write encrypted state does not automatically grant every consumer the configuration needed to read it.

The first alpha makes these lifecycle rules available for experimentation alongside the cryptographic implementation. Its practical contribution is a defined path for reading existing state, writing under a new method and maintaining access through key changes. That is the part of encryption that infrastructure operators need to understand before any later production adoption.