cipher

README

Cipher Functions

This package implements the cipher functions specified in the noise protocol framework.

Built-in Ciphers

Two cipher functions are supported, as specified in the noise specs.

1. AESGCM

   AESGCM is implemented based upon the official Go cipher package crypto/aes. Use it with caution though, as the AES operations in the crypto/aes package are not implemented using constant-time algorithms, which makes it vunerable to side channel attack.

   However, if the package is running on systems with hardware support for AES then it won't be an issue. More details can be found following this discussion.

   As for this package, AESGCM is tuned based on the noise specs:

   AES256 with GCM with a 128-bit tag appended to the ciphertext. The 96-bit nonce is formed by encoding 32 bits of zeros followed by big-endian encoding of n.

2. ChaChaPoly

   ChaChaPoly is implemented based on golang.org/x/crypto/chacha20poly1305 by using the ChaCha20-Poly1305 AEAD.

Customized Cipher Functions

To create your own cipher function, you'll need to implement the interface specified in cipher.go. Once implemented, you need to register it using Register(Name, Cipher).

Check examples/newcipher, which implements ChaChaPolyX, once implemented, Once implemented, it can be used via the protocol name,

// Register it for package babble.
noiseCipher.Register("ChaChaPolyX", newCipher)

// Now "ChaChaPolyX" is a valid hash name, and it can be used in the protocol name as,
p, _ := babble.NewProtocol("Noise_NN_25519_ChaChaPolyX_BLAKE2s", "Demo", true)

Documentation

Overview

Package cipher implements the cipher functions specified in the noise protocol.

It currently supports two ciphers:

• ChaCha20Poly1350, which uses https://golang.org/x/crypto/chacha20poly1305.
• AESGCM, which uses https://pkg.go.dev/crypto/aes. Be cautious when using this cipher as it might be vunlerable to side channel attack.

Index

• Constants
• Variables
• func Register(s string, f NewCipher)
• func SupportedCiphers() string
• type AEAD
  • func FromString(s string) (AEAD, error)
• type NewCipher

Examples

• FromString

Constants

const (

	// KeySize defines the size of the cipher key, in bytes.
	KeySize = 32

	// MaxNonce is an 8-byte unsigned integer and equals to 2^64-1.
	MaxNonce = ^uint64(0)
)

Variables

var (
	// ErrNonceOverflow is used when the nonce exceeds the 2^64-1 limit.
	ErrNonceOverflow = errors.New("nonce is too big")

	// ZEROLEN is a zero-length byte sequence.
	ZEROLEN []byte

	// ZEROS is a 32-byte array filled with zeros.
	ZEROS [KeySize]byte
)

Functions

func Register

func Register(s string, f NewCipher)

Register updates the supported ciphers used in package cipher.

func SupportedCiphers

func SupportedCiphers() string

SupportedCiphers gives the names of all the ciphers registered. If no new ciphers are registered, it returns a string as "AESGCM, ChaChaPoly", orders not preserved.

Types

type AEAD

type AEAD interface {
	fmt.Stringer

	// Cipher returns a cipher.AEAD. This function enforces that any cipher
	// implement this AEAD interface must also satisfy the cipher.AEAD.
	Cipher() cipher.AEAD

	// Decrypt uses a cipher key k of 32 bytes, an 8-byte unsigned integer nonce
	// n, and associated data ad, and returns the plaintext, unless
	// authentication fails, in which case an error is returned.
	Decrypt(n uint64, ad, ciphertext []byte) ([]byte, error)

	// EncodeNonce turns the nonce used in the noise protocol into a format
	// that's accepted by the specific cipher specs.
	EncodeNonce(n uint64) []byte

	// Encrypt uses the cipher key k of 32 bytes and an 8-byte unsigned integer
	// nonce n which must be unique for the key k, and returns the ciphertext.
	// Encryption must be done with an "AEAD" encryption mode with the
	// associated data ad and returns a ciphertext that is the same size as the
	// plaintext plus 16 bytes for authentication data.
	Encrypt(n uint64, ad, plaintext []byte) ([]byte, error)

	// InitCipher creates a cipher with the secret key.
	InitCipher(key [KeySize]byte) error

	// Rekey creates a new 32-byte cipher key as a pseudorandom function of key.
	// It returns the first 32 bytes from calling Encrypt with,
	//  - n as maxnonce, which equals 2^64-1,
	//  - ad as zerolen, a zero-length byte sequence,
	//  - plaintext as zeros, a sequence of 32 bytes filled with zeros.
	Rekey() [KeySize]byte

	// Reset cleans all the states to zero value, if any.
	Reset()
}

AEAD specifies an interface for building a cipher used by the babbel package.

func FromString

func FromString(s string) (AEAD, error)

FromString uses the provided cipher name, s, to query a built-in cipher.

Example

package main

import (
	"fmt"

	"github.com/yyforyongyu/babble/cipher"
)

func main() {
	// load cipher AESGCM
	aesgcm, _ := cipher.FromString("AESGCM")
	fmt.Println(aesgcm)

	// load cipher ChaChaPoly
	ccp, _ := cipher.FromString("ChaChaPoly")
	fmt.Println(ccp)
}

type NewCipher

type NewCipher func() AEAD

NewCipher returns an instance of a cipher.