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
- Variables
- func MaterialAAD(t Target) crypto.ProjectFieldAAD
- func MaterialAADFor(orgID, projectID, envID, keyID, versionRowID string) crypto.ProjectFieldAAD
- func Operate(material []byte, t Target, fn func(*crypto.TransitKey) ([]byte, error)) ([]byte, error)
- func PublicKeyFor(material []byte, t Target) ([]byte, error)
- type Custody
- type CustodyKind
- type ProjectSealers
- type Registry
- type Software
- func (s *Software) Available(context.Context) error
- func (s *Software) Create(ctx context.Context, t Target) (Version, error)
- func (s *Software) Decrypt(ctx context.Context, t Target, v Version, record, aad []byte) ([]byte, error)
- func (s *Software) Destroy(context.Context, Target, Version) error
- func (s *Software) Encrypt(ctx context.Context, t Target, v Version, plaintext, aad []byte) ([]byte, error)
- func (s *Software) Kind() CustodyKind
- func (s *Software) MAC(ctx context.Context, t Target, v Version, message []byte) ([]byte, error)
- func (s *Software) Sign(ctx context.Context, t Target, v Version, message []byte) ([]byte, error)
- type Target
- type Version
Constants ¶
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 ¶
var ( // 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).
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 ¶
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.
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 ¶
Available returns ErrUnavailable if the receiver or keyring is nil. It does not probe keyring or datastore health.
func (*Software) Create ¶
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 ¶
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) MAC ¶
MAC returns a raw HMAC-SHA256 for message under this version. Missing material, keyring, unsealing, and TransitKey.MAC 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). |