Kea 2.7.6
|
The D2UpdateMessage
encapsulates a DNS Update message.
More...
#include <d2_update_message.h>
Public Types | |
enum | Direction { INBOUND , OUTBOUND } |
Indicates if the D2UpdateMessage object encapsulates Inbound or Outbound message. More... | |
enum | QRFlag { REQUEST , RESPONSE } |
Indicates whether DNS Update message is a REQUEST or RESPONSE. More... | |
enum | UpdateMsgSection { SECTION_ZONE , SECTION_PREREQUISITE , SECTION_UPDATE , SECTION_ADDITIONAL } |
Identifies sections in the DNS Update Message. More... | |
Public Member Functions | |
D2UpdateMessage (const Direction direction=OUTBOUND) | |
Constructor used to create an instance of the DNS Update Message (either outgoing or incoming). | |
Functions returning iterators to RRsets in message sections. | |
const dns::RRsetIterator | beginSection (const UpdateMsgSection section) const |
Return iterators pointing to the beginning of the list of RRsets, which belong to the specified section. | |
const dns::RRsetIterator | endSection (const UpdateMsgSection section) const |
Return iterators pointing to the end of the list of RRsets, which belong to the specified section. | |
void | setZone (const dns::Name &zone, const dns::RRClass &rrclass) |
Sets the Zone record. | |
D2ZonePtr | getZone () const |
Returns a pointer to the object representing Zone record. | |
void | addRRset (const UpdateMsgSection section, const dns::RRsetPtr &rrset) |
Adds an RRset to the specified section. | |
Functions to handle message encoding and decoding. | |
void | toWire (dns::AbstractMessageRenderer &renderer, dns::TSIGContext *const tsig_ctx=NULL) |
Encode outgoing message into wire format. | |
void | fromWire (const void *received_data, size_t bytes_received, dns::TSIGContext *const tsig_context=NULL) |
Decode incoming message from the wire format. | |
Copy constructor and assignment operator | |
Copy constructor and assignment operator are private because we assume there will be no need to copy messages on the client side. | |
QRFlag | getQRFlag () const |
Returns enum value indicating if the message is a REQUEST or RESPONSE. | |
uint16_t | getId () const |
Returns message ID. | |
void | setId (const uint16_t id) |
Sets message ID. | |
const dns::Rcode & | getRcode () const |
Returns an object representing message RCode. | |
void | setRcode (const dns::Rcode &rcode) |
Sets message RCode. | |
unsigned int | getRRCount (const UpdateMsgSection section) const |
Returns number of RRsets in the specified message section. | |
The D2UpdateMessage
encapsulates a DNS Update message.
This class represents the DNS Update message. Functions exposed by this class allow to specify the data sections carried by the message and create an on-wire format of this message. This class is also used to decode messages received from the DNS server in the on-wire format.
Design choice: A dedicated class has been created to encapsulate DNS Update message because existing isc::dns::Message
is designed to support regular DNS messages (described in RFC 1035) only. Although DNS Update has the same format, particular sections serve different purposes. In order to avoid rewrite of significant portions of isc::dns::Message
class, this class is implemented in-terms-of isc::dns::Message
class to reuse its functionality where possible.
Definition at line 89 of file d2_update_message.h.
Indicates if the D2UpdateMessage
object encapsulates Inbound or Outbound message.
Enumerator | |
---|---|
INBOUND | |
OUTBOUND |
Definition at line 94 of file d2_update_message.h.
Indicates whether DNS Update message is a REQUEST or RESPONSE.
Enumerator | |
---|---|
REQUEST | |
RESPONSE |
Definition at line 100 of file d2_update_message.h.
Identifies sections in the DNS Update Message.
Each message comprises message Header and may contain the following sections:
The enum elements are used by functions such as getRRCount
(to get the number of records in a corresponding section) and beginSection
and endSection
(to access data in the corresponding section).
Enumerator | |
---|---|
SECTION_ZONE | |
SECTION_PREREQUISITE | |
SECTION_UPDATE | |
SECTION_ADDITIONAL |
Definition at line 117 of file d2_update_message.h.
Constructor used to create an instance of the DNS Update Message (either outgoing or incoming).
This constructor is used to create an instance of either incoming or outgoing DNS Update message. The boolean argument indicates whether it is incoming (true) or outgoing (false) message. For incoming messages the D2UpdateMessage::fromWire
function is used to parse on-wire data. For outgoing messages, modifier functions should be used to set the message contents and D2UpdateMessage::toWire
function to create on-wire data.
direction | indicates if this is an inbound or outbound message. |
Definition at line 20 of file d2_update_message.cc.
References isc::dns::Message::HEADERFLAG_QR, isc::dns::Rcode::NOERROR(), OUTBOUND, isc::dns::Message::setHeaderFlag(), isc::dns::Message::setOpcode(), isc::dns::Message::setRcode(), and isc::dns::Opcode::UPDATE_CODE.
void isc::d2::D2UpdateMessage::addRRset | ( | const UpdateMsgSection | section, |
const dns::RRsetPtr & | rrset ) |
Adds an RRset to the specified section.
This function may throw exception if the specified section is out of bounds or Zone section update is attempted. For Zone section D2UpdateMessage::setZone
function should be used instead. Also, this function expects that rrset
argument is non-NULL.
section | A message section where the RRset should be added. |
rrset | A reference to a RRset which should be added. |
Definition at line 95 of file d2_update_message.cc.
References isc::dns::Message::addRRset(), isc_throw, and SECTION_ZONE.
const dns::RRsetIterator isc::d2::D2UpdateMessage::beginSection | ( | const UpdateMsgSection | section | ) | const |
Return iterators pointing to the beginning of the list of RRsets, which belong to the specified section.
section | An UpdateMsgSection enum specifying a message section for which the iterator should be returned. |
Definition at line 65 of file d2_update_message.cc.
References isc::dns::Message::beginSection().
const dns::RRsetIterator isc::d2::D2UpdateMessage::endSection | ( | const UpdateMsgSection | section | ) | const |
Return iterators pointing to the end of the list of RRsets, which belong to the specified section.
section | An UpdateMsgSection enum specifying a message section for which the iterator should be returned. |
Definition at line 70 of file d2_update_message.cc.
References isc::dns::Message::endSection().
void isc::d2::D2UpdateMessage::fromWire | ( | const void * | received_data, |
size_t | bytes_received, | ||
dns::TSIGContext *const | tsig_context = NULL ) |
Decode incoming message from the wire format.
This function decodes the DNS Update message stored in the buffer specified by the function argument. If given a TSIG context, then the function will first attempt to use that context to verify the message signature. If verification fails a TSIGVerifyError exception will be thrown. The function then parses message header and extracts the section counters: ZOCOUNT, PRCOUNT, UPCOUNT and ADCOUNT. Using these counters, function identifies message sections, which follow message header. These sections can be later accessed using: D2UpdateMessage::getZone
, D2UpdateMessage::beginSection
and D2UpdateMessage::endSection
functions.
This function is NOT exception safe. It signals message decoding errors through exceptions. Message decoding error may occur if the received message does not conform to the general DNS Message format, specified in RFC 1035. Errors which are specific to DNS Update messages include:
received_data | buffer holding DNS Update message to be parsed. |
bytes_received | the number of bytes in received_data |
tsig_context | A TSIG context that is to be used to verify the message. If NULL TSIG verification will not be attempted. |
Definition at line 124 of file d2_update_message.cc.
References isc::dns::Message::beginQuestion(), isc::dns::Message::fromWire(), getRRCount(), isc::dns::Message::getTSIGRecord(), isc_throw, isc::dns::TSIGError::NOERROR(), SECTION_ZONE, and isc::dns::TSIGContext::verify().
uint16_t isc::d2::D2UpdateMessage::getId | ( | ) | const |
Returns message ID.
Definition at line 39 of file d2_update_message.cc.
References isc::dns::Message::getQid().
D2UpdateMessage::QRFlag isc::d2::D2UpdateMessage::getQRFlag | ( | ) | const |
Returns enum value indicating if the message is a REQUEST or RESPONSE.
The returned value is REQUEST if the message is created as an outgoing message. In such case the QR flag bit in the message header is cleared. The returned value is RESPONSE if the message is created as an incoming message and the QR flag bit was set in the received message header.
Definition at line 33 of file d2_update_message.cc.
References isc::dns::Message::getHeaderFlag(), isc::dns::Message::HEADERFLAG_QR, REQUEST, and RESPONSE.
Referenced by toWire().
const dns::Rcode & isc::d2::D2UpdateMessage::getRcode | ( | ) | const |
Returns an object representing message RCode.
Definition at line 50 of file d2_update_message.cc.
References isc::dns::Message::getRcode().
unsigned int isc::d2::D2UpdateMessage::getRRCount | ( | const UpdateMsgSection | section | ) | const |
Returns number of RRsets in the specified message section.
section | An UpdateMsgSection enum specifying a message section for which the number of RRsets is to be returned. |
Definition at line 60 of file d2_update_message.cc.
References isc::dns::Message::getRRCount().
Referenced by fromWire(), and toWire().
D2ZonePtr isc::d2::D2UpdateMessage::getZone | ( | ) | const |
Returns a pointer to the object representing Zone record.
Definition at line 90 of file d2_update_message.cc.
void isc::d2::D2UpdateMessage::setId | ( | const uint16_t | id | ) |
Sets message ID.
id | 16-bit value of the message id. |
Definition at line 44 of file d2_update_message.cc.
References isc::dns::Message::setQid().
void isc::d2::D2UpdateMessage::setRcode | ( | const dns::Rcode & | rcode | ) |
Sets message RCode.
rcode | An object representing message RCode. |
Definition at line 55 of file d2_update_message.cc.
References isc::dns::Message::setRcode().
void isc::d2::D2UpdateMessage::setZone | ( | const dns::Name & | zone, |
const dns::RRClass & | rrclass ) |
Sets the Zone record.
This function creates the D2Zone
object, representing a Zone record for the outgoing message. If the Zone record is already set, it is replaced by the new record being set by this function. The RRType for the record is always SOA.
zone | A name of the zone being updated. |
rrclass | A class of the zone record. |
Definition at line 75 of file d2_update_message.cc.
References isc::dns::Message::addQuestion(), isc::dns::Message::clearSection(), isc::dns::Question::getClass(), isc::dns::Question::getName(), isc::dns::Message::getRRCount(), isc::dns::Message::SECTION_QUESTION, and isc::dns::RRType::SOA().
void isc::d2::D2UpdateMessage::toWire | ( | dns::AbstractMessageRenderer & | renderer, |
dns::TSIGContext *const | tsig_ctx = NULL ) |
Encode outgoing message into wire format.
This function encodes the DNS Update into the wire format. The format of such a message is described in the RFC2136, section 2. Some of the sections which belong to encoded message may be empty. If a particular message section is empty (does not comprise any RRs), the corresponding counter in the message header is set to 0. These counters are: PRCOUNT, UPCOUNT, ADCOUNT for the Prerequisites, Update RRs and Additional Data RRs respectively. The ZOCOUNT must be equal to 1 because RFC2136 requires that the message comprises exactly one Zone record.
If given a TSIG context, this method will pass the context down into dns::Message.toWire() method which signs the message using the context.
This function does not guarantee exception safety. However, exceptions should be rare because D2UpdateMessage
class API prevents invalid use of the class. The typical case, when this function may throw an exception is when this it is called on the object representing incoming (instead of outgoing) message. In such case, the QR field will be set to RESPONSE, which is invalid setting when calling this function.
renderer | A renderer object used to generate the message wire format. |
tsig_ctx | A TSIG context that is to be used for signing the message. If NULL the message will not be signed. |
Definition at line 105 of file d2_update_message.cc.
References getQRFlag(), getRRCount(), isc_throw, REQUEST, SECTION_ZONE, and isc::dns::Message::toWire().
Referenced by isc::d2::DNSClientImpl::doUpdate().