Documentation
¶
Overview ¶
Package keyhandover is the statement a registry's outgoing release-signing key makes about its successor when the registry rotates to a new key on purpose: "the key that signs for this registry from now on is this one".
A client that pinned an earlier key on first use cannot tell a planned rotation from a takeover by looking at the new key set: both look like a key it has never seen. A handover signed by a key it already trusts can tell them apart. Following a chain of handovers, each verified with the key before it, lets the client trust the newest key without the person re-pinning, while a key that appears with no handover from a pinned key (a compromise, or a rotation forced past a lost key) is still never trusted on the registry's word alone.
A handover is a DSSE envelope of its own payload type, so a handover never verifies as an attestation or a managed settings document, and neither of those verifies as a handover.
Index ¶
Constants ¶
const Algorithm = "ecdsa-p256-sha256"
Algorithm is the only key algorithm a handover names: the registry signs with ECDSA P-256 over SHA-256.
const PayloadType = "application/vnd.agentry.signing-key-handover+json"
PayloadType is the DSSE payload type of a handover.
const Schema = "signing-key-handover/1"
Schema names the format of a handover's payload.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Chain ¶
Chain is the document a registry serves beside its key set: every handover it has made, oldest first.
type Envelope ¶
type Envelope = attest.DSSEEnvelope
Envelope is a signed handover as the registry serves it.
type Handover ¶
type Handover struct {
Schema string `json:"schema"`
// Registry is the base URL of the registry whose signing key changes.
Registry string `json:"registry"`
// From is the outgoing key's id: the key that signs this statement.
From string `json:"from"`
// To is the incoming key, whole, so a client can adopt it from the
// statement alone.
To Key `json:"to"`
// At is when the outgoing key signed it.
At time.Time `json:"at"`
}
Handover is what the outgoing key signs.
func Follow ¶
func Follow(registry string, trusted []Key, chain Chain, normalize func(string) string) ([]Handover, error)
Follow walks a registry's chain from the keys a client already trusts and returns the handovers it can verify, in the order it adopted them: each one opened with a key that was trusted before it, for the registry the client names. A handover from a key the client never trusted is passed over (it proves nothing to this client), and so is one for another registry. A key the walk already trusts is never handed over again, so a chain that loops back ends.
registry is compared after normalize, which the caller supplies so the package carries no rule of its own for spelling a registry's address.
func Open ¶
Open verifies an envelope with the outgoing key, which the caller already trusts, and decodes the handover. It refuses another payload type, a field the format does not have, a statement whose outgoing key is not the key that verified it, and an incoming key whose id does not match. It does not check the registry: Follow does.