noise

README

noise

This is a Go package that implements the Noise Protocol Framework. See the documentation for usage information.

Documentation

Overview

Package noise implements the Noise Protocol Framework.

Noise is a low-level framework for building crypto protocols. Noise protocols support mutual and optional authentication, identity hiding, forward secrecy, zero round-trip encryption, and other advanced features. For more details, visit https://noiseprotocol.org.

Index

• Constants
• Variables
• type Cipher
• type CipherFunc
• type CipherState
  • func UnsafeNewCipherState(cs CipherSuite, k [32]byte, n uint64) *CipherState
  • func (s *CipherState) Cipher() Cipher
  • func (s *CipherState) Decrypt(out, ad, ciphertext []byte) ([]byte, error)
  • func (s *CipherState) Encrypt(out, ad, plaintext []byte) ([]byte, error)
  • func (s *CipherState) Nonce() uint64
  • func (s *CipherState) Rekey()
  • func (s *CipherState) SetNonce(n uint64)
  • func (s *CipherState) UnsafeKey() [32]byte
• type CipherSuite
  • func NewCipherSuite(dh DHFunc, c CipherFunc, h HashFunc) CipherSuite
• type Config
• type DHFunc
• type DHKey
• type HandshakePattern
• type HandshakeState
  • func NewHandshakeState(c Config) (*HandshakeState, error)
  • func (s *HandshakeState) ChannelBinding() []byte
  • func (s *HandshakeState) LocalEphemeral() DHKey
  • func (s *HandshakeState) MessageIndex() int
  • func (s *HandshakeState) PeerEphemeral() []byte
  • func (s *HandshakeState) PeerStatic() []byte
  • func (s *HandshakeState) ReadMessage(out, message []byte) ([]byte, *CipherState, *CipherState, error)
  • func (s *HandshakeState) SetPresharedKey(psk []byte) error
  • func (s *HandshakeState) WriteMessage(out, payload []byte) ([]byte, *CipherState, *CipherState, error)
• type HashFunc
• type MessagePattern

Constants

const MaxMsgLen = 65535

MaxMsgLen is the maximum number of bytes that can be sent in a single Noise message.

const MaxNonce = uint64(math.MaxUint64) - 1

MaxNonce is the maximum value of n that is allowed. ErrMaxNonce is returned by Encrypt and Decrypt after this has been reached. 2^64-1 is reserved for rekeys.

Variables

var ErrCipherSuiteCopied = errors.New("noise: CipherSuite has been copied, state is invalid")

var ErrMaxNonce = errors.New("noise: cipherstate has reached maximum n, a new handshake must be performed")

var ErrShortMessage = errors.New("noise: message is too short")

ErrShortMessage is returned by ReadMessage if a message is not as long as it should be.

var HandshakeIK = HandshakePattern{
	Name:                 "IK",
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES, MessagePatternS, MessagePatternDHSS},
		{MessagePatternE, MessagePatternDHEE, MessagePatternDHSE},
	},
}

var HandshakeIN = HandshakePattern{
	Name: "IN",
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternS},
		{MessagePatternE, MessagePatternDHEE, MessagePatternDHSE},
	},
}

var HandshakeIX = HandshakePattern{
	Name: "IX",
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternS},
		{MessagePatternE, MessagePatternDHEE, MessagePatternDHSE, MessagePatternS, MessagePatternDHES},
	},
}

var HandshakeK = HandshakePattern{
	Name:                 "K",
	InitiatorPreMessages: []MessagePattern{MessagePatternS},
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES, MessagePatternDHSS},
	},
}

var HandshakeKK = HandshakePattern{
	Name:                 "KK",
	InitiatorPreMessages: []MessagePattern{MessagePatternS},
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES, MessagePatternDHSS},
		{MessagePatternE, MessagePatternDHEE, MessagePatternDHSE},
	},
}

var HandshakeKN = HandshakePattern{
	Name:                 "KN",
	InitiatorPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE},
		{MessagePatternE, MessagePatternDHEE, MessagePatternDHSE},
	},
}

