lndc

README

lndc

The lndc package implements a secure crypto messaging protocol based off of the Noise Protocol Framework. The package exposes the raw state machine that handles the handshake and subsequent message encryption/decryption scheme. Additionally, the package exposes a net.Conn and a net.Listener interface implementation which allows the encrypted transport to be seamlessly integrated into a codebase.

The secure messaging scheme implemented within this package uses NOISE_XX as the handshake for authenticated key exchange. Please note that this is not the same as brontide which uses the NOISE_XK protocol for handshakes and lndc is not compatible with the same.

This package has intentionally been designed so it can be used as a standalone package for any projects needing secure encrypted+authenticated communications between network enabled programs.

This package requires additional attribution to that of lit since it is adapted from the original brontide package. Please see license for details.

Documentation

Index

• Constants
• func EphemeralGenerator(gen func() (*koblitz.PrivateKey, error)) func(*Machine)
• type Conn
  • func Dial(localPriv *koblitz.PrivateKey, ipAddr string, remotePKH string, ...) (*Conn, error)
  • func (c *Conn) Close() error
  • func (c *Conn) LocalAddr() net.Addr
  • func (c *Conn) LocalPub() *koblitz.PublicKey
  • func (c *Conn) Read(b []byte) (n int, err error)
  • func (c *Conn) ReadNextMessage() ([]byte, error)
  • func (c *Conn) RemoteAddr() net.Addr
  • func (c *Conn) RemotePub() *koblitz.PublicKey
  • func (c *Conn) SetDeadline(t time.Time) error
  • func (c *Conn) SetReadDeadline(t time.Time) error
  • func (c *Conn) SetWriteDeadline(t time.Time) error
  • func (c *Conn) Write(b []byte) (n int, err error)
• type Listener
  • func NewListener(localStatic *koblitz.PrivateKey, port int) (*Listener, error)
  • func (l *Listener) Accept() (net.Conn, error)
  • func (l *Listener) Addr() net.Addr
  • func (l *Listener) Close() error
• type Machine
  • func NewNoiseMachine(initiator bool, localStatic *koblitz.PrivateKey, options ...func(*Machine)) *Machine
  • func (b *Machine) GenActOne() ([ActOneSize]byte, error)
  • func (b *Machine) GenActThree() ([ActThreeSize]byte, error)
  • func (b *Machine) GenActTwo() ([ActTwoSize]byte, error)
  • func (b *Machine) ReadMessage(r io.Reader) ([]byte, error)
  • func (b *Machine) RecvActOne(actOne [ActOneSize]byte) error
  • func (b *Machine) RecvActThree(actThree [ActThreeSize]byte) error
  • func (b *Machine) RecvActTwo(actTwo [ActTwoSize]byte) ([33]byte, error)
  • func (b *Machine) WriteMessage(w io.Writer, p []byte) error

Constants

const (
	// HandshakeVersion is the expected version of the lndc handshake.
	// Any messages that carry a different version will cause the handshake
	// to abort immediately.
	HandshakeVersion = byte(1) // TODO: add support for noise_XK (brontide) as well

	// ActOneSize is the size of the packet sent from initiator to
	// responder in ActOne. The packet consists of a handshake version, an
	// ephemeral key in compressed format, and a 16-byte poly1305 tag.
	// -> e
	// 1 + 33 + 16
	ActOneSize = 50

	// ActTwoSize is the size the packet sent from responder to initiator
	// in ActTwo. The packet consists of a handshake version, an ephemeral
	// key in compressed format, a public key in compressed format
	// and a 16-byte poly1305 tag.
	// <- e, ee, s, es
	// 1 + 33 + 33 + 16
	ActTwoSize = 83

	// ActThreeSize is the size of the packet sent from initiator to
	// responder in ActThree. The packet consists of a handshake version,
	// the initiators static key encrypted with strong forward secrecy and
	// a 16-byte poly1035 tag.
	// -> s, se
	// 1 + 33 + 16 + 16
	ActThreeSize = 66
)

Functions

func EphemeralGenerator

func EphemeralGenerator(gen func() (*koblitz.PrivateKey, error)) func(*Machine)

EphemeralGenerator is a functional option that allows callers to substitute a custom function for use when generating ephemeral keys for ActOne or ActTwo. The function closure return by this function can be passed into NewNoiseMachine as a function option parameter.

Types

type Conn

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

Conn is an implementation of net.Conn which enforces an authenticated key exchange and message encryption protocol based off the noise_XX protocol In the case of a successful handshake, all messages sent via the .Write() method are encrypted with an AEAD cipher along with an encrypted length-prefix. See the Machine struct for additional details w.r.t to the handshake and encryption scheme.

func Dial

func Dial(localPriv *koblitz.PrivateKey, ipAddr string, remotePKH string,
	dialer func(string, string) (net.Conn, error)) (*Conn, error)

Dial attempts to establish an encrypted+authenticated connection with the remote peer located at address which has remotePub as its long-term static public key. In the case of a handshake failure, the connection is closed and a non-nil error is returned.

func (*Conn) Close

func (c *Conn) Close() error

Close closes the connection. Any blocked Read or Write operations will be unblocked and return errors.

Part of the net.Conn interface.

func (*Conn) LocalAddr

func (c *Conn) LocalAddr() net.Addr

