unclassified

Documentation

Overview

Package secretbox encrypts and authenticates small messages.

Secretbox uses XSalsa20 and Poly1305 to encrypt and authenticate messages with secret-key cryptography. The length of messages is not hidden.

It is the caller's responsibility to ensure the uniqueness of nonces—for example, by using nonce 1 for the first message, nonce 2 for the second message, etc. Nonces are long enough that randomly generated nonces have negligible risk of collision.

Messages should be small because:

1. The whole message needs to be held in memory to be processed.

2. Using large messages pressures implementations on small machines to decrypt and process plaintext before authenticating it. This is very dangerous, and this API does not allow it, but a protocol that uses excessive message sizes might present some implementations with no other choice.

3. Fixed overheads will be sufficiently amortised by messages as small as 8KB.

4. Performance may be improved by working with messages that fit into data caches.

Thus large amounts of data should be chunked so that each message is small. (Each message still needs a unique nonce.) If in doubt, 16KB is a reasonable chunk size.

This package is interoperable with NaCl: https://nacl.cr.yp.to/secretbox.html.

Index

• Constants
• Variables
• func Chacha20_HChaCha20(key, nonce []byte) ([]byte, error)
• func Curve25519_X25519(scalar, point []byte) ([]byte, error)
• func Open(out, box []byte, nonce *[NonceSize]byte, key *[KeySize]byte) ([]byte, error)
• func OpenX(out, nonce, box, key []byte) ([]byte, error)
• func Seal(out, message []byte, nonce *[NonceSize]byte, key *[KeySize]byte) []byte
• func SealX(out, nonce, message, key []byte) []byte
• type Cipher
  • func (s *Cipher) SetCounter(counter uint32)
  • func (s *Cipher) XORKeyStream(dst, src []byte)
• type MAC
  • func (h *MAC) Sum(b []byte) []byte
  • func (h *MAC) Verify(expected []byte) bool
  • func (h *MAC) Write(p []byte) (n int, err error)

Constants

const (
	KeySize   = 32
	NonceSize = 24
	TagSize   = poly1305_TagSize
)

const Overhead = TagSize

Overhead is the number of bytes of overhead when boxing a message.

Variables

var Curve25519_Basepoint []byte

Functions

func Chacha20_HChaCha20

func Chacha20_HChaCha20(key, nonce []byte) ([]byte, error)

func Curve25519_X25519

func Curve25519_X25519(scalar, point []byte) ([]byte, error)

func Open

func Open(out, box []byte, nonce *[NonceSize]byte, key *[KeySize]byte) ([]byte, error)

Open authenticates and decrypts a box produced by Seal and appends the message to out, which must not overlap box. The output will be Overhead bytes smaller than box.

func OpenX

func OpenX(out, nonce, box, key []byte) ([]byte, error)

OpenX authenticates and decrypts a box produced by SealX and appends the message to out, which must not overlap box. The output will be Overhead bytes smaller than box.

func Seal

func Seal(out, message []byte, nonce *[NonceSize]byte, key *[KeySize]byte) []byte

Seal appends an encrypted and authenticated copy of message to out, which must not overlap message. The key and nonce pair must be unique for each distinct message and the output will be Overhead bytes longer than message.

func SealX

func SealX(out, nonce, message, key []byte) []byte

SealX appends an encrypted and authenticated copy of message to out, which must not overlap message. The key and nonce pair must be unique for each distinct message and the output will be Overhead bytes longer than message.

Types

type Cipher

type Cipher struct{}

func (*Cipher) SetCounter

func (s *Cipher) SetCounter(counter uint32)

func (*Cipher) XORKeyStream

func (s *Cipher) XORKeyStream(dst, src []byte)

type MAC

type MAC struct{}

func (*MAC) Sum

func (h *MAC) Sum(b []byte) []byte

func (*MAC) Verify

func (h *MAC) Verify(expected []byte) bool

func (*MAC) Write

func (h *MAC) Write(p []byte) (n int, err error)