OpenTofu — How It Works

Identical to Terraform internals (forked from 1.5.x) — with added client-side state encryption.

Core Engine

OpenTofu uses the exact same architecture as Terraform: HCL parsing → DAG → provider gRPC → state management. The key difference is the state encryption layer inserted before the state is written to the backend.

State Encryption Flow

sequenceDiagram
    participant CLI as OpenTofu CLI
    participant Enc as Encryption Layer
    participant KMS as Key Provider (AWS/GCP KMS, age, PBKDF2)
    participant Backend as Remote Backend (S3, GCS)

    CLI->>CLI: Compute state changes
    CLI->>Enc: Serialize state JSON
    Enc->>KMS: Request encryption key
    KMS-->>Enc: DEK (data encryption key)
    Enc->>Enc: AES-GCM encrypt state
    Enc->>Backend: Write encrypted state blob

    Note over Enc,Backend: Attacker with backend access<br/>sees only ciphertext

Key Rotation

flowchart LR
    Old["Old Key\n(fallback)"] --> Read["Decrypt with\nold key"]
    Read --> Reencrypt["Re-encrypt with\nnew key"]
    Reencrypt --> New["New Key\n(primary)"]

    style Old fill:#c62828,color:#fff
    style New fill:#2e7d32,color:#fff

OpenTofu supports a fallback key configuration to enable seamless key rotation without downtime.

Sources

• OpenTofu Architecture
• State Encryption