Skip to content
DNSid Docs

Go: dnsid — records & keys

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 ParseJWKSet

Section titled “func ParseJWKSet”
func ParseJWKSet(data []byte) (jwk.Set, error)

ParseJWKSet parses a JWKS JSON document and returns a validated raw JWK set.

func ParseLogRef

Section titled “func ParseLogRef”
func ParseLogRef(lr string) (method, entryRef string, err error)

ParseLogRef splits an lr= log reference of the form “method:entryRef” into its method and entry-reference parts. It returns a *ParseError for malformed references or invalid method names.

type DNSRecord

Section titled “type DNSRecord”

DNSRecord matches the OpenAPI DNSRecord schema.

type DNSRecord struct {
    Name  string `json:"name"`
    Type  string `json:"type"`
    Value string `json:"value"`
    TTL   int    `json:"ttl"`
}

type JWK

Section titled “type JWK”

JWK is a typed wrapper over a single JWK with SDK-level helpers.

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

func (*JWK) Alg

Section titled “func (*JWK) Alg”
func (k *JWK) Alg() JoseAlg

Alg returns the key’s effective signing algorithm, deriving it from kty/crv when the JWK alg member is absent.

func (*JWK) Kid

Section titled “func (*JWK) Kid”
func (k *JWK) Kid() string

Kid returns the key’s kid value, or empty string if unset.

func (*JWK) Raw

Section titled “func (*JWK) Raw”
func (k *JWK) Raw() jwk.Key

Raw returns the underlying jwk.Key.

func (*JWK) SignatureAlg

Section titled “func (*JWK) SignatureAlg”
func (k *JWK) SignatureAlg(profile string) (JoseAlg, error)

SignatureAlg returns the signing algorithm allowed by the selected identity-record profile. Unlike JWK.Alg, draft profiles require an explicit alg member that is consistent with the key type. An empty profile selects DefaultPublishProfile.

func (*JWK) Thumbprint

Section titled “func (*JWK) Thumbprint”
func (k *JWK) Thumbprint() (string, error)

Thumbprint returns the RFC 7638 SHA-256 thumbprint of this key, base64url-unpadded encoded.

func (*JWK) Use

Section titled “func (*JWK) Use”
func (k *JWK) Use() string

Use returns the key’s use value, or empty string if unset.

type JWKS

Section titled “type JWKS”

JWKS is a typed wrapper over a JWK Set with SDK-level helpers.

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

func NewJWKS

Section titled “func NewJWKS”
func NewJWKS(set jwk.Set) *JWKS

NewJWKS wraps a jwk.Set into the typed SDK form.

func ParseJWKS

Section titled “func ParseJWKS”
func ParseJWKS(data []byte) (*JWKS, error)

ParseJWKS parses a JWKS JSON document and returns the typed wrapper.

func (*JWKS) CurrentOperationalSigningKey

Section titled “func (*JWKS) CurrentOperationalSigningKey”
func (j *JWKS) CurrentOperationalSigningKey(profile string) (*JWK, error)

CurrentOperationalSigningKey returns the sole current operational signing key allowed by the selected identity-record profile.

func (*JWKS) CurrentRecordSigningKey

Section titled “func (*JWKS) CurrentRecordSigningKey”
func (j *JWKS) CurrentRecordSigningKey(profile string) (*JWK, error)

CurrentRecordSigningKey returns the sole current record-signing key allowed by the selected identity-record profile.

func (*JWKS) KeyByID

Section titled “func (*JWKS) KeyByID”
func (j *JWKS) KeyByID(kid string) *JWK

KeyByID returns the key with the given kid, or nil if not found. This is an unfiltered lookup; the returned key may have use=enc or any other use value. Callers that want a signing-eligible key should filter the result against SigningKeys() or check Use() themselves.

func (*JWKS) Raw

Section titled “func (*JWKS) Raw”
func (j *JWKS) Raw() jwk.Set

Raw returns the underlying jwk.Set.

func (*JWKS) SigningKeys

Section titled “func (*JWKS) SigningKeys”
func (j *JWKS) SigningKeys() []*JWK

SigningKeys returns all keys eligible for signature verification. Keys with unset use or use=sig are eligible.

func (*JWKS) Validate

Section titled “func (*JWKS) Validate”
func (j *JWKS) Validate() error

Validate enforces SDK invariants for signing keys.

func (*JWKS) ValidateOperational

Section titled “func (*JWKS) ValidateOperational”
func (j *JWKS) ValidateOperational(profile string) error

ValidateOperational verifies that the JWKS satisfies the selected identity-record profile’s operational-key constraints. An empty profile selects DefaultPublishProfile.

func (*JWKS) ValidateRecordSigning

Section titled “func (*JWKS) ValidateRecordSigning”
func (j *JWKS) ValidateRecordSigning(profile string) error

ValidateRecordSigning verifies that the JWKS satisfies the selected identity-record profile’s record-signing-key constraints. An empty profile selects DefaultPublishProfile.

type JoseAlg

Section titled “type JoseAlg”

JoseAlg is the default-deny allowlist of JOSE algorithms DNSid accepts.

