Package com.digicert.validation.client.dns

Class DnsClient

java.lang.Object
com.digicert.validation.client.dns.DnsClient
public class DnsClient extends Object
DnsClient is responsible for querying DNS records from specified DNS servers. It supports various DNS record types and handles errors encountered during the DNS query process.

This class uses the configuration provided by DcvConfiguration to initialize DNS servers, timeout and retries. The DnsClient class is designed to be flexible and robust, allowing for easy integration with different DNS servers and handling various DNS record types such as A, CNAME, TXT, and CAA. It also includes error handling mechanisms to manage common DNS query issues, ensuring reliable DNS data retrieval.

  • Field Details

    • dnsServers

      private final List<String> dnsServers
      The list of DNS servers to query.

      This list is initialized from the DcvConfiguration and contains the DNS servers that the client will query for DNS records. The order of the servers in the list can affect the query process, as the client will attempt to query each server in sequence until it receives a valid response or exhausts the list.

    • dnsTimeout

      private final int dnsTimeout
      The timeout for DNS queries in milliseconds.

      This timeout value, specified in milliseconds, determines how long the client will wait for a response from a DNS server before considering the query to have failed.

    • dnsRetries

      private final int dnsRetries
      The number of retries for DNS queries.

      This value specifies the number of times the client will retry a DNS query if it does not receive a valid response within the specified timeout period.

    • logLevelForErrors

      private final org.slf4j.event.Level logLevelForErrors
      The log level used for logging errors related to domain control validation (DCV).

  • Constructor Details

    • DnsClient

      public DnsClient(DcvContext dcvContext)
      Constructs a new DnsClient with the specified configuration.

      This constructor initializes the DnsClient using the provided DcvContext, which contains the necessary configuration settings such as DNS servers, timeout, and retries.

      Parameters:
      dcvContext - context where we can find the needed dependencies / configuration

  • Method Details

    • getDnsData

      public DnsData getDnsData(List<String> domains, DnsType type)
      Retrieves DNS records of the specified type for the given domains.

      This method iterates over the configured DNS servers, requesting DNS records of the specified type for each domain in the list. When a valid non-empty response is received, the method returns the DNS data for that domain. Querying is done sequentially and will end as soon as a valid response is received, so it is recommended to carefully consider the order of DNS servers in your configuration. If no valid response is received, it aggregates the errors encountered during the query process and returns an empty result with the collected errors.

      Parameters:
      domains - The list of domains to query.
      type - The type of DNS record to query.
      Returns:
      The DNS data containing the first records found and any errors encountered.

    • verifyInputData

      private void verifyInputData(List<String> domains)
      Verifies the input data for the DNS query.

      This method checks that the list of domains is not empty and that the DNS servers are configured. If the input data is invalid or missing, the method throws an IllegalArgumentException

      Parameters:
      domains - The list of domains to query.

    • getDnsData

      private DnsData getDnsData(String server, String domain, DnsType type)
      Retrieves DNS data for a specific server, domain, and DNS record type.

      This method performs a DNS query for the specified server, domain, and DNS record type. It creates a resolver for the DNS server and a lookup for the domain and record type. The method handles common exceptions such as UnknownHostException and TextParseException, logging the errors and returning an empty result with the appropriate error codes. The provided server may include a port number separated by a colon. (e.g. 8.8.8.8:53). If no port is provided, the default DNS port (53) is used.

      Parameters:
      server - The DNS server to query.
      domain - The domain to query.
      type - The type of DNS record to query.
      Returns:
      The DNS data containing the records and any errors encountered.

    • createZoneFromDomain

      private String createZoneFromDomain(String domain)
      Creates a zone name from the provided domain.

      This method ensures that the domain ends with a dot (.) to conform to DNS zone naming conventions. If the domain does not end with a dot, it appends one.

      Parameters:
      domain - The domain to convert into a zone name.
      Returns:
      The zone name created from the domain.

    • getDnsValues

      private List<DnsValue> getDnsValues(org.xbill.DNS.Message response)
      Extracts DNS values from the response message.

      This method retrieves the DNS records from the answer section of the response message and maps them to a list of DnsValue objects. If the response code is NOERROR, it processes the records; otherwise, it returns an empty list.

      Parameters:
      response - The DNS response message.
      Returns:
      A list of DnsValue objects containing the DNS records found in the response.

    • mapRecordToDnsValue

      private DnsValue mapRecordToDnsValue(org.xbill.DNS.Record recordValue)
      Maps a DNS record to a DnsValue object.

      This method converts a DNS record into a DnsValue object, extracting relevant information such as the value, name, type, and TTL. It handles different types of DNS records, including TXT, CNAME, A, MX, CAA, DS, and RRSIG.

      Parameters:
      recordValue - The DNS record to map.
      Returns:
      A DnsValue object containing the mapped data.

    • populateCaaRecordData

      private CaaValue populateCaaRecordData(org.xbill.DNS.CAARecord recordValue)
      Populates the CAARecord data into a DnsValue object.

      This method extracts the flags, tag, and value from the CAARecord and sets them in a new CaaRecord object.

      Parameters:
      recordValue - The CAARecord to populate data from.
      Returns:
      A CaaRecord object containing the populated data.

    • handleDnsException

      private DnsData handleDnsException(@NonNull @NonNull Exception e, DnsType type, String domain, String server)
      Handles exceptions that occur during DNS queries.

      This method processes exceptions thrown during DNS queries, logging the error and returning a DnsData object with the appropriate error codes. It categorizes the exceptions into specific client statuses and maps them to corresponding DcvError values.

      Parameters:
      e - The exception that occurred during the DNS query.
      type - The type of DNS record that was being queried.
      domain - The domain that was being queried.
      server - The DNS server that was being queried.
      Returns:
      A DnsData object containing the error information.

    • getClientStatus

      private ClientStatus getClientStatus(org.xbill.DNS.Message message, List<DnsValue> foundDnsValues)
      Determines the client status based on the DNS response message and the found DNS values.

      This method analyzes the response code of the DNS message and the list of found DNS values to determine the appropriate client status. It handles different response codes such as NOERROR, NXDOMAIN, and others, and categorizes the status accordingly.

      Parameters:
      message - The DNS response message.
      foundDnsValues - The list of DNS values found in the response.
      Returns:
      The determined client status based on the response code and found values.

    • createResolver

      protected org.xbill.DNS.ExtendedResolver createResolver(String server, Integer port) throws UnknownHostException
      Creates a new SimpleResolver for the specified DNS server.

      This method creates and configures a SimpleResolver for the specified DNS server and port. If a port is provided, it creates a resolver using the specified port; otherwise, it uses the default DNS port (53). The resolver is then wrapped in an ExtendedResolver to provide additional functionality such as retries and timeout management.

      Parameters:
      server - The DNS server to create a resolver for.
      port - The port to use for the resolver. If not port is specified, the default port (53) is used.
      Returns:
      The created ExtendedResolver.
      Throws:
      UnknownHostException - If the DNS server is unknown.

    • mapToDnsIntType

      private int mapToDnsIntType(DnsType dnsRecordType)
      Maps the DnsType enum to the corresponding integer value used by the DNS library.

      This method translates the DnsType enum values into the integer constants used by the DNS library. This mapping is necessary because the DNS library uses integer values to represent different DNS record types, while the client code uses the more readable DnsType enum.

      Parameters:
      dnsRecordType - The DnsType to map.
      Returns:
      The corresponding integer value for the DNS record type.

    • mapClientStatusToDcvError

      DcvError mapClientStatusToDcvError(ClientStatus clientStatus)
      Maps the ClientStatus enum to the corresponding DcvError DcvError.

      throws an IllegalArgumentException if the provided ClientStatus is not recognized.

      Parameters:
      clientStatus - The ClientStatus to map.
      Returns:
      The corresponding DcvError for the given ClientStatus.