signing

Documentation

Overview

Package signing provides Ed25519 helpers for ShiftLock high-value records.

It signs capabilities, config bundles, audit checkpoints, and quorum decisions using the Go standard library only — no custom cryptography.

Index

• Constants
• Variables
• func CanonicalJSON(v any) ([]byte, error)
• func EncodeSignature(sig Signature) string
• func HashPayload(v any) ([32]byte, error)
• func VerifyBytes(keys *KeyRing, payload []byte, sig Signature) error
• func VerifyCanonical(keys *KeyRing, v any, sig Signature) error
• type KeyID
• type KeyRing
  • func NewKeyRing() *KeyRing
  • func (r *KeyRing) Add(k PublicKey) error
  • func (r *KeyRing) IDs() []KeyID
  • func (r *KeyRing) Len() int
  • func (r *KeyRing) Lookup(id KeyID) (PublicKey, bool)
  • func (r *KeyRing) Remove(id KeyID)
  • func (r *KeyRing) Retire(id KeyID)
• type PrivateKey
  • func GenerateKey() (PrivateKey, error)
  • func (k PrivateKey) PublicView() PublicKey
• type PublicKey
  • func (k PublicKey) ValidAt(t time.Time) bool
• type Signature
  • func DecodeSignature(s string) (Signature, error)
  • func SignBytes(key PrivateKey, payload []byte) (Signature, error)
  • func SignCanonical(key PrivateKey, v any) (Signature, []byte, error)

Constants

const AlgorithmEd25519 = "ed25519"

Variables

var (
	ErrUnknownKey     = errors.New("signing: unknown key id")
	ErrExpiredKey     = errors.New("signing: key expired")
	ErrInvalidSig     = errors.New("signing: invalid signature")
	ErrEmptyPayload   = errors.New("signing: empty payload")
	ErrNoTrustedKeys  = errors.New("signing: no trusted keys")
	ErrDuplicateKeyID = errors.New("signing: duplicate key id")
)

Functions

func CanonicalJSON

func CanonicalJSON(v any) ([]byte, error)

CanonicalJSON produces deterministic JSON: sorted object keys, no HTML escape.

func EncodeSignature

func EncodeSignature(sig Signature) string

EncodeSignature returns a compact base64url encoding for transport.

func HashPayload

func HashPayload(v any) ([32]byte, error)

HashPayload returns SHA-256 of canonical JSON for v.

func VerifyBytes

func VerifyBytes(keys *KeyRing, payload []byte, sig Signature) error

VerifyBytes verifies a detached signature over payload.

func VerifyCanonical

func VerifyCanonical(keys *KeyRing, v any, sig Signature) error

VerifyCanonical verifies a signature over the canonical form of v.

Types

type KeyID

type KeyID string

KeyID identifies a trusted signing key across rotation windows.

type KeyRing

type KeyRing struct {
	// contains filtered or unexported fields
}

KeyRing holds multiple trusted public keys for rotation windows.

func NewKeyRing

func NewKeyRing() *KeyRing

NewKeyRing creates an empty ring.

func (*KeyRing) Add

func (r *KeyRing) Add(k PublicKey) error

Add trusts a public key. Duplicate IDs with different material are rejected.

func (*KeyRing) IDs

func (r *KeyRing) IDs() []KeyID

IDs returns sorted key IDs.

func (*KeyRing) Len

func (r *KeyRing) Len() int

Len returns the number of keys in the ring.

func (*KeyRing) Lookup

func (r *KeyRing) Lookup(id KeyID) (PublicKey, bool)

Lookup returns a trusted key by ID.

func (*KeyRing) Remove

func (r *KeyRing) Remove(id KeyID)

Remove drops a key entirely.

func (*KeyRing) Retire

func (r *KeyRing) Retire(id KeyID)

Retire marks a key as untrusted for new verification (rotation).

type PrivateKey

type PrivateKey struct {
	ID        KeyID
	Public    ed25519.PublicKey
	Private   ed25519.PrivateKey
	CreatedAt time.Time
	ExpiresAt *time.Time
}

PrivateKey holds a signing keypair. Never serialize private material to audit.

func GenerateKey

func GenerateKey() (PrivateKey, error)

GenerateKey creates a new Ed25519 keypair with a random key ID.

func (PrivateKey) PublicView

func (k PrivateKey) PublicView() PublicKey

PublicView returns the verification half.

type PublicKey

type PublicKey struct {
	ID        KeyID             `json:"id"`
	Public    ed25519.PublicKey `json:"public"`
	CreatedAt time.Time         `json:"created_at"`
	ExpiresAt *time.Time        `json:"expires_at,omitempty"`
	Retired   bool              `json:"retired,omitempty"`
}

PublicKey is a trusted verification key with optional expiry.

func (PublicKey) ValidAt

func (k PublicKey) ValidAt(t time.Time) bool

ValidAt reports whether the key may verify signatures at t.

type Signature

type Signature struct {
	KeyID     KeyID     `json:"key_id"`
	Algorithm string    `json:"algorithm"`
	Version   uint32    `json:"version"`
	SignedAt  time.Time `json:"signed_at"`
	Sig       []byte    `json:"sig"`
}

Signature is a versioned detached signature over canonical bytes.

func DecodeSignature

func DecodeSignature(s string) (Signature, error)

DecodeSignature parses EncodeSignature output.

func SignBytes

func SignBytes(key PrivateKey, payload []byte) (Signature, error)

SignBytes signs raw payload bytes with the private key.

func SignCanonical

func SignCanonical(key PrivateKey, v any) (Signature, []byte, error)

SignCanonical marshals v canonically and signs the bytes.