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
NewAPI uses the stdlib'scrypto/aespackage. - The
NewAESAPI 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 ¶
const BlockSize = 16
BlockSize is the size of block allowed by this package.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cipher ¶
type Cipher struct {
// contains filtered or unexported fields
}
Cipher is an instance of the HCTR2 cipher.
func New ¶
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 ¶
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 ¶
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.
Source Files
Directories