package noise

Import Path
	github.com/flynn/noise (on go.dev)

Dependency Relation
	imports 16 packages, and imported by one package

Involved Source Files

	    cipher_suite.go
	    hkdf.go
	    patterns.go
	  d state.go
		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.
Package-Level Type Names (total 11)

	/* sort by: alphabet | popularity */
	 type Cipher (interface)
		A Cipher is a AEAD cipher that has been initialized with a key.

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

			( Cipher) Encrypt(out []byte, n uint64, ad, plaintext []byte) []byte
				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.

		As Outputs Of (at least 3)
			func CipherFunc.Cipher(k [32]byte) Cipher
			func (*CipherState).Cipher() Cipher
			func CipherSuite.Cipher(k [32]byte) Cipher

	 type CipherFunc (interface)
		A CipherFunc implements an AEAD symmetric cipher.

		Methods (total 2)
			( CipherFunc) Cipher(k [32]byte) Cipher
				Cipher initializes the algorithm with the provided key and returns a Cipher.

			( CipherFunc) CipherName() string
				CipherName is the name of the cipher.

		Implemented By (at least one exported)
			 CipherSuite (interface)
		As Inputs Of (at least one exported)
			func NewCipherSuite(dh DHFunc, c CipherFunc, h HashFunc) CipherSuite
		As Types Of (total 2)
			  var CipherAESGCM
			  var CipherChaChaPoly

	 type CipherState (struct)
		A CipherState provides symmetric encryption and decryption after a successful
		handshake.

		Methods (total 7)
			(*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.

			(*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.

			(*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.

			(*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.

			(*CipherState) Rekey()
			(*CipherState) SetNonce(n uint64)
				SetNonce sets the current value of n.

			(*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.

		As Outputs Of (at least 5)
			func UnsafeNewCipherState(cs CipherSuite, k [32]byte, n uint64) *CipherState
			func (*HandshakeState).ReadMessage(out, message []byte) ([]byte, *CipherState, *CipherState, error)
			func (*HandshakeState).ReadMessage(out, message []byte) ([]byte, *CipherState, *CipherState, error)
			func (*HandshakeState).WriteMessage(out, payload []byte) ([]byte, *CipherState, *CipherState, error)
			func (*HandshakeState).WriteMessage(out, payload []byte) ([]byte, *CipherState, *CipherState, error)

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

		Methods (total 9)
			( CipherSuite) Cipher(k [32]byte) Cipher
				Cipher initializes the algorithm with the provided key and returns a Cipher.

			( CipherSuite) CipherName() string
				CipherName is the name of the cipher.

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

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

			( CipherSuite) DHName() string
				DHName is the name of the DH function.

			( CipherSuite) GenerateKeypair(random io.Reader) (DHKey, error)
				GenerateKeypair generates a new keypair using random as a source of
				entropy.

			( CipherSuite) Hash() hash.Hash
				Hash returns a hash state.

			( CipherSuite) HashName() string
				HashName is the name of the hash function.

			( CipherSuite) Name() []byte
		Implements (at least 3)
			 CipherSuite : CipherFunc
			 CipherSuite : DHFunc
			 CipherSuite : HashFunc
		As Outputs Of (at least one exported)
			func NewCipherSuite(dh DHFunc, c CipherFunc, h HashFunc) CipherSuite
		As Inputs Of (at least one exported)
			func UnsafeNewCipherState(cs CipherSuite, k [32]byte, n uint64) *CipherState

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

		Fields (total 11)
			CipherSuite CipherSuite
				CipherSuite is the set of cryptographic primitives that will be used.

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

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

			Pattern HandshakePattern
				Pattern is the pattern for the handshake.

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

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

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

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

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

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

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

		As Inputs Of (at least one exported)
			func NewHandshakeState(c Config) (*HandshakeState, error)

	 type DHFunc (interface)
		A DHFunc implements Diffie-Hellman key agreement.

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

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

			( DHFunc) DHName() string
				DHName is the name of the DH function.

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

		Implemented By (at least one exported)
			 CipherSuite (interface)
		As Inputs Of (at least one exported)
			func NewCipherSuite(dh DHFunc, c CipherFunc, h HashFunc) CipherSuite
		As Types Of (only one)
			  var DH25519

	 type DHKey (struct)
		A DHKey is a keypair used for Diffie-Hellman key agreement.

		Fields (total 2)
			Private []byte
			Public []byte
		As Outputs Of (at least 3)
			func CipherSuite.GenerateKeypair(random io.Reader) (DHKey, error)
			func DHFunc.GenerateKeypair(random io.Reader) (DHKey, error)
			func (*HandshakeState).LocalEphemeral() DHKey

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

		Fields (total 4)
			InitiatorPreMessages []MessagePattern
			Messages [][]MessagePattern
			Name string
			ResponderPreMessages []MessagePattern
		As Types Of (total 16)
			  var HandshakeIK
			  var HandshakeIN
			  var HandshakeIX
			  var HandshakeK
			  var HandshakeKK
			  var HandshakeKN
			  var HandshakeKX
			  var HandshakeN
			  var HandshakeNK
			  var HandshakeNN
			  var HandshakeNX
			  var HandshakeX
			  var HandshakeXK
			  var HandshakeXN
			  var HandshakeXX
			  var HandshakeXXfallback

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

		Methods (total 8)
			(*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.

			(*HandshakeState) LocalEphemeral() DHKey
				LocalEphemeral returns the local ephemeral key pair generated during
				a handshake.

			(*HandshakeState) MessageIndex() int
				MessageIndex returns the current handshake message id

			(*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.

			(*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.

			(*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.

			(*HandshakeState) SetPresharedKey(psk []byte) error
			(*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.

		As Outputs Of (at least one exported)
			func NewHandshakeState(c Config) (*HandshakeState, error)

	 type HashFunc (interface)
		A HashFunc implements a cryptographic hash function.

		Methods (total 2)
			( HashFunc) Hash() hash.Hash
				Hash returns a hash state.

			( HashFunc) HashName() string
				HashName is the name of the hash function.

		Implemented By (at least one exported)
			 CipherSuite (interface)
		As Inputs Of (at least one exported)
			func NewCipherSuite(dh DHFunc, c CipherFunc, h HashFunc) CipherSuite
		As Types Of (total 4)
			  var HashBLAKE2b
			  var HashBLAKE2s
			  var HashSHA256
			  var HashSHA512

	 type MessagePattern int (basic type)
		A MessagePattern is a single message or operation used in a Noise handshake.

		As Types Of (total 7)
			const MessagePatternDHEE
			const MessagePatternDHES
			const MessagePatternDHSE
			const MessagePatternDHSS
			const MessagePatternE
			const MessagePatternPSK
			const MessagePatternS


Package-Level Functions (total 3)

	 func NewCipherSuite(dh DHFunc, c CipherFunc, h HashFunc) CipherSuite
		NewCipherSuite returns a CipherSuite constructed from the specified
		primitives.

	 func NewHandshakeState(c Config) (*HandshakeState, error)
		NewHandshakeState starts a new handshake using the provided configuration.

	 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.


Package-Level Variables (total 26)

	  var CipherAESGCM CipherFunc
		CipherAESGCM is the AES256-GCM AEAD cipher.

	  var CipherChaChaPoly CipherFunc
		CipherChaChaPoly is the ChaCha20-Poly1305 AEAD cipher construction.

	  var DH25519 DHFunc
		DH25519 is the Curve25519 ECDH function.

	  var ErrCipherSuiteCopied error
	  var ErrMaxNonce error
	  var ErrShortMessage error
		ErrShortMessage is returned by ReadMessage if a message is not as long as it should be.

	  var HandshakeIK HandshakePattern
	  var HandshakeIN HandshakePattern
	  var HandshakeIX HandshakePattern
	  var HandshakeK HandshakePattern
	  var HandshakeKK HandshakePattern
	  var HandshakeKN HandshakePattern
	  var HandshakeKX HandshakePattern
	  var HandshakeN HandshakePattern
	  var HandshakeNK HandshakePattern
	  var HandshakeNN HandshakePattern
	  var HandshakeNX HandshakePattern
	  var HandshakeX HandshakePattern
	  var HandshakeXK HandshakePattern
	  var HandshakeXN HandshakePattern
	  var HandshakeXX HandshakePattern
	  var HandshakeXXfallback HandshakePattern
	  var HashBLAKE2b HashFunc
		HashBLAKE2b is the BLAKE2b hash function.

	  var HashBLAKE2s HashFunc
		HashBLAKE2s is the BLAKE2s hash function.

	  var HashSHA256 HashFunc
		HashSHA256 is the SHA-256 hash function.

	  var HashSHA512 HashFunc
		HashSHA512 is the SHA-512 hash function.


Package-Level Constants (total 9)

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

	const MaxNonce uint64 = 18446744073709551614
		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.

	const MessagePatternDHEE MessagePattern = 2
	const MessagePatternDHES MessagePattern = 3
	const MessagePatternDHSE MessagePattern = 4
	const MessagePatternDHSS MessagePattern = 5
	const MessagePatternE MessagePattern = 1
	const MessagePatternPSK MessagePattern = 6
	const MessagePatternS MessagePattern = 0

The pages are generated with Golds v0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.