Go: dnsid — key providers

Generated from the Go source by scripts/gen-docs.sh — do not edit; run it to regenerate. Canonical deep reference: pkg.go.dev/github.com/dnsid-ai/dnsid-go. Guides and account setup: https://docs.dnsid.ai.

Part of the root package github.com/dnsid-ai/dnsid-go — see Core: IdentityManager for the package overview.

func SignLogEventWithKey

func SignLogEventWithKey(event dnsidlog.LogEvent, role LogSignerRole, kp KeyProvider, canonicalizer LogEventCanonicalizer) (dnsidlog.LogEvent, error)

SignLogEventWithKey adds one lifecycle signature using an explicitly supplied key provider and bound log canonicalizer. It is suitable for accountable entity services that do not possess the operational private key.

type KeyAge

KeyAge is a DNSid key-age policy value.

type KeyAge string

type KeyProvider

KeyProvider abstracts key storage for the SDK.

type KeyProvider interface {
    // JWK returns one public JWK. With no kid it returns the active key.
    JWK(kid ...string) jwk.Key

    // ListKeyIds returns the active kid first, followed by retained kids.
    ListKeyIds() []string

    // Sign signs payload with the active key.
    Sign(payload []byte) (*KeySignature, error)

    // SignKey signs payload with a specific active or pending key.
    SignKey(kid string, payload []byte) (*KeySignature, error)

    // GenerateKey creates a pending key for alg and returns its kid.
    GenerateKey(alg JoseAlg) (string, error)

    // Activate promotes kid to active and retains the previous active key.
    Activate(kid string) error

    // Supersede removes a retained key after a completed rotation.
    Supersede(kid string) error

    // Purge removes a pending or retained key.
    Purge(kid string) error
}

type KeySignature

KeySignature is the result of signing with a KeyProvider’s active key.

type KeySignature struct {
    Kid       string
    Alg       JoseAlg
    Signature []byte
}

type LocalKeyProvider

LocalKeyProvider loads a JWK keypair from disk or holds in-memory keys. Only one provider instance may write a given file; there is no file locking.

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

func GenerateES256KeyProvider

func GenerateES256KeyProvider() *LocalKeyProvider

GenerateES256KeyProvider creates an ephemeral in-memory ES256 keypair.

func GenerateEd25519KeyProvider

func GenerateEd25519KeyProvider() *LocalKeyProvider

GenerateEd25519KeyProvider creates an ephemeral in-memory Ed25519 keypair.

func LoadOrCreateLocalKeyProvider

func LoadOrCreateLocalKeyProvider(path string, alg JoseAlg) (*LocalKeyProvider, error)

LoadOrCreateLocalKeyProvider loads a JWK keypair from disk, or creates one if path does not exist.

func NewLocalKeyProvider

func NewLocalKeyProvider(path string) (*LocalKeyProvider, error)

NewLocalKeyProvider loads a key store file. It accepts the current active/retained/pending store shape and the older flat private JWK shape.

func (*LocalKeyProvider) Activate

func (p *LocalKeyProvider) Activate(kid string) error

Activate promotes the named pending or retained key to active and retains the previously active key. It returns an *ArgumentError for unknown kids. Even when kid is already active, the store is persisted again so callers can retry a durability failure. On failure before publication the previous state is restored; ErrKeyStoreDurability leaves the new state in memory and on disk.

func (*LocalKeyProvider) GenerateKey

func (p *LocalKeyProvider) GenerateKey(alg JoseAlg) (string, error)

GenerateKey creates a new pending key for alg and returns its kid (the key’s RFC 7638 thumbprint). The new key is persisted to the provider’s key store file, when one is configured, before the kid is returned; the active key is unchanged until Activate is called. On ErrKeyStoreDurability, the pending key is retained and its kid is returned alongside the error.

func (*LocalKeyProvider) JWK

func (p *LocalKeyProvider) JWK(kidOpt ...string) jwk.Key

JWK returns the public JWK for the requested kid, or for the active key when no kid is given. The returned key carries kid, alg, and use=sig. It returns nil when the kid is unknown or no key is active.

func (*LocalKeyProvider) ListKeyIds

func (p *LocalKeyProvider) ListKeyIds() []string

ListKeyIds returns the active kid first, followed by retained kids in insertion order. Pending kids are not listed.

func (*LocalKeyProvider) Purge

func (p *LocalKeyProvider) Purge(kid string) error

Purge removes a pending or retained key and persists the change. Purging the active key or an unknown kid returns an *ArgumentError. On ErrKeyStoreDurability the removal is not rolled back.

func (*LocalKeyProvider) Sign

func (p *LocalKeyProvider) Sign(payload []byte) (*KeySignature, error)

Sign signs payload with the active key. It returns an error when no key is active. ES256 signatures are deterministic (RFC 6979) raw R||S; EdDSA signatures are standard Ed25519.

func (*LocalKeyProvider) SignKey

func (p *LocalKeyProvider) SignKey(kid string, payload []byte) (*KeySignature, error)

SignKey signs payload with the named key, which must be in the active or pending state; signing with a retained key returns an *ArgumentError.

func (*LocalKeyProvider) Supersede

func (p *LocalKeyProvider) Supersede(kid string) error

Supersede removes a retained key after a completed rotation. It returns an *ArgumentError when kid does not name a retained key.

type LogEventCanonicalizer

LogEventCanonicalizer produces the exact bytes covered by lifecycle-event signatures for one bound log method and reference.

type LogEventCanonicalizer interface {
    Canonical(event dnsidlog.LogEvent) ([]byte, error)
}

type LogSignerRole

LogSignerRole identifies a DNSid lifecycle-event signer. Signatures from all roles cover the same log-method canonical bytes.

type LogSignerRole string

The lifecycle-event signer roles: the accountable entity signature, the operational countersignature on ISSUANCE, and the previous- and new-operational signatures on KEY_ROTATION.

const (
    LogSignerEntity                      LogSignerRole = "entity"
    LogSignerOperationalCountersignature LogSignerRole = "operational_countersignature"
    LogSignerPreviousOperational         LogSignerRole = "previous_operational"
    LogSignerNewOperational              LogSignerRole = "new_operational"
)

func RequiredLogSignatures

func RequiredLogSignatures(event dnsidlog.LogEvent) ([]LogSignerRole, error)

RequiredLogSignatures returns the base draft-01 signer roles for event.