mse

Documentation

Overview

Package mse (Message Stream Encryption) provides a transparent wrapper for bidirectional data streams (e.g. TCP transports) that prevents passive eavesdroping and thus protocol or content identification.

It is also designed to provide limited protection against active MITM attacks and portscanning by requiring a weak shared secret to complete the handshake. You should note that the major design goal was payload and protocol obfuscation, not peer authentication and data integrity verification. Thus it does not offer protection against adversaries which already know the necessary data to establish connections (that is IP/Port/Shared Secret/Payload protocol).

To minimize the load on systems that employ this protocol fast cryptographic methods have been chosen over maximum-security algorithms.

See http://wiki.vuze.com/w/Message_Stream_Encryption for details.

Index

• func HashSKey(key []byte) [20]byte
• type Conn
  • func WrapConn(conn net.Conn) *Conn
  • func (c *Conn) Read(p []byte) (n int, err error)
  • func (c *Conn) Write(p []byte) (n int, err error)
• type CryptoMethod
  • func (c CryptoMethod) String() string
• type Stream
  • func NewStream(rw io.ReadWriter) *Stream
  • func (s *Stream) HandshakeIncoming(getSKey func(sKeyHash [20]byte) (sKey []byte), ...) (err error)
  • func (s *Stream) HandshakeOutgoing(sKey []byte, cryptoProvide CryptoMethod, initialPayload []byte) (selected CryptoMethod, err error)
  • func (s *Stream) Read(p []byte) (n int, err error)
  • func (s *Stream) Write(p []byte) (n int, err error)

Functions

func HashSKey

func HashSKey(key []byte) [20]byte

HashSKey returns the hash of key.

Types

type Conn

type Conn struct {
	net.Conn
	*Stream
}

Conn is a wrapper around net.Conn that does encryption/decryption on Read/Write methods.

func WrapConn

func WrapConn(conn net.Conn) *Conn

WrapConn returns a new wrapper around conn. You must call HandshakeIncoming or HandshakeOutgoing methods before using Read/Write methods.

func (*Conn) Read

func (c *Conn) Read(p []byte) (n int, err error)

func (*Conn) Write

func (c *Conn) Write(p []byte) (n int, err error)

type CryptoMethod

type CryptoMethod uint32

CryptoMethod is 32-bit bitfield each bit representing a single crypto method.

const (
	PlainText CryptoMethod = 1 << iota
	RC4
)

Crypto methods

func (CryptoMethod) String

func (c CryptoMethod) String() string

type Stream

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

Stream wraps a io.ReadWriter that automatically does encrypt/decrypt on read/write.

func NewStream

func NewStream(rw io.ReadWriter) *Stream

NewStream returns a new Stream. You must call HandshakeIncoming or HandshakeOutgoing methods before using Read/Write methods. If any error happens during the handshake underlying io.ReadWriter will be closed if it implements io.Closer.

func (*Stream) HandshakeIncoming

func (s *Stream) HandshakeIncoming(
	getSKey func(sKeyHash [20]byte) (sKey []byte),
	cryptoSelect func(provided CryptoMethod) (selected CryptoMethod)) (err error)

HandshakeIncoming initiates MSE handshake for incoming stream.

getSKey must return the correct stream identifier for given sKeyHash. sKeyHash can be calculated with mse.HashSKey function. If there is no matching sKeyHash in your application, you must return nil.

cryptoSelect is a function that takes provided methods as a bitfield and returns the selected crypto method. Function may return zero value that means none of the provided methods are selected and handshake fails.

payloadIn is a buffer for writing initial payload that is coming along with the handshake from the initiator of the handshake. If initial payload does not fit into payloadIn, handshake returns io.ErrShortBuffer.

lenPayloadIn is length of the data read into payloadIn.

processPayloadIn is an optional function that processes incoming initial payload and generate outgoing initial payload. If this function returns an error, handshake fails.

func (*Stream) HandshakeOutgoing

func (s *Stream) HandshakeOutgoing(sKey []byte, cryptoProvide CryptoMethod, initialPayload []byte) (selected CryptoMethod, err error)

HandshakeOutgoing initiates MSE handshake for outgoing stream.

sKey is stream identifier key. Same key must be used at the other side of the stream, otherwise handshake fails.

cryptoProvide is a bitfield for specifying supported encryption methods.

initialPayload is going to be sent along with handshake. It may be nil if you want to wait for the encryption negotiation.

func (*Stream) Read

func (s *Stream) Read(p []byte) (n int, err error)

Read from underlying io.ReadWriter, decrypt bytes and put into p.

func (*Stream) Write

func (s *Stream) Write(p []byte) (n int, err error)

Encrypt bytes in p and write into underlying io.ReadWriter.