stupidgcm: revamp package documentation
Maybe interesting for people following https://github.com/rfjakob/gocryptfs/issues/452
This commit is contained in:
parent
d598536709
commit
f47e287c20
|
@ -35,6 +35,8 @@ func init() {
|
||||||
// gocryptfs only uses ChaCha20-Poly1305 as a building block for OpenSSL
|
// gocryptfs only uses ChaCha20-Poly1305 as a building block for OpenSSL
|
||||||
// XChaCha20-Poly1305. This function is hot because it gets called once for each
|
// XChaCha20-Poly1305. This function is hot because it gets called once for each
|
||||||
// block by XChaCha20-Poly1305.
|
// block by XChaCha20-Poly1305.
|
||||||
|
//
|
||||||
|
// Only 32-bytes keys and 12-byte IVs are supported.
|
||||||
func NewChacha20poly1305(key []byte) *stupidChacha20poly1305 {
|
func NewChacha20poly1305(key []byte) *stupidChacha20poly1305 {
|
||||||
if len(key) != chacha20poly1305.KeySize {
|
if len(key) != chacha20poly1305.KeySize {
|
||||||
log.Panicf("Only %d-byte keys are supported, you passed %d bytes", chacha20poly1305.KeySize, len(key))
|
log.Panicf("Only %d-byte keys are supported, you passed %d bytes", chacha20poly1305.KeySize, len(key))
|
||||||
|
|
|
@ -0,0 +1,59 @@
|
||||||
|
// 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).
|
||||||
|
package stupidgcm
|
|
@ -1,7 +1,5 @@
|
||||||
// +build !without_openssl
|
// +build !without_openssl
|
||||||
|
|
||||||
// Package stupidgcm is a thin wrapper for OpenSSL's GCM encryption and
|
|
||||||
// decryption functions. It only support 32-byte keys and 16-bit IVs.
|
|
||||||
package stupidgcm
|
package stupidgcm
|
||||||
|
|
||||||
// #include <openssl/evp.h>
|
// #include <openssl/evp.h>
|
||||||
|
@ -25,10 +23,9 @@ type stupidGCM struct {
|
||||||
stupidAEADCommon
|
stupidAEADCommon
|
||||||
}
|
}
|
||||||
|
|
||||||
// Verify that we satisfy the interface
|
// New returns a new AES-GCM-256 cipher that satisfies the cipher.AEAD interface.
|
||||||
var _ cipher.AEAD = &stupidGCM{}
|
//
|
||||||
|
// Only 32-bytes keys and 16-byte IVs are supported.
|
||||||
// New returns a new cipher.AEAD implementation..
|
|
||||||
func New(keyIn []byte, forceDecode bool) cipher.AEAD {
|
func New(keyIn []byte, forceDecode bool) cipher.AEAD {
|
||||||
if len(keyIn) != keyLen {
|
if len(keyIn) != keyLen {
|
||||||
log.Panicf("Only %d-byte keys are supported", keyLen)
|
log.Panicf("Only %d-byte keys are supported", keyLen)
|
||||||
|
|
|
@ -26,12 +26,15 @@ type stupidXchacha20poly1305 struct {
|
||||||
wiped bool
|
wiped bool
|
||||||
}
|
}
|
||||||
|
|
||||||
// NewXchacha20poly1305 returns a XChaCha20-Poly1305 AEAD that uses the given 256-bit key.
|
// NewXchacha20poly1305 returns a XChaCha20-Poly1305 cipher that satisfied the
|
||||||
|
// cipher.AEAD interface.
|
||||||
//
|
//
|
||||||
// XChaCha20-Poly1305 is a ChaCha20-Poly1305 variant that takes a longer nonce,
|
// XChaCha20-Poly1305 is a ChaCha20-Poly1305 variant that takes a longer nonce,
|
||||||
// suitable to be generated randomly without risk of collisions. It should be
|
// suitable to be generated randomly without risk of collisions. It should be
|
||||||
// preferred when nonce uniqueness cannot be trivially ensured, or whenever
|
// preferred when nonce uniqueness cannot be trivially ensured, or whenever
|
||||||
// nonces are randomly generated.
|
// nonces are randomly generated.
|
||||||
|
//
|
||||||
|
// Only 32-bytes keys and 24-byte IVs are supported.
|
||||||
func NewXchacha20poly1305(key []byte) cipher.AEAD {
|
func NewXchacha20poly1305(key []byte) cipher.AEAD {
|
||||||
if len(key) != chacha20poly1305.KeySize {
|
if len(key) != chacha20poly1305.KeySize {
|
||||||
log.Panic("bad key length")
|
log.Panic("bad key length")
|
||||||
|
|
Loading…
Reference in New Issue