1 // Copyright 2012 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef NET_DNS_DNS_TRANSACTION_H_ 6 #define NET_DNS_DNS_TRANSACTION_H_ 7 8 #include <stdint.h> 9 10 #include <memory> 11 #include <optional> 12 #include <string> 13 #include <string_view> 14 15 #include "base/functional/callback.h" 16 #include "base/memory/weak_ptr.h" 17 #include "base/time/time.h" 18 #include "net/base/request_priority.h" 19 #include "net/dns/opt_record_rdata.h" 20 #include "net/dns/public/secure_dns_mode.h" 21 #include "net/dns/record_rdata.h" 22 #include "url/gurl.h" 23 24 namespace net { 25 26 class DnsResponse; 27 class DnsSession; 28 class NetLogWithSource; 29 class ResolveContext; 30 31 // The hostname probed by CreateDohProbeRunner(). 32 inline constexpr std::string_view kDohProbeHostname = "www.gstatic.com"; 33 34 // DnsTransaction implements a stub DNS resolver as defined in RFC 1034. 35 // The DnsTransaction takes care of retransmissions, name server fallback (or 36 // round-robin), suffix search, and simple response validation ("does it match 37 // the query") to fight poisoning. 38 // 39 // Destroying DnsTransaction cancels the underlying network effort. 40 class NET_EXPORT_PRIVATE DnsTransaction { 41 public: 42 // Called with the response or nullptr if no matching response was received. 43 // Note that the `GetDottedName()` of the response may be different than the 44 // original `hostname` (passed to `DnsTransactionFactory::CreateTransaction()` 45 // as a result of suffix search. 46 using ResponseCallback = 47 base::OnceCallback<void(int neterror, const DnsResponse* response)>; 48 49 virtual ~DnsTransaction() = default; 50 51 // Returns the original |hostname|. 52 virtual const std::string& GetHostname() const = 0; 53 54 // Returns the |qtype|. 55 virtual uint16_t GetType() const = 0; 56 57 // Starts the transaction. Always completes asynchronously. 58 virtual void Start(ResponseCallback callback) = 0; 59 60 virtual void SetRequestPriority(RequestPriority priority) = 0; 61 }; 62 63 // Startable/Cancellable object to represent a DNS probe sequence. 64 class DnsProbeRunner { 65 public: 66 // Destruction cancels the probes. 67 virtual ~DnsProbeRunner() = default; 68 69 // Starts all applicable probes that are not already running. May be called 70 // multiple times, but should not be called after destruction of the 71 // DnsTransactionFactory. 72 // 73 // Set |network_change| to indicate if this start or restart was triggered by 74 // a network connection change. Only used for logging and metrics. 75 virtual void Start(bool network_change) = 0; 76 77 // Gets the delay until the next scheduled probe to the specified DoH server. 78 // Returns base::TimeDelta() if no probe scheduled. 79 virtual base::TimeDelta GetDelayUntilNextProbeForTest( 80 size_t doh_server_index) const = 0; 81 }; 82 83 // Creates DnsTransaction which performs asynchronous DNS search. 84 // It does NOT perform caching, aggregation or prioritization of transactions. 85 // 86 // Destroying the factory does NOT affect any already created DnsTransactions. 87 // 88 // DnsProbeRunners, however, will safely abort themselves on destruction of 89 // their creating factory, and they should only be started or restarted while 90 // the factory is still alive. 91 class NET_EXPORT_PRIVATE DnsTransactionFactory { 92 public: 93 DnsTransactionFactory(); 94 virtual ~DnsTransactionFactory(); 95 96 // Creates DnsTransaction for the given |hostname| and |qtype| (assuming 97 // QCLASS is IN). |hostname| should be in the dotted form. A dot at the end 98 // implies the domain name is fully-qualified and will be exempt from suffix 99 // search. |hostname| should not be an IP literal. 100 // 101 // The |net_log| is used as the parent log. 102 // 103 // |secure| specifies whether DNS lookups should be performed using DNS-over- 104 // HTTPS (DoH) or using plaintext DNS. 105 // 106 // When |fast_timeout| is true, the transaction will timeout quickly after 107 // making its DNS attempts, without necessarily waiting long enough to allow 108 // slower-than-average requests to complete. Intended as an optimization for 109 // cases where the caller has reasonable fallback options to the transaction 110 // and it would be beneficial to move on to those options sooner on signals 111 // that the transaction is potentially slow or problematic. 112 [[nodiscard]] virtual std::unique_ptr<DnsTransaction> CreateTransaction( 113 std::string hostname, 114 uint16_t qtype, 115 const NetLogWithSource& net_log, 116 bool secure, 117 SecureDnsMode secure_dns_mode, 118 ResolveContext* resolve_context, 119 bool fast_timeout) = 0; 120 121 // Creates a runner to run the DoH probe sequence for all configured DoH 122 // resolvers. 123 [[nodiscard]] virtual std::unique_ptr<DnsProbeRunner> CreateDohProbeRunner( 124 ResolveContext* resolve_context) = 0; 125 126 // The given EDNS0 option will be included in all DNS queries performed by 127 // transactions from this factory. 128 virtual void AddEDNSOption(std::unique_ptr<OptRecordRdata::Opt> opt) = 0; 129 130 // Returns the default SecureDnsMode in the config. 131 virtual SecureDnsMode GetSecureDnsModeForTest() = 0; 132 133 // Creates a DnsTransactionFactory which creates DnsTransactionImpl using the 134 // |session|. 135 [[nodiscard]] static std::unique_ptr<DnsTransactionFactory> CreateFactory( 136 DnsSession* session); 137 138 base::WeakPtrFactory<DnsTransactionFactory> weak_factory_{this}; 139 }; 140 141 } // namespace net 142 143 #endif // NET_DNS_DNS_TRANSACTION_H_ 144