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
- type Argon2Params
- type KMSAPI
- type KMSClient
- type 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.
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 AWSKMSClient ¶ added in v1.7.0
type AWSKMSClient struct {
// contains filtered or unexported fields
}
AWSKMSClient wraps the AWS KMS SDK v2 client and implements both KMSEncrypter and KMSDecrypter.
func NewAWSKMSClient ¶ added in v1.9.0
func NewAWSKMSClient(ctx context.Context, arn string, opts ...KMSClientOption) (*AWSKMSClient, error)
NewAWSKMSClient creates a KMS client with the provided options.
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 ¶ added in v1.9.0
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 ¶ 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.
type KMSClientOption ¶ added in v1.9.0
type KMSClientOption func(*kmsClientConfig)
KMSClientOption configures an AWS KMS client.
func WithKMSConfig ¶ added in v1.9.0
func WithKMSConfig(cfg aws.Config) KMSClientOption
WithKMSConfig sets the full AWS config for KMS.
func WithKMSEndpoint ¶ added in v1.9.0
func WithKMSEndpoint(url string) KMSClientOption
WithKMSEndpoint sets a custom base URL for KMS (e.g. for MinIO or localstack).
func WithKMSRegion ¶ added in v1.9.0
func WithKMSRegion(region string) KMSClientOption
WithKMSRegion sets the AWS region for KMS.
Source Files