Documentation ¶
Overview ¶
Package nyquist implements the Noise Protocol Framework.
Index ¶
- Constants
- Variables
- type CipherState
- func (cs *CipherState) DecryptWithAd(dst, ad, ciphertext []byte) ([]byte, error)
- func (cs *CipherState) EncryptWithAd(dst, ad, plaintext []byte) ([]byte, error)
- func (cs *CipherState) HasKey() bool
- func (cs *CipherState) InitializeKey(key []byte)
- func (cs *CipherState) Rekey() error
- func (cs *CipherState) Reset()
- func (cs *CipherState) SetNonce(nonce uint64)
- type HandshakeConfig
- type HandshakeObserver
- type HandshakeState
- type HandshakeStatus
- type Protocol
- type SymmetricState
- func (ss *SymmetricState) CipherState() *CipherState
- func (ss *SymmetricState) DecryptAndHash(dst, ciphertext []byte) ([]byte, error)
- func (ss *SymmetricState) EncryptAndHash(dst, plaintext []byte) []byte
- func (ss *SymmetricState) GetHandshakeHash() []byte
- func (ss *SymmetricState) InitializeSymmetric(protocolName []byte)
- func (ss *SymmetricState) MixHash(data []byte)
- func (ss *SymmetricState) MixKey(inputKeyMaterial []byte)
- func (ss *SymmetricState) MixKeyAndHash(inputKeyMaterial []byte)
- func (ss *SymmetricState) Reset()
- func (ss *SymmetricState) Split() (*CipherState, *CipherState)
Constants ¶
const ( // DefaultMaxMessageSize is the default maximum message size. DefaultMaxMessageSize = 65535 PreSharedKeySize = 32 )
const (
// SymmetricKeySize is the size a symmetric key in bytes.
SymmetricKeySize = 32
)
const Version = 34
Version is the revision of the Noise specification implemented.
Variables ¶
var ( // ErrNonceExhausted is the error returned when the CipherState's // nonce space is exhausted. ErrNonceExhausted = errors.New("nyquist: nonce exhausted") // ErrMessageSize is the error returned when an operation fails due // to the message size being exceeded. ErrMessageSize = errors.New("nyquist: oversized message") // ErrOpen is the error returned on a authenticated decryption failure. ErrOpen = errors.New("nyquist: decryption failure") // ErrInvalidConfig is the error returned when the configuration is invalid. ErrInvalidConfig = errors.New("nyquist: invalid configuration") // ErrOutOfOrder is the error returned when ReadMessage/WriteMessage // are called out of order, given the handshake's initiator status. ErrOutOfOrder = errors.New("nyquist: out of order handshake operation") // ErrDone is the error returned when the handshake is complete. ErrDone = errors.New("nyquist: handshake complete") // ErrProtocolNotSupported is the error returned when a requested protocol // is not supported. ErrProtocolNotSupported = errors.New("nyquist: protocol not supported") )
Functions ¶
This section is empty.
Types ¶
type CipherState ¶
type CipherState struct {
// contains filtered or unexported fields
}
CipherState is a keyed AEAD algorithm instance.
func (*CipherState) DecryptWithAd ¶
func (cs *CipherState) DecryptWithAd(dst, ad, ciphertext []byte) ([]byte, error)
DecryptWihtAd authenticates and decrypts the additional data and ciphertext and increments the nonce iff the CipherState is keyed, and otherwise returns the plaintext. If an authentication failure occurs, the nonce is not incremented.
Note: The plaintext is appended to `dst`, and the new slice is returned.
func (*CipherState) EncryptWithAd ¶
func (cs *CipherState) EncryptWithAd(dst, ad, plaintext []byte) ([]byte, error)
EncryptWithAd encrypts and authenticates the additional data and plaintext and increments the nonce iff the CipherState is keyed, and otherwise returns the plaintext.
Note: The ciphertext is appended to `dst`, and the new slice is returned.
func (*CipherState) HasKey ¶
func (cs *CipherState) HasKey() bool
HasKey returns true iff the CipherState is keyed.
func (*CipherState) InitializeKey ¶
func (cs *CipherState) InitializeKey(key []byte)
InitializeKey initializes sets the cipher key to `key`, and nonce to 0.
func (*CipherState) Rekey ¶
func (cs *CipherState) Rekey() error
Rekey sets the CipherState's key to `REKEY(k)`.
func (*CipherState) Reset ¶
func (cs *CipherState) Reset()
Reset sets the CipherState to a un-keyed state.
func (*CipherState) SetNonce ¶
func (cs *CipherState) SetNonce(nonce uint64)
SetNonce sets the CipherState's nonce to `nonce`.
type HandshakeConfig ¶
type HandshakeConfig struct { // Protocol is the noise protocol to use for this handshake. Protocol *Protocol // Prologue is the optional pre-handshake prologue input to be included // in the handshake hash. Prologue []byte // LocalStatic is the local static keypair, if any (`s`). LocalStatic dh.Keypair // LocalEphemeral is the local ephemeral keypair, if any (`e`). LocalEphemeral dh.Keypair // RemoteStatic is the remote static public key, if any (`rs`). RemoteStatic dh.PublicKey // RemoteEphemeral is the remote ephemeral public key, if any (`re`). RemoteEphemeral dh.PublicKey // handshakes. PreSharedKeys [][]byte // Observer is the optional handshake observer. Observer HandshakeObserver // Rng is the entropy source to be used when generating new DH key pairs. // If the value is `nil`, `crypto/rand.Reader` will be used. Rng io.Reader // MaxMessageSize specifies the maximum Noise message size the handshake // and session will process or generate. If the value is `0`, // `DefaultMaxMessageSize` will be used. A negative value will disable // the maximum message size enforcement entirely. // // Warning: Values other than the default is a non-standard extension // to the protocol. MaxMessageSize int // IsInitiator should be set to true if this handshake is in the // initiator role. IsInitiator bool }
HandshakeConfig is a handshake configuration.
Warning: While the config may contain sensitive material like DH private keys or a pre-shared key, sanitizing such things are the responsibility of the caller, after the handshake completes (or aborts due to an error).
Altering any of the members of this structure while a handshake is in progress will result in undefined behavior.
type HandshakeObserver ¶
type HandshakeObserver interface { // OnPeerPublicKey will be called when a public key is received from // the peer, with the handshake pattern token (`pattern.Token_e`, // `pattern.Token_s`) and public key. // // Returning a non-nil error will abort the handshake immediately. OnPeerPublicKey(pattern.Token, dh.PublicKey) error }
HandshakeObserver is a handshake observer for monitoring handshake status.
type HandshakeState ¶
type HandshakeState struct {
// contains filtered or unexported fields
}
HandshakeState is the per-handshake state.
func NewHandshake ¶
func NewHandshake(cfg *HandshakeConfig) (*HandshakeState, error)
NewHandshake constructs a new HandshakeState with the provided configuration. This call is equivalent to the `Initialize` HandshakeState call in the Noise Protocol Framework specification.
func (*HandshakeState) GetStatus ¶
func (hs *HandshakeState) GetStatus() *HandshakeStatus
GetStatus returns the HandshakeState's status.
func (*HandshakeState) ReadMessage ¶
func (hs *HandshakeState) ReadMessage(dst, payload []byte) ([]byte, error)
ReadMessage processes a read step of the handshake protocol, appending the authentiated/decrypted message payload to dst, and returning the potentially new slice.
Iff the handshake is complete, the error returned will be `ErrDone`.
func (*HandshakeState) Reset ¶
func (hs *HandshakeState) Reset()
Reset clears the HandshakeState, to prevent future calls.
Warning: If either of the local keypairs were provided by the HandshakeConfig, they will be left intact.
func (*HandshakeState) SymmetricState ¶
func (hs *HandshakeState) SymmetricState() *SymmetricState
SymmetricState returns the HandshakeState's encapsulated SymmetricState.
Warning: There should be no reason to call this, ever.
func (*HandshakeState) WriteMessage ¶
func (hs *HandshakeState) WriteMessage(dst, payload []byte) ([]byte, error)
WriteMessage processes a write step of the handshake protocol, appending the handshake protocol message to dst, and returning the potentially new slice.
Iff the handshake is complete, the error returned will be `ErrDone`.
type HandshakeStatus ¶
type HandshakeStatus struct { // Err is the error representing the status of the handshake. // // It will be `nil` if the handshake is in progess, `ErrDone` if the // handshake is complete, and any other error if the handshake has failed. Err error // LocalEphemeral is the local ephemeral public key, if any (`e`). LocalEphemeral dh.PublicKey // RemoteStatic is the remote static public key, if any (`rs`). RemoteStatic dh.PublicKey // RemoteEphemeral is the remote ephemeral public key, if any (`re`). RemoteEphemeral dh.PublicKey // CipherStates is the resulting CipherState pair (`(cs1, cs2)`). // // Note: To prevent misuse, for one-way patterns `cs2` will be nil. CipherStates []*CipherState // HandshakeHash is the handshake hash (`h`). This field is only set // once the handshake is completed. HandshakeHash []byte }
HandshakeStatus is the status of a handshake.
Warning: It is the caller's responsibility to sanitize the CipherStates if desired. Altering any of the members of this structure while a handshake is in progress will result in undefined behavior.
type Protocol ¶
Protocol is a the protocol to be used with a handshake.
func NewProtocol ¶
NewProtocol returns a Protocol from the provided (case-sensitive) protocol name. Returned protocol objects may be reused across multiple HandshakeConfigs.
Note: Only protocols that can be built with the built-in crypto and patterns are supported. Using custom crypto/patterns will require manually building a Protocol object.
type SymmetricState ¶
type SymmetricState struct {
// contains filtered or unexported fields
}
SymmetricState encapsulates all symmetric cryptography used by the Noise protocol during a handshake.
Warning: There should be no reason to interact directly with this ever.
func (*SymmetricState) CipherState ¶
func (ss *SymmetricState) CipherState() *CipherState
CipherState returns the SymmetricState's encapsualted CipherState.
Warning: There should be no reason to call this, ever.
func (*SymmetricState) DecryptAndHash ¶
func (ss *SymmetricState) DecryptAndHash(dst, ciphertext []byte) ([]byte, error)
DecryptAndHash authenticates and decrypts the ciphertext, mixes the ciphertext with the handshake hash, appends the plaintext to dst, and returns the potentially new slice.
func (*SymmetricState) EncryptAndHash ¶
func (ss *SymmetricState) EncryptAndHash(dst, plaintext []byte) []byte
EncryptAndHash encrypts and authenticates the plaintext, mixes the ciphertext with the handshake hash, appends the ciphertext to dst, and returns the potentially new slice.
func (*SymmetricState) GetHandshakeHash ¶
func (ss *SymmetricState) GetHandshakeHash() []byte
GetHandshakeHash returns the handshake hash `h`.
func (*SymmetricState) InitializeSymmetric ¶
func (ss *SymmetricState) InitializeSymmetric(protocolName []byte)
InitializeSymmetric initializes the SymmetricState with the initial chaining key and handshake hash, based on the protocol name.
func (*SymmetricState) MixHash ¶
func (ss *SymmetricState) MixHash(data []byte)
MixHash mixes the provided data with the handshake hash.
func (*SymmetricState) MixKey ¶
func (ss *SymmetricState) MixKey(inputKeyMaterial []byte)
MixKey mixes the provided material with the chaining key, and initializes the encapsulated CipherState's key with the output.
func (*SymmetricState) MixKeyAndHash ¶
func (ss *SymmetricState) MixKeyAndHash(inputKeyMaterial []byte)
MixKeyAndHash mises the provided material with the chaining key, and mixes the handshake and initializes the encapsulated CipherState with the output.
func (*SymmetricState) Reset ¶
func (ss *SymmetricState) Reset()
Reset clears the SymmetricState, to prevent future calls.
Warning: The transcript hash (`h`) is left intact to allow for clearing this state as early as possible, while preserving the ability to call `GetHandshakeHash`.
func (*SymmetricState) Split ¶
func (ss *SymmetricState) Split() (*CipherState, *CipherState)
Split returns a pair of CipherState objects for encrypted transport messages.
Directories ¶
Path | Synopsis |
---|---|
Package cipher implments the Noise Protocol Framework cipher function abstract interface and standard cipher functions.
|
Package cipher implments the Noise Protocol Framework cipher function abstract interface and standard cipher functions. |
Package dh implments the Noise Protocol Framework Diffie-Hellman function abstract interface and standard DH functions.
|
Package dh implments the Noise Protocol Framework Diffie-Hellman function abstract interface and standard DH functions. |
Package hash implments the Noise Protocol Framework hash function abstract interface and standard hash functions.
|
Package hash implments the Noise Protocol Framework hash function abstract interface and standard hash functions. |
Package pattern implements the Noise Protocol Framework handshake pattern abstract interface and standard patterns.
|
Package pattern implements the Noise Protocol Framework handshake pattern abstract interface and standard patterns. |
Package vectors provides types for the JSON formatted test vectors.
|
Package vectors provides types for the JSON formatted test vectors. |