keyhandover

package
v0.7.15 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 11 Imported by: 0

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

View Source
const Algorithm = "ecdsa-p256-sha256"

Algorithm is the only key algorithm a handover names: the registry signs with ECDSA P-256 over SHA-256.

View Source
const PayloadType = "application/vnd.agentry.signing-key-handover+json"

PayloadType is the DSSE payload type of a handover.

View Source
const Schema = "signing-key-handover/1"

Schema names the format of a handover's payload.

Variables

This section is empty.

Functions

func KeyID

func KeyID(publicKeyPEM string) (string, error)

KeyID is the id a registry derives from a public key: the first 16 characters of the unpadded base64url SHA-256 of its DER encoding.

func Seal

func Seal(h Handover) ([]byte, error)

Seal encodes a valid handover as the payload the outgoing key signs.

Types

type Chain

type Chain struct {
	Registry  string     `json:"registry"`
	Handovers []Envelope `json:"handovers"`
}

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.

func Wrap

func Wrap(payload []byte, sig attest.DSSESignature) Envelope

Wrap puts a payload and the outgoing key's signature into an envelope.

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

func Open(env Envelope, fromPublicKeyPEM string) (Handover, error)

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.

func (Handover) Validate

func (h Handover) Validate() error

Validate checks that a handover is complete and that its incoming key's id is the id of the key it carries, so a statement cannot name one key and hand over another.

type Key

type Key struct {
	KeyID        string `json:"keyId"`
	Algorithm    string `json:"algorithm"`
	PublicKeyPEM string `json:"publicKeyPem"`
}

Key is a signing key as a handover names it.

Jump to

Keyboard shortcuts

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