Documentation
¶
Overview ¶
Package bundlesig implements the detached-signature sidecar format and the Ed25519 verification rules of Spec 101 (contracts/sidecar-format.md).
It is a pure leaf package: no file I/O, no globals, stdlib only, and it must not import internal/security/scanner. The scanner decides what to do with a verification outcome (which authority is active, rollback, activation); this package only answers "is this sidecar well-formed" and "did this key sign exactly these bytes", and does so with a stable machine-readable code for every refusal so two implementations can be shown to reject identically.
Index ¶
- Constants
- func CheckKeyIDAgreement(manifestKeyID string, sc *Sidecar, verified Key) error
- func CodeOf(err error) string
- func KeyID(pub ed25519.PublicKey) string
- func ParsePublicKey(s string) (ed25519.PublicKey, error)
- func SignSidecar(priv ed25519.PrivateKey, bundle []byte) []byte
- type Error
- type Key
- type Sidecar
- type TrustSet
Constants ¶
const ( CodeSidecarTooLarge = "sidecar_too_large" // row 1 CodeSidecarMalformed = "sidecar_malformed" // row 2 CodeSidecarMissingField = "sidecar_missing_field" // row 3 CodeSidecarUnknownField = "sidecar_unknown_field" // row 4 CodeSidecarDuplicateField = "sidecar_duplicate_field" // row 5 CodeSidecarType = "sidecar_type" // row 6 CodeSidecarVersionUnsupported = "sidecar_version_unsupported" // row 7 CodeSidecarAlgorithmUnsupported = "sidecar_algorithm_unsupported" // row 8 CodeSidecarKeyIDMalformed = "sidecar_key_id_malformed" // row 9 CodeSidecarSignatureMalformed = "sidecar_signature_malformed" // row 10 CodeKeyNotTrusted = "key_not_trusted" // row 11 CodeSignatureInvalid = "signature_invalid" // row 12 CodeKeyIDMismatch = "key_id_mismatch" // row 13 )
Rejection codes, one per contract row 1..13. They are part of the wire contract (surfaced as LastRejection reasons) and must not be renamed.
const MaxSidecarBytes = 4096
MaxSidecarBytes is the FR-011 cap on a sidecar. It is checked before any parsing because the sidecar is read before anything is authenticated.
Variables ¶
This section is empty.
Functions ¶
func CheckKeyIDAgreement ¶
CheckKeyIDAgreement enforces row 13: the manifest's key_id, the sidecar's key_id and the verifying key's id must all be identical. An empty manifest key id is a mismatch, never "unspecified".
func CodeOf ¶
CodeOf returns the contract reason code carried by err (looking through wrapping), or "" when err is nil or not a bundlesig rejection.
func KeyID ¶
KeyID returns the fingerprint of an Ed25519 public key: the lowercase hex SHA-256 of its 32 raw bytes. It is a property of the key itself, never an operator-chosen label, which is what makes "manifest names one publisher, bytes signed by another" detectable.
func ParsePublicKey ¶
ParsePublicKey decodes a configured signer: standard padded base64 of exactly 32 bytes. Like the sidecar signature it must be strict and canonical, so a trust anchor cannot be spelled two ways.
func SignSidecar ¶
func SignSidecar(priv ed25519.PrivateKey, bundle []byte) []byte
SignSidecar returns the canonical sidecar for bundle: one line, keys in the order sidecar_version, algorithm, key_id, signature, no trailing newline. It exists for publishers and tests; the loader never signs anything.
Types ¶
type Error ¶
Error is a contract rejection carrying its stable reason code. Detail is human-oriented context and never part of the contract.
type Key ¶
Key is one trusted signer. Authority names the root it belongs to; this package stores it and hands it back but attaches no meaning to it.
type Sidecar ¶
Sidecar is a parsed, grammar-valid sidecar. Parsing proves only that the sidecar is well-formed; nothing here is authenticated until TrustSet.Verify succeeds.
func ParseSidecar ¶
ParseSidecar parses sidecar bytes under the contract's total grammar, evaluating rows 1..10 in numerical order; the first matching row wins so overlapping conditions (e.g. {"foo":1} is both missing-a-field and has-an-unknown-key) always report the same reason.
JSON whitespace around the object is tolerated (a trailing newline is normal); any other trailing byte is sidecar_malformed.
type TrustSet ¶
type TrustSet struct {
// contains filtered or unexported fields
}
TrustSet is an immutable set of trusted keys indexed by key id.
func NewTrustSet ¶
NewTrustSet validates and indexes keys. It refuses a wrong-length key, a key whose ID is not the fingerprint of its Public bytes, and a duplicate id even across authorities: a single key must not be able to satisfy whichever root happens to be active. It copies the key bytes, so later mutation of the caller's slices cannot change what verifies.
func (*TrustSet) Verify ¶
Verify checks sc against bundle: row 11 (the sidecar's key id must be known to the WHOLE set) then row 12 (Ed25519 over the exact raw bundle bytes). On success it returns the verifying key.
Verify deliberately does not decide which authority is active. A genuine key of the non-active root must verify here so the caller can report authority_not_active rather than a misleading key_not_trusted.