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 section below.

Finally, before enabling encryption, please exercise your disaster recovery plan and make a temporary backup of your unencrypted state file. You should also 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 are migrating from an unencrypted state or plan file to an encrypted one, you may be surprised to find OpenTofu refusing to read your old data. This is a protection mechanism to prevent OpenTofu from reading manipulated, unencrypted data. Please see the initial setup section below for details.

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:

terraform {
  encryption {
    key_provider "some_key_provider" "some_name" {
      # Key provider options here
    }

    method "some_method" "some_method_name" {
      # Method options here
      keys = key_provider.some_key_provider.some_name
    }

    state {
      # Encryption/decryption for state data
      method = method.some_method.some_method_name
    }

    plan {
      # Encryption/decryption for plan data
      method = method.some_method.some_method_name
    }

    remote_state_data_sources {
      # See below
    }
  }
}

read -d '' TF_ENCRYPTION << EOF
terraform {
  encryption {
    key_provider "some_key_provider" "some_name" {
      # Key provider options here
    }

    method "some_method" "some_method_name" {
      # Method options here
      keys = key_provider.some_key_provider.some_name
    }

    state {
      # Encryption/decryption for state data
      method = method.some_method.some_method_name
    }

    plan {
      # Encryption/decryption for plan data
      method = method.some_method.some_method_name
    }

    remote_state_data_sources {
      # See below
    }
  }
}
EOF

$Env:TF_ENCRYPTION = @"
terraform {
  encryption {
    key_provider "some_key_provider" "some_name" {
      # Key provider options here
    }

    method "some_method" "some_method_name" {
      # Method options here
      keys = key_provider.some_key_provider.some_name
    }

    state {
      # Encryption/decryption for state data
      method = method.some_method.some_method_name
    }

    plan {
      # Encryption/decryption for plan data
      method = method.some_method.some_method_name
    }

    remote_state_data_sources {
      # See below
    }
  }
}
"@

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

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:

terraform {
  encryption {
    key_provider "pbkdf2" "foo" {
      # Specify a long / complex passphrase (min. 16 characters)
      passphrase = "correct-horse-battery-staple"

      # Adjust the key length to the encryption method (default: 32)
      key_length = 32

      # Specify the number of iterations (min. 200.000, default: 600.000)
      iterations = 600000

      # Specify the salt length in bytes (default: 32)
      salt_length = 32

      # Specify the hash function (sha256 or sha512, default: sha512)
      hash_function = "sha512"
    }
  }
}

AWS KMS​

This key provider uses the Amazon Web Servers Key Management Service to generate keys. The authentication options are identical to the S3 backend excluding any deprecated options. In addition, please provide the following options:

The following example illustrates a minimal example:

terraform {
  encryption {
    key_provider "aws_kms" "basic" {
      kms_key_id = "a4f791e1-0d46-4c8e-b489-917e0bec05ef"
      region = "us-east-1"
      key_spec = "AES_256"
    }
  }
}

Methods​

AES-GCM​

The only currently supported encryption method is AES-GCM. You can configure it in the following way:

terraform {
  encryption {
    # Key provider configuration here

    method "aes_gcm" "yourname" {
      keys = key_provider.yourkeyprovider.yourname
    }
  }
}

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:

terraform {
  encryption {
    # Methods and key providers here.

    state {
      method = method.some_method.new_method
      fallback {
        method = method.some_method.old_method
      }
    }

    plan {
      method = method.some_method.new_method
      fallback {
        method = method.some_method.old_method
      }
    }
  }
}

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​

When you first configure encryption, 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 will have to specify an empty fallback block:

terraform {
  encryption {
    # Methods and key providers here.

    state {
      method = method.some_method.new_method
      fallback {
        # The empty fallback block allows reading unencrypted state files.
      }
    }
  }
}

Rolling back encryption​

Similar to the initial setup above, migrating to unencrypted state and plan files is also possible in a similar manner. You simply have to specify no method in the target block as follows:

terraform {
  encryption {
    # Methods and key providers here.

    state {
      # The empty block allows writing unencrypted state files
      # unless the enforced setting is set to true.
      fallback {
        method = method.some_method.old_method
      }
    }
  }
}

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 looks as follows:

terraform {
  encryption {
    # Key provider and method configuration here

    remote_state_data_sources {
      default {
        method = method.my_method.my_name
      }
      remote_state_data_source "my_state" {
        method = method.my_method.my_other_name
      }
    }
  }
}

data "terraform_remote_state" "my_state" {
  # ...
}

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.