 |
Kea 2.7.5
|
|
Kea 2.7.5
|
The EDNS class represents the EDNS OPT RR defined in RFC2671.
More...
#include <edns.h>
Public Member Functions | |
Constructors and Destructor | |
We use the default copy constructor, default copy assignment operator, and default destructors intentionally. Note about copyability: This version of this class is copyable, but we may want to change it once we support EDNS options, when we want to revise this class using the pimpl idiom. But we should be careful about that: the python binding currently assumes this class is copyable. | |
| EDNS (const uint8_t version=SUPPORTED_VERSION) | |
| Constructor with the EDNS version. | |
| EDNS (const Name &name, const RRClass &rrclass, const RRType &rrtype, const RRTTL &ttl, const rdata::Rdata &rdata) | |
| Constructor from resource record (RR) parameters. | |
Getter and Setter Methods | |
| uint8_t | getVersion () const |
| Returns the version of EDNS. | |
| uint16_t | getUDPSize () const |
Returns the maximum payload size of UDP messages for the sender of the message containing this EDNS. | |
| void | setUDPSize (const uint16_t udp_size) |
| Specify the maximum payload size of UDP messages that use this EDNS. | |
| bool | getDNSSECAwareness () const |
| Returns whether the message sender is DNSSEC aware. | |
| void | setDNSSECAwareness (const bool is_aware) |
Specifies whether the sender of the message containing this EDNS is DNSSEC aware. | |
Converter Methods | |
| static const uint8_t | SUPPORTED_VERSION = 0 |
| The highest EDNS version this implementation supports. | |
| uint32_t | toWire (AbstractMessageRenderer &renderer, const uint8_t extended_rcode) const |
Render the EDNS in the wire format. | |
| uint32_t | toWire (isc::util::OutputBuffer &buffer, const uint8_t extended_rcode) const |
Render the EDNS in the wire format. | |
| std::string | toText () const |
| Convert the EDNS to a string. | |
The EDNS class represents the EDNS OPT RR defined in RFC2671.
This class encapsulates various optional features of EDNS such as the UDP payload size or the DNSSEC DO bit, and provides interfaces to manage these features. It is also responsible for conversion to and from wire-format OPT RR. One important exception is about the extended RCODE: The EDNS class is only responsible for extracting the 8-bit part of the 12-bit extended RCODE from the OPT RR's TTL field of an incoming message, and for setting the 8-bit part into the OPT RR TTL of an outgoing message. It's not supposed to know how to construct the complete RCODE, much less maintain the RCODE in it. It is the caller's responsibility (typically the Message class).
When converting wire-format OPT RR into an EDNS object, it normalizes the information, i.e., unknown flags will be ignored on construction.
This class is also supposed to support EDNS options such as NSID, but the initial implementation does not include it. This is a near term TODO item.
Notes to developers
The rest of the description is for developers who need to or want to understand the design of this API.
Representing EDNS is tricky. An OPT RR is no different from other RRs in terms of the wire format syntax, and in that sense we could use the generic RRset class to represent an OPT RR (BIND 9 adopts this approach). But the resulting interface would be inconvenient for developers. For example, the developer would need to know that the UDP size is encoded in the RR Class field. It's better to provide a more abstract interface along with the special semantics of OPT RR.
Another approach would be to realize each optional feature of EDNS as an attribute of the DNS message. NLnet Labs' ldns takes this approach. This way an operation for specifying the UDP size would be written like this:
which should be more intuitive. A drawback of this approach is that OPT RR is itself optional and the separate parameters may not necessarily indicate whether to include an OPT RR per se. For example, consider what should be done with this code:
Since the payload size of 512 is the default, it may mean the OPT RR should be skipped. But it might also mean the caller intentionally (for some reason) wants to insert an OPT RR specifying the default UDP size explicitly.
So, we use a separate class that encapsulates the EDNS semantics and knows the mapping between the semantics and the wire format representation. This way the interface can be semantics-based and is intuitive:
while we can explicitly specify whether to include an OPT RR by setting (or not setting) an EDNS object in a message:
There is still a non trivial point: How to manage extended RCODEs. An OPT RR encodes the upper 8 bits of extended 12-bit RCODE. In general, it would be better to provide a unified interface to get access to RCODEs whether or not they are traditional 4 bit codes or extended ones that have non 0 upper bits. However, since an OPT RR may not appear in a message the RCODE cannot be maintained in the EDNS class. But it would not be desirable to maintain the extended RCODEs completely in the Message class, either, because we wanted to hide the mapping between EDNS semantics and its wire format representation within the EDNS class; if we moved the responsibility about RCODEs to the Message class, it would have to parse and render the upper 8 bits of the RCODEs, dealing with wire representation of OPT RR. This is suboptimal in the sense of encapsulation.
As a compromise, our decision is to separate the knowledge about the relationship with RCODE from the knowledge about the wire format as noted in the beginning of this description.
This decoupling is based on the observation that the extended RCODE is a very special case where EDNS only has partial information. If a future version of the EDNS protocol introduces further relationship between the message and the EDNS, we might reconsider the interface, probably with higher abstraction.
|
explicit |
Constructor with the EDNS version.
An application would use this constructor to specify EDNS parameters and/or options for outgoing DNS messages.
All other parameters than the version number will be initialized to reasonable defaults. Specifically, the UDP payload size is set to Message::DEFAULT_MAX_UDPSIZE, and DNSSEC is assumed to be not supported. These parameters can be altered via setter methods of this class. Note, however, that the version number cannot be changed once constructed.
The version number parameter can be omitted, in which case the highest supported version in this implementation will be assumed. When specified, if it is larger than the highest supported version, an exception of class isc::InvalidParameter will be thrown.
This constructor throws no other exception.
| version | The version number of the EDNS to be constructed. |
Definition at line 52 of file edns.cc.
References isc_throw, and SUPPORTED_VERSION.
| isc::dns::EDNS::EDNS | ( | const Name & | name, |
| const RRClass & | rrclass, | ||
| const RRType & | rrtype, | ||
| const RRTTL & | ttl, | ||
| const rdata::Rdata & | rdata ) |
Constructor from resource record (RR) parameters.
This constructor is intended to be used to construct an EDNS object from an OPT RR contained in an incoming DNS message.
Unlike many other constructors for this purpose, this constructor does not take the bare wire-format data in the form of an InputBuffer object. This is because parsing incoming EDNS is highly context dependent and it's not feasible to handle it in a completely polymorphic way. For example, a DNS message parser would have to check an OPT RR appears at most once in the message, and if it appears it should be in the additional section. So, the parser needs to have an explicit check to see if an RR is of type OPT, and then (if other conditions are met) construct a corresponding EDNS object. At that point the parser would have already converted the wire data into corresponding objects of Name, RRClass, RRType, etc, and it makes more sense to pass them directly to the constructor.
In practice, top level applications rarely need to use this constructor directly. It should normally suffice to have a higher level class such as Message do that job.
This constructor checks the passed parameters to see if they are valid in terms of the EDNS protocol specification. name must be the root name ("."); otherwise, an exception of class DNSMessageFORMERR will be thrown. rrtype must specify the OPT RR type; otherwise, an exception of class isc::InvalidParameter will be thrown. The ENDS version number is extracted from rrttl. If it is larger than the higher supported version, an exception of class DNSMessageBADVERS will be thrown. Note that this is different from the case of the same error in the other constructor. This is intentional, so that the application can transparently convert the exception to a response RCODE according to the protocol specification.
This initial implementation does not support EDNS options at all, and rdata is simply ignored. Future versions will support options, and may throw exceptions while validating the given parameter.
Note: since no other type than OPT for rrtype is allowed, this parameter could actually have been omitted. But it is intentionally included as a parameter so that invalid usage of the construction can be detected. As noted above the caller should normally have the corresponding RRType object at the time of call to this constructor, so the overhead of having the additional parameter should be marginal.
| name | The owner name of the OPT RR. This must be the root name. |
| rrclass | The RR class of the OPT RR. |
| rrtype | This must specify the OPT RR type. |
| ttl | The TTL of the OPT RR. |
| rdata | The RDATA of the OPT RR. |
Definition at line 63 of file edns.cc.
References isc_throw, isc::dns::RRType::OPT(), isc::dns::Name::ROOT_NAME(), and SUPPORTED_VERSION.
Here is the call graph for this function:
|
inline |
|
inline |
|
inline |
|
inline |
Specifies whether the sender of the message containing this EDNS is DNSSEC aware.
If the parameter is true, a subsequent call to toWire() will set the DNSSEC DO bit on for the corresponding OPT RR.
This method never throws an exception.
| is_aware | true if DNSSEC is supported; false otherwise. |
|
inline |
Specify the maximum payload size of UDP messages that use this EDNS.
Unless explicitly specified, DEFAULT_MAX_UDPSIZE will be assumed for the maximum payload size, regardless of whether EDNS OPT RR is included or not. This means if an application wants to send a message with an EDNS OPT RR for specifying a larger UDP size, it must explicitly specify the value using this method.
This method never throws an exception.
| udp_size | The maximum payload size of UDP messages for the sender of the message containing this EDNS. |
| string isc::dns::EDNS::toText | ( | ) | const |
Convert the EDNS to a string.
The format of the resulting string is as follows:
where
The string will be terminated with a trailing newline character.
When EDNS options are supported the output of this method will be extended.
This method is mostly exception free, but it may require memory allocation and if it fails a corresponding standard exception will be thrown.
EDNS. See above for the format. Definition at line 87 of file edns.cc.
References getDNSSECAwareness(), getUDPSize(), and getVersion().
Here is the call graph for this function:| uint32_t isc::dns::EDNS::toWire | ( | AbstractMessageRenderer & | renderer, |
| const uint8_t | extended_rcode ) const |
Render the EDNS in the wire format.
This method renders the EDNS object as a form of DNS OPT RR via renderer, which encapsulates output buffer and other rendering contexts. Since the EDNS object does not maintain the extended RCODE information, a separate parameter extended_rcode must be passed to this method.
If by adding the OPT RR the message size would exceed the limit maintained in renderer, this method skips rendering the RR and returns 0; otherwise it returns 1, which is the number of RR rendered.
In the current implementation the return value is either 0 or 1, but the return type is unsigned int to be consistent with RRset::toWire(). In any case the caller shouldn't assume these are only possible return values from this method.
This method is mostly exception free, but it requires memory allocation and if it fails a corresponding standard exception will be thrown.
In practice, top level applications rarely need to use this method directly. It should normally suffice to have a higher level class such as Message do that job.
Note to developer: the current implementation constructs an RRset object for the OPT RR and calls its toWire() method, which is inefficient. In future, we may want to optimize this method by caching the rendered image and having the application reuse the same EDNS object when possible.
| renderer | DNS message rendering context that encapsulates the output buffer and name compression information. |
| extended_rcode | Upper 8 bits of extended RCODE to be rendered as part of the EDNS OPT RR. |
| uint32_t isc::dns::EDNS::toWire | ( | isc::util::OutputBuffer & | buffer, |
| const uint8_t | extended_rcode ) const |
|
static |
1.10.0