stupidgcm

Documentation

Overview

Package stupidgcm wraps OpenSSL to provide a cipher.AEAD interface for authenticated encryption algorithms.

The supported algorithms are:

(1) AES-GCM-256 (OpenSSL EVP_aes_256_gcm)

(2) ChaCha20-Poly1305 (OpenSSL EVP_chacha20_poly1305)

(3) XChaCha20-Poly1305 (OpenSSL EVP_chacha20_poly1305 + Go HChaCha20)

The golang.org/x/crypto libraries provides implementations for all algorithms, and the test suite verifies that the implementation in this package gives the exact same results.

However, OpenSSL has optimized assembly for almost all platforms, which Go does not. Example for a 32-bit ARM device (Odroid XU4):

$ gocrypts -speed
gocryptfs v2.1-68-gedf9d4c.stupidchacha; go-fuse v2.1.1-0.20210825171523-3ab5d95a30ae; 2021-09-04 go1.16.7 linux/arm
AES-GCM-256-OpenSSL               56.84 MB/s    (selected in auto mode)
AES-GCM-256-Go                    16.61 MB/s
AES-SIV-512-Go                    16.49 MB/s
XChaCha20-Poly1305-Go             39.08 MB/s    (use via -xchacha flag)
XChaCha20-Poly1305-OpenSSL       141.82 MB/s

This package is "stupid" in the sense that it only supports a narrow set of key- and iv-lengths, and panics if it does not like what you pass it. See the constructor functions for which restrictions apply for each algorithm. Also, it is only tested for block lengths up to 5000 bytes, because this is what gocryptfs uses.

Corrupt ciphertexts never cause a panic. Instead, ErrAuth is returned on decryption.

XChaCha20-Poly1305

The XChaCha20-Poly1305 implementation is more complicated than the others, because OpenSSL does not support XChaCha20-Poly1305 directly. Follow https://github.com/openssl/openssl/issues/5523 to get notified when it is accepted into OpenSSL.

Fortunately, XChaCha20-Poly1305 is just ChaCha20-Poly1305 with some key+iv mixing using HChaCha20 in front:

key (32 bytes), iv (24 bytes)
 |
 v
HChaCha20 (provided by golang.org/x/crypto/chacha20)
 |
 v
key2 (32 bytes), iv2 (16 bytes)
 |
 v
ChaCha20-Poly1305 (OpenSSL EVP_chacha20_poly1305)

As HChaCha20 is very fast, XChaCha20-Poly1305 gets almost the same throughput as ChaCha20-Poly1305 (for 4kiB blocks).

Index

• Constants
• Variables
• func CpuHasAES() bool
• func NewAES256GCM(keyIn []byte) cipher.AEAD
• func NewChacha20poly1305(key []byte) cipher.AEAD
• func NewXchacha20poly1305(key []byte) cipher.AEAD
• func PreferOpenSSLAES256GCM() bool
• func PreferOpenSSLXchacha20poly1305() bool

Constants

const (
	// BuiltWithoutOpenssl indicates if openssl been disabled at compile-time
	BuiltWithoutOpenssl = false
)

Variables

var ErrAuth = fmt.Errorf("stupidgcm: message authentication failed")

ErrAuth is returned when the message authentication fails

Functions

func CpuHasAES

func CpuHasAES() bool

CpuHasAES tells you if the CPU we are running has AES acceleration that is usable by the Go crypto library.

func NewAES256GCM

func NewAES256GCM(keyIn []byte) cipher.AEAD

NewAES256GCM returns a new AES-256-GCM cipher that satisfies the cipher.AEAD interface.

Only 32-bytes keys and 16-byte IVs are supported.

func NewChacha20poly1305

func NewChacha20poly1305(key []byte) cipher.AEAD

NewChacha20poly1305 returns a new instance of the OpenSSL ChaCha20-Poly1305 AEAD cipher ( https://www.openssl.org/docs/man1.1.1/man3/EVP_chacha20_poly1305.html ).

gocryptfs only uses ChaCha20-Poly1305 as a building block for OpenSSL XChaCha20-Poly1305. This function is hot because it gets called once for each block by XChaCha20-Poly1305.

Only 32-bytes keys and 12-byte IVs are supported.

func NewXchacha20poly1305

func NewXchacha20poly1305(key []byte) cipher.AEAD

NewXchacha20poly1305 returns a XChaCha20-Poly1305 cipher that satisfied the cipher.AEAD interface.

XChaCha20-Poly1305 is a ChaCha20-Poly1305 variant that takes a longer nonce, suitable to be generated randomly without risk of collisions. It should be preferred when nonce uniqueness cannot be trivially ensured, or whenever nonces are randomly generated.

Only 32-bytes keys and 24-byte IVs are supported.

func PreferOpenSSLAES256GCM

func PreferOpenSSLAES256GCM() bool

PreferOpenSSLAES256GCM tells us if OpenSSL AES-256-GCM is faster than Go stdlib on this machine.

Go GCM is only faster if the CPU either:

1. Is X86_64 && has AES instructions && Go is v1.6 or higher
2. Is ARM64 && has AES instructions && Go is v1.11 or higher (commit https://github.com/golang/go/commit/4f1f503373cda7160392be94e3849b0c9b9ebbda)

See https://github.com/rfjakob/gocryptfs/wiki/CPU-Benchmarks for benchmarks.

func PreferOpenSSLXchacha20poly1305

func PreferOpenSSLXchacha20poly1305() bool

PreferOpenSSLXchacha20poly1305 returns true if OpenSSL Xchacha20poly1305 is faster than Go stdlib on this machine.