{"id":31771454,"url":"https://github.com/fxpool/fxeccsocket","last_synced_at":"2025-10-10T03:29:00.337Z","repository":{"id":316602239,"uuid":"1064043327","full_name":"FxPool/fxeccsocket","owner":"FxPool","description":"A Go library providing encrypted TCP connections using Elliptic Curve Cryptography (ECC) for key exchange and ChaCha20-Poly1305 for symmetric encryption.","archived":false,"fork":false,"pushed_at":"2025-10-03T10:07:16.000Z","size":63,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T11:41:18.959Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FxPool.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-25T13:13:09.000Z","updated_at":"2025-10-03T10:07:19.000Z","dependencies_parsed_at":"2025-09-25T16:07:33.246Z","dependency_job_id":"9c7e7927-acd8-4c26-b1d2-6ed683dc55a6","html_url":"https://github.com/FxPool/fxeccsocket","commit_stats":null,"previous_names":["fxpool/fxeccsocket"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/FxPool/fxeccsocket","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FxPool%2Ffxeccsocket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FxPool%2Ffxeccsocket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FxPool%2Ffxeccsocket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FxPool%2Ffxeccsocket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FxPool","download_url":"https://codeload.github.com/FxPool/fxeccsocket/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FxPool%2Ffxeccsocket/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002632,"owners_count":26083425,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-10T03:28:57.303Z","updated_at":"2025-10-10T03:29:00.332Z","avatar_url":"https://github.com/FxPool.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ECC Socket - Secure Communication Library using Elliptic Curve Cryptography\n\n[![Go Version](https://img.shields.io/badge/Go-1.24+-blue.svg)](https://golang.org)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\nA secure network communication library for Go that provides end-to-end encrypted communication using Elliptic Curve Cryptography (ECC) with advanced traffic obfuscation capabilities.\n\n## Features\n\n- 🔒 **End-to-End Encryption**: ECDH key exchange with ChaCha20-Poly1305 encryption\n- 🎭 **Traffic Obfuscation**: Multiple obfuscation modes to hide traffic patterns\n- 🚀 **High Performance**: Modern cryptographic algorithms with low latency\n- 🔑 **Flexible Key Management**: Support for both static and ephemeral keys (forward secrecy)\n- 📜 **Standards Compliant**: PEM format for key storage\n- 🛡️ **Security Hardened**: Replay protection, integrity verification\n- 🔧 **Easy to Use**: net-like API design for easy integration\n\n## Installation\n\n```bash\ngo get github.com/fxpool/fxeccsocket\n```\n## Quick Start\n## Generating Key Pairs\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/yourusername/fxeccsocket\"\n)\n\nfunc main() {\n    // Generate new ECC key pair\n    privKey, err := fxeccsocket.GenerateKey(nil)\n    if err != nil {\n        panic(err)\n    }\n    \n    // Encode private key to PEM format\n    privPEM, err := fxeccsocket.EncodePrivateKey(privKey)\n    if err != nil {\n        panic(err)\n    }\n    \n    // Encode public key to PEM format\n    pubPEM, err := fxeccsocket.EncodePublicKey(\u0026privKey.PublicKey)\n    if err != nil {\n        panic(err)\n    }\n    \n    fmt.Println(\"Private Key:\\n\", privPEM)\n    fmt.Println(\"Public Key:\\n\", pubPEM)\n}\n```\n## Basic Example (No Obfuscation)\n```go\npackage main\n\nimport (\n  \"fmt\"\n  \"github.com/FxPool/fxeccsocket\"\n  \"io\"\n  \"log\"\n  \"net\"\n  \"time\"\n)\n\n// Server example\nfunc startServer() {\n  listener, err := fxeccsocket.Listen(\"tcp\", \":8080\", nil)\n  if err != nil {\n    log.Fatal(\"Server listen error:\", err)\n  }\n  defer listener.Close()\n\n  fmt.Println(\"ECC Server listening on :8080\")\n\n  for {\n    conn, err := listener.Accept()\n    if err != nil {\n      log.Println(\"Accept error:\", err)\n      continue\n    }\n\n    go handleServerConnection(conn)\n  }\n}\n\nfunc handleServerConnection(conn net.Conn) {\n  defer conn.Close()\n  fmt.Printf(\"New connection from %s\\n\", conn.RemoteAddr())\n\n  buffer := make([]byte, 1024)\n  for {\n    n, err := conn.Read(buffer)\n    if err != nil {\n      if err != io.EOF {\n        log.Println(\"server Read error:\", err)\n      }\n      break\n    }\n\n    message := string(buffer[:n])\n    fmt.Printf(\"Received: %s\", message)\n\n    response := fmt.Sprintf(\"Server response: %s\", message)\n    _, err = conn.Write([]byte(response))\n    if err != nil {\n      log.Println(\"Write error:\", err)\n      break\n    }\n  }\n}\n\n// Client example\nfunc startClient() {\n  time.Sleep(100 * time.Millisecond) // Wait for server to start\n\n  conn, err := fxeccsocket.Dial(\"tcp\", \"localhost:8080\", nil)\n  if err != nil {\n    log.Fatal(\"Client dial error:\", err)\n  }\n  defer conn.Close()\n\n  fmt.Printf(\"Connected to %s\\n\", conn.RemoteAddr())\n\n  // Send multiple messages for testing\n  messages := []string{\n    \"Hello, ECC Socket 1!\\n\",\n    \"This is message 2\\n\",\n    \"Final message 3\\n\",\n  }\n\n  for _, msg := range messages {\n    fmt.Printf(\"Sending: %s\", msg)\n    _, err = conn.Write([]byte(msg))\n    if err != nil {\n      log.Fatal(\"Write error:\", err)\n    }\n\n    buffer := make([]byte, 1024)\n    n, err := conn.Read(buffer)\n    if err != nil {\n      log.Fatal(\"client Read error:\", err)\n    }\n\n    fmt.Printf(\"Server reply: %s\", string(buffer[:n]))\n    time.Sleep(100 * time.Millisecond)\n  }\n}\n\nfunc main() {\n\t\n  // Start the server\n  go startServer()\n  time.Sleep(1 * time.Second)\n\n  // Start the client\n  startClient()\n}\n```\n## Advanced Example (With Traffic Obfuscation)\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/FxPool/fxeccsocket\"\n    \"log\"\n    \"time\"\n)\n\nfunc main() {\n    // Obfuscation configuration for both client and server\n    obfuscationConfig := \u0026fxeccsocket.ObfuscationConfig{\n        Enabled:    true,\n        Mode:       fxeccsocket.ObfuscationHTTPS,\n        Domain:     \"api.cloudflare.com\",\n        MinDelayMs: 5,\n        MaxDelayMs: 50,\n        MinPacketSize: 128,\n        MaxPacketSize: 1460,\n    }\n\n    serverConfig := \u0026fxeccsocket.Config{\n        Curve:       elliptic.P256(),\n        Obfuscation: obfuscationConfig,\n    }\n\n    clientConfig := \u0026fxeccsocket.Config{\n        Curve:       elliptic.P256(),\n        Obfuscation: obfuscationConfig,\n    }\n\n    // Start obfuscated server\n    go func() {\n        listener, err := fxeccsocket.Listen(\"tcp\", \":8081\", serverConfig)\n        if err != nil {\n            log.Fatal(\"Server listen error:\", err)\n        }\n        defer listener.Close()\n\n        fmt.Println(\"Obfuscated ECC Server listening on :8081\")\n\n        conn, err := listener.Accept()\n        if err != nil {\n            log.Fatal(\"Accept error:\", err)\n        }\n        defer conn.Close()\n\n        // Handle connection...\n    }()\n\n    time.Sleep(1 * time.Second)\n\n    // Connect with obfuscated client\n    conn, err := fxeccsocket.Dial(\"tcp\", \"localhost:8081\", clientConfig)\n    if err != nil {\n        log.Fatal(\"Client dial error:\", err)\n    }\n    defer conn.Close()\n\n    fmt.Println(\"Connected with traffic obfuscation enabled\")\n}\n```\n## Traffic Obfuscation\n### Obfuscation Modes\nThe library provides multiple traffic obfuscation modes to hide encryption patterns:\n1. HTTP Obfuscation\n- Masks traffic as standard HTTP requests/responses\n- Uses proper HTTP headers and chunked encoding\n- Simulates real web traffic patterns\n2. HTTPS Obfuscation\n- Similar to HTTP but with TLS-like characteristics\n- More convincing for environments expecting encrypted web traffic\n- Uses realistic domain names and user agents\n3. Random Padding Obfuscation\n- Adds random padding to disrupt packet size analysis\n- Randomizes packet timing with configurable delays\n- Makes traffic analysis more difficult\n## Obfuscation Configuration\n```go\ntype ObfuscationConfig struct {\n    Enabled       bool            // Enable/disable obfuscation\n    Mode          ObfuscationMode // Obfuscation mode (HTTP/HTTPS/Random)\n    Domain        string          // Domain for HTTP/HTTPS obfuscation\n    MinDelayMs    int             // Minimum delay between packets (ms)\n    MaxDelayMs    int             // Maximum delay between packets (ms)\n    MinPacketSize int             // Minimum packet size for padding\n    MaxPacketSize int             // Maximum packet size for padding\n}\n```\n## Usage Notes\n- Symmetric Configuration: Client and server must use identical obfuscation settings\n- Performance: Obfuscation adds minimal overhead (5-15% depending on mode)\n- Stealth: Effectively hides traffic from deep packet inspection (DPI) systems\n\n# API Documentation\n## Types\n## ECCConn\n## Encrypted connection type implementing net.Conn interface.\n\n```go\ntype ECCConn struct {\n    // unexported fields\n}\n```\n### Methods:\n- Read([]byte) (int, error) - Read and decrypt data\n- Write([]byte) (int, error) - Encrypt and write data\n- Close() error - Close the connection\n- GetPublicKey() *ecdsa.PublicKey - Get local public key\n- Standard net.Conn methods: LocalAddr(), RemoteAddr(), SetDeadline(), etc.\n### ECCListener\n### Encrypted connection listener.\n```go\ntype ECCListener struct {\n    // unexported fields\n}\n```\n### Methods:\n- `Accept() (net.Conn, error)` - Accept new connection\n- `Close() error` - Close listener\n- `Addr() net.Addr` - Get listen address\n\n### Config\n### Configuration parameters structure.\n```go\ntype Config struct {\n    Curve           elliptic.Curve      // Elliptic curve (default P-256)\n    PrivateKey      *ecdsa.PrivateKey   // Private key (optional)\n    PublicKey       *ecdsa.PublicKey    // Public key (optional)\n    UseEphemeralKey bool               // Use ephemeral keys (forward secrecy)\n    Obfuscation     *ObfuscationConfig  // Traffic obfuscation settings\n}\n```\n#### ObfuscationConfig\n#### Traffic obfuscation configuration.\n```go\ntype ObfuscationConfig struct {\n    Enabled       bool            // Enable traffic obfuscation\n    Mode          ObfuscationMode // Obfuscation mode\n    Domain        string          // Domain for HTTP/HTTPS obfuscation\n    MinDelayMs    int             // Minimum packet delay (milliseconds)\n    MaxDelayMs    int             // Maximum packet delay (milliseconds)\n    MinPacketSize int             // Minimum packet size\n    MaxPacketSize int             // Maximum packet size\n}\n```\n#### Obfuscation Modes\n```go\nconst (\n    ObfuscationNone    ObfuscationMode = iota // No obfuscation\n    ObfuscationHTTP                           // HTTP traffic obfuscation\n    ObfuscationHTTPS                          // HTTPS traffic obfuscation  \n    ObfuscationRandom                         // Random padding obfuscation\n)\n```\n### Functions\n### Key Management\n\n```go\nfunc GenerateKey(curve elliptic.Curve) (*ecdsa.PrivateKey, error)\nfunc EncodePrivateKey(key *ecdsa.PrivateKey) (string, error)\nfunc DecodePrivateKey(pemData string) (*ecdsa.PrivateKey, error)\nfunc EncodePublicKey(key *ecdsa.PublicKey) (string, error)\nfunc DecodePublicKey(pemData string) (*ecdsa.PublicKey, error)\n```\n### Connection Management\n```go\nfunc Dial(network, address string, config *Config) (*ECCConn, error)\nfunc Listen(network, address string, config *Config) (*ECCListener, error)\nfunc NewConn(conn net.Conn, config *Config, isClient bool) (*ECCConn, error)\n```\n## Protocol Details\n## Handshake Protocol\n1. Key Exchange: ECDH Elliptic Curve Diffie-Hellman key exchange\n2. Key Derivation: HKDF for symmetric key derivation from shared secret\n3. Bidirectional Authentication: Different key contexts for client and server\n4. Traffic Obfuscation: Optional masking of encrypted traffic\n\n### Message Format\n### Public Key Message\n\n```\n+------+--------+------------+\n| 0x01 | Length | Public Key |\n+------+--------+------------+\n| 1B   | 2B     | Variable   |\n+------+--------+------------+\n```\n\n### Encrypted Data Message\n\n```\n+------+-----------+----------------+\n| 0x02 | Length    | Encrypted Data |\n+------+-----------+----------------+\n| 1B   | 4B        | Variable       |\n+------+-----------+----------------+\n```\n\n## Obfuscated Message Format\n### HTTP Obfuscation Format\n```text\nHTTP Headers + Chunked Encoding + Encrypted Data\n```\n\n## Random Padding Format\n```text\nEncrypted Data + Random Padding (variable length)\n```\n\n## Key Derivation\n\n```\nclient_send_key = HKDF(shared_secret, salt, \"client_key\")\nserver_send_key = HKDF(shared_secret, salt, \"server_key\")\n```\n\n### Security Considerations\n### Recommended Configuration\n```go\n// For optimal security, recommended to use:\nconfig := \u0026fxeccsocket.Config{\n    Curve: elliptic.P256(),    // Or more secure curves\n    UseEphemeralKey: true,     // Enable forward secrecy\n    Obfuscation: \u0026fxeccsocket.ObfuscationConfig{\n    Enabled:    true,\n    Mode:       fxeccsocket.ObfuscationHTTPS,\n    Domain:     \"cdn.google.com\",\n    MinDelayMs: 10,\n    MaxDelayMs: 100,\n    },\n}\n```\n\n### Security Features\n- Forward Secrecy: When UseEphemeralKey is enabled, each connection uses different ephemeral keys\n- Replay Protection: Incrementing counter-based nonce prevents replay attacks\n- Integrity Verification: Poly1305 authentication tags ensure data integrity\n- Key Separation: Different encryption keys for client and server directions\n- Traffic Obfuscation: Hides encryption patterns from network analysis\n\n### Obfuscation Security Benefits\n- Pattern Hiding: Disrupts packet size and timing analysis\n- Protocol Mimicry: Appears as legitimate web traffic to DPI systems\n- Plausible Deniability: Traffic resembles common internet protocols\n\n### Performance Considerations\n- Uses ChaCha20-Poly1305 instead of AES-GCM for better performance on devices without AES hardware acceleration\n- Single connection throughput can reach Gbps levels\n- Low memory footprint, suitable for high-concurrency scenarios\n- Low memory footprint, suitable for high-concurrency scenarios\n\n### Obfuscation Performance Impact\n- HTTP/HTTPS Mode: ~10-15% overhead due to header processing\n- Random Padding: ~5-10% overhead depending on padding size\n- Network Delays: Configurable delays add latency but improve stealth\n\n### Limitations\n- Maximum message size: 64KB (configurable via maxMessageSize constant)\n- Currently only supports TCP protocol\n- Requires Go 1.16+ version\n- Obfuscation requires symmetric client/server configuration\n\n### Troubleshooting\n### Common Errors\n\n1. \"unexpected message type\"\n\n- - Check client and server version compatibility\n- - Verify network connection isn't being interfered with\n- - Check network connection isn't being interfered with\n\n2. \"public key too large\"\n\n- - Check if the elliptic curve used is reasonable\n- - Verify public key serialization is correct\n\n3. Authentication failures\n\n- - Check system clock synchronization\n- - Verify keys are loaded correctly\n\n4. Obfuscation mismatches\n\n- - Ensure client and server use identical ObfuscationConfig\n- - Verify Enabled flag and Mode are the same on both ends\n\n### Debug Mode\nAdd verbose logging to debug handshake process.\n\n### Benchmarks\nBasic performance metrics (on Intel i7-8700K):\n\n```\nEncryption throughput: ~800 Mbps\nHandshake time: ~2.5 ms\nMemory per connection: ~4 KB\nObfuscation overhead: 5-15% (depending on mode)\n```\n\n### Examples Directory\n- Check the `examples/` directory for additional usage examples\n- Check the `test/` directory for additional usage examples\n\n### Contributing\nWe welcome contributions! Please see our Contributing Guide for details.\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a Pull Request\n\n### Development Setup\n```base\ngit clone https://github.com/fxpool/fxeccsocket.git\ncd fxeccsocket\ngo test ./...\n```\n### Running Tests\n```base\ngo test -v -race ./...\n```\n\n### License\nThis project is open source under the MIT License - see the LICENSE file for details.\n\n### Acknowledgments\n- Uses Go standard library cryptographic primitives\n- Designed based on modern cryptographic best practices\n- Traffic obfuscation techniques inspired by modern anti-censorship tools\n- Thanks to all contributors\n\n### Support\n- If you encounter issues or have questions:\n- Check existing issues\n- Create a new issue with detailed description\n- Contact maintainers\n\n### Related Projects\n- libsodium - Portable cryptography library\n- Noise Protocol - Framework for crypto protocols\n- WireGuard - Modern VPN protocol\n- obfs4 - Pluggable transport for Tor\n\n### References\n- Elliptic Curve Cryptography\n- ChaCha20 and Poly1305\n- HKDF (HMAC-based Key Derivation Function)\n- Traffic Analysis Resistance\n- Pluggable Transports\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffxpool%2Ffxeccsocket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffxpool%2Ffxeccsocket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffxpool%2Ffxeccsocket/lists"}