Background

The original proposal for Terraform state encryption was created back in 2016 in the hashicorp/terraform repository. It was created by one of the core project maintainers. The Issue has been stale for years and there's even been an ignored pull request to implement the feature request.

It's clear that this feature request does not align with the HashiCorp roadmap and that they are ignoring the community. Odd considering the fact that they could easily use state encryption as an upsell and tie it into their Vault offering.

One can only speculate why this feature request has been ignored. Perhaps they don't think state encryption is important to a security story or that they think encryption at-rest is sufficient.

Introduction

In this blog post we'll briefly go over the new state encryption feature coming out in OpenTofu 1.7. This is a work-in-progress and various implementation details of the feature could possibly change.

Video

If you want to watch a video explaining all of the aspects of state encryption, check out the official video released by OpenTofu:

Why state encryption is important

When creating resources with OpenTofu, sensitive data or secrets are stored in the state file. The state file is in clear-text and unencrypted. This opens up the opportunity for someone with access to the state file to gain elevated access to another system using the clear-text sensitive data in the state file.

With data encryption, OpenTofu can be passed an encryption key to encrypt a state file or plan file. Environment variables or third-party key management systems such as AWS KMS, GCP Secrets Manager, or Azure Keyvault can be used to generate the client-side key. OpenTofu uses the key to encrypt not only the state file but also the plan file.

Since this is client-side encryption, an attacker would have to have access to the state storage and the encryption key to read sensitive data from the state file.

This improves an organizations security posture by following the standard layered security model.

Configuring encryption

The State encryption technical documentation goes into detail on how to configure state and plan encryption in your OpenTofu code.

Enable encryption

In order to use the new encryption feature, you must include encryption in the terraform block:

terraform {
  encryption {
    // Encryption options
  }
}

There are a few other options you must specify to enable encryption. These include configuring your key_provider and method. See State encryption for details. Official documentation to come when 1.7 is released.

Gotchas

There are a few gotchas with this implementation that may change over time.

Encryption can only be configured globally.
Pre-configured encryption settings cannot be included in modules.
Encryption only protects state and plan files at-rest.
Encryption does not change the output shown by the tofu command (json/show/plan).
Encryption only protects against unauthorized access

Key rollover

Key rollover is the ability to transition from one encryption key method to another.

To facilitate a rollover, the fallback configuration block should be used when renaming key providers or methods.

Environment variables

Encryption can also be configured using environment variables for maximum flexibility. All of the configuration explained in the State encryption can be configured using the TF_ENCRYPTION environment variable and passed to the tofu command.

Timeline

State encryption is slated to be released with OpenTofu 1.7. This will potentially be followed up by a state encryption library in OpenTofu 1.8.

Features

Learn More

Learn

Connect