aegis

README

aegis

This module implements the AEGIS-128L and AEGIS-256 AEAD algorithms.

See https://competitions.cr.yp.to/round3/aegisv11.pdf or https://www.ietf.org/archive/id/draft-denis-aegis-aead-00.html for more information.

Installation

go get github.com/ericlagergren/aegis@latest

Usage

The APIs conform to Go's crypto/cipher package. Note that the following example is not a substitute for reading the package documentation.

package main

import (
	"crypto/rand"

	"github.com/ericlagergren/aegis"
)

func main() {
	key := make([]byte, aegis.KeySize128L)
	if _, err := rand.Read(key); err != nil {
		// rand.Read failing is almost always catastrophic.
		panic(err)
	}

	nonce := make([]byte, aegis.NonceSize128L)
	if _, err := rand.Read(nonce); err != nil {
		// rand.Read failing is almost always catastrophic.
		panic(err)
	}

	aead, err := aegis.New(key)
	if err != nil {
		// New will only return an error if the key is an invalid
		// length.
		panic(err)
	}

	// Plaintext is encrypted and authenticated.
	plaintext := []byte("example plaintext")

	// Additional data is authenticated alongside the plaintext,
	// but not included in the ciphertext.
	additionalData := []byte("example additional authenticated data")

	// Encrypt and authenticate |plaintext| and authenticate
	// |additionalData|.
	ciphertext := aead.Seal(nil, nonce, plaintext, additionalData)

	// Decrypt and authentiate |ciphertext| and authenticate
	// |additionalData|.
	plaintext, err = aead.Open(nil, nonce, ciphertext, additionalData)
	if err != nil {
		// Authentication failed. Either the ciphertext or
		// additionalData (or both) were invalid for the 
		// (key, nonce) pair.
		[...]
	}
}

Performance

The x86-64 and ARMv8 assembly implementations run at 0.3 and 0.4 cycles per byte, respectively. The x86-64 implementation requires SSE4.1 and AES instructions. The ARMv8 implementation requires NEON and AES instructions.

The default pure Go implementation will be selected if the CPU does not support either assembly implementation. (This implementation can also be selected with the purego build tag.) It is much slower at around 5.6 cycles per byte.

Note also that the pure Go implementation uses S-boxes and leaks cache timing information. See golang.org/issues/13795 for more information.

Security

Disclosure

This project uses full disclosure. If you find a security bug in an implementation, please e-mail me or create a GitHub issue.

Disclaimer

You should only use cryptography libraries that have been reviewed by cryptographers or cryptography engineers. While I am a cryptography engineer, I'm not your cryptography engineer, and I have not had this project reviewed by any other cryptographers.

Documentation

Overview

Package aegis implements the AEGIS AEAD algorithm.

[aegis]: https://www.ietf.org/archive/id/draft-denis-aegis-aead-00.html

Index

• Constants
• func New(key []byte) (cipher.AEAD, error)

Constants

const (
	// KeySize128L is the size in bytes of an AEGIS-128L key.
	KeySize128L = 16
	// NonceSize128L is the size in bytes of an AEGIS-128L nonce.
	NonceSize128L = 16
	// TagSize128L is the size in bytes of an AEGIS-128L
	// authentication tag.
	TagSize128L = 16
	// BlockSize128L is the size in bytes of an AEGIS-128L block.
	BlockSize128L = 32

	// MaxPlaintextSize128L is the size in bytes of the largest
	// allowed AESGIS-128L plaintext.
	MaxPlaintextSize128L = 1 << 61
	// MaxAdditionalDataSize128L is the size in bytes of the
	// largest allowed AEGIS-128L additional data.
	MaxAdditionalDataSize128L = 1 << 61

	// KeySize256 is the size in bytes of an AEGIS-256 key.
	KeySize256 = 32
	// NonceSize256 is the size in bytes of an AEGIS-256 nonce.
	NonceSize256 = 32
	// TagSize256 is the size in bytes of an AEGIS-256
	// authentication tag.
	TagSize256 = 16
	// BlockSize256 is the size in bytes of an AEGIS-256 block.
	BlockSize256 = 16

	// MaxPlaintextSize256 is the size in bytes of the largest
	// allowed AESGIS-256 plaintext.
	MaxPlaintextSize256 = 1 << 61
	// MaxAdditionalDataSize256 is the size in bytes of the
	// largest allowed AEGIS-256 additional data.
	MaxAdditionalDataSize256 = 1 << 61
)

Functions

func New

func New(key []byte) (cipher.AEAD, error)

New creates an instance of the AEGIS AEAD algorithm.

New accepts two key lengths. If the key is 128 bits, New returns an instance of AEGIS-128L. Otherwise, if the key is 256 bits, New returns an instance of AEGIS-256. Any other key lengths are an error.