142 lines
4.8 KiB
Markdown
142 lines
4.8 KiB
Markdown
# Terraform Provider for Tor Bridges
|
|
|
|
[![][ci-badge]][ci]
|
|
[](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]:
|