qsocket

README

QSocket Go

Go library for qsocket...

Documentation

Example

Usage is really simple, qsocket.New() function simply creates a new quantum socket with given secret, it includes all the functions of standard net sockets and also implements io Read/Write. After creating a socket you need to dial the QSRN network by calling Dial* functions. Simple example below...

    qsock := qsocket.New("my-secret", true);  // Create a new QSocket with TLS fingerprint checking...
    qsock.Dial() // Dial using TLS and certificate fingerprint checking...
    // OR
    qsock.DialTCP() // Dial using TCP... 

After dialing the QSRN, socket is ready for read/write operations.

Documentation

Index

• Constants
• Variables
• func BindSockets(con1, con2 *QSocket) error
• func CalcChecksum(data []byte, base byte) byte
• func CreateSocketChan(sock *QSocket) chan []byte
• func GetDefaultTag() byte
• func NewKnockSequence(uuid [16]byte, tag byte) ([]byte, error)
• type QSocket
  • func NewSocket(secret string) *QSocket
  • func (qs *QSocket) AddIdTag(idTag byte) error
  • func (qs *QSocket) Close()
  • func (qs *QSocket) Dial() error
  • func (qs *QSocket) DialProxy(proxyAddr string) error
  • func (qs *QSocket) DialTCP() error
  • func (qs *QSocket) InitClientSRP() ([]byte, error)
  • func (qs *QSocket) InitE2ECipher(key []byte) error
  • func (qs *QSocket) InitServerSRP() ([]byte, error)
  • func (qs *QSocket) IsClient() bool
  • func (qs *QSocket) IsClosed() bool
  • func (qs *QSocket) IsE2E() bool
  • func (qs *QSocket) IsTLS() bool
  • func (qs *QSocket) LocalAddr() net.Addr
  • func (qs *QSocket) Read(b []byte) (int, error)
  • func (qs *QSocket) RemoteAddr() net.Addr
  • func (qs *QSocket) SendKnockSequence() error
  • func (qs *QSocket) SetCertPinning(v bool) error
  • func (qs *QSocket) SetE2E(v bool) error
  • func (qs *QSocket) SetReadDeadline(t time.Time) error
  • func (qs *QSocket) SetWriteDeadline(t time.Time) error
  • func (qs *QSocket) Write(b []byte) (int, error)

Constants

const (
	// QSRN_GATE is the static gate address for the QSocket network.
	QSRN_GATE = "gate.qsocket.io"
	// QSRN_GATE_TLS_PORT Default TLS port for the QSocket gate.
	QSRN_GATE_TLS_PORT = 443
	// QSRN_GATE_PORT Default TCP port for the QSocket gate.
	QSRN_GATE_PORT = 80
	// CERT_FINGERPRINT is the static TLS certificate fingerprint for QSRN_GATE.
	CERT_FINGERPRINT = "32ADEB12BA582C97E157D10699080C1598ECC3793C09D19020EDF51CDC67C145"

	// KNOCK_CHECKSUM_BASE is the constant base value for calculating knock packet checksums.
	KNOCK_CHECKSUM_BASE = 0xEE
	// KNOCK_HEADER_B1 is the first magic byte of the knock packet.
	KNOCK_HEADER_B1 uint = 0xC0
	// KNOCK_HEADER_B2 is the second magic byte of the knock packet.
	KNOCK_HEADER_B2 uint = 0xDE
	// KNOCK_SUCCESS is the knock sequence response code indicating successful connection.
	KNOCK_SUCCESS uint = 0xE0
	// KNOCK_FAIL is the knock sequence response code indicating failed connection.
	KNOCK_FAIL uint = 0xE1
	// KNOCK_BUSY is the knock sequence response code indicating busy connection.
	KNOCK_BUSY uint = 0xE2
)

Some global constants for These values can be changed for obfuscating the knock protocol

