tlswrapper

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

Status: Stable

• Features
• Protocol Stack
• Authentication Model
• Quick Start
  • Generating Key Pair
  • Creating Config Files
    • Notes
  • 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

Credits

• go
• gosnippets
• yamux