Kea  2.1.7-git
isc::dns::EDNS Class Reference

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. More...
 
 EDNS (const Name &name, const RRClass &rrclass, const RRType &rrtype, const RRTTL &ttl, const rdata::Rdata &rdata)
 Constructor from resource record (RR) parameters. More...
 
Getter and Setter Methods
uint8_t getVersion () const
 Returns the version of EDNS. More...
 
uint16_t getUDPSize () const
 Returns the maximum payload size of UDP messages for the sender of the message containing this EDNS. More...
 
void setUDPSize (const uint16_t udp_size)
 Specify the maximum payload size of UDP messages that use this EDNS. More...
 
bool getDNSSECAwareness () const
 Returns whether the message sender is DNSSEC aware. More...
 
void setDNSSECAwareness (const bool is_aware)
 Specifies whether the sender of the message containing this EDNS is DNSSEC aware. More...
 
Converter Methods
unsigned int toWire (AbstractMessageRenderer &renderer, const uint8_t extended_rcode) const
 Render the EDNS in the wire format. More...
 
unsigned int toWire (isc::util::OutputBuffer &buffer, const uint8_t extended_rcode) const
 Render the EDNS in the wire format. More...
 
std::string toText () const
 Convert the EDNS to a string. More...
 

Static Public Attributes

static const uint8_t SUPPORTED_VERSION = 0
 The highest EDNS version this implementation supports. More...
 

Detailed Description

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:

message->setUDPSize(4096);

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:

message->setUDPSize(512);

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:

edns->setUDPSize(4096);

while we can explicitly specify whether to include an OPT RR by setting (or not setting) an EDNS object in a message:

message->setEDNS(edns); // unless we do this OPT RR is skipped

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.

Definition at line 123 of file edns.h.

Constructor & Destructor Documentation

◆ EDNS() [1/2]

isc::dns::EDNS::EDNS ( const uint8_t  version = SUPPORTED_VERSION)
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.

Parameters
versionThe version number of the EDNS to be constructed.

Definition at line 55 of file edns.cc.

References isc_throw, and SUPPORTED_VERSION.

Referenced by isc::dns::createEDNSFromRR().

◆ EDNS() [2/2]

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.

Parameters
nameThe owner name of the OPT RR. This must be the root name.
rrclassThe RR class of the OPT RR.
rrtypeThis must specify the OPT RR type.
ttlThe TTL of the OPT RR.
rdataThe RDATA of the OPT RR.

Definition at line 67 of file edns.cc.

References isc::dns::RRClass::getCode(), isc::dns::RRTTL::getValue(), isc_throw, isc::dns::RRType::OPT(), isc::dns::Name::ROOT_NAME(), and SUPPORTED_VERSION.

+ Here is the call graph for this function:

Member Function Documentation

◆ getDNSSECAwareness()

bool isc::dns::EDNS::getDNSSECAwareness ( ) const
inline

Returns whether the message sender is DNSSEC aware.

This method never throws an exception.

Returns
true if DNSSEC is supported; otherwise false.

Definition at line 253 of file edns.h.

Referenced by toText().

◆ getUDPSize()

uint16_t isc::dns::EDNS::getUDPSize ( ) const
inline

Returns the maximum payload size of UDP messages for the sender of the message containing this EDNS.

This method never throws an exception.

Definition at line 231 of file edns.h.

Referenced by toText().

◆ getVersion()

uint8_t isc::dns::EDNS::getVersion ( ) const
inline

Returns the version of EDNS.

This method never throws an exception.

Definition at line 225 of file edns.h.

Referenced by toText().

◆ setDNSSECAwareness()

void isc::dns::EDNS::setDNSSECAwareness ( const bool  is_aware)
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.

Parameters
is_awaretrue if DNSSEC is supported; false otherwise.

Definition at line 264 of file edns.h.

◆ setUDPSize()

void isc::dns::EDNS::setUDPSize ( const uint16_t  udp_size)
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.

Parameters
udp_sizeThe maximum payload size of UDP messages for the sender of the message containing this EDNS.

Definition at line 246 of file edns.h.

◆ toText()

string isc::dns::EDNS::toText ( ) const

Convert the EDNS to a string.

The format of the resulting string is as follows:

; EDNS: version: <version>, flags: <edns flags>; udp: <udp size>

where

  • version is the EDNS version number (integer).
  • edns flags is a sequence of EDNS flag bits. The only possible flag is the "DNSSEC OK", which is represented as "do".
  • udp size is sender's UDP payload size in bytes.

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.

Returns
A string representation of EDNS. See above for the format.

Definition at line 92 of file edns.cc.

References getDNSSECAwareness(), getUDPSize(), getVersion(), isc::dns::RRType::OPT(), isc::dns::Name::ROOT_NAME(), and version().

Referenced by isc::dns::operator<<().

+ Here is the call graph for this function:

◆ toWire() [1/2]

unsigned int 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.

Parameters
rendererDNS message rendering context that encapsulates the output buffer and name compression information.
extended_rcodeUpper 8 bits of extended RCODE to be rendered as part of the EDNS OPT RR.
Returns
1 if the OPT RR fits in the message size limit; otherwise 0.

Definition at line 134 of file edns.cc.

References isc::dns::AbstractMessageRenderer::getLength(), and isc::dns::AbstractMessageRenderer::getLengthLimit().

+ Here is the call graph for this function:

◆ toWire() [2/2]

unsigned int isc::dns::EDNS::toWire ( isc::util::OutputBuffer buffer,
const uint8_t  extended_rcode 
) const

Render the EDNS in the wire format.

This method is same as toWire(MessageRenderer&,uint8_t)const except it renders the OPT RR in an OutputBuffer and therefore does not care about message size limit. As a consequence it always returns 1.

Definition at line 149 of file edns.cc.

Member Data Documentation

◆ SUPPORTED_VERSION

const uint8_t isc::dns::EDNS::SUPPORTED_VERSION = 0
static

The highest EDNS version this implementation supports.

Definition at line 351 of file edns.h.

Referenced by EDNS().


The documentation for this class was generated from the following files: