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 Argon2Params
- type KMSClient
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.
const HKDFInfoPackIndexV1 = "cloudstic-pack-index-v1"
HKDFInfoPackIndexV1 is the info string used for deriving the AES-256 key that seals the pack catalog and packfile footers. PackStore sits below the EncryptedStore layer and writes those objects straight to the backend, so it needs its own key rather than the master key.
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 ¶ added in v1.4.0
ComputeHMAC computes an HMAC-SHA256 hash of the given data and returns it as a hex string.
func Decrypt ¶
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 ¶
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 ¶
Encrypt encrypts plaintext using AES-256-GCM with a random nonce. Returns version(1) || nonce(12) || ciphertext || tag(16).
func GenerateKey ¶
GenerateKey generates a cryptographically random 256-bit key.
func GenerateRecoveryMnemonic ¶
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 ¶
IsEncrypted reports whether data starts with a known encryption version byte and is long enough to be a valid ciphertext.
func MnemonicToKey ¶
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 ¶ added in v1.4.0
NewHMACHash returns a new HMAC-SHA256 hash.Hash initialized with the given key.
Types ¶
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 KMSClient ¶ added in v1.9.0
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.
The interface lives here, alongside the encryption primitives it is used with, while implementations live in their own packages — pkg/crypto/kms provides the AWS one. That split is what keeps pkg/crypto (and everything importing it: pkg/keychain, pkg/secretref/backends, the root client) free of a cloud SDK unless a caller actually wraps a key with KMS. See RFC 0022 §6.
Source Files
Directories