README
¶
Portal
A Go implementation of HTTP tunneling through a tunnel
Overview
The main goal of this project is to provide access from cloud to on-prem without opening ports on-prem. This library provides a mechanism to build a 2-node HTTP tunnel.
The tunnel has two sides: client and server. An on-prem application running tunnel client will connect to tunnel server running in cloud. Proxy port can be opened on cloud side to allow access to on-prem via HTTP tunnelling: https://en.wikipedia.org/wiki/HTTP_tunnel
This library only supports HTTPS tunneling that uses HTTP CONNECT to initiate connection.
Install
go get github.com/oatcode/portal
Usage
Wrap the tunnel connection with Framer interface and use TunnelServe:
coch := make(chan portal.ConnectOperation)
portal.TunnelServe(ctx, framer, coch)
Framer interface is for reading and writing messages with boundaries (i.e. frame). The examples show a simple length/bytes and WebSocket framer.
coch is the channel to handle incoming proxy connection. Fill the ConnectOperation struct with net.Conn and proxy connect address. The examples illustrate how this is done with Go's http Hijack function.
Examples
Included in the projects are example code to establish the tunnel and make HTTPS connection through it.
+---------+
| Cloud |
| Client |
+----+----+
|
|
+-------v-------+
| Proxy Server |
+---------------+
| Tunnel Server |
+-----+---^-----+
Internet | |
------------------+---+--------------------
On-prem | |
+-----v---+-----+
| |
| Tunnel Client |
| |
+-------+-------+
|
|
+----v----+
| On-prem |
| Server |
+---------+
To run the examples locally, create certificates for tunnel and https server:
openssl req -x509 -nodes -newkey rsa:2048 -sha256 -keyout tunnel-server.key -out tunnel-server.crt -subj "/C=US/CN=tunnel-server" -extensions SAN -config <(cat /etc/ssl/openssl.cnf <(printf "\n[SAN]\nsubjectAltName=DNS:localhost\n"))
openssl req -x509 -nodes -newkey rsa:2048 -sha256 -keyout tunnel-client.key -out tunnel-client.crt -subj "/C=US/CN=tunnel-client" -extensions SAN -config <(cat /etc/ssl/openssl.cnf <(printf "\n[SAN]\nsubjectAltName=DNS:localhost\n"))
openssl req -x509 -nodes -newkey rsa:2048 -sha256 -keyout https-server.key -out https-server.crt -subj "/C=US/CN=https-server" -extensions SAN -config <(cat /etc/ssl/openssl.cnf <(printf "\n[SAN]\nsubjectAltName=DNS:localhost\n"))
Simple tunnel example
The example runs tunnel on port 10001 and proxy on port 10002:
simple-tunnel -server -tunnelAddress :10001 -proxyAddress :10002
simple-tunnel -client -tunnelAddress localhost:10001
Run sample HTTPS server on port 10003 and client via proxy port 10002:
sample-https-server -address :10003 -cert https-server.crt -key https-server.key
sample-https-client --proxy http://localhost:10002 -url https://localhost:10003/test -trust https-server.crt
Websocket tunnel example
The example runs both websocket tunnel and proxy on port 10001. In addition, tunnel and proxy are protected by TLS and user/password:
ws-tunnel -server -address :10001 -proxyUsername user1 -proxyPassword pw1 -tunnelUsername tunnel1 -tunnelPassword pw1 -cert tunnel-server.crt -key tunnel-server.key
ws-tunnel -client -address localhost:10001 -tunnelUsername tunnel1 -tunnelPassword pw1 -trust tunnel-server.crt
Run sample HTTPS server on port 10003 and client via proxy port 10001:
sample-https-server -address :10003 -cert https-server.crt -key https-server.key
sample-https-client --proxy https://user1:pw1@localhost:10001 -url https://localhost:10003/test -trust https-server.crt -trust tunnel-server.crt
Other ways to set proxy
The sample-https-client sets proxy programmatically. But it can be set in other ways. For example:
- export https_proxy=[proxy-host]:[proxy-port]
- java -Dhttps.proxyHost=[proxy-host] -Dhttps.proxyPort=[proxy-port]
Documentation
¶
Overview ¶
Package portal provides the ability to build a 2-node HTTP tunnel
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // Logf is for setting logging function Logf func(string, ...interface{}) )
Functions ¶
func TunnelServe ¶
func TunnelServe(ctx context.Context, c Framer, coch <-chan ConnectOperation)
TunnelServe starts the communication with the remote side with tunnel messages connection c. It handles new proxy connections coming into connection channel cch.
Types ¶
type ConnectOperation ¶ added in v0.1.5
type ConnectOperation struct {
// Hijacked HTTP connection for CONNECT method
// or a connection with HTTP CONNECT processed
Conn net.Conn
// Address section from the HTTP CONNECT line
Address string
}
ConnectOperation is for handling HTTP CONNECT request
type Framer ¶ added in v0.1.5
type Framer interface {
// Read reads a message from the connection
// The returned byte array is of the exact length of the message
Read() (b []byte, err error)
// Write writes the entire byte array as a message to the connection
Write(b []byte) error
// Close closes the connection
// Error maybe used by the underlying connection protocol
Close(err error) error
}
Framer is for reading and writing messages with boundaries (i.e. frame)
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
sample-https-client
command
|
|
|
sample-https-server
command
|
|
|
simple-tunnel
command
|
|
|
ws-tunnel
command
|
|
|
pkg
|
|