api

Documentation

Overview

Package api implements the MRAE API and common helpers.

Index

• func Bzero(b []byte)
• func ECDHAndTweak(key []byte, publicKey, privateKey *[32]byte, h func() hash.Hash, tweak []byte)
• func GenerateKeyPair(rng io.Reader) (publicKey, privateKey *[32]byte, err error)
• func TestBoxIntegration(t *testing.T, impl Box, ctor func([]byte) (cipher.AEAD, error), keySize int)
• type Box

Functions

func Bzero

func Bzero(b []byte)

Bzero clears the slice.

func ECDHAndTweak

func ECDHAndTweak(key []byte, publicKey, privateKey *[32]byte, h func() hash.Hash, tweak []byte)

ECDHAndTweak applies the X25519 scalar multiply with the given public and private keys, and applies a HMAC based tweak to the resulting output.

func GenerateKeyPair

func GenerateKeyPair(rng io.Reader) (publicKey, privateKey *[32]byte, err error)

GenerateKeyPair generates a public/private key pair suitable for use with the Box interface.

func TestBoxIntegration

func TestBoxIntegration(t *testing.T, impl Box, ctor func([]byte) (cipher.AEAD, error), keySize int)

TestBoxIntegration tests a box implementation.

Types

type Box

type Box interface {
	// DeriveSymmetricKey derives a MRAE AEAD symmetric key suitable for
	// use with the Box API from the provided X25519 public and private keys.
	DeriveSymmetricKey(key []byte, publicKey, privateKey *[32]byte)

	// Seal seals ("boxes") the provided additional data and plaintext
	// via the MRAE AEAD primitive using a symmetric key derived from the
	// provided X25519 public and private keys, appending the result
	// to dst, returning the updated slice.  The nonce MUST be
	// aead.NonceSize() bytes long and SHOULD be unique for all time,
	// for a given public and private key tuple.
	//
	// The plaintext and dst must overlap exactly or not at all.  To reuse
	// plaintext's storage for encrypted output, use plaintext[:0] as dst.
	Seal(dst, nonce, plaintext, additionalData []byte, peersPublicKey, privateKey *[32]byte) []byte

	// Open opens ("unboxes") the provided additional data and ciphertext
	// via the MRAE AEAD primitive using a symmetric key dervied from the
	// provided X25519 public and private keys and, if successful, appends
	// the resulting plaintext to dst, returning the updated slice. The
	// nonce MUST be aead.NonceSize() bytes long and SHOULD be unique for
	// all time, for a given public and private key tuple.
	//
	// The ciphertext and dst must overlap exactly or not at all.  To reuse
	// ciphertext's storage for the decrypted output, use ciphertext[:0] as dst.
	//
	// Even if the function fails, the contents of dst, up to it's capacity,
	// may be overwritten.
	Open(dst, nonce, plaintext, additionalData []byte, peersPublicKey, privateKey *[32]byte) ([]byte, error)
}

Box is the interface for using MRAE AEAD primitives with asymmetric public key cryptography.