{"id":49787891,"url":"https://github.com/hexian000/tlswrapper","last_synced_at":"2026-05-12T02:01:35.956Z","repository":{"id":57636376,"uuid":"420576004","full_name":"hexian000/tlswrapper","owner":"hexian000","description":"Wrap your TCP-based service with multiplexing mTLS tunnels.","archived":false,"fork":false,"pushed_at":"2026-05-09T17:05:29.000Z","size":772,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-05-09T19:10:23.374Z","etag":null,"topics":["go","multiplexer","port-forwarding","tls"],"latest_commit_sha":null,"homepage":"","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/hexian000.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":"2021-10-24T03:17:31.000Z","updated_at":"2026-05-09T17:05:34.000Z","dependencies_parsed_at":"2023-12-02T08:26:05.668Z","dependency_job_id":"ed8618a2-fc4f-4a54-9861-b9f057e3592a","html_url":"https://github.com/hexian000/tlswrapper","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/hexian000/tlswrapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexian000%2Ftlswrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexian000%2Ftlswrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexian000%2Ftlswrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexian000%2Ftlswrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hexian000","download_url":"https://codeload.github.com/hexian000/tlswrapper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexian000%2Ftlswrapper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32920398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-11T17:09:15.040Z","status":"online","status_checked_at":"2026-05-12T02:00:06.338Z","response_time":102,"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":["go","multiplexer","port-forwarding","tls"],"created_at":"2026-05-12T02:01:33.643Z","updated_at":"2026-05-12T02:01:35.936Z","avatar_url":"https://github.com/hexian000.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tlswrapper\n\n[![MIT License](https://img.shields.io/github/license/hexian000/tlswrapper)](https://github.com/hexian000/tlswrapper/blob/master/LICENSE)\n[![Build](https://github.com/hexian000/tlswrapper/actions/workflows/build.yaml/badge.svg)](https://github.com/hexian000/tlswrapper/actions/workflows/build.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/hexian000/tlswrapper/v4)](https://goreportcard.com/report/github.com/hexian000/tlswrapper/v4)\n[![Downloads](https://img.shields.io/github/downloads/hexian000/tlswrapper/total.svg)](https://github.com/hexian000/tlswrapper/releases)\n[![Release](https://img.shields.io/github/release/hexian000/tlswrapper.svg?style=flat)](https://github.com/hexian000/tlswrapper/releases)\n\nWrap TCP-based services with multiplexed mutual TLS tunnels.\n\n- [Features](#features)\n- [Protocol Stack](#protocol-stack)\n- [Authentication Model](#authentication-model)\n- [Quick Start](#quick-start)\n  - [Generating Key Pairs](#generating-key-pairs)\n  - [Creating Config Files](#creating-config-files)\n  - [Starting](#starting)\n- [Building or Installing from Source](#building-or-installing-from-source)\n- [Credits](#credits)\n\n## Features\n\n- **Multiplexed**: Multiple TCP streams share a single long-lived transport connection.\n- **Bidirectional Forwarding**: Each peer can expose local services and reach remote services over the same underlying connection.\n- **mTLS 1.3 Security**: Protect traffic with [mutual authenticated TLS](https://en.wikipedia.org/wiki/Mutual_authentication#mTLS), or run in plaintext on trusted links.\n- **Built-in Certificate Tool**: Generate RSA, ECDSA, or Ed25519 key pairs, either self-signed or signed by an existing key pair.\n- **Certificate Allowlist**: Authorize exact peer certificates or any certificates signed by an authorized issuer. System CAs are never consulted.\n- **Named Peer Routing**: Map peer identities to config-driven mux dial targets and local listen addresses.\n- **Automatic Recovery**: Config-driven tunnels can redial mux_connect targets with backoff on disconnect.\n- **Hot Reloading**: Apply updated configuration at runtime via SIGHUP or the HTTP management API without restarting the process.\n- **Tunable Limits**: Configure keepalive, timeouts, flow-control windows, session and stream limits, backlog, and connection throttling.\n- **Observability**: Expose health checks, human-readable stats, Prometheus metrics, and recent events through the optional HTTP management API.\n- **systemd Integration**: Sends sd_notify Ready, Reloading, and Stopping state notifications when managed by systemd.\n\nAt runtime, tlswrapper maintains two tunnel lifecycles: config-driven tunnels loaded from configuration, and inbound ephemeral tunnels created for accepted mux connections. The latter are removed as soon as the underlying mux connection closes.\n\n```\n       Trusted      |     Untrusted    |     Trusted\n+--------+    +------------+    +------------+    +--------+\n| Client |-n-\u003e|            |    |            |-n-\u003e| Server |\n+--------+    |            |    |            |    +--------+\n              | tlswrapper |-1-\u003e| tlswrapper |\n+--------+    |            |    |            |    +--------+\n| Server |\u003c-n-|            |    |            |\u003c-n-| Client |\n+--------+    +------------+    +------------+    +--------+\n```\n\n## Protocol Stack\n\n```\n+-------------------------------+\n|          TCP streams          |\n+-------------------------------+\n|   gRPC / HTTP/2 multiplexing  |\n+-------------------------------+\n|   mutual TLS 1.3 (optional)   |\n+-------------------------------+\n|  TCP/IP (untrusted network)   |\n+-------------------------------+\n```\n\n## Authentication Model\n\nWhen TLS is enabled, tlswrapper uses mutual TLS: each peer presents an X.509 certificate and proves possession of the corresponding PKCS #8 private key during the handshake.\n\nTrust is configured through `authcerts`. Each entry can be either:\n\n- A specific peer certificate, for direct certificate pinning.\n- A signing certificate, to trust any peer certificate issued by that signer.\n\nThe TLS handshake and certificate verification are delegated to Go's [crypto/tls](https://pkg.go.dev/crypto/tls) implementation. A connection is accepted only if the remote certificate chain validates against the local `authcerts` pool.\n\nIf the `tls` section is omitted, tlswrapper runs in plaintext mode and does not provide certificate-based peer authentication. Use that mode only on links you already trust.\n\n## Quick Start\n\n### Generating Key Pairs\n\n```sh\n# generate self-signed certificates (default: RSA-4096)\n./tlswrapper -gencerts client,server\n# client-cert.pem, client-key.pem, server-cert.pem, server-key.pem\n\n# set the SNI value embedded in the certificate subject/SAN\n./tlswrapper -gencerts server -sni example.com\n\n# generate a self-signed CA key pair\n./tlswrapper -gencerts ca -sni ca.example.com\n# ca-cert.pem, ca-key.pem\n\n# sign a peer certificate with that CA key pair\n./tlswrapper -gencerts peer -sign ca\n```\n\n`-keytype` accepts `rsa` (default), `ecdsa`, or `ed25519`. `-keysize` sets the key size (RSA: bits, ECDSA: 224/256/384/521); `0` selects a safe default for the chosen type.\n\nAdding `ca-cert.pem` to `\"authcerts\"` allows peer certificates signed by that CA.\n\n### Creating Config Files\n\n**Connection Graph**\n\n`http client -\u003e tlswrapper client -\u003e tlswrapper server -\u003e http server`\n\n**server.json**\n\n```json\n{\n    \"mux_listen\": \"0.0.0.0:38000\",\n    \"connect\": \"127.0.0.1:80\",\n    \"tls\": {\n        \"cert\": \"@server-cert.pem\",\n        \"key\": \"@server-key.pem\",\n        \"authcerts\": [\n            \"@client-cert.pem\"\n        ]\n    },\n    \"identity\": {\n        \"claim\": \"server\"\n    }\n}\n```\n\n**client.json**\n\n```json\n{\n    \"tls\": {\n        \"cert\": \"@client-cert.pem\",\n        \"key\": \"@client-key.pem\",\n        \"authcerts\": [\n            \"@server-cert.pem\"\n        ]\n    },\n    \"identity\": {\n        \"claim\": \"client\",\n        \"mux_connect\": [\n            \"example.com:38000\"\n        ],\n        \"listen\": {\n            \"server\": \"127.0.0.1:8080\"\n        }\n    }\n}\n```\n\nFor complex cases, see the [full example](https://github.com/hexian000/tlswrapper/wiki/Configuration-Example).\n\nFor field descriptions, defaults, and the complete configuration format, see [schema.json](v4/config/schema.json).\n\n### Starting\n\n```sh\n./tlswrapper -c server.json\n\n./tlswrapper -c client.json\n```\n\n## Building or Installing from Source\n\n```sh\n# clone the source code\ngit clone https://github.com/hexian000/tlswrapper.git\ncd tlswrapper\n# build a debug binary\n./m.sh d\n\n# or install the latest development version\ngo install github.com/hexian000/tlswrapper/v4/cmd/tlswrapper@master\n```\n\n## Credits\n\n- [go](https://github.com/golang/go)\n- [gosnippets](https://github.com/hexian000/gosnippets)\n- [Prometheus client_golang](https://github.com/prometheus/client_golang)\n- [grpc-go](https://github.com/grpc/grpc-go)\n- [protobuf-go](https://github.com/protocolbuffers/protobuf-go)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexian000%2Ftlswrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhexian000%2Ftlswrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexian000%2Ftlswrapper/lists"}