var HandshakeKX = HandshakePattern{
	Name:                 "KX",
	InitiatorPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE},
		{MessagePatternE, MessagePatternDHEE, MessagePatternDHSE, MessagePatternS, MessagePatternDHES},
	},
}

var HandshakeN = HandshakePattern{
	Name:                 "N",
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES},
	},
}

var HandshakeNK = HandshakePattern{
	Name:                 "NK",
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES},
		{MessagePatternE, MessagePatternDHEE},
	},
}

var HandshakeNN = HandshakePattern{
	Name: "NN",
	Messages: [][]MessagePattern{
		{MessagePatternE},
		{MessagePatternE, MessagePatternDHEE},
	},
}

var HandshakeNX = HandshakePattern{
	Name: "NX",
	Messages: [][]MessagePattern{
		{MessagePatternE},
		{MessagePatternE, MessagePatternDHEE, MessagePatternS, MessagePatternDHES},
	},
}

var HandshakeX = HandshakePattern{
	Name:                 "X",
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES, MessagePatternS, MessagePatternDHSS},
	},
}

var HandshakeXK = HandshakePattern{
	Name:                 "XK",
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES},
		{MessagePatternE, MessagePatternDHEE},
		{MessagePatternS, MessagePatternDHSE},
	},
}

var HandshakeXN = HandshakePattern{
	Name: "XN",
	Messages: [][]MessagePattern{
		{MessagePatternE},
		{MessagePatternE, MessagePatternDHEE},
		{MessagePatternS, MessagePatternDHSE},
	},
}

var HandshakeXX = HandshakePattern{
	Name: "XX",
	Messages: [][]MessagePattern{
		{MessagePatternE},
		{MessagePatternE, MessagePatternDHEE, MessagePatternS, MessagePatternDHES},
		{MessagePatternS, MessagePatternDHSE},
	},
}

var HandshakeXXfallback = HandshakePattern{
	Name:                 "XXfallback",
	ResponderPreMessages: []MessagePattern{MessagePatternE},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHEE, MessagePatternS, MessagePatternDHSE},
		{MessagePatternS, MessagePatternDHES},
	},
}

Types

type Cipher

type Cipher interface {
	// Encrypt encrypts the provided plaintext with a nonce and then appends the
	// ciphertext to out along with an authentication tag over the ciphertext
	// and optional authenticated data.
	Encrypt(out []byte, n uint64, ad, plaintext []byte) []byte

	// Decrypt authenticates the ciphertext and optional authenticated data and
	// then decrypts the provided ciphertext using the provided nonce and
	// appends it to out.
	Decrypt(out []byte, n uint64, ad, ciphertext []byte) ([]byte, error)
}

A Cipher is a AEAD cipher that has been initialized with a key.

type CipherFunc

type CipherFunc interface {
	// Cipher initializes the algorithm with the provided key and returns a Cipher.
	Cipher(k [32]byte) Cipher

	// CipherName is the name of the cipher.
	CipherName() string
}

A CipherFunc implements an AEAD symmetric cipher.

var CipherAESGCM CipherFunc = cipherFn{cipherAESGCM, "AESGCM"}

CipherAESGCM is the AES256-GCM AEAD cipher.

var CipherChaChaPoly CipherFunc = cipherFn{cipherChaChaPoly, "ChaChaPoly"}

CipherChaChaPoly is the ChaCha20-Poly1305 AEAD cipher construction.

type CipherState

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

A CipherState provides symmetric encryption and decryption after a successful handshake.

func UnsafeNewCipherState

func UnsafeNewCipherState(cs CipherSuite, k [32]byte, n uint64) *CipherState

UnsafeNewCipherState reconstructs a CipherState from exported components. It is important that, when resuming from an exported state, care is taken to synchronize the nonce state and not allow rollbacks.

func (*CipherState) Cipher

func (s *CipherState) Cipher() Cipher

