keymgmt

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 7, 2025 License: MIT Imports: 27 Imported by: 1

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrDescriptorVersion indicates an unknown descriptor version.
	ErrDescriptorVersion = errors.New("kryptograf/keymgmt: unsupported descriptor version")
	// ErrDescriptorHash indicates an unsupported HKDF hash identifier.
	ErrDescriptorHash = errors.New("kryptograf/keymgmt: unsupported HKDF hash")
	// ErrContextMismatch indicates that the caller-supplied context bytes do
	// not match the descriptor's context digest.
	ErrContextMismatch = errors.New("kryptograf/keymgmt: context digest mismatch")
)
View Source 
var ErrInvalidPBKDF2Params = errors.New("kryptograf/keymgmt: invalid PBKDF2 parameters")

ErrInvalidPBKDF2Params indicates bad configuration values.

View Source 
var (
	// ErrInvalidRootKeyLength indicates that the provided byte slice did not
	// contain exactly 32 bytes.
	ErrInvalidRootKeyLength = errors.New("kryptograf/keymgmt: invalid root key length")
)
View Source 
var ErrNoSink = errors.New("kryptograf/keymgmt: no sink configured for commit")

ErrNoSink indicates that the store was created without a destination for persisting changes.

View Source 
var ErrUnsupportedPBKDF2Hash = errors.New("kryptograf/keymgmt: unsupported PBKDF2 hash")

ErrUnsupportedPBKDF2Hash indicates the hash function cannot be serialised.

Functions

func DeriveKeyFromPassphrase 

func DeriveKeyFromPassphrase(passphrase []byte, params ...PBKDF2Params) (RootKey, PBKDF2Params, error)

DeriveKeyFromPassphrase produces a RootKey using PBKDF2, applying secure defaults when params is omitted. The resulting parameters are returned so callers can persist them alongside the derived key.

func GenerateSalt 

func GenerateSalt(n int) ([]byte, error)

GenerateSalt returns n bytes of cryptographically secure random data.

func MarshalPBKDF2Params 

func MarshalPBKDF2Params(params PBKDF2Params) ([]byte, error)

MarshalPBKDF2Params serialises PBKDF2 parameters for persistence.

func PromptAndDeriveRootKey 

func PromptAndDeriveRootKey(r io.Reader, prompt string, w io.Writer, params ...PBKDF2Params) (RootKey, PBKDF2Params, error)

PromptAndDeriveRootKey prompts the user for a passphrase using reader r, derives a RootKey with optional PBKDF2 parameters, and returns both the key and the parameters actually used. Supplying no params applies the secure defaults (SHA-256, 600k iterations, 32-byte salt, 32-byte key). If r is nil, os.Stdin is used. When r is attached to a terminal, the input is read without echo; otherwise a newline-terminated passphrase is consumed.

func PromptPassphrase 

func PromptPassphrase(r io.Reader, prompt string, w io.Writer) ([]byte, error)

PromptPassphrase reads a passphrase from r without echoing when r is a TTY. The prompt is written to w if provided. If r is nil, os.Stdin is used.

Types

type DEK 

type DEK [dekBytes]byte

DEK represents a 256-bit data-encryption key derived from a root key.

func DEKFromHex 

func DEKFromHex(encoded string) (DEK, error)

DEKFromHex decodes a hex string into a DEK.

func ReconstructDEK 

func ReconstructDEK(root RootKey, context []byte, desc Descriptor) (DEK, error)

ReconstructDEK reproduces a previously minted DEK using the stored descriptor and the original context bytes.

func (DEK) Bytes 

func (d DEK) Bytes() []byte

Bytes exposes the DEK key material. The returned slice aliases the internal array and becomes invalid if Zero is called.

func (DEK) EncodeToHex 

func (d DEK) EncodeToHex() string

EncodeToHex exports the DEK as a hex string.

func (*DEK) Zero 

func (d *DEK) Zero()

Zero overwrites the DEK material with zeros.

type Descriptor 

type Descriptor struct {
	Version       uint8
	HKDFHash      uint8
	NonceSize     uint8
	Salt          [saltBytes]byte
	Nonce         [maxNonceSize]byte
	ContextDigest [sha256.Size]byte
}

Descriptor contains the metadata required to reconstruct a DEK.

func DescriptorFromHex 

func DescriptorFromHex(encoded string) (Descriptor, error)

DescriptorFromHex decodes a hex string into a Descriptor.

func (Descriptor) EncodeToHex 

func (d Descriptor) EncodeToHex() (string, error)

EncodeToHex renders the descriptor as a hex string.

func (Descriptor) MarshalBinary 

func (d Descriptor) MarshalBinary() ([]byte, error)

MarshalBinary encodes the descriptor into a stable binary representation.

func (Descriptor) NonceBytes 

func (d Descriptor) NonceBytes() int

NonceBytes returns the number of bytes in the stored nonce prefix.

func (Descriptor) NoncePrefix 

func (d Descriptor) NoncePrefix() []byte

