Skip to content

JDWX DNSQuery Resolver

Jump to bottom
JDW edited this page Jul 17, 2022 · 1 revision

JDWX\DNSQuery\Resolver

This is the main resolver class, providing DNS query functions.

Constants

VERSION

const VERSION = '2.0.0'

RESOLV_CONF

const RESOLV_CONF = '/etc/resolv.conf'

Properties

recurse

public  recurse = true
  • Visibility: public

strictQueryMode

public  strictQueryMode = false
  • Visibility: public

cache

protected  cache = null
  • Visibility: protected

authSignature

protected  authSignature = null
  • Visibility: protected

dnsPort

protected  dnsPort = 53
  • Visibility: protected

dnssec

protected  dnssec = false
  • Visibility: protected

dnssecADFlag

protected  dnssecADFlag = false
  • Visibility: protected

dnssecCDFlag

protected  dnssecCDFlag = false
  • Visibility: protected

dnssecPayloadSize

protected  dnssecPayloadSize = 4000
  • Visibility: protected

domain

protected  domain = ''
  • Visibility: protected

lastException

protected  lastException = null
  • Visibility: protected

lastExceptionList

protected  lastExceptionList = []
  • Visibility: protected

localAddress

protected  localAddress = ''
  • Visibility: protected

localPort

protected  localPort
  • Visibility: protected

nsRandom

protected  nsRandom = false
  • Visibility: protected

searchList

protected  searchList = []
  • Visibility: protected

timeout

protected  timeout = 5
  • Visibility: protected

transportManager

protected  transportManager
  • Visibility: protected

useResolvOptions

protected  useResolvOptions = false
  • Visibility: protected

useTCP

protected  useTCP = false
  • Visibility: protected

nameServers

private  nameServers = []
  • Visibility: private

Methods

dns_get_record

array|false JDWX\DNSQuery\Resolver::dns_get_record(string i_hostname, int i_type, null|array|string nameServers, null|string resolvConf)

An easy way to use the query interface for those familiar with dns_get_record().

This does not return Authority and Additional sections because I was not able to find any case where the dns_get_record() function returns them when querying a recursive local resolver. If you find one, please open an issue on GitHub with the details.

  • Visibility: public
  • This method is static.

Arguments

  • i_hostname string - The hostname to use for the query.
  • i_type int - The type of record to look up (using PHP constants like DNS_A)
  • nameServers null|array|string - Optional name server or list of name servers to use.
  • resolvConf null|string - Optional path to resolv.conf file to use.

compatQuery

array[]|false JDWX\DNSQuery\Resolver::compatQuery(string i_hostname, int i_type, array|null authoritativeNameServers, array|null additionalRecords, null|string[]|string nameServers, null|string resolvConf)

An interface similar to dns_get_record that allows customizing the resolver request.

This is the very simplest query interface. It's suitable if you're adapting from dns_get_record() and just making one quick query, for example to query a different name server than your local resolver.

If you are making multiple queries, it's better to use instantiate the resolver class and use the native query() method or the compatQuery() method, which also returns results similar to dns_get_record().

  • Visibility: public

Arguments

  • i_hostname string - The hostname to look up
  • i_type int - The type of record to look up (using PHP constants)
  • authoritativeNameServers array|null - (output) Any authoritative name servers found.
  • additionalRecords array|null - (output) Any additional records found.
  • nameServers null|string[]|string - Optional name server or list of name servers to use.
  • resolvConf null|string - Optional resolv.conf file to use.

iquery

\JDWX\DNSQuery\Packet\ResponsePacket JDWX\DNSQuery\Resolver::iquery(\JDWX\DNSQuery\RR\RR rr)

does an inverse query for the given RR; most DNS servers do not implement inverse queries, but they should be able to return "not implemented"

  • Visibility: public

Arguments

query

\JDWX\DNSQuery\Packet\ResponsePacket JDWX\DNSQuery\Resolver::query(string i_name, string i_type, string i_class)

does a basic DNS lookup query

  • Visibility: public

Arguments

  • i_name string - the DNS name to lookup
  • i_type string - the name of the RR type to lookup
  • i_class string - the name of the RR class to lookup

setCache

static JDWX\DNSQuery\Resolver::setCache(\JDWX\DNSQuery\Cache\ICache i_cache)

Adds a caching implementation to the resolver object.

  • Visibility: public

Arguments

setCacheDefault

static JDWX\DNSQuery\Resolver::setCacheDefault()

Adds a default caching implementation.

  • Visibility: public

setCacheInterface

static JDWX\DNSQuery\Resolver::setCacheInterface(\Psr\SimpleCache\CacheInterface i_cacheInterface)

Adds a default caching implementation using a provided PSR-16 cache.

  • Visibility: public

Arguments

  • i_cacheInterface Psr\SimpleCache\CacheInterface - The PSR-16 cache implementation to use

setRecurse

static JDWX\DNSQuery\Resolver::setRecurse(bool i_recurse)

Whether to ask the name server to do recursive lookups.

This controls whether RD will be set in outgoing queries.

  • Visibility: public

Arguments

  • i_recurse bool - Whether to ask for recursive lookups.

setStrictQueryMode

static JDWX\DNSQuery\Resolver::setStrictQueryMode(bool i_strictQueryMode)

Enables strict query mode.

By default, according to RFC 1034, CNAME RRs cause special action in DNS software. When a name server fails to find a desired RR in the resource set associated with the domain name, it checks to see if the resource set consists of a CNAME record with a matching class. If so, the name server includes the CNAME record in the response and restarts the query at the domain name specified in the data field of the CNAME record.

this can cause "unexpected" behaviours, since i'm sure most people don't know DNS does this; there may be cases where the resolver returns a positive response, even though the hostname the user looked up did not actually exist.

Enable strict query mode means that if the hostname that was looked up isn't actually in the answer section of the response, the resolver will return an empty answer section, instead of an answer section that could contain CNAME records.

  • Visibility: public

Arguments

  • i_strictQueryMode bool - Whether to enable strict mode or not.

__construct

mixed JDWX\DNSQuery\BaseQuery::__construct(array|string|null i_nameServers, ?string i_resolvConf)

Constructor - base constructor for the Notifier, Resolver and Updater

Arguments

  • i_nameServers array|string|null
  • i_resolvConf ?string

expandIPv6

string JDWX\DNSQuery\BaseQuery::expandIPv6(string i_address)

formats the given IPv6 address as a fully expanded IPv6 address

Arguments

  • i_address string - the IPv6 address to expand

expandUint32

string JDWX\DNSQuery\BaseQuery::expandUint32(int i_int)

PHP doesn't support unsigned integers, but many of the RRs return unsigned values (like SOA), so there is the possibility that the value will overrun on 32bit systems, and you'll end up with a negative value.

64bit systems are not affected, as their PHP_INT_MAX value should be 64bit (ie 9223372036854775807)

This function returns a negative integer value, as a string, with the correct unsigned value.

Arguments

  • i_int int - the unsigned integer value to check

isIPv4

bool JDWX\DNSQuery\BaseQuery::isIPv4(string i_address)

returns true/false if the given address is a valid IPv4 address

Arguments

  • i_address string - the IPv4 address to check

isIPv6

bool JDWX\DNSQuery\BaseQuery::isIPv6(string i_address)

returns true/false if the given address is a valid IPv6 address

Arguments

  • i_address string - the IPv6 address to check

closeSockets

void JDWX\DNSQuery\BaseQuery::closeSockets()

give users access to close all open sockets on the resolver object; resetting each array, calls the destructor on the Socket object, which calls the close() method on each object.

getNameServers

string[] JDWX\DNSQuery\BaseQuery::getNameServers()

Gets the currently-configured name servers or loads them from the default resolv.conf if none are specified.

setDNSPort

static JDWX\DNSQuery\BaseQuery::setDNSPort(int i_dnsPort)

Set the DNS server port to use. (Default is 53 for both TCP and UDP DNS.)

Arguments

  • i_dnsPort int

setDNSSEC

static JDWX\DNSQuery\BaseQuery::setDNSSEC(bool i_dnssec)

Request DNSSEC values, by setting the DO flag to 1; this actually makes the resolver add an OPT RR to the additional section, and sets the DO flag in this RR to 1

Arguments

  • i_dnssec bool - Whether to use DNSSEC.

setDNSSECADFlag

static JDWX\DNSQuery\BaseQuery::setDNSSECADFlag(bool i_dnssecADFlag)

set the DNSSEC AD (Authentic Data) bit on/off; the AD bit on the request side was previously undefined, and resolvers we instructed to always clear the AD bit when sending a request.

RFC6840 section 5.7 defines setting the AD bit in the query as a signal to the server that it wants the value of the AD bit, without needed to request all the DNSSEC data via the DO bit.

Arguments

  • i_dnssecADFlag bool

setDNSSECCDFlag

static JDWX\DNSQuery\BaseQuery::setDNSSECCDFlag(bool i_dnssecCDFlag)

set the DNSSEC CD (Checking Disabled) bit on/off; turning this off means that the DNS resolver will perform its own signature validation so the DNS servers simply pass through all the details.

Arguments

  • i_dnssecCDFlag bool

setDNSSECPayloadSize

static JDWX\DNSQuery\BaseQuery::setDNSSECPayloadSize(int i_dnssecPayloadSize)

the EDNS(0) UDP payload size to use when making DNSSEC requests see RFC 4035 section 4.1 - EDNS Support.

there are some different ideas on the suggested size to support; but it seems to be "at least" 1220 bytes, but SHOULD support 4000 bytes. If this is not set, the default is 4000 bytes.

Arguments

  • i_dnssecPayloadSize int - Payload size in bytes.

setLocalAddress

static JDWX\DNSQuery\BaseQuery::setLocalAddress(string i_localHost)

Set the local IP address to use. (Default is empty, which means to use the default local IP address.)

Arguments

  • i_localHost string

setLocalPort

static JDWX\DNSQuery\BaseQuery::setLocalPort(int i_localPort)

Set the local port to use. (Default is 0, which means to use a local port selected by the OS.)

Arguments

  • i_localPort int - Local port value to use

setNameServer

mixed JDWX\DNSQuery\BaseQuery::setNameServer(string i_nameServer)

Shortcut to set a single name server.

Arguments

  • i_nameServer string - IPv4 or IPv6 address of the desired name server

setNameServers

mixed JDWX\DNSQuery\BaseQuery::setNameServers(string[] i_nameServers)

Sets the name servers to be used, specified as IPv4 or IPv6 addresses.

Arguments

  • i_nameServers string[] - a list of IPv4 or IPv6 addresses

setRandomizeNameServers

static JDWX\DNSQuery\BaseQuery::setRandomizeNameServers(bool i_randomize)

Set whether to randomize the name server list. (Default is false.)

Arguments

  • i_randomize bool - True to randomize the name server list, false to not randomize

setTimeout

static JDWX\DNSQuery\BaseQuery::setTimeout(int i_timeout)

Set the timeout value to use for socket connections. (Default is 5 seconds.)

Arguments

  • i_timeout int - Timeout value in seconds.

setUseResolvOptions

static JDWX\DNSQuery\BaseQuery::setUseResolvOptions(bool i_useResolvOptions)

Set whether to use options found in resolv.conf if one is parsed.

Note that this will not affect the use of the resolv.conf file if it is loaded from the constructor. So if you want this option, set it and then manually call useResolvConf().

Arguments

  • i_useResolvOptions bool - Whether to use options found in resolv.conf

setUseTCP

static JDWX\DNSQuery\BaseQuery::setUseTCP(bool i_useTCP)

Default to using TCP for requests. (TCP will always be used for large requests or AXFR requests.)

Arguments

  • i_useTCP bool - Whether to use TCP for requests by default.

signSIG0

void JDWX\DNSQuery\BaseQuery::signSIG0(\JDWX\DNSQuery\RR\SIG|string i_filename)

Add a SIG RR object for authentication.

Arguments

  • i_filename JDWX\DNSQuery\RR\SIG|string - a signature or the name of a file to load the signature from.

signTSIG

void JDWX\DNSQuery\BaseQuery::signTSIG(\JDWX\DNSQuery\RR\TSIG|string i_keyName, string i_signature, string i_algorithm)

Add a TSIG RR object for authentication

Arguments

  • i_keyName JDWX\DNSQuery\RR\TSIG|string - Key name to use for the TSIG RR
  • i_signature string - Key to sign the request.
  • i_algorithm string - Algorithm to use

useResolvConf

static JDWX\DNSQuery\BaseQuery::useResolvConf(?string i_resolvConf)

sets the name servers to be used, specified as IPv4 or IPv6 addresses

Arguments

  • i_resolvConf ?string - Filename to parse in the resolv.conf format or null to use the default resolv.conf file

sendPacket

\JDWX\DNSQuery\Packet\ResponsePacket JDWX\DNSQuery\BaseQuery::sendPacket(\JDWX\DNSQuery\Packet\RequestPacket i_request, bool i_useTCP)

Sends a RequestPacket

Arguments

parseOptions

void JDWX\DNSQuery\BaseQuery::parseOptions(string i_options)

parses the options line from a resolv.conf file; we don't support all the options yet, and using them is optional.

Arguments

  • i_options string - The "options" string from the resolv.conf file.

sendTCPRequest

\JDWX\DNSQuery\Packet\ResponsePacket JDWX\DNSQuery\BaseQuery::sendTCPRequest(string i_ns, string i_data, bool i_axfr)

sends a DNS request using TCP

Arguments

  • i_ns string - Name server to use for the request
  • i_data string - Raw DNS packet data
  • i_axfr bool - Whether this is a zone transfer request

sendUDPRequest

\JDWX\DNSQuery\Packet\ResponsePacket JDWX\DNSQuery\BaseQuery::sendUDPRequest(string i_ns, string i_data)

sends a DNS request using UDP

Arguments

  • i_ns string - the name server to use for the request
  • i_data string - the raw DNS packet data
Clone this wiki locally