noise

package module
v0.0.0-...-9749acc Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 21, 2024 License: BSD-3-Clause Imports: 16 Imported by: 0

README

noise Go Reference CI Status

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

View Source 
const MaxMsgLen = 65535

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

View Source 
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

View Source 
var ErrCipherSuiteCopied = errors.New("noise: CipherSuite has been copied, state is invalid")
View Source 
var ErrMaxNonce = errors.New("noise: cipherstate has reached maximum n, a new handshake must be performed")
View Source 
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.

View Source 
var HandshakeIK = HandshakePattern{
	Name:                 "IK",
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES, MessagePatternS, MessagePatternDHSS},
		{MessagePatternE, MessagePatternDHEE, MessagePatternDHSE},
	},
}
View Source 
var HandshakeIN = HandshakePattern{
	Name: "IN",
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternS},
		{MessagePatternE, MessagePatternDHEE, MessagePatternDHSE},
	},
}
View Source 
var HandshakeIX = HandshakePattern{
	Name: "IX",
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternS},
		{MessagePatternE, MessagePatternDHEE, MessagePatternDHSE, MessagePatternS, MessagePatternDHES},
	},
}
View Source 
var HandshakeK = HandshakePattern{
	Name:                 "K",
	InitiatorPreMessages: []MessagePattern{MessagePatternS},
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES, MessagePatternDHSS},
	},
}
View Source 
var HandshakeKK = HandshakePattern{
	Name:                 "KK",
	InitiatorPreMessages: []MessagePattern{MessagePatternS},
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES, MessagePatternDHSS},
		{MessagePatternE, MessagePatternDHEE, MessagePatternDHSE},
	},
}
View Source 
var HandshakeKN = HandshakePattern{
	Name:                 "KN",
	InitiatorPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE},
		{MessagePatternE, MessagePatternDHEE, MessagePatternDHSE},
	},
}
View Source 
var HandshakeKX = HandshakePattern{
	Name:                 "KX",
	InitiatorPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE},
		{MessagePatternE, MessagePatternDHEE, MessagePatternDHSE, MessagePatternS, MessagePatternDHES},
	},
}
View Source 
var HandshakeN = HandshakePattern{
	Name:                 "N",
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES},
	},
}
View Source 
var HandshakeNK = HandshakePattern{
	Name:                 "NK",
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES},
		{MessagePatternE, MessagePatternDHEE},
	},
}
View Source 
var HandshakeNN = HandshakePattern{
	Name: "NN",
	Messages: [][]MessagePattern{
		{MessagePatternE},
		{MessagePatternE, MessagePatternDHEE},
	},
}
View Source 
var HandshakeNX = HandshakePattern{
	Name: "NX",
	Messages: [][]MessagePattern{
		{MessagePatternE},
		{MessagePatternE, MessagePatternDHEE, MessagePatternS, MessagePatternDHES},
	},
}
View Source 
var HandshakeX = HandshakePattern{
	Name:                 "X",
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES, MessagePatternS, MessagePatternDHSS},
	},
}
View Source 
var HandshakeXK = HandshakePattern{
	Name:                 "XK",
	ResponderPreMessages: []MessagePattern{MessagePatternS},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHES},
		{MessagePatternE, MessagePatternDHEE},
		{MessagePatternS, MessagePatternDHSE},
	},
}
View Source 
var HandshakeXN = HandshakePattern{
	Name: "XN",
	Messages: [][]MessagePattern{
		{MessagePatternE},
		{MessagePatternE, MessagePatternDHEE},
		{MessagePatternS, MessagePatternDHSE},
	},
}
View Source 
var HandshakeXX = HandshakePattern{
	Name: "XX",
	Messages: [][]MessagePattern{
		{MessagePatternE},
		{MessagePatternE, MessagePatternDHEE, MessagePatternS, MessagePatternDHES},
		{MessagePatternS, MessagePatternDHSE},
	},
}
View Source 
var HandshakeXXfallback = HandshakePattern{
	Name:                 "XXfallback",
	ResponderPreMessages: []MessagePattern{MessagePatternE},
	Messages: [][]MessagePattern{
		{MessagePatternE, MessagePatternDHEE, MessagePatternS, MessagePatternDHSE},
		{MessagePatternS, MessagePatternDHES},
	},
}

Functions

This section is empty.

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. 

var DHSECP256 DHFunc = dhsecp256{}

DHSECP256 is the secp256r1 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
)

type SymmetricState 

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

func NewSymmetricState 

func NewSymmetricState(cs CipherSuite, patternName string, pskModifier string) SymmetricState

func (*SymmetricState) Checkpoint 

func (s *SymmetricState) Checkpoint()

func (*SymmetricState) DecryptAndHash 

func (s *SymmetricState) DecryptAndHash(out, data []byte) ([]byte, error)

func (*SymmetricState) EncryptAndHash 

func (s *SymmetricState) EncryptAndHash(out, plaintext []byte) ([]byte, error)

func (*SymmetricState) GetHash 

func (s *SymmetricState) GetHash() []byte

func (*SymmetricState) InitializeSymmetric 

func (s *SymmetricState) InitializeSymmetric(handshakeName []byte)

func (*SymmetricState) MixHash 

func (s *SymmetricState) MixHash(data []byte)

func (*SymmetricState) MixKey 

func (s *SymmetricState) MixKey(dhOutput []byte)

func (*SymmetricState) MixKeyAndHash 

func (s *SymmetricState) MixKeyAndHash(data []byte)

func (*SymmetricState) Rollback 

func (s *SymmetricState) Rollback()

func (*SymmetricState) Split 

func (s *SymmetricState) Split() (*CipherState, *CipherState)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.