LocalAddr returns the local network address.

Part of the net.Conn interface.

func (*Conn) LocalPub

func (c *Conn) LocalPub() *koblitz.PublicKey

LocalPub returns the local peer's static public key.

func (*Conn) Read

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

Read reads data from the connection. Read can be made to time out and return an Error with Timeout() == true after a fixed time limit; see SetDeadline and SetReadDeadline.

Part of the net.Conn interface.

func (*Conn) ReadNextMessage

func (c *Conn) ReadNextMessage() ([]byte, error)

ReadNextMessage uses the connection in a message-oriented instructing it to read the next _full_ message with the lndc stream. This function will block until the read succeeds.

func (*Conn) RemoteAddr

func (c *Conn) RemoteAddr() net.Addr

RemoteAddr returns the remote network address.

Part of the net.Conn interface.

func (*Conn) RemotePub

func (c *Conn) RemotePub() *koblitz.PublicKey

RemotePub returns the remote peer's static public key.

func (*Conn) SetDeadline

func (c *Conn) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with the connection. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.

Part of the net.Conn interface.

func (*Conn) SetReadDeadline

func (c *Conn) SetReadDeadline(t time.Time) error

SetReadDeadline sets the deadline for future Read calls. A zero value for t means Read will not time out.

Part of the net.Conn interface.

func (*Conn) SetWriteDeadline

func (c *Conn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the deadline for future Write calls. 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.

Part of the net.Conn interface.

func (*Conn) Write

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

Write writes data to the connection. Write can be made to time out and return an Error with Timeout() == true after a fixed time limit; see SetDeadline and SetWriteDeadline.

Part of the net.Conn interface.

type Listener

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

Listener is an implementation of a net.Conn which executes an authenticated key exchange and message encryption protocol dubbed "Machine" after initial connection acceptance. See the Machine struct for additional details w.r.t the handshake and encryption scheme used within the connection.

func NewListener

func NewListener(localStatic *koblitz.PrivateKey, port int) (*Listener,
	error)

NewListener returns a new net.Listener which enforces the lndc scheme during both initial connection establishment and data transfer.

func (*Listener) Accept

func (l *Listener) Accept() (net.Conn, error)

Accept waits for and returns the next connection to the listener. All incoming connections are authenticated via the three act lndc key-exchange scheme. This function will fail with a non-nil error in the case that either the handshake breaks down, or the remote peer doesn't know our static public key.

Part of the net.Listener interface.

func (*Listener) Addr

func (l *Listener) Addr() net.Addr

Addr returns the listener's network address.

Part of the net.Listener interface.

func (*Listener) Close

func (l *Listener) Close() error

Close closes the listener. Any blocked Accept operations will be unblocked and return errors.

Part of the net.Listener interface.

type Machine

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

func NewNoiseMachine

func NewNoiseMachine(initiator bool, localStatic *koblitz.PrivateKey,
	options ...func(*Machine)) *Machine

NewNoiseMachine creates a new instance of the lndc state-machine. If the responder (listener) is creating the object, then the remotePub should be nil. The handshake state within lndc is initialized using the ascii string "lightning" as the prologue. The last parameter is a set of variadic arguments for adding additional options to the lndc Machine initialization.

func (*Machine) GenActOne

func (b *Machine) GenActOne() ([ActOneSize]byte, error)

func (*Machine) GenActThree

func (b *Machine) GenActThree() ([ActThreeSize]byte, error)

GenActThree creates the final (act three) packet of the handshake. Act three is to be sent from the initiator to the responder. The purpose of act three is to transmit the initiator's public key under strong forward secrecy to the responder. This act also includes the final ECDH operation which yields the final session. -> s, se

func (*Machine) GenActTwo

func (b *Machine) GenActTwo() ([ActTwoSize]byte, error)

GenActTwo generates the second packet (act two) to be sent from the responder to the initiator <- e, ee, s, es

func (*Machine) ReadMessage

func (b *Machine) ReadMessage(r io.Reader) ([]byte, error)

ReadMessage attempts to read the next message from the passed io.Reader. In the case of an authentication error, a non-nil error is returned.

func (*Machine) RecvActOne

func (b *Machine) RecvActOne(actOne [ActOneSize]byte) error

RecvActOne processes the act one packet sent by the initiator. The responder executes the mirrored actions to that of the initiator extending the handshake digest and deriving a new shared secret based on an ECDH with the initiator's ephemeral key and responder's static key.

func (*Machine) RecvActThree

func (b *Machine) RecvActThree(actThree [ActThreeSize]byte) error

RecvActThree processes the final act (act three) sent from the initiator to the responder. After processing this act, the responder learns of the initiator's static public key. Decryption of the static key serves to authenticate the initiator to the responder.

func (*Machine) RecvActTwo

func (b *Machine) RecvActTwo(actTwo [ActTwoSize]byte) ([33]byte, error)

RecvActTwo processes the second packet (act two) sent from the responder to the initiator. A successful processing of this packet authenticates the initiator to the responder.

func (*Machine) WriteMessage

func (b *Machine) WriteMessage(w io.Writer, p []byte) error

WriteMessage writes the next message p to the passed io.Writer. The ciphertext of the message is prepended with an encrypt+auth'd length which must be used as the AD to the AEAD construction when being decrypted by the other side.