Terraform Provider for Tor Bridges

A Terraform/OpenTofu provider for managing obfs4 Tor bridge cryptographic identity and state.

Canonical Repository: https://guardianproject.dev/ops/terraform-provider-tor

Overview

This provider enables stateless deployment of obfs4 Tor bridges by pre-generating all required cryptographic identity materials in Terraform/OpenTofu. Instead of bridges generating new identity keys at startup (which would change on each deployment), this provider manages the identity lifecycle within your infrastructure-as-code workflow.

Why?

When deploying obfs4 bridges at scale, maintaining consistent bridge identity across VM upgrades and replacements is crucial. This provider solves that by:

• Generating relay identity keys (RSA and Ed25519)
• Creating obfs4 state including certificates for bridge lines
• Providing complete bridge line generation for client distribution
• Enabling fully immutable bridge VMs that retain identity across deployments

Usage

terraform {
  required_providers {
    tor = {
      source = "guardianproject/tor"
    }
  }
}

provider "tor" {}

# Generate family (tor 0.4.9.2-alpha or later)
resource "tor_family_identity" "example" {
  family_name = "MyFamily"
}

output "family_id" {
  description = "Family ID for the bridge"
  value       = tor_family_identity.this.id
}

resource "local_sensitive_file" "family_key" {
  content_base64 = tor_family_identity.this.secret_key
  filename       = "./data/keys/MyKey.secret_family_key"
  file_permission = "0600"
}

# Generate relay identity keys
resource "tor_relay_identity_rsa" "bridge" {}

resource "tor_relay_identity_ed25519" "bridge" {}

resource "tor_obfs4_state" "bridge" {
  rsa_identity_private_key     = tor_relay_identity_rsa.bridge.private_key_pem
  ed25519_identity_private_key = tor_relay_identity_ed25519.bridge.private_key_pem
}

# Generate bridge line for client distribution
data "tor_obfs4_bridge_line" "bridge" {
  ip_address                  = "192.0.2.1"
  port                        = 443
  identity_fingerprint_sha1   = tor_relay_identity_rsa.bridge.public_key_fingerprint_sha1
  obfs4_state_certificate     = tor_obfs4_state.bridge.certificate
  obfs4_state_iat_mode        = tor_obfs4_state.bridge.iat_mode
}

# Output bridge configuration for deployment
output "rsa_identity_pem" {
  description = "RSA identity private key for bridge configuration"
  value       = tor_relay_identity_rsa.bridge.private_key_pem
  sensitive   = true
}

output "ed25519_identity_pem" {
  description = "Ed25519 identity private key for bridge configuration"
  value       = tor_relay_identity_ed25519.bridge.private_key_pem
  sensitive   = true
}

output "obfs4_state_json" {
  description = "Complete obfs4 state for bridge runtime"
  value       = tor_obfs4_state.bridge.state_json
  sensitive   = true
}

output "bridge_line" {
  description = "Complete bridge line for client use"
  value       = data.tor_obfs4_bridge_line.bridge.bridge_line
}

Provider Options

This provider requires no configuration options.

Documentation

Complete documentation is available in the docs/ directory:

• tor_relay_identity_rsa
• tor_relay_identity_ed25519
• tor_obfs4_state
• tor_obfs4_bridge_line (data source)

Requirements

• Terraform >= 1.0 or OpenTofu >= 1.0
• Go >= 1.23 (for development)

Versioning

This provider follows Semantic Versioning 2.0.0. See CHANGELOG.md for release history.

Maintenance

This provider is actively maintained by Guardian Project.

Issues

For bug reports and feature requests, please use the Issues page.

Security

For security-related issues, please contact us through our [security policy][sec].

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on how to contribute to this project.

References

• lyrebird - the obfs4 Go implementation used by this provider
• Tor Bridge Operations - Setting up Tor bridges
• obfs4 Protocol Specification

License

Copyright © 2025 Abel Luck abel@guardianproject.info

This project is licensed under the GNU General Public License v3.0 or later - see the LICENSE file for details.

[sec]: