mqtunnel

README

mqtunnel: tunnel via MQTT broker

This tool tunnels TCP Connection through the MQTT Broker.

In other words, poor-man's AWS IoT Secure tunnel.

Note: This tool is under construction. Please do not use this yet.

How to use

1. Prepare config file with MQTT broker connection endpoint. control means a topic name which is used for sending control packet. The topics used for a tunnel will be created at the same level as this control topic. Therefore, wildcard permission of at least + for this level is required.

{
    "host": "localhost",
    "port": 1883,
    "control": "device/1/control"
}

1. Run on remote host mqtunnel -c config.json
2. Run on local host mqtunnel -c config.json -l 2022 -r 22 with same config.json.
   • -l : local port
   • -r : remote port
3. Enjoy!

Config file

We can use certs in Config file.

{
    "host": "A11222333.iot.ap-northeast-1.amazonaws.com",
    "port": 8883,
    "caCert": "certs/root-CA.crt",
    "clientCert": "certs/5a880e326f-certificate.pem.crt",
    "privateKey": "certs/5a880e326f-private.pem.key",
    "control": "device/1/control"
}

Important Notice: Security

This tool itself has no security. If encryption is required, use ssh or similar.

Also, please note that although the topics used add random strings, they can be easily sniffed by others who are authorized to read wildcards.

Architecture

Example: Local port = 2022, Remote port = 22,

sequenceDiagram

LocalTCP ->> LocalMQTunnel: conn read from port 2022
LocalMQTunnel ->> MQTTBroker: Publish to local port topic '/2022'
MQTTBroker ->> RemoteMQTunnel: Recieve from local port topic '/2022'
RemoteMQTunnel ->> RemoteTCP: conn write to port 22
RemoteTCP ->> RemoteMQTunnel: conn read from port 22
RemoteMQTunnel ->> MQTTBroker: Publish to local port topic '/22'
MQTTBroker ->> LocalMQTunnel: Recieve from local port topic '/22'
LocalMQTunnel ->> LocalTCP: conn write to port 2022

More internal architecture

sequenceDiagram

participant Remote
participant RemoteTCP
participant RemoteTCPConnection
participant RemoteMQTunnel

RemoteMQTunnel ->> RemoteMQTunnel: subscribe control topic
LocalMQTunnel ->> LocalMQTunnel: make a Tunnel instance which includes local/remote port pair
LocalMQTunnel ->> LocalTCP: NewTCPConnection()
LocalTCP ->> LocalTCP: start listening
Local ->> LocalTCP: connect
LocalTCP ->> LocalMQTunnel: OpenTunnel()
LocalMQTunnel ->> RemoteMQTunnel: Publish control packet
RemoteMQTunnel ->> RemoteTCPConnection: NewTCPConnection()
RemoteTCPConnection ->> RemoteTCP: connect()
RemoteTCP ->> Remote: connect()

License

• Apache License

Documentation

Index

• func NewMQTTBroker(conf Config, controlCh chan controlPacket) (*mqttBroker, error)
• type Config
  • func ReadConfig(filePath string) (Config, error)
• type MQTunnel
  • func NewMQTunnel(conf Config) (*MQTunnel, error)
  • func (mqt *MQTunnel) Start(ctx context.Context, localPort, remotePort int) error
• type TCPConnection
  • func NewTCPConnection(port int, tun *Tunnel) (*TCPConnection, error)
• type TCPListener
  • func NewTCPListener(conf Config, port int) (*TCPListener, error)
• type Tunnel
  • func NewTunnelFromConnect(ctx context.Context, mqttBroker *mqttBroker, conn net.Conn, topicRoot string, ...) (*Tunnel, error)
  • func NewTunnelFromControl(ctx context.Context, mqttBroker *mqttBroker, ctl controlPacket) (*Tunnel, error)

Functions

func NewMQTTBroker

func NewMQTTBroker(conf Config, controlCh chan controlPacket) (*mqttBroker, error)

Types

type Config

type Config struct {
	Host     string `json:"host"`
	Port     int    `json:"port"`
	UserName string `json:"username"`
	Password string `json:"password"`
	ClientID string `json:"clientId"`

	CaCert     string `json:"caCert"`
	ClientCert string `json:"clientCert"`
	PrivateKey string `json:"privateKey"`

	Control string `json:"control"`
}

func ReadConfig

func ReadConfig(filePath string) (Config, error)

type MQTunnel

type MQTunnel struct {
	// contains filtered or unexported fields
}

MQTunnel is a main component of mqtunnel.

func NewMQTunnel

func NewMQTunnel(conf Config) (*MQTunnel, error)

func (*MQTunnel) Start

func (mqt *MQTunnel) Start(ctx context.Context, localPort, remotePort int) error

Start starts a MQTT tunnel.

type TCPConnection

type TCPConnection struct {
	// contains filtered or unexported fields
}

func NewTCPConnection

func NewTCPConnection(port int, tun *Tunnel) (*TCPConnection, error)

type TCPListener

type TCPListener struct {
	// contains filtered or unexported fields
}

func NewTCPListener

func NewTCPListener(conf Config, port int) (*TCPListener, error)

type Tunnel

type Tunnel struct {
	ID          string
	LocalPort   int
	LocalTopic  string
	RemotePort  int
	RemoteTopic string
	// contains filtered or unexported fields
}

func NewTunnelFromConnect

func NewTunnelFromConnect(ctx context.Context, mqttBroker *mqttBroker, conn net.Conn, topicRoot string, local, remote int) (*Tunnel, error)

NewTunnelFromConnect creates a new Tunnel on local

func NewTunnelFromControl

func NewTunnelFromControl(ctx context.Context, mqttBroker *mqttBroker, ctl controlPacket) (*Tunnel, error)

NewTunnelFromControl creates a new Tunnel on remote side.