Documentation
¶
Overview ¶
Package format implements the frozen v1 offline-vault binary formats. It performs no file I/O, prompting, KDF work or persistence. Callers must reserve nonce budgets and manage key lifetimes before using encryption primitives.
Index ¶
- Constants
- Variables
- func ItemFilename(itemID string) (string, error)
- func KeyFileWrappingKey(m Meta, key []byte) ([]byte, error)
- func ManifestRoot(hashes [][32]byte) ([32]byte, error)
- func OpenItem(data, key []byte, expected ItemIdentity) (credential.Secret, error)
- func SealBudget(b Budget, dek []byte) ([]byte, error)
- func SealItem(i ItemIdentity, nonce [12]byte, key []byte, secret credential.Secret) ([]byte, error)
- func SealMeta(m Meta, wrappingKey, dek []byte) ([]byte, error)
- func SealTransaction(t Transaction, sourceKey, targetKey []byte) ([]byte, error)
- type Budget
- type Current
- type Endpoint
- type ItemIdentity
- type KeyIdentity
- type ManifestBlock
- type ManifestEntry
- type ManifestVerifier
- type Meta
- type Operation
- type Stage
- type Transaction
- type WrapSuite
Constants ¶
const ( // Version identifies the frozen v1 container layout. Incompatible layouts // require a new version; existing suite identifiers must not be reassigned. Version = 1 // MaxIDBytes bounds each identifier without changing other stores' contracts. MaxIDBytes = 1024 // MaxSecretBytes bounds the plaintext of a single item. MaxSecretBytes = 64 * 1024 // MaxMetaBytes bounds an entire wrapped-key container. MaxMetaBytes = 4096 // MaxItemBytes includes the largest header and authentication tag. MaxItemBytes = 67667 // MaxEncryptions counts reserved encryptions, including unsuccessful writes. MaxEncryptions = 1 << 20 // WarningEncryptions is ceil(90% of MaxEncryptions). WarningEncryptions = 943719 )
const (
// MaxManifestBytes bounds one manifest block, including its header.
MaxManifestBytes = 1 << 20
)
const (
// MaxStateBytes bounds the complete JSON state envelope.
MaxStateBytes = 16 * 1024
)
Variables ¶
var ( // ErrCorrupt indicates malformed or unauthentic data, without echoing input. ErrCorrupt = errors.New("offline credential data is corrupt") // ErrUnsupported indicates an unknown version or suite. ErrUnsupported = errors.New("offline credential format is unsupported") // ErrIdentity indicates a mismatch with the caller's expected identity. ErrIdentity = errors.New("offline credential identity mismatch") )
Functions ¶
func ItemFilename ¶
ItemFilename never uses caller identifiers as filesystem path components.
func KeyFileWrappingKey ¶
KeyFileWrappingKey derives the wrapping key from an independent key file. The caller must clear the result and must never reuse a salt for new wrapping.
func ManifestRoot ¶
ManifestRoot hashes ordered block hashes. Callers must also validate consecutive block indices, cross-block ItemID ordering and the total entry count while streaming.
func OpenItem ¶
func OpenItem(data, key []byte, expected ItemIdentity) (credential.Secret, error)
OpenItem authenticates identity and expiry without imposing a wall clock. Maintenance can read expired data; ordinary Get must check expiry before delivery.
func SealBudget ¶
SealBudget authenticates a count. Durable monotonic updates remain the file layer's responsibility.
func SealItem ¶
func SealItem(i ItemIdentity, nonce [12]byte, key []byte, secret credential.Secret) ([]byte, error)
SealItem encrypts a secret, preserving expiry including historical expiries. The caller must durably reserve an encryption and supply a fresh random nonce. Ordinary Put must additionally reject an already-expired secret.
func SealMeta ¶
SealMeta wraps a DEK using a prepared header and wrapping key. This low-level primitive requires a fresh salt, nonce and one-use wrapping key from its caller.
func SealTransaction ¶
func SealTransaction(t Transaction, sourceKey, targetKey []byte) ([]byte, error)
SealTransaction authenticates all state under the supplied source and/or target keys. Missing keys produce empty MAC fields; at least one valid key is required.
Types ¶
type Budget ¶
type Budget struct {
VaultID [16]byte
Generation uint64
Consumed uint64
Sequence uint64
StoreID string
}
Budget is an authenticated reservation count, not an anti-rollback anchor.
type Current ¶
Current is an unauthenticated publication pointer until matched to valid Meta.
func ParseCurrent ¶
ParseCurrent validates syntax, not publication authenticity or freshness.
func (Current) MarshalBinary ¶
MarshalBinary encodes the fixed-size publication pointer.
type Endpoint ¶
type Endpoint struct {
VaultID [16]byte
StoreID string
Revision uint64
Generation uint64
MetaHash [32]byte
ManifestRoot [32]byte
ItemCount uint64
}
Endpoint identifies one transaction side and its authenticated snapshot.
type ItemIdentity ¶
type ItemIdentity struct {
VaultID [16]byte
Generation uint64
Ref credential.Ref
}
ItemIdentity binds an item to the requested store, vault and DEK generation.
func InspectItem ¶
func InspectItem(data []byte) (ItemIdentity, error)
InspectItem reads bounded, unauthenticated identity metadata for enumeration. Callers must compare it with the vault and filename, then authenticate OpenItem.
type KeyIdentity ¶
KeyIdentity identifies a vault key independently of a publication or item.
type ManifestBlock ¶
type ManifestBlock struct {
Index uint32
Entries []ManifestEntry
}
ManifestBlock is a bounded, strictly ordered chunk of a source or target snapshot.
func ParseManifestBlock ¶
func ParseManifestBlock(data []byte) (ManifestBlock, error)
ParseManifestBlock does not authenticate the block; verify its root via state MAC.
func (ManifestBlock) MarshalBinary ¶
func (m ManifestBlock) MarshalBinary() ([]byte, error)
MarshalBinary validates strict byte ordering and bounds before allocating output.
type ManifestEntry ¶
ManifestEntry describes a ciphertext, never a plaintext secret.
type ManifestVerifier ¶
type ManifestVerifier struct {
// contains filtered or unexported fields
}
ManifestVerifier checks an entire snapshot without retaining all block hashes. It is single-owner, contains public metadata only, and performs no I/O.
func NewManifestVerifier ¶
func NewManifestVerifier(blocks uint32, items uint64) (*ManifestVerifier, error)
NewManifestVerifier fixes the authenticated expected counts before reading blocks.
func (*ManifestVerifier) Add ¶
func (v *ManifestVerifier) Add(data []byte) error
Add validates a consecutive, strictly ordered block and adds its exact-byte hash. Rejected blocks do not advance the verifier.
func (*ManifestVerifier) Finish ¶
func (v *ManifestVerifier) Finish(expected [32]byte) error
Finish verifies counts and the state-authenticated root. It cannot prove that the listed files actually exist; the file layer must authenticate those files.
type Meta ¶
type Meta struct {
Suite WrapSuite
VaultID [16]byte
Generation uint64
Revision uint64
Salt []byte
Nonce [12]byte
StoreID string
}
Meta contains public wrapping metadata. Parsed metadata is not authenticated.
type Operation ¶
type Operation byte
Operation identifies a maintenance operation, not a normal item write.
const ( // OpInit creates a new vault. OpInit Operation = iota + 1 // OpRewrap changes wrapping material while retaining the DEK. OpRewrap // OpReencrypt creates a new DEK. OpReencrypt // OpRestore restores a trusted backup under a new DEK. OpRestore // OpClone creates an independent vault. OpClone // OpPrune cleans explicitly selected obsolete revisions. OpPrune )
type Stage ¶
type Stage byte
Stage is a recovery hint, never proof of the current durable publication.
const ( // Prepared records intent before target construction. Prepared Stage = iota + 1 // Building records incomplete target construction. Building // Verified records a fully validated and synced target. Verified // Published records a pointer switch which must still be checked. Published // Committed records confirmed durable publication. Committed // CleanupPending records explicitly requested unfinished cleanup. CleanupPending )
type Transaction ¶
type Transaction struct {
OperationID [16]byte
Operation Operation
Stage Stage
Source Endpoint
Target Endpoint
CleanupRevisions []uint64
}
Transaction contains public state only. Validate current files before recovery actions.
func InspectTransaction ¶
func InspectTransaction(data []byte) (Transaction, error)
InspectTransaction validates public syntax only, to locate wrapping metadata. Its result MUST NOT authorize reads, publication or deletion without a valid MAC.
func OpenTransaction ¶
func OpenTransaction(data, key []byte, expected KeyIdentity, target bool) (Transaction, error)
OpenTransaction verifies the selected side against a trusted expected key identity. It does not assert that the other side or any file is recoverable.
Source Files