type JoseAlg string

The JOSE algorithms DNSid accepts: Ed25519 (EdDSA) and ECDSA over P-256 with SHA-256 (ES256). All other algorithms are rejected.

const (
    JoseAlgEdDSA JoseAlg = "EdDSA"
    JoseAlgES256 JoseAlg = "ES256"
)

func (JoseAlg) String

Section titled “func (JoseAlg) String”
func (a JoseAlg) String() string

String returns the JOSE alg identifier as a string.

func (JoseAlg) Valid

Section titled “func (JoseAlg) Valid”
func (a JoseAlg) Valid() bool

Valid reports whether a is in the DNSid JOSE algorithm allowlist.

type PolicyFlag

Section titled “type PolicyFlag”

PolicyFlag is a DNSid TXT-record policy flag.

type PolicyFlag string

DNSid TXT-record policy flags understood by the verifier.

const (
    PolicyFlagMTLS     PolicyFlag = "mtls"
    PolicyFlagLogCheck PolicyFlag = "logchk"
)

type TXTRecord

Section titled “type TXTRecord”

TXTRecord represents a parsed _dnsid TXT record.

type TXTRecord struct {
    Version      string            // v= — DNSid wire profile
    GovernanceID string            // gi= — governance identifier
    EntityKeyURI string            // ek= — accountable-entity record-signing JWKS URI
    KeyURI       string            // ku= — JWKS endpoint URL
    LogRef       string            // lr= — ledger address
    StatusURI    string            // su= — status endpoint URL
    Signature    string            // sg= — base64url owner signature
    Flags        []string          // fl= — parsed flag list (nil if absent)
    KeyAge       string            // ka= — key age policy (empty if absent)
    Capabilities string            // cu= — Agent Card URL (empty if absent)
    UnknownTags  map[string]string // syntactically valid extension tags, preserved but ignored semantically
}

func ParseTXTRecord

Section titled “func ParseTXTRecord”
func ParseTXTRecord(txt string) (*TXTRecord, error)

ParseTXTRecord parses a concatenated TXT record string into a TXTRecord.

func ParseUnsignedCanonical

Section titled “func ParseUnsignedCanonical”
func ParseUnsignedCanonical(txt string) (*TXTRecord, error)

ParseUnsignedCanonical parses registry-supplied unsigned canonical TXT content. It accepts required non-signature inputs and extension tags, but rejects sg=.

func (*TXTRecord) Canonical

Section titled “func (*TXTRecord) Canonical”
func (r *TXTRecord) Canonical() string

Canonical returns the canonical string used for TXT-record signature verification.

func (*TXTRecord) CanonicalContent

Section titled “func (*TXTRecord) CanonicalContent”
func (r *TXTRecord) CanonicalContent() []byte

CanonicalContent returns the canonical byte string for signing under the record’s declared profile. Values are signed as raw ASCII TXT tag values.

func (*TXTRecord) KnownTagsCanonical

Section titled “func (*TXTRecord) KnownTagsCanonical”
func (r *TXTRecord) KnownTagsCanonical() []byte

KnownTagsCanonical returns the canonical byte string for known TXT tags only, excluding sg=. Unknown extension tags are ignored.

func (*TXTRecord) MarshalTXT

Section titled “func (*TXTRecord) MarshalTXT”
func (r *TXTRecord) MarshalTXT() (string, error)

MarshalTXT serializes the record as one _dnsid TXT value for wire output. It emits v= first, then all other tags sorted lexically; signing order is profile-defined and may differ.

func (*TXTRecord) Serialize

Section titled “func (*TXTRecord) Serialize”
func (r *TXTRecord) Serialize() string

Serialize serializes the record as one _dnsid TXT value.

func (*TXTRecord) Tags

Section titled “func (*TXTRecord) Tags”
func (r *TXTRecord) Tags() map[string]string

Tags returns the record’s tag-value pairs as a map, excluding empty optional fields. It always emits the current wire tag names.

func (*TXTRecord) Validate

Section titled “func (*TXTRecord) Validate”
func (r *TXTRecord) Validate(identityFQDN string) error

Validate checks record-level semantics with identity-domain context.

func (*TXTRecord) WithSignature

Section titled “func (*TXTRecord) WithSignature”
func (r *TXTRecord) WithSignature(sig string) *TXTRecord

WithSignature returns a copy of the record with Signature set to sig.

type TXTRecordRData

Section titled “type TXTRecordRData”

TXTRecordRData is one concatenated TXT RDATA value plus resolver metadata.

type TXTRecordRData struct {
    Value string
    TTL   time.Duration
}

Known Systems AI, Inc. is an affiliate of Identity Digital that solves identity fragmentation for the AI agent economy. As agents become more autonomous and interoperable, they introduce risk and security challenges existing systems weren't designed for—starting with a consistent way to verify ownership across organizational boundaries. Known Systems AI, Inc. combines Identity Digital's DNS expertise with an Immutable Log to establish a global coordination layer for AI agent identity, and participates in open standards communities, including the Linux Foundation. For more information, visit DNSid.ai.