Kea: isc::d2::D2UpdateMessage Class Reference

| Kea 3.2.0-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).
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.

## 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

enum isc::d2::D2UpdateMessage::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

enum isc::d2::D2UpdateMessage::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

enum isc::d2::D2UpdateMessage::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

  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, INBOUND, isc::dns::Rcode::NOERROR(), OUTBOUND, 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

  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_throw, and SECTION_ZONE.

## ◆ 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

  section | An `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.

## ◆ 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

  section | An `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.

## ◆ 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_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 getRRCount(), isc_throw, isc::dns::TSIGError::NOERROR(), SECTION_ZONE, 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.

## ◆ 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::HEADERFLAG_QR, REQUEST, and RESPONSE.

Referenced by toWire().

## ◆ 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.

## ◆ getRRCount()

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

Returns number of RRsets in the specified message section.

Parameters

  section | An `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.

Referenced by fromWire(), and toWire().

## ◆ 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

  id | 16-bit value of the message id.

Definition at line 44 of file d2_update_message.cc.

## ◆ setRcode()

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

Sets message RCode.

Parameters

  rcode | An object representing message RCode.

Definition at line 55 of file d2_update_message.cc.

## ◆ 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

  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::Question::getClass(), isc::dns::Question::getName(), 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

  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, and SECTION_ZONE.

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:

- d2_update_message.h
- d2_update_message.cc