Kea  2.3.5-git
isc::d2::D2UpdateMessage Class Reference

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). More...
 
void addRRset (const UpdateMsgSection section, const dns::RRsetPtr &rrset)
 Adds an RRset to the specified section. More...
 
uint16_t getId () const
 Returns message ID. More...
 
QRFlag getQRFlag () const
 Returns enum value indicating if the message is a REQUEST or RESPONSE. More...
 
const dns::RcodegetRcode () const
 Returns an object representing message RCode. More...
 
unsigned int getRRCount (const UpdateMsgSection section) const
 Returns number of RRsets in the specified message section. More...
 
D2ZonePtr getZone () const
 Returns a pointer to the object representing Zone record. More...
 
void setId (const uint16_t id)
 Sets message ID. More...
 
void setRcode (const dns::Rcode &rcode)
 Sets message RCode. More...
 
void setZone (const dns::Name &zone, const dns::RRClass &rrclass)
 Sets the Zone record. More...
 
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. More...
 
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. More...
 
Functions to handle message encoding and decoding.
void toWire (dns::AbstractMessageRenderer &renderer, dns::TSIGContext *const tsig_ctx=NULL)
 Encode outgoing message into wire format. More...
 
void fromWire (const void *received_data, size_t bytes_received, dns::TSIGContext *const tsig_context=NULL)
 Decode incoming message from the wire format. More...
 

Detailed Description

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.

Member Enumeration Documentation

◆ Direction

Indicates if the D2UpdateMessage object encapsulates Inbound or Outbound message.

Enumerator
INBOUND 
OUTBOUND 

Definition at line 94 of file d2_update_message.h.

◆ QRFlag

Indicates whether DNS Update message is a REQUEST or RESPONSE.

Enumerator
REQUEST 
RESPONSE 

Definition at line 100 of file d2_update_message.h.

◆ UpdateMsgSection

Identifies sections in the DNS Update Message.

Each message comprises message Header and may contain the following sections:

  • ZONE
  • PREREQUISITE
  • UPDATE
  • ADDITIONAL

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 & Destructor Documentation

◆ D2UpdateMessage()

isc::d2::D2UpdateMessage::D2UpdateMessage ( const Direction  direction = OUTBOUND)

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.

Parameters
directionindicates 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.

+ Here is the call graph for this function:

Member Function Documentation

◆ addRRset()

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.

Parameters
sectionA message section where the RRset should be added.
rrsetA 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.

+ Here is the call graph for this function:

◆ beginSection()

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.

Parameters
sectionAn UpdateMsgSection enum specifying a message section for which the iterator should be returned.
Returns
An iterator pointing to the beginning of the list of the RRsets, which belong to the specified section.

Definition at line 65 of file d2_update_message.cc.

References isc::dns::Message::beginSection().

+ Here is the call graph for this function:

◆ endSection()

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.

Parameters
sectionAn UpdateMsgSection enum specifying a message section for which the iterator should be returned.
Returns
An iterator pointing to the end of the list of the RRsets, which belong to the specified section.

Definition at line 70 of file d2_update_message.cc.

References isc::dns::Message::endSection().

+ Here is the call graph for this function:

◆ fromWire()

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:

  • Invalid Opcode - not an UPDATE.
  • Invalid QR flag - the QR bit should be set to indicate that the message is the server response.
  • The number of records in the Zone section is greater than 1.
Parameters
received_databuffer holding DNS Update message to be parsed.
bytes_receivedthe number of bytes in received_data
tsig_contextA 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::db::error, isc::dns::Message::fromWire(), isc::dns::Opcode::getCode(), isc::dns::Message::getOpcode(), getQRFlag(), getRRCount(), isc::dns::Message::getTSIGRecord(), isc_throw, isc::dns::TSIGError::NOERROR(), REQUEST, SECTION_ADDITIONAL, isc::dns::Message::SECTION_ADDITIONAL, isc::dns::Message::SECTION_ANSWER, isc::dns::Message::SECTION_AUTHORITY, SECTION_PREREQUISITE, isc::dns::Message::SECTION_QUESTION, SECTION_UPDATE, SECTION_ZONE, isc::dns::TSIGError::toText(), isc::dns::Opcode::UPDATE(), and isc::dns::TSIGContext::verify().

+ Here is the call graph for this function:

◆ getId()

uint16_t isc::d2::D2UpdateMessage::getId ( ) const

Returns message ID.

Returns
message ID.

Definition at line 39 of file d2_update_message.cc.

References isc::dns::Message::getQid().

+ Here is the call graph for this function:

◆ getQRFlag()

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.

Returns
An enum value indicating whether the message is a REQUEST or RESPONSE.

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 fromWire(), and toWire().

+ Here is the call graph for this function:

◆ getRcode()

const dns::Rcode & isc::d2::D2UpdateMessage::getRcode ( ) const

Returns an object representing message RCode.

Returns
An object representing message RCode.

Definition at line 50 of file d2_update_message.cc.

References isc::dns::Message::getRcode().

+ Here is the call graph for this function:

◆ getRRCount()

unsigned int isc::d2::D2UpdateMessage::getRRCount ( const UpdateMsgSection  section) const

Returns number of RRsets in the specified message section.

Parameters
sectionAn UpdateMsgSection enum specifying a message section for which the number of RRsets is to be returned.
Returns
A number of RRsets in the specified message section.

Definition at line 60 of file d2_update_message.cc.

References isc::dns::Message::getRRCount().

Referenced by fromWire(), and toWire().

+ Here is the call graph for this function:

◆ getZone()

D2ZonePtr isc::d2::D2UpdateMessage::getZone ( ) const

Returns a pointer to the object representing Zone record.

Returns
A pointer to the object representing Zone record.

Definition at line 90 of file d2_update_message.cc.

◆ setId()

void isc::d2::D2UpdateMessage::setId ( const uint16_t  id)

Sets message ID.

Parameters
id16-bit value of the message id.

Definition at line 44 of file d2_update_message.cc.

References isc::dns::Message::setQid().

+ Here is the call graph for this function:

◆ setRcode()

void isc::d2::D2UpdateMessage::setRcode ( const dns::Rcode rcode)

Sets message RCode.

Parameters
rcodeAn object representing message RCode.

Definition at line 55 of file d2_update_message.cc.

References isc::dns::Message::setRcode().

+ Here is the call graph for this function:

◆ setZone()

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.

Parameters
zoneA name of the zone being updated.
rrclassA 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().

+ Here is the call graph for this function:

◆ toWire()

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.

Parameters
rendererA renderer object used to generate the message wire format.
tsig_ctxA 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().

+ Here is the call graph for this function:

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