cryptocore

Documentation

Overview

Package cryptocore wraps OpenSSL and Go GCM crypto and provides a nonce generator.

Index

• Constants
• func HkdfDerive(masterkey []byte, info string, outLen int) (out []byte)
• func RandBytes(n int) []byte
• func RandUint64() uint64
• type AEADTypeEnum
• type CryptoCore
  • func New(key []byte, aeadType AEADTypeEnum, IVBitLen int, useHKDF bool, ...) *CryptoCore
  • func (c *CryptoCore) Wipe()

Constants

const (
	// KeyLen is the cipher key length in bytes.  32 for AES-256.
	KeyLen = 32
	// AuthTagLen is the length of a GCM auth tag in bytes.
	AuthTagLen = 16
)

const (
	// "info" data that HKDF mixes into the generated key to make it unique.
	// For convenience, we use a readable string.
	HkdfInfoEMENames = "EME filename encryption"
)

Functions

func HkdfDerive

func HkdfDerive(masterkey []byte, info string, outLen int) (out []byte)

hkdfDerive derives "outLen" bytes from "masterkey" and "info" using HKDF-SHA256 (RFC 5869). It returns the derived bytes or panics.

func RandBytes

func RandBytes(n int) []byte

RandBytes gets "n" random bytes from /dev/urandom or panics

func RandUint64

func RandUint64() uint64

RandUint64 returns a secure random uint64

Types

type AEADTypeEnum

type AEADTypeEnum int

AEADTypeEnum indicates the type of AEAD backend in use.

const (
	// BackendOpenSSL specifies the OpenSSL backend.
	BackendOpenSSL AEADTypeEnum = 3
	// BackendGoGCM specifies the Go based GCM backend.
	BackendGoGCM AEADTypeEnum = 4
	// BackendAESSIV specifies an AESSIV backend.
	BackendAESSIV AEADTypeEnum = 5
)

type CryptoCore

type CryptoCore struct {
	// EME is used for filename encryption.
	EMECipher *eme.EMECipher
	// GCM or AES-SIV. This is used for content encryption.
	AEADCipher cipher.AEAD
	// Which backend is behind AEADCipher?
	AEADBackend AEADTypeEnum
	// GCM needs unique IVs (nonces)
	IVGenerator *nonceGenerator
	IVLen       int
}

CryptoCore is the low level crypto implementation.

func New

func New(key []byte, aeadType AEADTypeEnum, IVBitLen int, useHKDF bool, forceDecode bool) *CryptoCore

New returns a new CryptoCore object or panics.

Even though the "GCMIV128" feature flag is now mandatory, we must still support 96-bit IVs here because they were used for encrypting the master key in gocryptfs.conf up to gocryptfs v1.2. v1.3 switched to 128 bits.

Note: "key" is either the scrypt hash of the password (when decrypting a config file) or the masterkey (when finally mounting the filesystem).

func (*CryptoCore) Wipe

func (c *CryptoCore) Wipe()

Wipe tries to wipe secret keys from memory by overwriting them with zeros and/or setting references to nil.

This is not bulletproof due to possible GC copies, but still raises to bar for extracting the key.