crypto

Documentation

Overview

Package crypto provides authenticated encryption primitives for backup data.

Ciphertext format: version(1) || nonce(12) || ciphertext || GCM_tag(16) Version 0x01 = AES-256-GCM with 12-byte random nonce.

Index

• Constants
• Variables
• func ComputeHMAC(key, data []byte) string
• func Decrypt(ciphertext, key []byte) ([]byte, error)
• func DeriveKey(masterKey []byte, info string) ([]byte, error)
• func DeriveKeyFromPassword(password string, salt []byte, params Argon2Params) []byte
• func Encrypt(plaintext, key []byte) ([]byte, error)
• func GenerateKey() ([]byte, error)
• func GenerateRecoveryMnemonic() (mnemonic string, rawKey []byte, err error)
• func IsEncrypted(data []byte) bool
• func MnemonicToKey(mnemonic string) ([]byte, error)
• func NewHMACHash(key []byte) hash.Hash
• func UnwrapKey(wrapped, wrappingKey []byte) ([]byte, error)
• func WrapKey(key, wrappingKey []byte) ([]byte, error)
• type AWSKMSDecrypter
  • func NewAWSKMSDecrypter(ctx context.Context) (*AWSKMSDecrypter, error)
  • func (d *AWSKMSDecrypter) Decrypt(ctx context.Context, ciphertext []byte) ([]byte, error)
• type Argon2Params
• type KMSDecrypter

Constants

const (
	Version1  byte = 0x01
	NonceSize      = 12
	TagSize        = 16
	KeySize        = 32
	Overhead       = 1 + NonceSize + TagSize // version + nonce + tag
)

const HKDFInfoBackupV1 = "cloudstic-backup-v1"

HKDFInfoBackupV1 is the info string used for deriving the AES-256 backup encryption key from a master key. Shared by web and CLI.

const HKDFInfoDedupV1 = "cloudstic-dedup-mac-v1"

HKDFInfoDedupV1 is the info string used for deriving the HMAC-SHA256 key for chunk deduplication hashing.

Variables

var (
	ErrInvalidCiphertext = errors.New("crypto: invalid ciphertext")
	ErrDecryptFailed     = errors.New("crypto: decryption failed (wrong key or tampered data)")
)

var DefaultArgon2Params = Argon2Params{
	Time:    3,
	Memory:  64 * 1024,
	Threads: 4,
}

DefaultArgon2Params provides reasonable defaults (~1s on modern hardware).

Functions

func ComputeHMAC

func ComputeHMAC(key, data []byte) string

ComputeHMAC computes an HMAC-SHA256 hash of the given data and returns it as a hex string.

func Decrypt

func Decrypt(ciphertext, key []byte) ([]byte, error)

Decrypt decrypts ciphertext produced by Encrypt. Returns ErrInvalidCiphertext if the data is too short or has an unknown version, and ErrDecryptFailed if authentication fails.

func DeriveKey

func DeriveKey(masterKey []byte, info string) ([]byte, error)

DeriveKey derives a 256-bit encryption key from a master key using HKDF-SHA256. The info string should be unique per purpose.

func DeriveKeyFromPassword

func DeriveKeyFromPassword(password string, salt []byte, params Argon2Params) []byte

DeriveKeyFromPassword derives a 256-bit key from a password using Argon2id.

func Encrypt

func Encrypt(plaintext, key []byte) ([]byte, error)

Encrypt encrypts plaintext using AES-256-GCM with a random nonce. Returns version(1) || nonce(12) || ciphertext || tag(16).

func GenerateKey

func GenerateKey() ([]byte, error)

GenerateKey generates a cryptographically random 256-bit key.

func GenerateRecoveryMnemonic

func GenerateRecoveryMnemonic() (mnemonic string, rawKey []byte, err error)

GenerateRecoveryMnemonic generates a 256-bit recovery key and returns it as both a BIP39 24-word mnemonic and raw key bytes. The mnemonic is shown to the user once; the raw key is used to wrap the master key.

func IsEncrypted

func IsEncrypted(data []byte) bool

IsEncrypted reports whether data starts with a known encryption version byte and is long enough to be a valid ciphertext.

func MnemonicToKey

func MnemonicToKey(mnemonic string) ([]byte, error)

MnemonicToKey converts a BIP39 24-word mnemonic back to the 256-bit raw key. Returns an error if the mnemonic is invalid or has a bad checksum.

func NewHMACHash

func NewHMACHash(key []byte) hash.Hash

NewHMACHash returns a new HMAC-SHA256 hash.Hash initialized with the given key.

func UnwrapKey

func UnwrapKey(wrapped, wrappingKey []byte) ([]byte, error)

UnwrapKey decrypts a wrapped key using a wrapping key.

func WrapKey

func WrapKey(key, wrappingKey []byte) ([]byte, error)

WrapKey encrypts a key with a wrapping key using AES-256-GCM. The output format is the same as Encrypt.

Types

type AWSKMSDecrypter

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

AWSKMSDecrypter wraps the AWS KMS SDK v2 client.

func NewAWSKMSDecrypter

func NewAWSKMSDecrypter(ctx context.Context) (*AWSKMSDecrypter, error)

NewAWSKMSDecrypter creates a KMS decrypter using the default AWS credential chain. The key ARN is embedded in the ciphertext blob so it does not need to be supplied at decryption time.

func (*AWSKMSDecrypter) Decrypt

func (d *AWSKMSDecrypter) Decrypt(ctx context.Context, ciphertext []byte) ([]byte, error)

type Argon2Params

type Argon2Params struct {
	Time    uint32 `json:"time"`
	Memory  uint32 `json:"memory"`
	Threads uint8  `json:"threads"`
}

Argon2Params controls the cost of Argon2id password hashing.

type KMSDecrypter

type KMSDecrypter interface {
	Decrypt(ctx context.Context, ciphertext []byte) ([]byte, error)
}

KMSDecrypter can decrypt a KMS ciphertext blob. Implementations must be safe for concurrent use.