hctr2

README

hctr2

Length-preserving encryption algorithm https://eprint.iacr.org/2021/1441.pdf

Installation

go get github.com/ericlagergren/hctr2@latest

Performance

The performance of HCTR2 is primarily determined by the XCTR and POLYVAL implementations. This module provides ARMv8 and x86-64 assembly XCTR implementations and uses a hardware-accelerated POLYVAL implementation (see github.com/ericlagergren/polyval).

Results

CPU	ISA	Frequency	Cycles per byte	API
M1	ARMv8	3.2 GHz	0.8	NewAES
M1	ARMv8	3.2 GHz	3.2	New
M1	x86	2.5 GHz	0.7	NewAES
RK3399	ARMv8	1.8 GHz	2.7	NewAES
RK3399	ARMv8	1.8 GHz	6.1	New
Skylake	x86	3.9 GHz	1.4	NewAES
Skylake	x86	3.9 GHz	6.1	New

For reference, here are the numbers for the reference C implementation.

CPU	ISA	Frequency	Cycles per byte	API
RK3399	ARMv8	1.8 GHz	1.8	simd
Skylake	x86	3.9 GHz	1.2	simd

Notes

• The table is computed for 8192-byte messages.
• The table is for encryption (decryption is equivalent).
• The New API uses the stdlib's crypto/aes package.
• The NewAES API uses this package's assembly XCTR implementation.
• CPU frequencies are approximate and always assume the maximum available frequency. E.g., benchmarks for big.LITTLE CPUs are assumed to only use the big cores.

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 HCTR2 implements the HCTR2 length-preserving encryption algorithm.

HCTR2 is designed for situations where the length of the ciphertext must exactly match the length of the plaintext, like disk encryption.

This implementation uses a hardware-accelerated POLYVAL implementation when possible; the block cipher is left to the caller. The recommended block cipher is AES.

Index

• Constants
• type Cipher
  • func New(block cipher.Block) (*Cipher, error)
  • func NewAES(key []byte) (*Cipher, error)
  • func (c *Cipher) Decrypt(plaintext, ciphertext, tweak []byte)
  • func (c *Cipher) Encrypt(ciphertext, plaintext, tweak []byte)

Constants

const BlockSize = 16

BlockSize is the size of block allowed by this package.

Types

type Cipher

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

Cipher is an instance of the HCTR2 cipher.

func New

func New(block cipher.Block) (*Cipher, error)

New creates a HCTR2 cipher.

The provided Block must have a block size of exactly BlockSize. This restriction may be lifted in the future.

The recommended block cipher is AES.

func NewAES

func NewAES(key []byte) (*Cipher, error)

NewAES creates a HCTR2 cipher using AES.

If supported, the returned Cipher will use a hardware XCTR implementation. Otherwise, it defers to crypto/aes.

The provided AES key should be either 16, 24, or 32 bytes to choose AES-128, AES-192, or AES-256, respectively.

func (*Cipher) Decrypt

func (c *Cipher) Decrypt(plaintext, ciphertext, tweak []byte)

Decrypt decrypts ciphertext with tweak and writes the result to plaintext.

The length of plaintext must be greater than or equal to the length of plaintext.

plaintext and ciphertext must overlap entirely or not at all.

func (*Cipher) Encrypt

func (c *Cipher) Encrypt(ciphertext, plaintext, tweak []byte)

Encrypt encrypts plaintext with tweak and writes the result to ciphertext.

plaintext must be at least one block long.

The length of ciphertext must be greater than or equal to the length of plaintext.

ciphertext and plaintext must overlap entirely or not at all.