cryptocore

Documentation

Overview

Package cryptocore holds the cryptographic primitives for vaultwright: password hardening, the per-seal key hierarchy, the authenticated-encryption envelope, and the fresh ephemeral challenge-response handshake.

Key hierarchy (both factors strictly required):

P    = Argon2id(password, salt)              -- factor 1 (operator)
sk,pk                                        -- fresh X25519 keypair per seal
S    = HKDF(sk, "vaultwright/asset-share/v1")   -- 16 bytes; factor 2 lives in warden
K_a  = HKDF(S || P)                          -- asset key

Index

• Constants
• func DeriveAssetKey(share, p []byte) []byte
• func DeriveAssetKeySolo(p []byte) []byte
• func DeriveP(password, salt []byte) []byte
• func DeriveShare(sk *ecdh.PrivateKey) []byte
• func NewKeyPair() (*ecdh.PrivateKey, error)
• func NewSalt() ([]byte, error)
• func Open(key, ciphertext, aad []byte) ([]byte, error)
• func RecoverShare(ePriv *ecdh.PrivateKey, pk, response []byte) ([]byte, error)
• func Respond(sk *ecdh.PrivateKey, ePub []byte) ([]byte, error)
• func Seal(key, plaintext, aad []byte) ([]byte, error)

Constants

const (
	SaltLen     = 16 // password salt, stored plaintext in the vault blob
	ShareLen    = 16 // S, the asset-key share carried by the handshake (12 words)
	AssetKeyLen = 32 // K_a

)

Sizes used across the project.

Functions

func DeriveAssetKey

func DeriveAssetKey(share, p []byte) []byte

DeriveAssetKey combines the handshake share S with the password key P into K_a.

func DeriveAssetKeySolo

func DeriveAssetKeySolo(p []byte) []byte

DeriveAssetKeySolo derives K_a from the password key P alone, for single-factor (--no-warden) seals: no handshake share, no warden. A distinct info label keeps it domain-separated from DeriveAssetKey.

func DeriveP

func DeriveP(password, salt []byte) []byte

DeriveP hardens the password into a 32-byte key with Argon2id.

func DeriveShare

func DeriveShare(sk *ecdh.PrivateKey) []byte

DeriveShare reproduces S from the private key. Only the warden (which holds sk) can compute it; the vault never can.

func NewKeyPair

func NewKeyPair() (*ecdh.PrivateKey, error)

NewKeyPair generates a fresh X25519 keypair for a seal.

func NewSalt

func NewSalt() ([]byte, error)

NewSalt returns a fresh random salt.

func Open

func Open(key, ciphertext, aad []byte) ([]byte, error)

Open reverses Seal. A wrong key, tampered ciphertext, or wrong aad fails here.

func RecoverShare

func RecoverShare(ePriv *ecdh.PrivateKey, pk, response []byte) ([]byte, error)

RecoverShare is the vault side: unwrap S from the warden's response using the ephemeral private key and the vault's stored public key pk.

func Respond

func Respond(sk *ecdh.PrivateKey, ePub []byte) ([]byte, error)

Respond is the warden side: given the vault's ephemeral public key, wrap the share S with a one-time pad derived from the shared secret.

func Seal

func Seal(key, plaintext, aad []byte) ([]byte, error)

Seal encrypts plaintext with XChaCha20-Poly1305 under key, prepending a random 24-byte nonce. aad is authenticated but not encrypted (may be nil).