edns.h 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445
  1. // Copyright (C) 2010 Internet Systems Consortium, Inc. ("ISC")
  2. //
  3. // Permission to use, copy, modify, and/or distribute this software for any
  4. // purpose with or without fee is hereby granted, provided that the above
  5. // copyright notice and this permission notice appear in all copies.
  6. //
  7. // THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  8. // REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  9. // AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  10. // INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  11. // LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  12. // OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  13. // PERFORMANCE OF THIS SOFTWARE.
  14. #ifndef __EDNS_H
  15. #define __EDNS_H 1
  16. #include <stdint.h>
  17. #include <boost/shared_ptr.hpp>
  18. #include <ostream>
  19. #include <dns/rdata.h>
  20. namespace isc {
  21. namespace util {
  22. class OutputBuffer;
  23. }
  24. namespace dns {
  25. class EDNS;
  26. class Name;
  27. class AbstractMessageRenderer;
  28. class RRClass;
  29. class RRTTL;
  30. class RRType;
  31. class Rcode;
  32. /// \brief A pointer-like type pointing to an \c EDNS object.
  33. typedef boost::shared_ptr<EDNS> EDNSPtr;
  34. /// \brief A pointer-like type pointing to an immutable \c EDNS object.
  35. typedef boost::shared_ptr<const EDNS> ConstEDNSPtr;
  36. /// The \c EDNS class represents the %EDNS OPT RR defined in RFC2671.
  37. ///
  38. /// This class encapsulates various optional features of %EDNS such as
  39. /// the UDP payload size or the DNSSEC DO bit, and provides interfaces
  40. /// to manage these features. It is also responsible for conversion
  41. /// to and from wire-format OPT RR.
  42. /// One important exception is about the extended RCODE:
  43. /// The \c EDNS class is only responsible for extracting the 8-bit part
  44. /// of the 12-bit extended RCODE from the OPT RR's TTL field of an
  45. /// incoming message, and for setting the 8-bit part into the OPT RR TTL
  46. /// of an outgoing message. It's not supposed to know how to construct the
  47. /// complete RCODE, much less maintain the RCODE in it.
  48. /// It is the caller's responsibility (typically the \c Message class).
  49. ///
  50. /// When converting wire-format OPT RR into an \c EDNS object, it normalizes
  51. /// the information, i.e., unknown flags will be ignored on construction.
  52. ///
  53. /// This class is also supposed to support %EDNS options such as NSID,
  54. /// but the initial implementation does not include it. This is a near term
  55. /// TODO item.
  56. ///
  57. /// <b>Notes to developers</b>
  58. ///
  59. /// The rest of the description is for developers who need to or want to
  60. /// understand the design of this API.
  61. ///
  62. /// Representing %EDNS is tricky. An OPT RR is no different from other RRs
  63. /// in terms of the wire format syntax, and in that sense we could use the
  64. /// generic \c RRset class to represent an OPT RR (BIND 9 adopts this
  65. /// approach). But the resulting interface would be inconvenient for
  66. /// developers. For example, the developer would need to know that the
  67. /// UDP size is encoded in the RR Class field. It's better to provide
  68. /// a more abstract interface along with the special semantics of OPT RR.
  69. ///
  70. /// Another approach would be to realize each optional feature of EDNS
  71. /// as an attribute of the DNS message.
  72. /// NLnet Labs' ldns takes this approach.
  73. /// This way an operation for specifying the UDP size would be written
  74. /// like this:
  75. /// \code message->setUDPSize(4096); \endcode
  76. /// which should be more intuitive.
  77. /// A drawback of this approach is that OPT RR is itself optional and the
  78. /// separate parameters may not necessarily indicate whether to include an
  79. /// OPT RR per se.
  80. /// For example, consider what should be done with this code:
  81. /// \code message->setUDPSize(512); \endcode
  82. /// Since the payload size of 512 is the default, it may mean the OPT RR
  83. /// should be skipped. But it might also mean the caller intentionally
  84. /// (for some reason) wants to insert an OPT RR specifying the default UDP
  85. /// size explicitly.
  86. ///
  87. /// So, we use a separate class that encapsulates the EDNS semantics and
  88. /// knows the mapping between the semantics and the wire format representation.
  89. /// This way the interface can be semantics-based and is intuitive:
  90. /// \code edns->setUDPSize(4096); \endcode
  91. /// while we can explicitly specify whether to include an OPT RR by setting
  92. /// (or not setting) an \c EDNS object in a message:
  93. /// \code message->setEDNS(edns); // unless we do this OPT RR is skipped
  94. /// \endcode
  95. ///
  96. /// There is still a non trivial point: How to manage extended RCODEs.
  97. /// An OPT RR encodes the upper 8 bits of extended 12-bit RCODE.
  98. /// In general, it would be better to provide a unified interface to get
  99. /// access to RCODEs whether or not they are traditional 4 bit codes or
  100. /// extended ones that have non 0 upper bits.
  101. /// However, since an OPT RR may not appear in a message the RCODE cannot be
  102. /// maintained in the \c EDNS class.
  103. /// But it would not be desirable to maintain the extended RCODEs completely
  104. /// in the \c Message class, either, because we wanted to hide the mapping
  105. /// between %EDNS semantics and its wire format representation within the
  106. /// \c EDNS class; if we moved the responsibility about RCODEs to the
  107. /// \c Message class, it would have to parse and render the upper 8 bits of
  108. /// the RCODEs, dealing with wire representation of OPT RR.
  109. /// This is suboptimal in the sense of encapsulation.
  110. ///
  111. /// As a compromise, our decision is to separate the knowledge about the
  112. /// relationship with RCODE from the knowledge about the wire format as
  113. /// noted in the beginning of this description.
  114. ///
  115. /// This decoupling is based on the observation that the extended RCODE
  116. /// is a very special case where %EDNS only has partial information.
  117. /// If a future version of the %EDNS protocol introduces further relationship
  118. /// between the message and the %EDNS, we might reconsider the interface,
  119. /// probably with higher abstraction.
  120. class EDNS {
  121. public:
  122. ///
  123. /// \name Constructors and Destructor
  124. ///
  125. /// We use the default copy constructor, default copy assignment operator,
  126. /// and default destructors intentionally.
  127. ///
  128. /// Note about copyability: This version of this class is copyable,
  129. /// but we may want to change it once we support EDNS options, when
  130. /// we want to revise this class using the pimpl idiom.
  131. /// But we should be careful about that: the python binding currently
  132. /// assumes this class is copyable.
  133. //@{
  134. /// Constructor with the EDNS version.
  135. /// An application would use this constructor to specify EDNS parameters
  136. /// and/or options for outgoing DNS messages.
  137. ///
  138. /// All other parameters than the version number will be initialized to
  139. /// reasonable defaults.
  140. /// Specifically, the UDP payload size is set to
  141. /// \c Message::DEFAULT_MAX_UDPSIZE, and DNSSEC is assumed to be not
  142. /// supported.
  143. /// These parameters can be altered via setter methods of this class.
  144. /// Note, however, that the version number cannot be changed once
  145. /// constructed.
  146. ///
  147. /// The version number parameter can be omitted, in which case the highest
  148. /// supported version in this implementation will be assumed.
  149. /// When specified, if it is larger than the highest supported version,
  150. /// an exception of class \c isc::InvalidParameter will be thrown.
  151. ///
  152. /// This constructor throws no other exception.
  153. ///
  154. /// \param version The version number of the EDNS to be constructed.
  155. explicit EDNS(const uint8_t version = SUPPORTED_VERSION);
  156. /// \brief Constructor from resource record (RR) parameters.
  157. ///
  158. /// This constructor is intended to be used to construct an EDNS object
  159. /// from an OPT RR contained in an incoming DNS message.
  160. ///
  161. /// Unlike many other constructors for this purpose, this constructor
  162. /// does not take the bare wire-format %data in the form of an
  163. /// \c InputBuffer object. This is because parsing incoming EDNS is
  164. /// highly context dependent and it's not feasible to handle it in a
  165. /// completely polymorphic way. For example, a DNS message parser would
  166. /// have to check an OPT RR appears at most once in the message, and if
  167. /// it appears it should be in the additional section. So, the parser
  168. /// needs to have an explicit check to see if an RR is of type OPT, and
  169. /// then (if other conditions are met) construct a corresponding \c EDNS
  170. /// object. At that point the parser would have already converted the
  171. /// wire %data into corresponding objects of \c Name, \c RRClass,
  172. /// \c RRType, etc, and it makes more sense to pass them directly to the
  173. /// constructor.
  174. ///
  175. /// In practice, top level applications rarely need to use this
  176. /// constructor directly. It should normally suffice to have a higher
  177. /// level class such as \c Message do that job.
  178. ///
  179. /// This constructor checks the passed parameters to see if they are
  180. /// valid in terms of the EDNS protocol specification.
  181. /// \c name must be the root name ("."); otherwise, an exception of
  182. /// class \c DNSMessageFORMERR will be thrown.
  183. /// \c rrtype must specify the OPT RR type; otherwise, an exception of
  184. /// class \c isc::InvalidParameter will be thrown.
  185. /// The ENDS version number is extracted from \c rrttl. If it is larger
  186. /// than the higher supported version, an exception of class
  187. /// \c DNSMessageBADVERS will be thrown. Note that this is different from
  188. /// the case of the same error in the other constructor.
  189. /// This is intentional, so that the application can transparently convert
  190. /// the exception to a response RCODE according to the protocol
  191. /// specification.
  192. ///
  193. /// This initial implementation does not support EDNS options at all,
  194. /// and \c rdata is simply ignored. Future versions will support
  195. /// options, and may throw exceptions while validating the given parameter.
  196. ///
  197. /// \b Note: since no other type than OPT for \c rrtype is allowed, this
  198. /// parameter could actually have been omitted. But it is intentionally
  199. /// included as a parameter so that invalid usage of the construction
  200. /// can be detected. As noted above the caller should normally have
  201. /// the corresponding \c RRType object at the time of call to this
  202. /// constructor, so the overhead of having the additional parameter
  203. /// should be marginal.
  204. ///
  205. /// \param name The owner name of the OPT RR. This must be the root name.
  206. /// \param rrclass The RR class of the OPT RR.
  207. /// \param rrtype This must specify the OPT RR type.
  208. /// \param ttl The TTL of the OPT RR.
  209. /// \param rdata The RDATA of the OPT RR.
  210. EDNS(const Name& name, const RRClass& rrclass, const RRType& rrtype,
  211. const RRTTL& ttl, const rdata::Rdata& rdata);
  212. //@}
  213. ///
  214. /// \name Getter and Setter Methods
  215. ///
  216. //@{
  217. /// \brief Returns the version of EDNS.
  218. ///
  219. /// This method never throws an exception.
  220. uint8_t getVersion() const { return (version_); }
  221. /// \brief Returns the maximum payload size of UDP messages for the sender
  222. /// of the message containing this \c EDNS.
  223. ///
  224. /// This method never throws an exception.
  225. uint16_t getUDPSize() const { return (udp_size_); }
  226. /// \brief Specify the maximum payload size of UDP messages that use
  227. /// this EDNS.
  228. ///
  229. /// Unless explicitly specified, \c DEFAULT_MAX_UDPSIZE will be assumed
  230. /// for the maximum payload size, regardless of whether EDNS OPT RR is
  231. /// included or not. This means if an application wants to send a message
  232. /// with an EDNS OPT RR for specifying a larger UDP size, it must
  233. /// explicitly specify the value using this method.
  234. ///
  235. /// This method never throws an exception.
  236. ///
  237. /// \param udp_size The maximum payload size of UDP messages for the sender
  238. /// of the message containing this \c EDNS.
  239. void setUDPSize(const uint16_t udp_size) { udp_size_ = udp_size; }
  240. /// \brief Returns whether the message sender is DNSSEC aware.
  241. ///
  242. /// This method never throws an exception.
  243. ///
  244. /// \return true if DNSSEC is supported; otherwise false.
  245. bool getDNSSECAwareness() const { return (dnssec_aware_); }
  246. /// \brief Specifies whether the sender of the message containing this
  247. /// \c EDNS is DNSSEC aware.
  248. ///
  249. /// If the parameter is true, a subsequent call to \c toWire() will
  250. /// set the DNSSEC DO bit on for the corresponding OPT RR.
  251. ///
  252. /// This method never throws an exception.
  253. ///
  254. /// \param is_aware \c true if DNSSEC is supported; \c false otherwise.
  255. void setDNSSECAwareness(const bool is_aware) { dnssec_aware_ = is_aware; }
  256. //@}
  257. ///
  258. /// \name Converter Methods
  259. ///
  260. //@{
  261. /// \brief Render the \c EDNS in the wire format.
  262. ///
  263. /// This method renders the \c EDNS object as a form of DNS OPT RR
  264. /// via \c renderer, which encapsulates output buffer and other rendering
  265. /// contexts.
  266. /// Since the \c EDNS object does not maintain the extended RCODE
  267. /// information, a separate parameter \c extended_rcode must be passed to
  268. /// this method.
  269. ///
  270. /// If by adding the OPT RR the message size would exceed the limit
  271. /// maintained in \c renderer, this method skips rendering the RR
  272. /// and returns 0; otherwise it returns 1, which is the number of RR
  273. /// rendered.
  274. ///
  275. /// In the current implementation the return value is either 0 or 1, but
  276. /// the return type is <code>unsigned int</code> to be consistent with
  277. /// \c RRset::toWire(). In any case the caller shouldn't assume these are
  278. /// only possible return values from this method.
  279. ///
  280. /// This method is mostly exception free, but it requires memory
  281. /// allocation and if it fails a corresponding standard exception will be
  282. /// thrown.
  283. ///
  284. /// In practice, top level applications rarely need to use this
  285. /// method directly. It should normally suffice to have a higher
  286. /// level class such as \c Message do that job.
  287. ///
  288. /// <b>Note to developer:</b> the current implementation constructs an
  289. /// \c RRset object for the OPT RR and calls its \c toWire() method,
  290. /// which is inefficient. In future, we may want to optimize this method
  291. /// by caching the rendered image and having the application reuse the
  292. /// same \c EDNS object when possible.
  293. ///
  294. /// \param renderer DNS message rendering context that encapsulates the
  295. /// output buffer and name compression information.
  296. /// \param extended_rcode Upper 8 bits of extended RCODE to be rendered as
  297. /// part of the EDNS OPT RR.
  298. /// \return 1 if the OPT RR fits in the message size limit; otherwise 0.
  299. unsigned int toWire(AbstractMessageRenderer& renderer,
  300. const uint8_t extended_rcode) const;
  301. /// \brief Render the \c EDNS in the wire format.
  302. ///
  303. /// This method is same as \c toWire(MessageRenderer&,uint8_t)const
  304. /// except it renders the OPT RR in an \c OutputBuffer and therefore
  305. /// does not care about message size limit.
  306. /// As a consequence it always returns 1.
  307. unsigned int toWire(isc::util::OutputBuffer& buffer,
  308. const uint8_t extended_rcode) const;
  309. /// \brief Convert the EDNS to a string.
  310. ///
  311. /// The format of the resulting string is as follows:
  312. /// \code ; EDNS: version: <version>, flags: <edns flags>; udp: <udp size>
  313. /// \endcode
  314. /// where
  315. /// - \em version is the EDNS version number (integer).
  316. /// - <em>edns flags</em> is a sequence of EDNS flag bits. The only
  317. /// possible flag is the "DNSSEC OK", which is represented as "do".
  318. /// - <em>udp size</em> is sender's UDP payload size in bytes.
  319. ///
  320. /// The string will be terminated with a trailing newline character.
  321. ///
  322. /// When EDNS options are supported the output of this method will be
  323. /// extended.
  324. ///
  325. /// This method is mostly exception free, but it may require memory
  326. /// allocation and if it fails a corresponding standard exception will be
  327. /// thrown.
  328. ///
  329. /// \return A string representation of \c EDNS. See above for the format.
  330. std::string toText() const;
  331. //@}
  332. // TBD: This method is currently not implemented. We'll eventually need
  333. // something like this.
  334. //void addOption();
  335. public:
  336. /// \brief The highest EDNS version this implementation supports.
  337. static const uint8_t SUPPORTED_VERSION = 0;
  338. private:
  339. // We may eventually want to migrate to pimpl, especially when we support
  340. // EDNS options. In this initial implementation, we keep it simple.
  341. const uint8_t version_;
  342. uint16_t udp_size_;
  343. bool dnssec_aware_;
  344. };
  345. /// \brief Create a new \c EDNS object from a set of RR parameters, also
  346. /// providing the extended RCODE value.
  347. ///
  348. /// This function is similar to the EDNS class constructor
  349. /// \c EDNS::EDNS(const Name&, const RRClass&, const RRType&, const RRTTL&, const rdata::Rdata&)
  350. /// but is different in that
  351. /// - It dynamically creates a new object
  352. /// - It returns (via a reference argument) the topmost 8 bits of the extended
  353. /// RCODE encoded in the \c ttl.
  354. ///
  355. /// On success, \c extended_rcode will be updated with the 8-bit part of
  356. /// the extended RCODE encoded in the TTL of the OPT RR.
  357. ///
  358. /// The intended usage of this function is to parse an OPT RR of an incoming
  359. /// DNS message, while updating the RCODE of the message.
  360. /// One common usage pattern is as follows:
  361. ///
  362. /// \code Message msg;
  363. /// ...
  364. /// uint8_t extended_rcode;
  365. /// ConstEDNSPtr edns = ConstEDNSPtr(createEDNSFromRR(..., extended_rcode));
  366. /// rcode = Rcode(msg.getRcode().getCode(), extended_rcode);
  367. /// \endcode
  368. /// (although, like the \c EDNS constructor, normal applications wouldn't have
  369. /// to use this function directly).
  370. ///
  371. /// This function provides the strong exception guarantee: Unless an
  372. /// exception is thrown \c extended_code won't be modified.
  373. ///
  374. /// This function validates the given parameters and throws exceptions on
  375. /// failure in the same way as the \c EDNS class constructor.
  376. /// In addition, if memory allocation for the new object fails it throws the
  377. /// corresponding standard exception.
  378. ///
  379. /// Note that this function returns a bare pointer to the newly allocated
  380. /// object, not a shared pointer object enclosing the pointer.
  381. /// The caller is responsible for deleting the object after the use of it
  382. /// (typically, the caller would immediately encapsulate the returned pointer
  383. /// in a shared pointer object, \c EDNSPtr or \c ConstEDNSPtr).
  384. /// It returns a bare pointer so that it can be used where the use of a shared
  385. /// pointer is impossible or not desirable.
  386. ///
  387. /// Note to developers: there is no strong technical reason why this function
  388. /// cannot be a constructor of the \c EDNS class or even integrated into the
  389. /// constructor. But we decided to make it a separate free function so that
  390. /// constructors will be free from side effects (which is in itself a matter
  391. /// of preference).
  392. ///
  393. /// \param name The owner name of the OPT RR. This must be the root name.
  394. /// \param rrclass The RR class of the OPT RR.
  395. /// \param rrtype This must specify the OPT RR type.
  396. /// \param ttl The TTL of the OPT RR.
  397. /// \param rdata The RDATA of the OPT RR.
  398. /// \param extended_rcode A placeholder to store the topmost 8 bits of the
  399. /// extended Rcode.
  400. /// \return A pointer to the created \c EDNS object.
  401. EDNS* createEDNSFromRR(const Name& name, const RRClass& rrclass,
  402. const RRType& rrtype, const RRTTL& ttl,
  403. const rdata::Rdata& rdata, uint8_t& extended_rcode);
  404. /// \brief Insert the \c EDNS as a string into stream.
  405. ///
  406. /// This method convert \c edns into a string and inserts it into the
  407. /// output stream \c os.
  408. ///
  409. /// \param os A \c std::ostream object on which the insertion operation is
  410. /// performed.
  411. /// \param edns A reference to an \c EDNS object output by the operation.
  412. /// \return A reference to the same \c std::ostream object referenced by
  413. /// parameter \c os after the insertion operation.
  414. std::ostream& operator<<(std::ostream& os, const EDNS& edns);
  415. }
  416. }
  417. #endif // __EDNS_H
  418. // Local Variables:
  419. // mode: c++
  420. // End: