pkarr

Documentation

Overview

Package pkarr implements the pkarr (https://pkarr.org) signed DNS packet format used by iroh for endpoint discovery.

Wire format: <32-byte public key><64-byte signature><8-byte big-endian microsecond timestamp><DNS wire packet>. The signature covers the BEP-0044 signable bytes derived from the timestamp and the encoded DNS packet. The DNS packet must be at most 1000 bytes; the total signed packet is at most 1104.

It is a port of iroh-dns/src/pkarr.rs.

Index

• Constants
• Variables
• type SignedPacket
  • func FromBytes(b []byte) (*SignedPacket, error)
  • func FromBytesUnchecked(b []byte) (*SignedPacket, error)
  • func FromRelayPayload(pub key.PublicKey, payload []byte) (*SignedPacket, error)
  • func FromTxtStrings(sk key.SecretKey, name string, values []string, ttl uint32) (*SignedPacket, error)
  • func (p *SignedPacket) AllTxtRecords() [][2]string
  • func (p *SignedPacket) Bytes() []byte
  • func (p *SignedPacket) EncodedPacket() []byte
  • func (p *SignedPacket) MoreRecentThan(other *SignedPacket) bool
  • func (p *SignedPacket) PublicKey() key.PublicKey
  • func (p *SignedPacket) RelayPayload() []byte
  • func (p *SignedPacket) Signature() key.Signature
  • func (p *SignedPacket) Timestamp() Timestamp
  • func (p *SignedPacket) TxtRecords(name string) []string
• type Timestamp
  • func Now() Timestamp
  • func TimestampFromMicros(micros uint64) Timestamp
  • func (t Timestamp) Micros() uint64

Constants

const (

	// MaxBytes is the maximum total size of a serialized signed packet.
	MaxBytes = headerSize + maxDNSPacketSize
)

Variables

var (
	ErrPacketTooLarge = errors.New("pkarr: DNS packet too large")
	ErrTooShort       = errors.New("pkarr: signed packet too short")
	ErrTooLarge       = errors.New("pkarr: signed packet too large")
	ErrSignature      = errors.New("pkarr: invalid signature")
	ErrDNS            = errors.New("pkarr: DNS decoding error")
	ErrInvalidKey     = errors.New("pkarr: invalid public key")
)

Errors returned by this package.

Types

type SignedPacket

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

SignedPacket is a signed DNS packet in the pkarr format. It is immutable; all accessors derive their result from the stored wire bytes.

func FromBytes

func FromBytes(b []byte) (*SignedPacket, error)

FromBytes parses and verifies a signed packet from its wire representation.

func FromBytesUnchecked

func FromBytesUnchecked(b []byte) (*SignedPacket, error)

FromBytesUnchecked parses a signed packet without verifying its signature. It still validates the minimum length and that the DNS packet parses.

func FromRelayPayload

func FromRelayPayload(pub key.PublicKey, payload []byte) (*SignedPacket, error)

FromRelayPayload reconstructs a signed packet from a public key and a relay payload (signature + timestamp + DNS packet, i.e. everything after the key).

func FromTxtStrings

func FromTxtStrings(sk key.SecretKey, name string, values []string, ttl uint32) (*SignedPacket, error)

FromTxtStrings creates a signed packet containing one TXT record per value, all under the single DNS name relative to the signer's z-base-32 public key (the common case, e.g. name "_iroh"). ttl is the record TTL in seconds.

func (*SignedPacket) AllTxtRecords

func (p *SignedPacket) AllTxtRecords() [][2]string

AllTxtRecords returns all TXT records as (name-relative-to-origin, value) pairs.

func (*SignedPacket) Bytes

func (p *SignedPacket) Bytes() []byte

Bytes returns the full serialized wire bytes. The result must not be mutated.

func (*SignedPacket) EncodedPacket

func (p *SignedPacket) EncodedPacket() []byte

EncodedPacket returns the encoded DNS packet bytes.

func (*SignedPacket) MoreRecentThan

func (p *SignedPacket) MoreRecentThan(other *SignedPacket) bool

MoreRecentThan reports whether p is more recent than other, breaking ties on equal timestamps by comparing the encoded DNS packets.

func (*SignedPacket) PublicKey

func (p *SignedPacket) PublicKey() key.PublicKey

PublicKey returns the signer's public key.

func (*SignedPacket) RelayPayload

func (p *SignedPacket) RelayPayload() []byte

RelayPayload returns the relay payload: everything after the public key.

func (*SignedPacket) Signature

func (p *SignedPacket) Signature() key.Signature

Signature returns the packet signature.

func (*SignedPacket) Timestamp

func (p *SignedPacket) Timestamp() Timestamp

Timestamp returns the packet timestamp.

func (*SignedPacket) TxtRecords

func (p *SignedPacket) TxtRecords(name string) []string

TxtRecords returns the TXT string values under the given DNS name (normalized relative to the signer's z-base-32 public key).

type Timestamp

type Timestamp uint64

Timestamp is a pkarr timestamp in microseconds since the UNIX epoch.

func Now

func Now() Timestamp

Now returns a strictly monotonic timestamp: greater than any previous call, even if the system clock moves backward.

func TimestampFromMicros

func TimestampFromMicros(micros uint64) Timestamp

TimestampFromMicros creates a timestamp from a raw microseconds value.

func (Timestamp) Micros

func (t Timestamp) Micros() uint64

Micros returns the raw microseconds value.