transit

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MPL-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package transit is the custody seam of the transit surface (#156, transit ADR D3). A custody provider decides where one key version's material lives and performs the operations that need it; it never decides whether an operation is permitted (the service does, inside its transaction) and it never touches a cryptographic primitive (internal/crypto does).

Two providers exist. Software custody seals material under the owning project DEK, so the key hierarchy's rotation, reencrypt and crypto-shred cover it. External custody (an HSM, KMIP or a cloud KMS) holds the material itself and Hikyo stores an opaque reference; this release ships only the in-memory mock in transittest, used to prove both providers keep identical semantics.

The seam is operation-level on purpose: a hardware provider must never have to release material to Hikyo, so "give me the key bytes" is not a method.

Index

Constants

View Source
const (
	MaterialOwnerTable = "transit_key_versions"
	MaterialFieldTag   = "material"
)

MaterialOwnerTable and MaterialFieldTag anchor a software-custody version's sealed material: a project_field envelope bound to the version row, the environment and the transit key. The reencrypt walk re-seals exactly this AAD, so the two must never drift.

Variables

View Source
var (
	// ErrUnavailable is the fail-closed answer of a custody provider that is not
	// registered, not reachable, or reports itself down. It is retryable and it
	// never triggers a fallback to another provider.
	ErrUnavailable = errors.New("transit: key custody provider unavailable")
	// ErrMaterialMissing reports a version whose material is gone at the
	// provider (destroyed, trimmed, or never created there), for example after a
	// restore resurrected a reference the provider no longer holds.
	ErrMaterialMissing = errors.New("transit: key version material is not held by its custody provider")
)

Functions

func MaterialAAD

func MaterialAAD(t Target) crypto.ProjectFieldAAD

MaterialAAD is the project_field AAD of one version's sealed material.

func MaterialAADFor

func MaterialAADFor(orgID, projectID, envID, keyID, versionRowID string) crypto.ProjectFieldAAD

MaterialAADFor is MaterialAAD from the row coordinates alone, for the reencrypt walk, which re-seals rows without knowing their algorithm.

func Operate

func Operate(material []byte, t Target, fn func(*crypto.TransitKey) ([]byte, error)) ([]byte, error)

Operate derives the operation key for one version from material and runs fn with it, destroying the derived key afterwards. It is the shared tail of every provider that holds raw material (software, and the test mock).

func PublicKeyFor

func PublicKeyFor(material []byte, t Target) ([]byte, error)

PublicKeyFor returns the Ed25519 public key for signing material, or nil for any other algorithm.

Types

type Custody

type Custody interface {
	Kind() CustodyKind
	// Available reports ErrUnavailable when the provider cannot serve.
	Available(ctx context.Context) error
	// Create makes new material for t and returns what the datastore stores.
	Create(ctx context.Context, t Target) (Version, error)
	Encrypt(ctx context.Context, t Target, v Version, plaintext, aad []byte) ([]byte, error)
	Decrypt(ctx context.Context, t Target, v Version, record, aad []byte) ([]byte, error)
	Sign(ctx context.Context, t Target, v Version, message []byte) ([]byte, error)
	MAC(ctx context.Context, t Target, v Version, message []byte) ([]byte, error)
	// Destroy erases the material at the provider. Software custody has nothing
	// to erase outside the row the caller deletes.
	Destroy(ctx context.Context, t Target, v Version) error
}

Custody performs the material-bearing half of every transit operation. Implementations must be safe for concurrent use and must honour ctx.

type CustodyKind

type CustodyKind string

CustodyKind is the closed custody set, fixed per key at creation.

const (
	CustodySoftware CustodyKind = "software"
	CustodyExternal CustodyKind = "external"
)

func ParseCustodyKind

func ParseCustodyKind(s string) (CustodyKind, error)

ParseCustodyKind refuses anything outside the closed set.

type ProjectSealers

type ProjectSealers interface {
	ForProject(ctx context.Context, orgID, projectID string) (*crypto.ProjectSealer, error)
}

ProjectSealers is the slice of the keyring software custody needs. *crypto.Keyring satisfies it.

type Registry

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

Registry resolves a key's recorded custody kind to its provider. A kind with no registered provider is ErrUnavailable: the key row's custody decides, and nothing substitutes another provider.

func NewRegistry

func NewRegistry(providers ...Custody) *Registry

NewRegistry registers providers by their own Kind. A duplicate kind is a wiring bug and panics.

func (*Registry) Registered

func (r *Registry) Registered(kind CustodyKind) bool

Registered reports whether a provider is registered for kind, so key creation can refuse a custody the instance cannot serve.

func (*Registry) Resolve

func (r *Registry) Resolve(kind CustodyKind) (Custody, error)

Resolve returns the provider for kind, or ErrUnavailable.

type Software

type Software struct {
	Keyring ProjectSealers
}

Software keeps material sealed under the owning project DEK (transit ADR D3). It is always available while the keyring is.

func (*Software) Available

func (s *Software) Available(context.Context) error

Available returns ErrUnavailable if the receiver or keyring is nil. It does not probe keyring or datastore health.

func (*Software) Create

func (s *Software) Create(ctx context.Context, t Target) (Version, error)

Create seals fresh material under the project DEK.

fence:delegated. It returns the DEK version it sealed under (Version.SealedDEKVersion); the service fences on exactly that version in the transaction that writes the row (service.Transit.fenceSealed), so material sealed under a DEK version a concurrent rotate-dek is retiring is refused rather than stranded.

func (*Software) Decrypt

func (s *Software) Decrypt(ctx context.Context, t Target, v Version, record, aad []byte) ([]byte, error)

Decrypt opens a transit record with matching caller context in aad. Missing material, keyring, unsealing, and TransitKey.Decrypt errors propagate.

func (*Software) Destroy

func (s *Software) Destroy(context.Context, Target, Version) error

Destroy has nothing to erase at a provider: the material exists only in the version row, which the caller nulls or deletes in its own transaction.

func (*Software) Encrypt

func (s *Software) Encrypt(ctx context.Context, t Target, v Version, plaintext, aad []byte) ([]byte, error)

Encrypt seals plaintext with this version and binds aad as caller context. Missing material, keyring, unsealing, and TransitKey.Encrypt errors propagate.

func (*Software) Kind

func (s *Software) Kind() CustodyKind

Kind identifies software custody.

func (*Software) MAC

func (s *Software) MAC(ctx context.Context, t Target, v Version, message []byte) ([]byte, error)

MAC returns a raw HMAC-SHA256 for message under this version. Missing material, keyring, unsealing, and TransitKey.MAC errors propagate.

func (*Software) Sign

func (s *Software) Sign(ctx context.Context, t Target, v Version, message []byte) ([]byte, error)

Sign returns a raw Ed25519 signature for message under this version. Missing material, keyring, unsealing, and TransitKey.Sign errors propagate.

type Target

type Target struct {
	Binding      crypto.TransitBinding
	VersionRowID string
}

Target names one key version: the binding every derived key is bound to, plus the version row id the software provider's sealing AAD is anchored to.

type Version

type Version struct {
	Sealed []byte
	// SealedDEKVersion is the project DEK version Sealed was written under; the
	// caller fences on it in the transaction that stores the row.
	SealedDEKVersion uint32
	ExternalRef      string
	PublicKey        []byte
}

Version is what the datastore keeps for one key version. Exactly one of Sealed (software) or ExternalRef (external) is set. PublicKey is public metadata for signing keys.

Directories

Path Synopsis
Package transittest holds the in-memory mock external custody provider (transit ADR D3).
Package transittest holds the in-memory mock external custody provider (transit ADR D3).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL