# Terraform Provider for Tor Bridges

[![][ci-badge]][ci]
[![Go Report Card](https://goreportcard.com/badge/github.com/guardianproject/terraform-provider-tor)](https://goreportcard.com/report/github.com/guardianproject/terraform-provider-tor)

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

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

provider "tor" {}

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

resource "tor_relay_identity_ed25519" "bridge" {}

# Generate obfs4 state using the identity keys
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
  iat_mode                     = 1
}

# 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/](docs/) directory:

- [tor_relay_identity_rsa](docs/resources/relay_identity_rsa.md)
- [tor_relay_identity_ed25519](docs/resources/relay_identity_ed25519.md)
- [tor_obfs4_state](docs/resources/obfs4_state.md)
- [tor_obfs4_bridge_line (data source)](docs/data-sources/obfs4_bridge_line.md)

## Requirements

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

## Versioning

This provider follows [Semantic Versioning 2.0.0](https://semver.org/). See [CHANGELOG.md](CHANGELOG.md) for release history.

## Maintenance

This provider is actively maintained by [Guardian Project](https://guardianproject.info).

### Issues

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

### Security

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

## Contributing

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

## References

- [lyrebird](https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/lyrebird) - the obfs4 Go implementation used by this provider
- [Tor Bridge Operations](https://community.torproject.org/relay/setup/bridge/) - Setting up Tor bridges
- [obfs4 Protocol Specification](https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/lyrebird/-/blob/main/doc/obfs4-spec.txt)

## 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](LICENSE) file for details.

[repo]: https://guardianproject.dev/ops/terraform-provider-tor
[ci]: https://guardianproject.dev/ops/terraform-provider-tor/actions
[ci]: https://guardianproject.dev/ops/terraform-provider-tor/actions
[ci-badge]:  https://guardianproject.dev/ops/terraform-provider-tor/badges/workflows/ci/badge.svg
[issues]: https://guardianproject.dev/ops/terraform-provider-tor/issues
[sec]: