net: golang.org/x/net/dns/dnsmessage Index | Examples | Files

package dnsmessage

import "golang.org/x/net/dns/dnsmessage"

Package dnsmessage provides a mostly RFC 1035 compliant implementation of DNS message packing and unpacking.

This implementation is designed to minimize heap allocations and avoid unnecessary packing and unpacking as much as possible.

Index

Examples

Package Files

message.go

Constants

const (
    // ResourceHeader.Type and Question.Type
    TypeA     Type = 1
    TypeNS    Type = 2
    TypeCNAME Type = 5
    TypeSOA   Type = 6
    TypePTR   Type = 12
    TypeMX    Type = 15
    TypeTXT   Type = 16
    TypeAAAA  Type = 28
    TypeSRV   Type = 33

    // Question.Type
    TypeWKS   Type = 11
    TypeHINFO Type = 13
    TypeMINFO Type = 14
    TypeAXFR  Type = 252
    TypeALL   Type = 255

    // ResourceHeader.Class and Question.Class
    ClassINET   Class = 1
    ClassCSNET  Class = 2
    ClassCHAOS  Class = 3
    ClassHESIOD Class = 4

    // Question.Class
    ClassANY Class = 255

    // Message.Rcode
    RCodeSuccess        RCode = 0
    RCodeFormatError    RCode = 1
    RCodeServerFailure  RCode = 2
    RCodeNameError      RCode = 3
    RCodeNotImplemented RCode = 4
    RCodeRefused        RCode = 5
)

Wire constants.

Variables

var (
    // ErrNotStarted indicates that the prerequisite information isn't
    // available yet because the previous records haven't been appropriately
    // parsed, skipped or finished.
    ErrNotStarted = errors.New("parsing/packing of this type isn't available yet")

    // ErrSectionDone indicated that all records in the section have been
    // parsed or finished.
    ErrSectionDone = errors.New("parsing/packing of this section has completed")
)

type AAAAResource Uses

type AAAAResource struct {
    AAAA [16]byte
}

An AAAAResource is an AAAA Resource record.

type AResource Uses

type AResource struct {
    A [4]byte
}

An AResource is an A Resource record.

type Builder Uses

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

A Builder allows incrementally packing a DNS message.

func (*Builder) AAAAResource Uses

func (b *Builder) AAAAResource(h ResourceHeader, r AAAAResource) error

AAAAResource adds a single AAAAResource.

func (*Builder) AResource Uses

func (b *Builder) AResource(h ResourceHeader, r AResource) error

AResource adds a single AResource.

func (*Builder) CNAMEResource Uses

func (b *Builder) CNAMEResource(h ResourceHeader, r CNAMEResource) error

CNAMEResource adds a single CNAMEResource.

func (*Builder) Finish Uses

func (b *Builder) Finish() ([]byte, error)

Finish ends message building and generates a binary packet.

func (*Builder) MXResource Uses

func (b *Builder) MXResource(h ResourceHeader, r MXResource) error

MXResource adds a single MXResource.

func (*Builder) NSResource Uses

func (b *Builder) NSResource(h ResourceHeader, r NSResource) error

NSResource adds a single NSResource.

func (*Builder) PTRResource Uses

func (b *Builder) PTRResource(h ResourceHeader, r PTRResource) error

PTRResource adds a single PTRResource.

func (*Builder) Question Uses

func (b *Builder) Question(q Question) error

Question adds a single Question.

func (*Builder) SOAResource Uses

func (b *Builder) SOAResource(h ResourceHeader, r SOAResource) error

SOAResource adds a single SOAResource.

func (*Builder) SRVResource Uses

func (b *Builder) SRVResource(h ResourceHeader, r SRVResource) error

SRVResource adds a single SRVResource.

func (*Builder) Start Uses

func (b *Builder) Start(buf []byte, h Header)

Start initializes the builder.

buf is optional (nil is fine), but if provided, Start takes ownership of buf.

func (*Builder) StartAdditionals Uses

func (b *Builder) StartAdditionals() error

StartAdditionals prepares the builder for packing Additionals.

func (*Builder) StartAnswers Uses

func (b *Builder) StartAnswers() error

StartAnswers prepares the builder for packing Answers.

