tlswrapper

Wrap any TCP-based service with multiplexed mutual TLS tunnels.

Status: Stable

Features
Protocol Stack
Authentication Model
Quick Start
Building/Installing from Source
Credits

Features

Multiplexed: All traffic goes over one TCP connection.
Mutual Forwarded: Each peer can listen from and connect to the other peer simultaneously over the same underlying connection.
Secured: All traffic is optionally protected by mutual authenticated TLS.
Incompatible: Always enforce the latest TLS version.

In terms of performance, creating multiplexed TCP tunnels is generally not a good idea, see Head-of-line blocking. Make sure you have a good reason to do so.

       Trusted      |     Untrusted    |     Trusted
+--------+    +------------+    +------------+    +--------+
| Client |-n->|            |    |            |-n->| Server |
+--------+    |            |    |            |    +--------+
              | tlswrapper |-1->| tlswrapper |
+--------+    |            |    |            |    +--------+
| Server |<-n-|            |    |            |<-n-| Client |
+--------+    +------------+    +------------+    +--------+

Protocol Stack

+-------------------------------+
|          TCP traffic          |
+-------------------------------+
|   yamux stream multiplexing   |
+-------------------------------+
|   mutual TLS 1.3 (optional)   |
+-------------------------------+
|  TCP/IP (untrusted network)   |
+-------------------------------+

Authentication Model

Like SSH, each peer should have a key pair (X.509 certificate + PKCS #8 private key) and an authorized list. Only certificates in the authorized list (or signed by any authorized certificate) can communicate with the peer.

TLS behavior is based on "crypto/tls" library in Go.

Quick Start

Generating Key Pair

# generate self-signed certificates
./tlswrapper -gencerts client,server
# client-cert.pem, client-key.pem, server-cert.pem, server-key.pem

Adding a certificate to "authcerts" will allow all certificates signed by it.

Creating Config Files

Connection Graph

http client -> tlswrapper client -> tlswrapper server -> http server

server.json

{
    "muxlisten": "0.0.0.0:38000",
    "services": {
        "myhttp": "127.0.0.1:80"
    },
    "certs": [
        {
            "cert": "@server-cert.pem",
            "key": "@server-key.pem"
        }
    ],
    "authcerts": [
        "@client-cert.pem"
    ]
}

client.json

{
    "peers": {
        "tlswrapper server": {
            "addr": "example.com:38000",
            "listen": "127.0.0.1:8080",
            "service": "myhttp"
        }
    },
    "certs": [
        {
            "cert": "@client-cert.pem",
            "key": "@client-key.pem"
        }
    ],
    "authcerts": [
        "@server-cert.pem"
    ]
}

For complex cases, see the full example.

Notes

Feel free to add more services/peers, or bring up forwards/reverses between the same instances.

"peername": local peer name
"muxlisten": listener bind address
"services": local service forwards
"services[*]": local service dial address
"peers": named peers to that need to keep connected
"peers[*].addr": dial address
"peers[*].listen": listen for port forwarding
"peers[*].service": the service name we ask the peer for
"certs": local certificates
"certs[*].cert": PEM encoded certificate (use "@filename" to read external file, same below)
"certs[*].key": PEM encoded private key
"authcerts": peer authorized certificates list, bundles are supported
"authcerts[*].cert": PEM encoded certificate

See source code for a complete list of all available options.

See config.json for example config file.

Start

./tlswrapper -c server.json

./tlswrapper -c client.json

Building/Installing from Source

# get source code
git clone https://github.com/hexian000/tlswrapper.git
cd tlswrapper
# build for debug
./m.sh d

# or install the latest development version
go install github.com/hexian000/tlswrapper/v3/cmd/tlswrapper@master

hexian000/tlswrapper