First working version

2025-06-03 13:23:45 +02:00 · 2025-06-03 13:23:45 +02:00 · d8eda81e0e
commit d8eda81e0e
parent 63ed6316bc
31 changed files with 3134 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,142 @@
+# 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]: