noise: github.com/katzenpost/noise Index | Files | Directories

package noise

import "github.com/katzenpost/noise"

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

Package Files

cipher_suite.go hfs.go hkdf.go patterns.go state.go

Constants

const DefaultMaxMsgLen = 65535

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

Variables

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 HandshakeXXhfs = HandshakePattern{
    Name: "XXhfs",
    Messages: [][]MessagePattern{
        {MessagePatternE, MessagePatternF},
        {MessagePatternE, MessagePatternF, MessagePatternDHEE, MessagePatternFF, MessagePatternS, MessagePatternDHES},
        {MessagePatternS, MessagePatternDHSE},
    },
}

type Cipher Uses

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 Uses

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 Uses

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

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

func (*CipherState) Cipher Uses

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 Uses

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.

func (*CipherState) Encrypt Uses

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

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.

func (*CipherState) Rekey Uses

func (s *CipherState) Rekey()

type CipherSuite Uses

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

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

func NewCipherSuite Uses

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

NewCipherSuite returns a CipherSuite constructed from the specified primitives.

func NewCipherSuiteHFS Uses

func NewCipherSuiteHFS(dh DHFunc, c CipherFunc, h HashFunc, hfs HFSFunc) CipherSuite

NewCipherSuite HFS returns a CipherSuite constructed from the specified primitives, with the Hybrid Forward Secrecy extension.

type Config Uses

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

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

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

type DHFunc Uses

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

    // 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 Uses

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

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

type HFSFunc Uses

type HFSFunc interface {
    // GenerateKeypairF generates a new key pair for the hybrid forward
    // secrecy algorithm relative to a remote public key rf. The rf value
    // will be empty for the first "f" token in the handshake, and non-empty
    // for the second "f" token.
    GenerateKeypairF(rng io.Reader, rf []byte) HFSKey

    // FF performs a hybrid forward secrecy calculation that mixes a local key
    // pair with a remote public key.
    FF(keypair HFSKey, pubkey []byte) []byte

    // FLen1 is a constant specifying the size in bytes of the output from
    // GenerateKeypairF(rf) when rf is empty.
    FLen1() int

    // Flen2 is a constant specifying the size in bytes of the output from
    // GenerateKeypairF(rf) when rf is not empty.
    FLen2() int

    // FLen is constant specifying the size in bytes of the output from FF().
    FLen() int

    // HFSName is the name of the HFS function.
    HFSName() string
}

HFSFunc implements a hybrid forward secrecy function, for the Noise HFS extension (version 1draft-5).

See: https://github.com/noiseprotocol/noise_spec/blob/master/extensions/ext_hybrid_forward_secrecy.md

var HFSNewHopeSimple HFSFunc = hfsNewHopeSimple{}

HFSNewHopeSimple is the NewHope-Simple HFS function.

type HFSKey Uses

type HFSKey interface {
    Public() []byte
}

type HandshakePattern Uses

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 Uses

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 Uses

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

NewHandshakeState starts a new handshake using the provided configuration.

func (*HandshakeState) ChannelBinding Uses

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) PeerStatic Uses

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 Uses

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) WriteMessage Uses

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 Uses

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 Uses

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

    MessagePatternF
    MessagePatternFF
)

Directories

PathSynopsis
vectorgen

Package noise imports 17 packages (graph) and is imported by 4 packages. Updated 2019-09-17. Refresh now. Tools for package owners.