func (*Builder) StartAuthorities Uses

func (b *Builder) StartAuthorities() error

StartAuthorities prepares the builder for packing Authorities.

func (*Builder) StartQuestions Uses

func (b *Builder) StartQuestions() error

StartQuestions prepares the builder for packing Questions.

func (*Builder) StartWithoutCompression Uses

func (b *Builder) StartWithoutCompression(buf []byte, h Header)

StartWithoutCompression initializes the builder with compression disabled.

This avoids compression related allocations, but can result in larger message sizes. Be careful with this mode as it can cause messages to exceed the UDP size limit.

buf is optional (nil is fine), but if provided, Start takes ownership of buf.

func (*Builder) TXTResource Uses

func (b *Builder) TXTResource(h ResourceHeader, r TXTResource) error

TXTResource adds a single TXTResource.

type CNAMEResource Uses

type CNAMEResource struct {
    CNAME Name
}

A CNAMEResource is a CNAME Resource record.

type Class Uses

type Class uint16

A Class is a type of network.

type Header struct {
    ID                 uint16
    Response           bool
    OpCode             OpCode
    Authoritative      bool
    Truncated          bool
    RecursionDesired   bool
    RecursionAvailable bool
    RCode              RCode
}

Header is a representation of a DNS message header.

type MXResource Uses

type MXResource struct {
    Pref uint16
    MX   Name
}

An MXResource is an MX Resource record.

type Message Uses

type Message struct {
    Header
    Questions   []Question
    Answers     []Resource
    Authorities []Resource
    Additionals []Resource
}

Message is a representation of a DNS message.

func (*Message) AppendPack Uses

func (m *Message) AppendPack(b []byte) ([]byte, error)

AppendPack is like Pack but appends the full Message to b and returns the extended buffer.

func (*Message) Pack Uses

func (m *Message) Pack() ([]byte, error)

Pack packs a full Message.

func (*Message) Unpack Uses

func (m *Message) Unpack(msg []byte) error

Unpack parses a full Message.

type NSResource Uses

type NSResource struct {
    NS Name
}

An NSResource is an NS Resource record.

type Name Uses

type Name struct {
    Data   [nameLen]byte
    Length uint8
}

A Name is a non-encoded domain name. It is used instead of strings to avoid allocations.

func NewName Uses

func NewName(name string) (Name, error)

NewName creates a new Name from a string.

func (Name) String Uses

func (n Name) String() string

type OpCode Uses

type OpCode uint16

An OpCode is a DNS operation code.

type PTRResource Uses

type PTRResource struct {
    PTR Name
}

A PTRResource is a PTR Resource record.

type Parser Uses

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

A Parser allows incrementally parsing a DNS message.

When parsing is started, the Header is parsed. Next, each Question can be either parsed or skipped. Alternatively, all Questions can be skipped at once. When all Questions have been parsed, attempting to parse Questions will return (nil, nil) and attempting to skip Questions will return (true, nil). After all Questions have been either parsed or skipped, all Answers, Authorities and Additionals can be either parsed or skipped in the same way, and each type of Resource must be fully parsed or skipped before proceeding to the next type of Resource.

Note that there is no requirement to fully skip or parse the message.

Code:

package main

import (
    "fmt"
    "net"
    "strings"

    "golang.org/x/net/dns/dnsmessage"
)

func mustNewName(name string) dnsmessage.Name {
    n, err := dnsmessage.NewName(name)
    if err != nil {
        panic(err)
    }
    return n
}

func main() {
    msg := dnsmessage.Message{
        Header: dnsmessage.Header{Response: true, Authoritative: true},
        Questions: []dnsmessage.Question{
            {
                Name:  mustNewName("foo.bar.example.com."),
                Type:  dnsmessage.TypeA,
                Class: dnsmessage.ClassINET,
            },
            {
                Name:  mustNewName("bar.example.com."),
                Type:  dnsmessage.TypeA,
                Class: dnsmessage.ClassINET,
            },
        },
        Answers: []dnsmessage.Resource{
            {
                dnsmessage.ResourceHeader{
                    Name:  mustNewName("foo.bar.example.com."),
                    Type:  dnsmessage.TypeA,
                    Class: dnsmessage.ClassINET,
                },
                &dnsmessage.AResource{[4]byte{127, 0, 0, 1}},
            },
            {
                dnsmessage.ResourceHeader{
                    Name:  mustNewName("bar.example.com."),
                    Type:  dnsmessage.TypeA,
                    Class: dnsmessage.ClassINET,
                },
                &dnsmessage.AResource{[4]byte{127, 0, 0, 2}},
            },
        },
    }

    buf, err := msg.Pack()
    if err != nil {
        panic(err)
    }

    wantName := "bar.example.com."

    var p dnsmessage.Parser
    if _, err := p.Start(buf); err != nil {
        panic(err)
    }

    for {
        q, err := p.Question()
        if err == dnsmessage.ErrSectionDone {
            break
        }
        if err != nil {
            panic(err)
        }

        if q.Name.String() != wantName {
            continue
        }

        fmt.Println("Found question for name", wantName)
        if err := p.SkipAllQuestions(); err != nil {
            panic(err)
        }
        break
    }

    var gotIPs []net.IP
    for {
        h, err := p.AnswerHeader()
        if err == dnsmessage.ErrSectionDone {
            break
        }
        if err != nil {
            panic(err)
        }

        if (h.Type != dnsmessage.TypeA && h.Type != dnsmessage.TypeAAAA) || h.Class != dnsmessage.ClassINET {
            continue
        }

        if !strings.EqualFold(h.Name.String(), wantName) {
            if err := p.SkipAnswer(); err != nil {
                panic(err)
            }
            continue
        }

        switch h.Type {
        case dnsmessage.TypeA:
            r, err := p.AResource()
            if err != nil {
                panic(err)
            }
            gotIPs = append(gotIPs, r.A[:])
        case dnsmessage.TypeAAAA:
            r, err := p.AAAAResource()
            if err != nil {
                panic(err)
            }
            gotIPs = append(gotIPs, r.AAAA[:])
        }
    }

    fmt.Printf("Found A/AAAA records for name %s: %v\n", wantName, gotIPs)

}

func (*Parser) AAAAResource Uses

func (p *Parser) AAAAResource() (AAAAResource, error)

AAAAResource parses a single AAAAResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) AResource Uses

func (p *Parser) AResource() (AResource, error)

AResource parses a single AResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) Additional Uses

func (p *Parser) Additional() (Resource, error)

Additional parses a single Additional Resource.

func (*Parser) AdditionalHeader Uses

func (p *Parser) AdditionalHeader() (ResourceHeader, error)

AdditionalHeader parses a single Additional ResourceHeader.

func (*Parser) AllAdditionals Uses

func (p *Parser) AllAdditionals() ([]Resource, error)

AllAdditionals parses all Additional Resources.

func (*Parser) AllAnswers Uses

func (p *Parser) AllAnswers() ([]Resource, error)

AllAnswers parses all Answer Resources.

func (*Parser) AllAuthorities Uses

func (p *Parser) AllAuthorities() ([]Resource, error)

AllAuthorities parses all Authority Resources.

func (*Parser) AllQuestions Uses

func (p *Parser) AllQuestions() ([]Question, error)

AllQuestions parses all Questions.

func (*Parser) Answer Uses

func (p *Parser) Answer() (Resource, error)

Answer parses a single Answer Resource.

func (*Parser) AnswerHeader Uses

func (p *Parser) AnswerHeader() (ResourceHeader, error)

AnswerHeader parses a single Answer ResourceHeader.

func (*Parser) Authority Uses

func (p *Parser) Authority() (Resource, error)

Authority parses a single Authority Resource.

func (*Parser) AuthorityHeader Uses

func (p *Parser) AuthorityHeader() (ResourceHeader, error)

AuthorityHeader parses a single Authority ResourceHeader.

func (*Parser) CNAMEResource Uses

func (p *Parser) CNAMEResource() (CNAMEResource, error)

CNAMEResource parses a single CNAMEResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) MXResource Uses

func (p *Parser) MXResource() (MXResource, error)

MXResource parses a single MXResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) NSResource Uses

func (p *Parser) NSResource() (NSResource, error)

NSResource parses a single NSResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) PTRResource Uses

func (p *Parser) PTRResource() (PTRResource, error)

PTRResource parses a single PTRResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) Question Uses

func (p *Parser) Question() (Question, error)

Question parses a single Question.

func (*Parser) SOAResource Uses

func (p *Parser) SOAResource() (SOAResource, error)

SOAResource parses a single SOAResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) SRVResource Uses

func (p *Parser) SRVResource() (SRVResource, error)

SRVResource parses a single SRVResource.

One of the XXXHeader methods must have been called before calling this method.

func (*Parser) SkipAdditional Uses

func (p *Parser) SkipAdditional() error

SkipAdditional skips a single Additional Resource.

func (*Parser) SkipAllAdditionals Uses

func (p *Parser) SkipAllAdditionals() error

SkipAllAdditionals skips all Additional Resources.

func (*Parser) SkipAllAnswers Uses

func (p *Parser) SkipAllAnswers() error

SkipAllAnswers skips all Answer Resources.

func (*Parser) SkipAllAuthorities Uses

func (p *Parser) SkipAllAuthorities() error

SkipAllAuthorities skips all Authority Resources.

func (*Parser) SkipAllQuestions Uses

func (p *Parser) SkipAllQuestions() error

SkipAllQuestions skips all Questions.

func (*Parser) SkipAnswer Uses

func (p *Parser) SkipAnswer() error

SkipAnswer skips a single Answer Resource.

func (*Parser) SkipAuthority Uses

func (p *Parser) SkipAuthority() error

SkipAuthority skips a single Authority Resource.

func (*Parser) SkipQuestion Uses

func (p *Parser) SkipQuestion() error

SkipQuestion skips a single Question.

func (*Parser) Start Uses

func (p *Parser) Start(msg []byte) (Header, error)

Start parses the header and enables the parsing of Questions.

func (*Parser) TXTResource Uses

func (p *Parser) TXTResource() (TXTResource, error)

TXTResource parses a single TXTResource.

One of the XXXHeader methods must have been called before calling this method.

type Question Uses

type Question struct {
    Name  Name
    Type  Type
    Class Class
}

A Question is a DNS query.

type RCode Uses

type RCode uint16

An RCode is a DNS response status code.

type Resource Uses

type Resource struct {
    Header ResourceHeader
    Body   ResourceBody
}

A Resource is a DNS resource record.

type ResourceBody Uses

type ResourceBody interface {
    // contains filtered or unexported methods
}

A ResourceBody is a DNS resource record minus the header.

type ResourceHeader Uses

type ResourceHeader struct {
    // Name is the domain name for which this resource record pertains.
    Name Name

    // Type is the type of DNS resource record.
    //
    // This field will be set automatically during packing.
    Type Type

    // Class is the class of network to which this DNS resource record
    // pertains.
    Class Class

    // TTL is the length of time (measured in seconds) which this resource
    // record is valid for (time to live). All Resources in a set should
    // have the same TTL (RFC 2181 Section 5.2).
    TTL uint32

    // Length is the length of data in the resource record after the header.
    //
    // This field will be set automatically during packing.
    Length uint16
}

A ResourceHeader is the header of a DNS resource record. There are many types of DNS resource records, but they all share the same header.

type SOAResource Uses

type SOAResource struct {
    NS      Name
    MBox    Name
    Serial  uint32
    Refresh uint32
    Retry   uint32
    Expire  uint32

    // MinTTL the is the default TTL of Resources records which did not
    // contain a TTL value and the TTL of negative responses. (RFC 2308
    // Section 4)
    MinTTL uint32
}

An SOAResource is an SOA Resource record.

type SRVResource Uses

type SRVResource struct {
    Priority uint16
    Weight   uint16
    Port     uint16
    Target   Name // Not compressed as per RFC 2782.
}

An SRVResource is an SRV Resource record.

type TXTResource Uses

type TXTResource struct {
    Txt string // Not a domain name.
}

A TXTResource is a TXT Resource record.

type Type Uses

type Type uint16

A Type is a type of DNS request and response.

Package dnsmessage imports 1 packages (graph) and is imported by 1 packages. Updated 2017-12-12. Refresh now. Tools for package owners.