Cipher returns the low-level symmetric encryption primitive. It should only be used if nonces need to be managed manually, for example with a network protocol that can deliver out-of-order messages. This is dangerous, users must ensure that they are incrementing a nonce after every encrypt operation. After calling this method, it is an error to call Encrypt/Decrypt on the CipherState.

func (*CipherState) Decrypt

func (s *CipherState) Decrypt(out, ad, ciphertext []byte) ([]byte, error)

Decrypt checks the authenticity of the ciphertext and authenticated data and then decrypts and appends the plaintext to out. This method automatically increments the nonce after every call, messages must be provided in the same order that they were encrypted with no missing messages. ErrMaxNonce is returned after the maximum nonce of 2^64-2 is reached.

func (*CipherState) Encrypt

func (s *CipherState) Encrypt(out, ad, plaintext []byte) ([]byte, error)

Encrypt encrypts the plaintext and then appends the ciphertext and an authentication tag across the ciphertext and optional authenticated data to out. This method automatically increments the nonce after every call, so messages must be decrypted in the same order. ErrMaxNonce is returned after the maximum nonce of 2^64-2 is reached.

func (*CipherState) Nonce

func (s *CipherState) Nonce() uint64

Nonce returns the current value of n. This can be used to determine if a new handshake should be performed due to approaching MaxNonce.

func (*CipherState) Rekey

func (s *CipherState) Rekey()

func (*CipherState) SetNonce

func (s *CipherState) SetNonce(n uint64)

SetNonce sets the current value of n.

func (*CipherState) UnsafeKey

func (s *CipherState) UnsafeKey() [32]byte

UnsafeKey returns the current value of k. This exports the current key for the CipherState. Intended to be used alongside UnsafeNewCipherState to resume a CipherState at a later point.

type CipherSuite

type CipherSuite interface {
	DHFunc
	CipherFunc
	HashFunc
	Name() []byte
}

A CipherSuite is a set of cryptographic primitives used in a Noise protocol. It should be constructed with NewCipherSuite.

func NewCipherSuite

func NewCipherSuite(dh DHFunc, c CipherFunc, h HashFunc) CipherSuite

NewCipherSuite returns a CipherSuite constructed from the specified primitives.

type Config

type Config struct {
	// CipherSuite is the set of cryptographic primitives that will be used.
	CipherSuite CipherSuite

	// Random is the source for cryptographically appropriate random bytes. If
	// zero, it is automatically configured.
	Random io.Reader

	// Pattern is the pattern for the handshake.
	Pattern HandshakePattern

	// Initiator must be true if the first message in the handshake will be sent
	// by this peer.
	Initiator bool

	// Prologue is an optional message that has already be communicated and must
	// be identical on both sides for the handshake to succeed.
	Prologue []byte

	// PresharedKey is the optional preshared key for the handshake.
	PresharedKey []byte

	// PresharedKeyPlacement specifies the placement position of the PSK token
	// when PresharedKey is specified
	PresharedKeyPlacement int

	// StaticKeypair is this peer's static keypair, required if part of the
	// handshake.
	StaticKeypair DHKey

	// EphemeralKeypair is this peer's ephemeral keypair that was provided as
	// a pre-message in the handshake.
	EphemeralKeypair DHKey

	// PeerStatic is the static public key of the remote peer that was provided
	// as a pre-message in the handshake.
	PeerStatic []byte

	// PeerEphemeral is the ephemeral public key of the remote peer that was
	// provided as a pre-message in the handshake.
	PeerEphemeral []byte
}

A Config provides the details necessary to process a Noise handshake. It is never modified by this package, and can be reused.

type DHFunc

type DHFunc interface {
	// GenerateKeypair generates a new keypair using random as a source of
	// entropy.
	GenerateKeypair(random io.Reader) (DHKey, error)

	// DH performs a Diffie-Hellman calculation between the provided private and
	// public keys and returns the result.
	DH(privkey, pubkey []byte) ([]byte, error)

	// DHLen is the number of bytes returned by DH.
	DHLen() int

	// DHName is the name of the DH function.
	DHName() string
}

A DHFunc implements Diffie-Hellman key agreement.

var DH25519 DHFunc = dh25519{}

DH25519 is the Curve25519 ECDH function.

type DHKey

type DHKey struct {
	Private []byte
	Public  []byte
}

A DHKey is a keypair used for Diffie-Hellman key agreement.

type HandshakePattern

type HandshakePattern struct {
	Name                 string
	InitiatorPreMessages []MessagePattern
	ResponderPreMessages []MessagePattern
	Messages             [][]MessagePattern
}

A HandshakePattern is a list of messages and operations that are used to perform a specific Noise handshake.

type HandshakeState

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

A HandshakeState tracks the state of a Noise handshake. It may be discarded after the handshake is complete.

func NewHandshakeState

func NewHandshakeState(c Config) (*HandshakeState, error)

NewHandshakeState starts a new handshake using the provided configuration.

func (*HandshakeState) ChannelBinding

func (s *HandshakeState) ChannelBinding() []byte

ChannelBinding provides a value that uniquely identifies the session and can be used as a channel binding. It is an error to call this method before the handshake is complete.

func (*HandshakeState) LocalEphemeral

func (s *HandshakeState) LocalEphemeral() DHKey

LocalEphemeral returns the local ephemeral key pair generated during a handshake.

func (*HandshakeState) MessageIndex

func (s *HandshakeState) MessageIndex() int

MessageIndex returns the current handshake message id

func (*HandshakeState) PeerEphemeral

func (s *HandshakeState) PeerEphemeral() []byte

PeerEphemeral returns the ephemeral key provided by the remote peer during a handshake. It is an error to call this method if a handshake message containing a static key has not been read.

func (*HandshakeState) PeerStatic

func (s *HandshakeState) PeerStatic() []byte

PeerStatic returns the static key provided by the remote peer during a handshake. It is an error to call this method if a handshake message containing a static key has not been read.

func (*HandshakeState) ReadMessage

func (s *HandshakeState) ReadMessage(out, message []byte) ([]byte, *CipherState, *CipherState, error)

ReadMessage processes a received handshake message and appends the payload, if any to out. If the handshake is completed by the call, two CipherStates will be returned, one is used for encryption of messages to the remote peer, the other is used for decryption of messages from the remote peer. It is an error to call this method out of sync with the handshake pattern.

func (*HandshakeState) SetPresharedKey

func (s *HandshakeState) SetPresharedKey(psk []byte) error

func (*HandshakeState) WriteMessage

func (s *HandshakeState) WriteMessage(out, payload []byte) ([]byte, *CipherState, *CipherState, error)

WriteMessage appends a handshake message to out. The message will include the optional payload if provided. If the handshake is completed by the call, two CipherStates will be returned, one is used for encryption of messages to the remote peer, the other is used for decryption of messages from the remote peer. It is an error to call this method out of sync with the handshake pattern.

type HashFunc

type HashFunc interface {
	// Hash returns a hash state.
	Hash() hash.Hash

	// HashName is the name of the hash function.
	HashName() string
}

A HashFunc implements a cryptographic hash function.

var HashBLAKE2b HashFunc = hashFn{blake2bNew, "BLAKE2b"}

HashBLAKE2b is the BLAKE2b hash function.

var HashBLAKE2s HashFunc = hashFn{blake2sNew, "BLAKE2s"}

HashBLAKE2s is the BLAKE2s hash function.

var HashSHA256 HashFunc = hashFn{sha256.New, "SHA256"}

HashSHA256 is the SHA-256 hash function.

var HashSHA512 HashFunc = hashFn{sha512.New, "SHA512"}

HashSHA512 is the SHA-512 hash function.

type MessagePattern

type MessagePattern int

A MessagePattern is a single message or operation used in a Noise handshake.

const (
	MessagePatternS MessagePattern = iota
	MessagePatternE
	MessagePatternDHEE
	MessagePatternDHES
	MessagePatternDHSE
	MessagePatternDHSS
	MessagePatternPSK
)