const (
	// TAG_ARCH_AMD64 Tag ID value representing connections from devices with AMD64 architecture.
	TAG_ARCH_AMD64 = 0xE0 // 00110000 => AMD64
	// TAG_ARCH_386 Tag ID value representing connections from devices with 386 architecture.
	TAG_ARCH_386 = 0x20 // 00100000 => 386
	// TAG_ARCH_ARM64 Tag ID value representing connections from devices with ARM64 architecture.
	TAG_ARCH_ARM64 = 0x40 // 01000000 => ARM64
	// TAG_ARCH_ARM Tag ID value representing connections from devices with ARM architecture.
	TAG_ARCH_ARM = 0x60 // 01100000 => ARM
	// TAG_ARCH_MIPS64 Tag ID value representing connections from devices with MIPS64 architecture.
	TAG_ARCH_MIPS64 = 0x80 // 10000000 => MIPS64
	// TAG_ARCH_MIPS Tag ID value representing connections from devices with MIPS architecture.
	TAG_ARCH_MIPS = 0xA0 // 10100000 => MIPS
	// TAG_ARCH_MIPS64LE Tag ID value representing connections from devices with MIPS64LE architecture.
	TAG_ARCH_MIPS64LE = 0xC0 // 11000000 => MIPS64LE
	// TAG_ARCH_UNKNOWN Tag ID value representing connections from devices with UNKNOWN architecture.
	TAG_ARCH_UNKNOWN = 0x00 // 11100000 => UNKNOWN

	// TAG_OS_LINUX Tag ID value representing connections from LINUX devices.
	TAG_OS_LINUX = 0x1C // 00000000 => LINUX
	// TAG_OS_DARWIN Tag ID value representing connections from DARWIN devices.
	TAG_OS_DARWIN = 0x04 // 00000100 => DARWIN
	// TAG_OS_WINDOWS Tag ID value representing connections from WINDOWS devices.
	TAG_OS_WINDOWS = 0x08 // 00001000 => WINDOWS
	// TAG_OS_ANDROID Tag ID value representing connections from ANDROID devices.
	TAG_OS_ANDROID = 0x0C // 00001100 => ANDROID
	// TAG_OS_IOS Tag ID value representing connections from IOS devices.
	TAG_OS_IOS = 0x10 // 00010000 => IOS
	// TAG_OS_FREEBSD Tag ID value representing connections from FREEBSD devices.
	TAG_OS_FREEBSD = 0x14 // 00010100 => FREEBSD
	// TAG_OS_OPENBSD Tag ID value representing connections from OPENBSD devices.
	TAG_OS_OPENBSD = 0x18 // 00011000 => MIPS64LE
	// TAG_OS_UNKNOWN Tag ID value representing connections from UNKNOWN devices.
	TAG_OS_UNKNOWN = 0x00 // 00011100 => UNKNOWN

	// TAG_PEER_PROXY Tag ID for representing proxy mode connections.
	TAG_PEER_PROXY = 0x02 // 00000010 => Proxy connection
	// Tag ID for representing server mode connections.
	TAG_PEER_SRV = 0x00 // 00000000 => Server
	// Tag ID for representing client mode connections.
	TAG_PEER_CLI = 0x01 // 00000001 => Client
	// =====================================================================
	SRP_BITS = 4096
)

Knock tags 000 000 0 0 | | | | [ARCH] | |

    |   | |
    [OS]| |
	       | |
	       [PROXY]
	         [SRV|CLI]

Variables

var (
	ErrInvalidKnockResponse = errors.New("invalid knock response")
	ErrKnockSendFailed      = errors.New("knock sequence send failed")
	ErrConnRefused          = errors.New("connection refused (no server listening with given secret)")
	ErrSocketBusy           = errors.New("socket busy")
)

var (
	ErrUntrustedCert       = errors.New("certificate fingerprint mismatch")
	ErrUninitializedSocket = errors.New("socket not initiated")
	ErrQSocketSessionEnd   = errors.New("qSocket session has ended")
	ErrUnexpectedSocket    = errors.New("unexpected socket type")
	ErrInvalidIdTag        = errors.New("invalid peer ID tag")
	ErrNoTlsConnection     = errors.New("TLS socket is nil")
	ErrSocketNotConnected  = errors.New("socket is not connected")
	ErrSrpFailed           = errors.New("SRP auth failed")
	ErrSocketInUse         = errors.New("socket already dialed")
)

Functions

func BindSockets

func BindSockets(con1, con2 *QSocket) error

BindSockets is used for creating a full duplex channel between `con1` and `con2` sockets, effectively binding two sockets.

func CalcChecksum

func CalcChecksum(data []byte, base byte) byte

CalcChecksum calculates the modulus based checksum of the given data, modulus base is given in the base variable.

func CreateSocketChan

func CreateSocketChan(sock *QSocket) chan []byte

chanFromConn creates a channel from a Conn object, and sends everything it

Read()s from the socket to the channel.

func GetDefaultTag

func GetDefaultTag() byte

GetDefaultTag creates a device ID tag based based on the device operating system and architecture.

func NewKnockSequence

func NewKnockSequence(uuid [16]byte, tag byte) ([]byte, error)

NewKnockSequence generates a new knock packet with given UUID and tag values.

Types

type QSocket

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

A QSocket structure contains required values for performing a knock sequence with the QSRN gate.

`Secret` value can be considered as the password for the QSocket connection, It will be used for generating a 128bit unique identifier (UID) for the connection.

`tag` value is used internally for QoS purposes. It specifies the operating system, architecture and the type of connection initiated by the peers, the relay server uses these values for optimizing the connection performance.

func NewSocket

func NewSocket(secret string) *QSocket

NewSocket creates a new QSocket structure with the given secret. `certVerify` value is used for enabling the certificate validation on TLS connections

func (*QSocket) AddIdTag

func (qs *QSocket) AddIdTag(idTag byte) error

AddIdTag adds a peer identification tag to the QSocket.

func (*QSocket) Close

func (qs *QSocket) Close()

Close closes the QSocket connection and underlying TCP/TLS connections.

func (*QSocket) Dial

func (qs *QSocket) Dial() error

Dial creates a TLS connection to the `QSRN_GATE` on `QSRN_GATE_TLS_PORT`. Based on the `VerifyCert` parameter, certificate fingerprint validation (a.k.a. SSL pinning) will be performed after establishing the TLS connection.

func (*QSocket) DialProxy

func (qs *QSocket) DialProxy(proxyAddr string) error

DialProxy tries to create TCP connection to the `QSRN_GATE` using a SOCKS5 proxy. `proxyAddr` should contain a valid SOCKS5 proxy.

func (*QSocket) DialTCP

func (qs *QSocket) DialTCP() error

DialTCP creates a TCP connection to the `QSRN_GATE` on `QSRN_GATE_PORT`.

func (*QSocket) InitClientSRP

func (qs *QSocket) InitClientSRP() ([]byte, error)

InitClientSRP performs the client SRP sequence for establishing PAKE.

func (*QSocket) InitE2ECipher

func (qs *QSocket) InitE2ECipher(key []byte) error

InitE2ECipher initiates the end-to-end encrypted stream with the given key.

func (*QSocket) InitServerSRP

func (qs *QSocket) InitServerSRP() ([]byte, error)

InitServerSRP performs the server SRP sequence for establishing PAKE.

func (*QSocket) IsClient

func (qs *QSocket) IsClient() bool

IsClient checks if the QSocket connection is initiated as a client or a server.

func (*QSocket) IsClosed

func (qs *QSocket) IsClosed() bool

IsClosed checks if the QSocket connection to the `QSRN_GATE` is ended.

func (*QSocket) IsE2E

func (qs *QSocket) IsE2E() bool

IsE2E checks if the underlying connection is E2E encrypted or not.

func (*QSocket) IsTLS

func (qs *QSocket) IsTLS() bool

IsTLS checks if the underlying connection is TLS or not.

func (*QSocket) LocalAddr

func (qs *QSocket) LocalAddr() net.Addr

LocalAddr returns the local network address.

func (*QSocket) Read

func (qs *QSocket) Read(b []byte) (int, error)

Read reads data from the connection.

As Read calls Handshake, in order to prevent indefinite blocking a deadline must be set for both Read and Write before Read is called when the handshake has not yet completed. See SetDeadline, SetReadDeadline, and SetWriteDeadline.

func (*QSocket) RemoteAddr

func (qs *QSocket) RemoteAddr() net.Addr

RemoteAddr returns the remote network address.

func (*QSocket) SendKnockSequence

func (qs *QSocket) SendKnockSequence() error

SendKnockSequence sends a knock sequence to the QSRN gate with the socket properties.

func (*QSocket) SetCertPinning

func (qs *QSocket) SetCertPinning(v bool) error

AddIdTag adds a peer identification tag to the QSocket.

func (*QSocket) SetE2E

func (qs *QSocket) SetE2E(v bool) error

AddIdTag adds a peer identification tag to the QSocket.

func (*QSocket) SetReadDeadline

func (qs *QSocket) SetReadDeadline(t time.Time) error

SetReadDeadline sets the read deadline on the underlying connection. A zero value for t means Read will not time out.

func (*QSocket) SetWriteDeadline

func (qs *QSocket) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the write deadline on the underlying connection. A zero value for t means Write will not time out. After a Write has timed out, the TLS state is corrupt and all future writes will return the same error. Even if write times out, it may return n > 0, indicating that some of the data was successfully written. A zero value for t means Write will not time out.

func (*QSocket) Write

func (qs *QSocket) Write(b []byte) (int, error)

Write writes data to the connection.

As Write calls Handshake, in order to prevent indefinite blocking a deadline must be set for both Read and Write before Write is called when the handshake has not yet completed. See SetDeadline, SetReadDeadline, and SetWriteDeadline.