Source file src/github.com/miekg/dns/client.go

Documentation: github.com/miekg/dns

     1  package dns
     2  
     3  // A client implementation.
     4  
     5  import (
     6  	"context"
     7  	"crypto/tls"
     8  	"encoding/binary"
     9  	"io"
    10  	"net"
    11  	"strings"
    12  	"time"
    13  )
    14  
    15  const (
    16  	dnsTimeout     time.Duration = 2 * time.Second
    17  	tcpIdleTimeout time.Duration = 8 * time.Second
    18  )
    19  
    20  func isPacketConn(c net.Conn) bool {
    21  	if _, ok := c.(net.PacketConn); !ok {
    22  		return false
    23  	}
    24  
    25  	if ua, ok := c.LocalAddr().(*net.UnixAddr); ok {
    26  		return ua.Net == "unixgram" || ua.Net == "unixpacket"
    27  	}
    28  
    29  	return true
    30  }
    31  
    32  // A Conn represents a connection to a DNS server.
    33  type Conn struct {
    34  	net.Conn                         // a net.Conn holding the connection
    35  	UDPSize        uint16            // minimum receive buffer for UDP messages
    36  	TsigSecret     map[string]string // secret(s) for Tsig map[<zonename>]<base64 secret>, zonename must be in canonical form (lowercase, fqdn, see RFC 4034 Section 6.2)
    37  	TsigProvider   TsigProvider      // An implementation of the TsigProvider interface. If defined it replaces TsigSecret and is used for all TSIG operations.
    38  	tsigRequestMAC string
    39  }
    40  
    41  func (co *Conn) tsigProvider() TsigProvider {
    42  	if co.TsigProvider != nil {
    43  		return co.TsigProvider
    44  	}
    45  	// tsigSecretProvider will return ErrSecret if co.TsigSecret is nil.
    46  	return tsigSecretProvider(co.TsigSecret)
    47  }
    48  
    49  // A Client defines parameters for a DNS client.
    50  type Client struct {
    51  	Net       string      // if "tcp" or "tcp-tls" (DNS over TLS) a TCP query will be initiated, otherwise an UDP one (default is "" for UDP)
    52  	UDPSize   uint16      // minimum receive buffer for UDP messages
    53  	TLSConfig *tls.Config // TLS connection configuration
    54  	Dialer    *net.Dialer // a net.Dialer used to set local address, timeouts and more
    55  	// Timeout is a cumulative timeout for dial, write and read, defaults to 0 (disabled) - overrides DialTimeout, ReadTimeout,
    56  	// WriteTimeout when non-zero. Can be overridden with net.Dialer.Timeout (see Client.ExchangeWithDialer and
    57  	// Client.Dialer) or context.Context.Deadline (see ExchangeContext)
    58  	Timeout      time.Duration
    59  	DialTimeout  time.Duration     // net.DialTimeout, defaults to 2 seconds, or net.Dialer.Timeout if expiring earlier - overridden by Timeout when that value is non-zero
    60  	ReadTimeout  time.Duration     // net.Conn.SetReadTimeout value for connections, defaults to 2 seconds - overridden by Timeout when that value is non-zero
    61  	WriteTimeout time.Duration     // net.Conn.SetWriteTimeout value for connections, defaults to 2 seconds - overridden by Timeout when that value is non-zero
    62  	TsigSecret   map[string]string // secret(s) for Tsig map[<zonename>]<base64 secret>, zonename must be in canonical form (lowercase, fqdn, see RFC 4034 Section 6.2)
    63  	TsigProvider TsigProvider      // An implementation of the TsigProvider interface. If defined it replaces TsigSecret and is used for all TSIG operations.
    64  
    65  	// SingleInflight previously serialised multiple concurrent queries for the
    66  	// same Qname, Qtype and Qclass to ensure only one would be in flight at a
    67  	// time.
    68  	//
    69  	// Deprecated: This is a no-op. Callers should implement their own in flight
    70  	// query caching if needed. See github.com/miekg/dns/issues/1449.
    71  	SingleInflight bool
    72  }
    73  
    74  // Exchange performs a synchronous UDP query. It sends the message m to the address
    75  // contained in a and waits for a reply. Exchange does not retry a failed query, nor
    76  // will it fall back to TCP in case of truncation.
    77  // See client.Exchange for more information on setting larger buffer sizes.
    78  func Exchange(m *Msg, a string) (r *Msg, err error) {
    79  	client := Client{Net: "udp"}
    80  	r, _, err = client.Exchange(m, a)
    81  	return r, err
    82  }
    83  
    84  func (c *Client) dialTimeout() time.Duration {
    85  	if c.Timeout != 0 {
    86  		return c.Timeout
    87  	}
    88  	if c.DialTimeout != 0 {
    89  		return c.DialTimeout
    90  	}
    91  	return dnsTimeout
    92  }
    93  
    94  func (c *Client) readTimeout() time.Duration {
    95  	if c.ReadTimeout != 0 {
    96  		return c.ReadTimeout
    97  	}
    98  	return dnsTimeout
    99  }
   100  
   101  func (c *Client) writeTimeout() time.Duration {
   102  	if c.WriteTimeout != 0 {
   103  		return c.WriteTimeout
   104  	}
   105  	return dnsTimeout
   106  }
   107  
   108  // Dial connects to the address on the named network.
   109  func (c *Client) Dial(address string) (conn *Conn, err error) {
   110  	return c.DialContext(context.Background(), address)
   111  }
   112  
   113  // DialContext connects to the address on the named network, with a context.Context.
   114  func (c *Client) DialContext(ctx context.Context, address string) (conn *Conn, err error) {
   115  	// create a new dialer with the appropriate timeout
   116  	var d net.Dialer
   117  	if c.Dialer == nil {
   118  		d = net.Dialer{Timeout: c.getTimeoutForRequest(c.dialTimeout())}
   119  	} else {
   120  		d = *c.Dialer
   121  	}
   122  
   123  	network := c.Net
   124  	if network == "" {
   125  		network = "udp"
   126  	}
   127  
   128  	useTLS := strings.HasPrefix(network, "tcp") && strings.HasSuffix(network, "-tls")
   129  
   130  	conn = new(Conn)
   131  	if useTLS {
   132  		network = strings.TrimSuffix(network, "-tls")
   133  
   134  		tlsDialer := tls.Dialer{
   135  			NetDialer: &d,
   136  			Config:    c.TLSConfig,
   137  		}
   138  		conn.Conn, err = tlsDialer.DialContext(ctx, network, address)
   139  	} else {
   140  		conn.Conn, err = d.DialContext(ctx, network, address)
   141  	}
   142  	if err != nil {
   143  		return nil, err
   144  	}
   145  	conn.UDPSize = c.UDPSize
   146  	return conn, nil
   147  }
   148  
   149  // Exchange performs a synchronous query. It sends the message m to the address
   150  // contained in a and waits for a reply. Basic use pattern with a *dns.Client:
   151  //
   152  //	c := new(dns.Client)
   153  //	in, rtt, err := c.Exchange(message, "127.0.0.1:53")
   154  //
   155  // Exchange does not retry a failed query, nor will it fall back to TCP in
   156  // case of truncation.
   157  // It is up to the caller to create a message that allows for larger responses to be
   158  // returned. Specifically this means adding an EDNS0 OPT RR that will advertise a larger
   159  // buffer, see SetEdns0. Messages without an OPT RR will fallback to the historic limit
   160  // of 512 bytes
   161  // To specify a local address or a timeout, the caller has to set the `Client.Dialer`
   162  // attribute appropriately
   163  func (c *Client) Exchange(m *Msg, address string) (r *Msg, rtt time.Duration, err error) {
   164  	co, err := c.Dial(address)
   165  
   166  	if err != nil {
   167  		return nil, 0, err
   168  	}
   169  	defer co.Close()
   170  	return c.ExchangeWithConn(m, co)
   171  }
   172  
   173  // ExchangeWithConn has the same behavior as Exchange, just with a predetermined connection
   174  // that will be used instead of creating a new one.
   175  // Usage pattern with a *dns.Client:
   176  //
   177  //	c := new(dns.Client)
   178  //	// connection management logic goes here
   179  //
   180  //	conn := c.Dial(address)
   181  //	in, rtt, err := c.ExchangeWithConn(message, conn)
   182  //
   183  // This allows users of the library to implement their own connection management,
   184  // as opposed to Exchange, which will always use new connections and incur the added overhead
   185  // that entails when using "tcp" and especially "tcp-tls" clients.
   186  func (c *Client) ExchangeWithConn(m *Msg, conn *Conn) (r *Msg, rtt time.Duration, err error) {
   187  	return c.ExchangeWithConnContext(context.Background(), m, conn)
   188  }
   189  
   190  // ExchangeWithConnContext has the same behaviour as ExchangeWithConn and
   191  // additionally obeys deadlines from the passed Context.
   192  func (c *Client) ExchangeWithConnContext(ctx context.Context, m *Msg, co *Conn) (r *Msg, rtt time.Duration, err error) {
   193  	opt := m.IsEdns0()
   194  	// If EDNS0 is used use that for size.
   195  	if opt != nil && opt.UDPSize() >= MinMsgSize {
   196  		co.UDPSize = opt.UDPSize()
   197  	}
   198  	// Otherwise use the client's configured UDP size.
   199  	if opt == nil && c.UDPSize >= MinMsgSize {
   200  		co.UDPSize = c.UDPSize
   201  	}
   202  
   203  	// write with the appropriate write timeout
   204  	t := time.Now()
   205  	writeDeadline := t.Add(c.getTimeoutForRequest(c.writeTimeout()))
   206  	readDeadline := t.Add(c.getTimeoutForRequest(c.readTimeout()))
   207  	if deadline, ok := ctx.Deadline(); ok {
   208  		if deadline.Before(writeDeadline) {
   209  			writeDeadline = deadline
   210  		}
   211  		if deadline.Before(readDeadline) {
   212  			readDeadline = deadline
   213  		}
   214  	}
   215  	co.SetWriteDeadline(writeDeadline)
   216  	co.SetReadDeadline(readDeadline)
   217  
   218  	co.TsigSecret, co.TsigProvider = c.TsigSecret, c.TsigProvider
   219  
   220  	if err = co.WriteMsg(m); err != nil {
   221  		return nil, 0, err
   222  	}
   223  
   224  	if isPacketConn(co.Conn) {
   225  		for {
   226  			r, err = co.ReadMsg()
   227  			// Ignore replies with mismatched IDs because they might be
   228  			// responses to earlier queries that timed out.
   229  			if err != nil || r.Id == m.Id {
   230  				break
   231  			}
   232  		}
   233  	} else {
   234  		r, err = co.ReadMsg()
   235  		if err == nil && r.Id != m.Id {
   236  			err = ErrId
   237  		}
   238  	}
   239  	rtt = time.Since(t)
   240  	return r, rtt, err
   241  }
   242  
   243  // ReadMsg reads a message from the connection co.
   244  // If the received message contains a TSIG record the transaction signature
   245  // is verified. This method always tries to return the message, however if an
   246  // error is returned there are no guarantees that the returned message is a
   247  // valid representation of the packet read.
   248  func (co *Conn) ReadMsg() (*Msg, error) {
   249  	p, err := co.ReadMsgHeader(nil)
   250  	if err != nil {
   251  		return nil, err
   252  	}
   253  
   254  	m := new(Msg)
   255  	if err := m.Unpack(p); err != nil {
   256  		// If an error was returned, we still want to allow the user to use
   257  		// the message, but naively they can just check err if they don't want
   258  		// to use an erroneous message
   259  		return m, err
   260  	}
   261  	if t := m.IsTsig(); t != nil {
   262  		// Need to work on the original message p, as that was used to calculate the tsig.
   263  		err = TsigVerifyWithProvider(p, co.tsigProvider(), co.tsigRequestMAC, false)
   264  	}
   265  	return m, err
   266  }
   267  
   268  // ReadMsgHeader reads a DNS message, parses and populates hdr (when hdr is not nil).
   269  // Returns message as a byte slice to be parsed with Msg.Unpack later on.
   270  // Note that error handling on the message body is not possible as only the header is parsed.
   271  func (co *Conn) ReadMsgHeader(hdr *Header) ([]byte, error) {
   272  	var (
   273  		p   []byte
   274  		n   int
   275  		err error
   276  	)
   277  
   278  	if isPacketConn(co.Conn) {
   279  		if co.UDPSize > MinMsgSize {
   280  			p = make([]byte, co.UDPSize)
   281  		} else {
   282  			p = make([]byte, MinMsgSize)
   283  		}
   284  		n, err = co.Read(p)
   285  	} else {
   286  		var length uint16
   287  		if err := binary.Read(co.Conn, binary.BigEndian, &length); err != nil {
   288  			return nil, err
   289  		}
   290  
   291  		p = make([]byte, length)
   292  		n, err = io.ReadFull(co.Conn, p)
   293  	}
   294  
   295  	if err != nil {
   296  		return nil, err
   297  	} else if n < headerSize {
   298  		return nil, ErrShortRead
   299  	}
   300  
   301  	p = p[:n]
   302  	if hdr != nil {
   303  		dh, _, err := unpackMsgHdr(p, 0)
   304  		if err != nil {
   305  			return nil, err
   306  		}
   307  		*hdr = dh
   308  	}
   309  	return p, err
   310  }
   311  
   312  // Read implements the net.Conn read method.
   313  func (co *Conn) Read(p []byte) (n int, err error) {
   314  	if co.Conn == nil {
   315  		return 0, ErrConnEmpty
   316  	}
   317  
   318  	if isPacketConn(co.Conn) {
   319  		// UDP connection
   320  		return co.Conn.Read(p)
   321  	}
   322  
   323  	var length uint16
   324  	if err := binary.Read(co.Conn, binary.BigEndian, &length); err != nil {
   325  		return 0, err
   326  	}
   327  	if int(length) > len(p) {
   328  		return 0, io.ErrShortBuffer
   329  	}
   330  
   331  	return io.ReadFull(co.Conn, p[:length])
   332  }
   333  
   334  // WriteMsg sends a message through the connection co.
   335  // If the message m contains a TSIG record the transaction
   336  // signature is calculated.
   337  func (co *Conn) WriteMsg(m *Msg) (err error) {
   338  	var out []byte
   339  	if t := m.IsTsig(); t != nil {
   340  		// Set tsigRequestMAC for the next read, although only used in zone transfers.
   341  		out, co.tsigRequestMAC, err = TsigGenerateWithProvider(m, co.tsigProvider(), co.tsigRequestMAC, false)
   342  	} else {
   343  		out, err = m.Pack()
   344  	}
   345  	if err != nil {
   346  		return err
   347  	}
   348  	_, err = co.Write(out)
   349  	return err
   350  }
   351  
   352  // Write implements the net.Conn Write method.
   353  func (co *Conn) Write(p []byte) (int, error) {
   354  	if len(p) > MaxMsgSize {
   355  		return 0, &Error{err: "message too large"}
   356  	}
   357  
   358  	if isPacketConn(co.Conn) {
   359  		return co.Conn.Write(p)
   360  	}
   361  
   362  	msg := make([]byte, 2+len(p))
   363  	binary.BigEndian.PutUint16(msg, uint16(len(p)))
   364  	copy(msg[2:], p)
   365  	return co.Conn.Write(msg)
   366  }
   367  
   368  // Return the appropriate timeout for a specific request
   369  func (c *Client) getTimeoutForRequest(timeout time.Duration) time.Duration {
   370  	var requestTimeout time.Duration
   371  	if c.Timeout != 0 {
   372  		requestTimeout = c.Timeout
   373  	} else {
   374  		requestTimeout = timeout
   375  	}
   376  	// net.Dialer.Timeout has priority if smaller than the timeouts computed so
   377  	// far
   378  	if c.Dialer != nil && c.Dialer.Timeout != 0 {
   379  		if c.Dialer.Timeout < requestTimeout {
   380  			requestTimeout = c.Dialer.Timeout
   381  		}
   382  	}
   383  	return requestTimeout
   384  }
   385  
   386  // Dial connects to the address on the named network.
   387  func Dial(network, address string) (conn *Conn, err error) {
   388  	conn = new(Conn)
   389  	conn.Conn, err = net.Dial(network, address)
   390  	if err != nil {
   391  		return nil, err
   392  	}
   393  	return conn, nil
   394  }
   395  
   396  // ExchangeContext performs a synchronous UDP query, like Exchange. It
   397  // additionally obeys deadlines from the passed Context.
   398  func ExchangeContext(ctx context.Context, m *Msg, a string) (r *Msg, err error) {
   399  	client := Client{Net: "udp"}
   400  	r, _, err = client.ExchangeContext(ctx, m, a)
   401  	// ignoring rtt to leave the original ExchangeContext API unchanged, but
   402  	// this function will go away
   403  	return r, err
   404  }
   405  
   406  // ExchangeConn performs a synchronous query. It sends the message m via the connection
   407  // c and waits for a reply. The connection c is not closed by ExchangeConn.
   408  // Deprecated: This function is going away, but can easily be mimicked:
   409  //
   410  //	co := &dns.Conn{Conn: c} // c is your net.Conn
   411  //	co.WriteMsg(m)
   412  //	in, _  := co.ReadMsg()
   413  //	co.Close()
   414  func ExchangeConn(c net.Conn, m *Msg) (r *Msg, err error) {
   415  	println("dns: ExchangeConn: this function is deprecated")
   416  	co := new(Conn)
   417  	co.Conn = c
   418  	if err = co.WriteMsg(m); err != nil {
   419  		return nil, err
   420  	}
   421  	r, err = co.ReadMsg()
   422  	if err == nil && r.Id != m.Id {
   423  		err = ErrId
   424  	}
   425  	return r, err
   426  }
   427  
   428  // DialTimeout acts like Dial but takes a timeout.
   429  func DialTimeout(network, address string, timeout time.Duration) (conn *Conn, err error) {
   430  	client := Client{Net: network, Dialer: &net.Dialer{Timeout: timeout}}
   431  	return client.Dial(address)
   432  }
   433  
   434  // DialWithTLS connects to the address on the named network with TLS.
   435  func DialWithTLS(network, address string, tlsConfig *tls.Config) (conn *Conn, err error) {
   436  	if !strings.HasSuffix(network, "-tls") {
   437  		network += "-tls"
   438  	}
   439  	client := Client{Net: network, TLSConfig: tlsConfig}
   440  	return client.Dial(address)
   441  }
   442  
   443  // DialTimeoutWithTLS acts like DialWithTLS but takes a timeout.
   444  func DialTimeoutWithTLS(network, address string, tlsConfig *tls.Config, timeout time.Duration) (conn *Conn, err error) {
   445  	if !strings.HasSuffix(network, "-tls") {
   446  		network += "-tls"
   447  	}
   448  	client := Client{Net: network, Dialer: &net.Dialer{Timeout: timeout}, TLSConfig: tlsConfig}
   449  	return client.Dial(address)
   450  }
   451  
   452  // ExchangeContext acts like Exchange, but honors the deadline on the provided
   453  // context, if present. If there is both a context deadline and a configured
   454  // timeout on the client, the earliest of the two takes effect.
   455  func (c *Client) ExchangeContext(ctx context.Context, m *Msg, a string) (r *Msg, rtt time.Duration, err error) {
   456  	conn, err := c.DialContext(ctx, a)
   457  	if err != nil {
   458  		return nil, 0, err
   459  	}
   460  	defer conn.Close()
   461  
   462  	return c.ExchangeWithConnContext(ctx, m, conn)
   463  }
   464  

View as plain text