Documentation
¶
Overview ¶
Package secrets implements envelope encryption for cluster secrets (spec §3.13, design §2.10):
recovery passphrase ──argon2id──▶ KEK ──AES-GCM──▶ sealed data key (in Raft) data key (memory only) ──AES-GCM──▶ every secret value (in Raft)
Control nodes hold the plaintext data key in memory; a joining control node receives it from the leader over mTLS. Restore from backup requires the passphrase.
Index ¶
- Constants
- Variables
- func GenerateDataKey() ([]byte, error)
- func GeneratePassphrase() (string, error)
- func SealDataKey(dataKey []byte, passphrase string, keyVersion uint32) (*zatterav1.ClusterKeyMaterial, error)
- func UnsealDataKey(m *zatterav1.ClusterKeyMaterial, passphrase string) ([]byte, error)
- type Keyring
- type Sealer
Constants ¶
const ( ArgonTime = argonTime ArgonMemoryKiB = argonMemoryKiB ArgonThreads = argonThreads ArgonKeyLen = keyLen ArgonSaltLen = saltLen )
Exported argon2id parameters, reused by password hashing (T-04) so it stays in lockstep with the cluster-key KDF.
Variables ¶
var ErrSealedDataInvalid = errors.New("secrets: wrong passphrase or corrupted key material")
ErrSealedDataInvalid covers wrong passphrase and corrupted material — AES-GCM cannot distinguish them.
Functions ¶
func GenerateDataKey ¶
GenerateDataKey returns a fresh random 32-byte cluster data key.
func GeneratePassphrase ¶
GeneratePassphrase returns a human-typable recovery passphrase (8 groups of 4 base32 chars ≈ 160 bits).
func SealDataKey ¶
func SealDataKey(dataKey []byte, passphrase string, keyVersion uint32) (*zatterav1.ClusterKeyMaterial, error)
SealDataKey encrypts the data key under a passphrase-derived KEK, producing the ClusterKeyMaterial stored in Raft.
func UnsealDataKey ¶
func UnsealDataKey(m *zatterav1.ClusterKeyMaterial, passphrase string) ([]byte, error)
UnsealDataKey recovers the data key from ClusterKeyMaterial + passphrase. Uses the argon2 parameters recorded in the material (forward compat).
Types ¶
type Keyring ¶
type Keyring struct {
// contains filtered or unexported fields
}
Keyring holds the cluster data key in memory only. Control nodes keep it for the lifetime of the process; it is never written to disk. A joining control node receives it from the leader over mTLS (M2); a restore from backup derives it from the recovery passphrase.
func NewKeyring ¶
NewKeyring wraps a plaintext data key. It copies the key so the caller may zero its own buffer.
func (*Keyring) DataKey ¶
DataKey returns a copy of the plaintext data key (for handing to a joining control node over mTLS). Handle with care; never log or persist it.
func (*Keyring) KeyVersion ¶
KeyVersion returns the data key version.
type Sealer ¶
type Sealer interface {
Seal(plaintext []byte) (*zatterav1.EncryptedValue, error)
Open(v *zatterav1.EncryptedValue) ([]byte, error)
}
Sealer encrypts/decrypts individual secret values with the cluster data key. The zero Sealer is unusable; obtain one via NewSealer.
Source Files