NoncePrefix exposes the nonce prefix as a slice sized to NonceBytes().

func (*Descriptor) UnmarshalBinary 

func (d *Descriptor) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes the descriptor from its binary representation.

func (*Descriptor) Validate 

func (d *Descriptor) Validate() error

Validate checks whether the descriptor uses a supported version/hash pair.

type Format 

type Format int

Format enumerates the supported bundle encodings. 

const (
	FormatUnknown Format = iota
	FormatPEM
	FormatProtobuf
)

Supported store formats for serialising key bundles.

type Material 

type Material struct {
	Key        DEK
	Descriptor Descriptor
}

Material bundles a DEK with its descriptor so callers can pass them around as a single unit.

func MintDEK 

func MintDEK(root RootKey, context []byte) (Material, error)

MintDEK derives a short-lived DEK using HKDF-SHA256. The caller supplies the contextual bytes that should bind the DEK (for example, object identifiers or deployment-specific entropy).

func MintDEKWithNonceSize 

func MintDEKWithNonceSize(root RootKey, context []byte, nonceSize int) (Material, error)

MintDEKWithNonceSize derives a DEK and descriptor with the specified nonce size. nonceSize must be between 4 and maxNonceSize bytes.

func ReconstructMaterial 

func ReconstructMaterial(root RootKey, context []byte, desc Descriptor) (Material, error)

ReconstructMaterial rebuilds the DEK and returns it alongside the supplied descriptor.

func (*Material) Zero 

func (m *Material) Zero()

Zero overwrites the key material with zeros and leaves the descriptor intact.

type PBKDF2Params 

type PBKDF2Params struct {
	Hash       func() hash.Hash
	Iterations int
	Salt       []byte
	KeyLength  int
}

PBKDF2Params describes the hash function and iteration count used to derive a root key from a passphrase.

func GeneratePBKDF2Params 

func GeneratePBKDF2Params() (PBKDF2Params, error)

GeneratePBKDF2Params produces a PBKDF2Params struct populated with secure defaults: SHA-256, 600k iterations, a fresh 32-byte salt, and a 32-byte key.

func MustGeneratePBKDF2Params 

func MustGeneratePBKDF2Params() PBKDF2Params

MustGeneratePBKDF2Params is the panic-on-error variant of GeneratePBKDF2Params.

func UnmarshalPBKDF2Params 

func UnmarshalPBKDF2Params(data []byte) (PBKDF2Params, error)

UnmarshalPBKDF2Params deserialises PBKDF2 parameters created with MarshalPBKDF2Params.

type PEMBundle 

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

PEMBundle wraps a set of PEM blocks and exposes helpers for inserting and retrieving kryptograf-specific material while preserving all other blocks.

func LoadPEMBundle 

func LoadPEMBundle(r io.Reader) (*PEMBundle, error)

LoadPEMBundle reads all PEM blocks from r.

func NewPEMBundle 

func NewPEMBundle() *PEMBundle

NewPEMBundle returns an empty bundle.

func (*PEMBundle) Blocks 

func (b *PEMBundle) Blocks() []*pem.Block

Blocks returns a copy of the PEM blocks for inspection.

func (*PEMBundle) Bytes 

func (b *PEMBundle) Bytes() ([]byte, error)

Bytes renders the bundle back into PEM-encoded bytes.

func (*PEMBundle) Descriptor 

func (b *PEMBundle) Descriptor(name string) (Descriptor, bool, error)

Descriptor retrieves a descriptor stored under the provided name.

func (*PEMBundle) Encode 

func (b *PEMBundle) Encode(w io.Writer) error

Encode writes the PEM bundle to w.

func (*PEMBundle) PBKDF2Params 

func (b *PEMBundle) PBKDF2Params() (PBKDF2Params, bool, error)

PBKDF2Params retrieves stored PBKDF2 parameters, if present.

func (*PEMBundle) RootKey 

func (b *PEMBundle) RootKey() (RootKey, bool, error)

RootKey retrieves the root key stored in the bundle, if present.

func (*PEMBundle) SetDescriptor 

func (b *PEMBundle) SetDescriptor(name string, desc Descriptor) error

SetDescriptor inserts or replaces the descriptor stored under name.

func (*PEMBundle) SetPBKDF2Params 

func (b *PEMBundle) SetPBKDF2Params(params PBKDF2Params) error

SetPBKDF2Params inserts or replaces stored PBKDF2 parameters.

func (*PEMBundle) SetRootKey 

func (b *PEMBundle) SetRootKey(key RootKey)

SetRootKey inserts or replaces the root key block.

type ProtoBundle 

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

ProtoBundle wraps the protobuf representation of a key bundle used by the storage backends.

func LoadProtoBundle 

func LoadProtoBundle(r io.Reader) (*ProtoBundle, error)

LoadProtoBundle reads and unmarshals bundle data from the provided reader.

func NewProtoBundle 

func NewProtoBundle() *ProtoBundle

