keyring

type Algorithm string

type DekHandle struct {
	DekID uuid.UUID
}

type Envelope struct {
	DekID      uuid.UUID
	Ciphertext []byte
	Nonce      []byte
}

type Fake struct {

	// FailEncrypt, FailDecrypt, FailAllocate, FailRewrap, FailSign, when
	// non-nil, make the matching method return the stored error. Useful for
	// failure-path tests in callers.
	FailEncrypt  error
	FailDecrypt  error
	FailAllocate error
	FailRewrap   error
	FailSign     error
	// contains filtered or unexported fields
}

type KMSKeeper interface {
	Decrypt(ctx context.Context, ciphertext []byte) ([]byte, error)
	Close() error
}

type KMSService interface {
	// OpenKeeper opens the KMS keeper at keyURI and returns it.
	// The caller must call Close on the returned keeper when done.
	OpenKeeper(ctx context.Context, keyURI string) (KMSKeeper, error)
}

type KekUseCase interface {
	// Create generates a new KEK wrapped under the active master key and persists it.
	Create(ctx context.Context, masterKeyChain *MasterKeyChain, alg Algorithm) error

	// Rotate creates a new KEK version wrapped under the active master key,
	// incrementing the version counter relative to the current highest KEK.
	Rotate(ctx context.Context, masterKeyChain *MasterKeyChain, alg Algorithm) error
}

type KeySigner interface {
	// SignWithKey signs data using a key derived from the active KEK via HKDF-SHA256.
	// Returns the 32-byte HMAC-SHA256 signature and the ID of the KEK used.
	SignWithKey(data []byte) (sig []byte, kekID uuid.UUID, err error)

	// VerifyWithKey verifies data against sig using the KEK identified by kekID.
	// Returns ErrSignatureInvalid if the signature does not match.
	// Returns ErrKekNotFound if the KEK is not present in the chain.
	VerifyWithKey(kekID uuid.UUID, data, sig []byte) error
}

type Keyring interface {
	KeySigner

	// Encrypt creates a fresh DEK, persists it, and uses it to encrypt
	// plaintext exactly once. The returned Envelope contains everything a
	// future Decrypt call needs.
	Encrypt(ctx context.Context, plaintext []byte) (Envelope, error)

	// Decrypt reverses Encrypt for an Envelope produced by this Keyring.
	Decrypt(ctx context.Context, env Envelope) ([]byte, error)

	// AllocateDek creates and persists a new DEK and returns a handle to it.
	// The DEK is wrapped under the active KEK with the given algorithm.
	AllocateDek(ctx context.Context, alg Algorithm) (DekHandle, error)

	// EncryptWith encrypts plaintext under the DEK identified by handle and
	// authenticates the optional aad. Reuses the DEK across many calls.
	EncryptWith(
		ctx context.Context,
		handle DekHandle,
		plaintext, aad []byte,
	) (ciphertext, nonce []byte, err error)

	// DecryptWith reverses EncryptWith for ciphertext produced under the
	// same DekHandle with the same aad.
	DecryptWith(
		ctx context.Context,
		handle DekHandle,
		ciphertext, nonce, aad []byte,
	) ([]byte, error)

	// Rewrap re-encrypts an existing DEK under the active KEK without
	// changing the underlying key material. Used by KEK rotation.
	Rewrap(ctx context.Context, dekID uuid.UUID) error

	// RewrapAll re-encrypts, in batches, every DEK not already under the
	// active KEK. Returns the total number of DEKs rewrapped across all
	// batches. Used by the KEK rotation worker.
	RewrapAll(ctx context.Context, batchSize int) (int, error)

	// ActiveKekID returns the ID of the KEK currently used for new
	// encryption. Exposed so the rotation worker can confirm it is
	// targeting the same KEK the application is using.
	ActiveKekID() uuid.UUID
}

type MasterKey struct {
	ID  string
	Key []byte
}

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

type NullSigner struct{}