README
¶
cxnoise
The cxnoise 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 cxnoise 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 (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
- type 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 cxnoise 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 )
Variables ¶
This section is empty.
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, prologue []byte, 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 ¶
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 ¶
LocalAddr returns the local network address.
Part of the net.Conn interface.
func (*Conn) Read ¶
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 ¶
ReadNextMessage uses the connection in a message-oriented instructing it to read the next _full_ message with the cxnoise stream. This function will block until the read succeeds.
func (*Conn) RemoteAddr ¶
RemoteAddr returns the remote network address.
Part of the net.Conn interface.
func (*Conn) SetDeadline ¶
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 ¶
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 ¶
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.
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 cxnoise scheme during both initial connection establishment and data transfer.
func (*Listener) Accept ¶
Accept waits for and returns the next connection to the listener. All incoming connections are authenticated via the three act cxnoise 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.
type Machine ¶
type Machine struct {
// contains filtered or unexported fields
}
Machine is a state-machine which implements cxnoise: an Authenticated-key Exchange in Three Acts. cxnoise is derived from the Noise framework, specifically implementing the Noise_XX handshake. Once the initial 3-act handshake has completed all messages are encrypted with a chacha20 AEAD cipher. On the wire, all messages are prefixed with an authenticated+encrypted length field. Additionally, the encrypted+auth'd length prefix is used as the AD when encrypting+decryption messages. This construction provides confidentiality of packet length, avoids introducing a padding-oracle, and binds the encrypted packet length to the packet itself. Noise protocol reference: http://noiseprotocol.org/noise.html
The acts proceeds the following order (initiator on the left):
GenActOne() ->
RecvActOne()
<- GenActTwo()
RecvActTwo()
GenActThree() ->
RecvActThree()
The protocol has the following steps involved: XX(s, rs):
INITIATOR -> e RESPONDER INITIATOR <- e, ee, s, es RESPONDER INITIATOR -> s, se RESPONDER
s refers to the static key (or public key) belonging to an entity e refers to the ephemeral key e, ee, es refer to a DH exchange between the initiator's key pair and the responder's key pair. The letters e and s hold the same meaning as before.
func NewNoiseMachine ¶
func NewNoiseMachine(initiator bool, prologue []byte, localStatic *koblitz.PrivateKey, options ...func(*Machine)) *Machine
NewNoiseMachine creates a new instance of the cxnoise state-machine. If the responder (listener) is creating the object, then the remotePub should be nil. The handshake state within cxnoise is initialized using the ascii string "opencx" as the prologue. The last parameter is a set of variadic arguments for adding additional options to the cxnoise Machine initialization.
func (*Machine) GenActOne ¶
func (b *Machine) GenActOne() ([ActOneSize]byte, error)
GenActOne generates the initial packet (act one) to be sent from initiator to responder. During act one the initiator generates an ephemeral key and hashes it into the handshake digest. Future payloads are encrypted with a key derived from this result. -> e
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 ¶
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 ¶
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.
Source Files