OpenTofu Feature Preview: State Encryption
Published: 2024-04-19 14:48:09

## Background
The original [proposal](https://github.com/hashicorp/terraform/issues/9556) 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](https://github.com/hashicorp/terraform/pull/28603) 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: https://www.youtube.com/embed/rR4IbhlRSkI?si=IRt95ACIDA6nTeyy

## 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](https://github.com/opentofu/opentofu/blob/main/docs/state_encryption.md) 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](https://github.com/opentofu/opentofu/blob/main/docs/state_encryption.md) 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](https://github.com/opentofu/opentofu/blob/main/docs/state_encryption.md) 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.

## Interesting links
- [RFC: Client Side State Encryption](https://github.com/opentofu/opentofu/issues/874)
- [Implementation details](https://github.com/opentofu/opentofu/issues/1030)
- [Technical description](https://github.com/opentofu/opentofu/blob/main/docs/state_encryption.md)

## Terrateam
[Terrateam](https://terrateam.io) integrates seamlessly with OpenTofu. [Schedule a demo](https://terrateam.io/demo) to see OpenTofu and Terrateam side by side.