NewProtoBundle constructs an empty protobuf bundle ready to accept entries.

func (*ProtoBundle) Bytes 

func (p *ProtoBundle) Bytes() ([]byte, error)

Bytes implements the backend interface expected by Store.

func (*ProtoBundle) Descriptor 

func (p *ProtoBundle) Descriptor(name string) (Descriptor, bool, error)

Descriptor retrieves the descriptor stored under the supplied name.

func (*ProtoBundle) Marshal 

func (p *ProtoBundle) Marshal() ([]byte, error)

Marshal serialises the bundle into protobuf bytes.

func (*ProtoBundle) PBKDF2Params 

func (p *ProtoBundle) PBKDF2Params() (PBKDF2Params, bool, error)

PBKDF2Params retrieves stored PBKDF2 parameters, if present.

func (*ProtoBundle) RootKey 

func (p *ProtoBundle) RootKey() (RootKey, bool, error)

RootKey returns the stored root key, signalling whether it was present.

func (*ProtoBundle) SetDescriptor 

func (p *ProtoBundle) SetDescriptor(name string, desc Descriptor) error

SetDescriptor inserts or replaces the descriptor associated with name.

func (*ProtoBundle) SetPBKDF2Params 

func (p *ProtoBundle) SetPBKDF2Params(params PBKDF2Params) error

SetPBKDF2Params overwrites the stored PBKDF2 parameters in the bundle.

func (*ProtoBundle) SetRootKey 

func (p *ProtoBundle) SetRootKey(key RootKey)

SetRootKey overwrites the stored root key in the bundle.

func (*ProtoBundle) WriteTo 

func (p *ProtoBundle) WriteTo(w io.Writer) error

WriteTo serialises the bundle and writes it to w.

type RootKey 

type RootKey [rootKeyBytes]byte

RootKey represents a 256-bit symmetric key used to mint short-lived DEKs.

func GenerateRootKey 

func GenerateRootKey() (RootKey, error)

GenerateRootKey produces a new cryptographically secure 256-bit root key.

func MustGenerateRootKey 

func MustGenerateRootKey() RootKey

MustGenerateRootKey is a helper for test scenarios and command line tools. It panics if key generation fails.

func RootKeyFromBase64 

func RootKeyFromBase64(encoded string) (RootKey, error)

RootKeyFromBase64 decodes a base64 (raw, URL-safe) encoded string into a RootKey.

func RootKeyFromBytes 

func RootKeyFromBytes(b []byte) (RootKey, error)

RootKeyFromBytes copies b into a RootKey. Returns an error if b does not contain exactly 32 bytes.

func RootKeyFromHex 

func RootKeyFromHex(encoded string) (RootKey, error)

RootKeyFromHex decodes a hex string into a RootKey.

func (RootKey) Bytes 

func (rk RootKey) Bytes() []byte

Bytes returns the key material as a byte slice. The returned slice aliases the underlying array; callers must copy it if they intend to keep it.

func (RootKey) EncodeToBase64 

func (rk RootKey) EncodeToBase64() string

EncodeToBase64 exports the root key as a base64 raw standard encoded string.

func (RootKey) EncodeToHex 

func (rk RootKey) EncodeToHex() string

EncodeToHex exports the root key as a hex string.

func (*RootKey) Zero 

func (rk *RootKey) Zero()

Zero overwrites the key material with zeros.

type Store 

type Store interface {
	RootKey() (key RootKey, found bool, err error)
	SetRootKey(RootKey)
	EnsureRootKey() (RootKey, error)
	PBKDF2Params() (PBKDF2Params, bool, error)
	SetPBKDF2Params(PBKDF2Params) error
	EnsurePBKDF2Params() (PBKDF2Params, error)
	Descriptor(name string) (desc Descriptor, found bool, err error)
	SetDescriptor(name string, desc Descriptor) error
	EnsureDescriptor(name string, root RootKey, context []byte) (Material, error)
	Bytes() ([]byte, error)
	Commit() error
	Format() Format
}

Store exposes a unified API for reading/writing root keys, PBKDF2 parameters, and descriptors regardless of the underlying storage format (PEM, protobuf, etc.).

func Load 

func Load(from any) (Store, error)

Load ingests bundle data from any supported source. If the source is a file path, the store will default to writing back to that file on Commit.

func LoadInto 

func LoadInto(from, to any) (Store, error)

LoadInto ingests bundle data from a source while explicitly specifying the destination sink that Commit should write to.

func LoadPEM 

func LoadPEM(from any) (Store, error)

LoadPEM forces PEM format regardless of content.

func LoadPEMInto 

func LoadPEMInto(from, to any) (Store, error)

LoadPEMInto forces PEM format and writes to the provided sink on Commit.

func LoadProto 

func LoadProto(from any) (Store, error)

LoadProto forces protobuf format regardless of content.

func LoadProtoInto 

func LoadProtoInto(from, to any) (Store, error)

LoadProtoInto forces protobuf format for the provided sink.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.