norx

README

NORX - A Parallel and Scalable Authenticated Encryption Algorithm

Yawning Angel (yawning at schwanenlied dot me)

Warning

NORX is a rather new authenticated encryption algorithm. The authors are confident that it is secure but nevertheless NORX should be considered experimental. Therefore, do not use it in your applications!

This package implements the NORX Authenticated Encryption Algorithm, specifically the NORX64-4-1 and NORX64-6-1 variants, as recommended by the designers for software implementations on modern 64-bit CPUs.

This implementation is derived from the Public Domain reference implementation by Jean-Philippe Aumasson, Philipp Jovanovic, and Samuel Neves.

Documentation

Overview

Package norx implements the NORX Authenticated Encryption Algorithm, specifically the NORX64-4-1 and NORX64-6-1 variants, as recommended by the designers for software implementations on modern 64-bit CPUs.

This implementation is derived from the Public Domain reference implementation by Jean-Philippe Aumasson, Philipp Jovanovic, and Samuel Neves.

Warning: NORX is a rather new authenticated encryption algorithm. The authors are confident that it is secure but nevertheless NORX should be considered experimental. Therefore, do not use it in your applications!

Index

• Constants
• Variables
• func IsHardwareAccelerated() bool
• type AEAD
  • func New6441(key []byte) *AEAD
  • func New6461(key []byte) *AEAD
  • func (ae *AEAD) NonceSize() int
  • func (ae *AEAD) Open(dst, nonce, ciphertext, header, footer []byte) ([]byte, error)
  • func (ae *AEAD) Overhead() int
  • func (ae *AEAD) Reset()
  • func (ae *AEAD) Seal(dst, nonce, plaintext, header, footer []byte) []byte
  • func (ae *AEAD) ToRuntime() cipher.AEAD

Constants

const (
	// KeySize is the size of a key in bytes.
	KeySize = 32

	// NonceSize is the size of a nonce in bytes.
	NonceSize = 32

	// TagSize is the size of an authentication tag in bytes.
	TagSize = 32

	// Version is the version of the NORX specification implemented.
	Version = "3.0"
)

Variables

var (
	// ErrInvalidKeySize is the error thrown via a panic when a key is an
	// invalid size.
	ErrInvalidKeySize = errors.New("norx: invalid key size")

	// ErrInvalidNonceSize is the error thrown via a panic when a nonce is
	// an invalid size.
	ErrInvalidNonceSize = errors.New("norx: invalid nonce size")

	// ErrOpen is the error returned when the message authentication fails
	// during an Open call.
	ErrOpen = errors.New("norx: message authentication failed")
)

Functions

func IsHardwareAccelerated

func IsHardwareAccelerated() bool

IsHardwareAccelerated returns true iff the NORX implementation will use hardware acceleration (eg: AVX2).

Types

type AEAD

type AEAD struct {
	// contains filtered or unexported fields
}

AEAD is a parameterized and keyed NORX instance, in the spirit of crypto/cipher.AEAD.

func New6441

func New6441(key []byte) *AEAD

New6441 returns a new keyed NORX64-4-1 instance.

func New6461

func New6461(key []byte) *AEAD

New6461 returns a new keyed NORX64-6-1 instance.

func (*AEAD) NonceSize

func (ae *AEAD) NonceSize() int

NonceSize returns the size of the nonce that must be passed to Seal and Open.

func (*AEAD) Open

func (ae *AEAD) Open(dst, nonce, ciphertext, header, footer []byte) ([]byte, error)

Open decrypts and authenticates ciphertext, authenticates the optonal header and footer (additional data) and, if successful, appends the resulting plaintext to dst, returning the updated slice. The nonce must be NonceSize() bytes long and both it and the additional data must match the value passed to Seal.

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 its capacity, may be overwritten.

func (*AEAD) Overhead

func (ae *AEAD) Overhead() int

Overhead returns the maximum difference between the lengths of a plaintext and its ciphertext.

func (*AEAD) Reset

func (ae *AEAD) Reset()

Reset securely purges stored sensitive data from the AEAD instance.

func (*AEAD) Seal

func (ae *AEAD) Seal(dst, nonce, plaintext, header, footer []byte) []byte

Seal encrypts and authenticates plaintext, authenticates the optional header and footer (additional data) and, appends the result to dst, returning the updated slice. The nonce must be NonceSize() bytes long and unique for all time, for a given key.

The plaintext and dst must overlap exactly or not at all. To reuse plaintext's storage for the encrypted output, use plaintext[:0] as dst.

func (*AEAD) ToRuntime

func (ae *AEAD) ToRuntime() cipher.AEAD

ToRuntime converts an AEAD instance to a crypto/cipher.AEAD instance.

The interfaces are distinct as NORX supports both a header and footer as additional data, while the runtime interface only has a singular additonal data parameter. The resulting cipher.AEAD instance will use the header for additional data if provided, ignoring the footer.