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 AWSKMSClient
  • func NewAWSKMSClient(ctx context.Context, arn string, opts ...KMSClientOption) (*AWSKMSClient, error)
  • func (d *AWSKMSClient) Decrypt(ctx context.Context, ciphertext []byte) ([]byte, error)
  • func (d *AWSKMSClient) Encrypt(ctx context.Context, plaintext []byte) ([]byte, error)
• type Argon2Params
• type KMSAPI
• type KMSClient
• type KMSClientOption
  • func WithKMSConfig(cfg aws.Config) KMSClientOption
  • func WithKMSEndpoint(url string) KMSClientOption
  • func WithKMSRegion(region string) KMSClientOption

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 AWSKMSClient

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

AWSKMSClient wraps the AWS KMS SDK v2 client and implements both KMSEncrypter and KMSDecrypter.

func NewAWSKMSClient

func NewAWSKMSClient(ctx context.Context, arn string, opts ...KMSClientOption) (*AWSKMSClient, error)

NewAWSKMSClient creates a KMS client with the provided options.

func (*AWSKMSClient) Decrypt

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

func (*AWSKMSClient) Encrypt

func (d *AWSKMSClient) Encrypt(ctx context.Context, plaintext []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 KMSAPI

type KMSAPI interface {
	Encrypt(ctx context.Context, params *kms.EncryptInput, optFns ...func(*kms.Options)) (*kms.EncryptOutput, error)
	Decrypt(ctx context.Context, params *kms.DecryptInput, optFns ...func(*kms.Options)) (*kms.DecryptOutput, error)
}

KMSAPI defines the subset of the AWS KMS SDK client required by AWSKMSClient.

type KMSClient

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

KMSClient represents a KMS client capable of both encrypting and decrypting.

type KMSClientOption

type KMSClientOption func(*kmsClientConfig)

KMSClientOption configures an AWS KMS client.

func WithKMSConfig

func WithKMSConfig(cfg aws.Config) KMSClientOption

WithKMSConfig sets the full AWS config for KMS.

func WithKMSEndpoint

func WithKMSEndpoint(url string) KMSClientOption

WithKMSEndpoint sets a custom base URL for KMS (e.g. for MinIO or localstack).

func WithKMSRegion

func WithKMSRegion(region string) KMSClientOption

WithKMSRegion sets the AWS region for KMS.