algorithms

Documentation

Overview

Package algorithms is tdns's runtime registry of DNSSEC signature algorithms — the bridge between miekg/dns's algorithm registry and the rest of tdns (CLI argument validation, --help text, key generation flows). Applications register an algorithm by codepoint and capability set; tdns code queries the registry to decide what names are valid input and what algorithms appear in --help.

Built-in algorithms (RSASHA*, ECDSAP*, ED25519) are pre-registered at this package's init time. Out-of-tree algorithms (typically ML-DSA / SLH-DSA / Falcon / MAYO / SNOVA via the github.com/johanix/dnssec-algorithms subpackages) are registered by the application's main package:

import (
    algs "github.com/johanix/tdns/v2/algorithms"
    "github.com/johanix/dnssec-algorithms/mldsa44"
)

func init() {
    algs.Register(199, mldsa44.New(),
        algs.Capabilities{ForSIG0: true, ForDNSSEC: false})
}

Applications that handle algorithm names but don't sign/verify themselves (cliv2 talking to a server) use RegisterMetadata instead — same name+codepoint+capability tracking without importing a heavyweight algorithm implementation.

Index

• func AlgorithmName(num uint8) (string, bool)
• func AlgorithmNumber(name string) (uint8, bool)
• func Register(num uint8, impl dns.Algorithm, caps Capabilities, facts Facts)
• func RegisterMetadata(num uint8, name string, caps Capabilities, facts Facts)
• func SupportedDNSSEC() []string
• func SupportedKSK() []string
• func SupportedSIG0() []string
• func SupportedZSK() []string
• type AlgorithmInfo
  • func All() []AlgorithmInfo
• type Capabilities
  • func Caps(num uint8) (Capabilities, bool)
  • func CapsReal(num uint8) (Capabilities, bool)
• type Facts

Functions

func AlgorithmName

func AlgorithmName(num uint8) (string, bool)

AlgorithmName returns the registered name for codepoint num, or "", false if no algorithm is registered at that codepoint.

func AlgorithmNumber

func AlgorithmNumber(name string) (uint8, bool)

AlgorithmNumber returns the DNSSEC algorithm number registered for name, or 0, false if name is unknown. name is case-sensitive — the canonical form is the uppercase string the algorithm registered itself with (e.g. "MLDSA44").

func Register

func Register(num uint8, impl dns.Algorithm, caps Capabilities, facts Facts)

Register wires impl into miekg/dns's algorithm registry at the given codepoint and records the capability set and static facts so tdns code can query them. Panics on conflict (init-time pattern — the application must resolve duplicate codepoints itself).

func RegisterMetadata

func RegisterMetadata(num uint8, name string, caps Capabilities, facts Facts)

RegisterMetadata records an algorithm's codepoint, name, capabilities, and static facts without touching miekg/dns's registry. Used by binaries that only need name-aware UI (e.g. CLI argument validation, --help text) but don't sign or verify with the algorithm themselves. Panics on conflict.

func SupportedDNSSEC

func SupportedDNSSEC() []string

SupportedDNSSEC returns the names of all registered algorithms whose capabilities permit DNSSEC zone signing, sorted by codepoint.

func SupportedKSK

func SupportedKSK() []string

SupportedKSK returns the names of all registered algorithms usable as a Key Signing Key, sorted by codepoint.

func SupportedSIG0

func SupportedSIG0() []string

SupportedSIG0 returns the names of all registered algorithms whose capabilities permit SIG(0) use, sorted by codepoint.

func SupportedZSK

func SupportedZSK() []string

SupportedZSK returns the names of all registered algorithms usable as a Zone Signing Key, sorted by codepoint.

Types

type AlgorithmInfo

type AlgorithmInfo struct {
	Number    uint8  `json:"number"`
	Name      string `json:"name"`
	ForSIG0   bool   `json:"forsig0"`
	ForDNSSEC bool   `json:"fordnssec"`
	ForKSK    bool   `json:"forksk"`
	ForZSK    bool   `json:"forzsk"`
	// Facts is the static, machine-independent enrichment (sizes, NIST
	// level, maturity, description). Carried so a server can report it to
	// the CLI listing, replacing the old algorithms.yaml enrichment file.
	Facts Facts `json:"facts"`
}

AlgorithmInfo is a serializable view of one registry entry. It is the unit returned by All and is what a server reports to the CLI so the CLI can resolve names to codepoints without its own hardcoded table.

func All

func All() []AlgorithmInfo

All returns every genuinely-usable (real) algorithm, sorted by codepoint. Metadata-only entries are excluded: a server must not advertise algorithms it cannot actually generate, sign, or verify with. This is the authoritative set a server reports to the CLI.

type Capabilities

type Capabilities struct {
	// ForSIG0 means the algorithm is accepted for SIG(0) transaction
	// signing — KEY rdata, SIG(0) message authentication.
	ForSIG0 bool

	// ForDNSSEC means the algorithm is accepted for DNSSEC zone
	// signing — DNSKEY rdata, RRSIG over RRsets. It is the umbrella
	// capability; ForKSK and ForZSK refine which zone-signing role(s)
	// the algorithm may fill.
	ForDNSSEC bool

	// ForKSK means the algorithm may be used as a Key Signing Key;
	// ForZSK means it may be used as a Zone Signing Key. They refine
	// ForDNSSEC: an algorithm whose signature is small enough to sit on
	// every RRSIG is ForZSK; one whose signature is only tolerable in
	// the (occasional, TCP/DoT) DNSKEY response — e.g. a code-based
	// signature of several KiB — is ForKSK but not ForZSK. Both are
	// meaningless unless ForDNSSEC is set. A classical algorithm is
	// typically {ForDNSSEC, ForKSK, ForZSK} all true.
	ForKSK bool
	ForZSK bool
}

Capabilities describes how an algorithm may be used.

func Caps

func Caps(num uint8) (Capabilities, bool)

Caps returns the capability set registered for codepoint num, or zero-value + false if num is unknown.

func CapsReal

func CapsReal(num uint8) (Capabilities, bool)

CapsReal is like Caps but returns ok=false for a metadata-only entry (one registered via RegisterMetadata but with no real implementation linked into this binary). Use it where accepting an algorithm implies the binary can actually generate/sign/verify with it — e.g. validating a DNSSEC policy's KSK/ZSK algorithms on a signing server, which must reject an algorithm it only knows the name of.

type Facts

type Facts struct {
	PubKeyBytes   int    `json:"pubkeybytes,omitempty"`
	SigBytes      int    `json:"sigbytes,omitempty"`
	SecKeyBytes   int    `json:"seckeybytes,omitempty"`
	SecurityLevel int    `json:"securitylevel,omitempty"`
	Maturity      string `json:"maturity,omitempty"`
	Description   string `json:"description,omitempty"`
}

Facts is static, machine-independent information about an algorithm, fixed by its specification (sizes, NIST level, maturity, description). It mirrors dnssec-algorithms/registry.Facts; the generated metadata carries it through so a binary can display it without a separate config file. All fields are optional — a zero value means "not provided" and is rendered as "-" by callers. Machine-dependent costs are deliberately NOT here (they belong in the measured, per-arch cost data).