Current File : //backups/router/usr/local/include/kea/d2srv/d2_update_message.h
// Copyright (C) 2013-2021 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
#ifndef D2_UPDATE_MESSAGE_H
#define D2_UPDATE_MESSAGE_H
#include <d2srv/d2_zone.h>
#include <dns/message.h>
#include <dns/name.h>
#include <dns/rcode.h>
#include <dns/rrclass.h>
#include <dns/rrset.h>
#include <dns/tsig.h>
#include <map>
namespace isc {
namespace d2 {
/// @brief Exception indicating that Zone section contains invalid content.
///
/// This exception is thrown when ZONE section of the DNS Update message
/// is invalid. According to RFC2136, section 2.3, the zone section is
/// allowed to contain exactly one record. When Request message contains
/// more records or is empty, this exception is thrown.
class InvalidZoneSection : public Exception {
public:
InvalidZoneSection(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) {}
};
/// @brief Exception indicating that QR flag has invalid value.
///
/// This exception is thrown when QR flag has invalid value for
/// the operation performed on the particular message. For instance,
/// the QR flag must be set to indicate that the given message is
/// a RESPONSE when @c D2UpdateMessage::fromWire is performed.
/// The QR flag must be cleared when @c D2UpdateMessage::toWire
/// is executed.
class InvalidQRFlag : public Exception {
public:
InvalidQRFlag(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) {}
};
/// @brief Exception indicating that the parsed message is not DNS Update.
///
/// This exception is thrown when decoding the DNS message which is not
/// a DNS Update.
class NotUpdateMessage : public Exception {
public:
NotUpdateMessage(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) {}
};
/// @brief Exception indicating that a signed, inbound message failed to verify
///
/// This exception is thrown when TSIG verification of a DNS server's response
/// fails.
class TSIGVerifyError : public Exception {
public:
TSIGVerifyError(const char* file, size_t line, const char* what) :
isc::Exception(file, line, what) {}
};
class D2UpdateMessage;
/// @brief Pointer to the DNS Update Message.
typedef boost::shared_ptr<D2UpdateMessage> D2UpdateMessagePtr;
/// @brief The @c 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.
///
/// <b>Design choice:</b> A dedicated class has been created to encapsulate
/// DNS Update message because existing @c 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 @c isc::dns::Message
/// class, this class is implemented in-terms-of @c isc::dns::Message class
/// to reuse its functionality where possible.
class D2UpdateMessage {
public:
/// @brief Indicates if the @c D2UpdateMessage object encapsulates Inbound
/// or Outbound message.
enum Direction {
INBOUND,
OUTBOUND
};
/// @brief Indicates whether DNS Update message is a REQUEST or RESPONSE.
enum QRFlag {
REQUEST,
RESPONSE
};
/// @brief 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 @c getRRCount (to get
/// the number of records in a corresponding section) and @c beginSection
/// and @c endSection (to access data in the corresponding section).
enum UpdateMsgSection {
SECTION_ZONE,
SECTION_PREREQUISITE,
SECTION_UPDATE,
SECTION_ADDITIONAL
};
public:
/// @brief 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 @c D2UpdateMessage::fromWire function is used to parse on-wire data.
/// For outgoing messages, modifier functions should be used to set the
/// message contents and @c D2UpdateMessage::toWire function to create
/// on-wire data.
///
/// @param direction indicates if this is an inbound or outbound message.
D2UpdateMessage(const Direction direction = OUTBOUND);
///
/// @name 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.
//@{
private:
D2UpdateMessage(const D2UpdateMessage& source);
D2UpdateMessage& operator=(const D2UpdateMessage& source);
//@}
public:
/// @brief 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.
///
/// @return An enum value indicating whether the message is a
/// REQUEST or RESPONSE.
QRFlag getQRFlag() const;
/// @brief Returns message ID.
///
/// @return message ID.
uint16_t getId() const;
/// @brief Sets message ID.
///
/// @param id 16-bit value of the message id.
void setId(const uint16_t id);
/// @brief Returns an object representing message RCode.
///
/// @return An object representing message RCode.
const dns::Rcode& getRcode() const;
/// @brief Sets message RCode.
///
/// @param rcode An object representing message RCode.
void setRcode(const dns::Rcode& rcode);
/// @brief Returns number of RRsets in the specified message section.
///
/// @param section An @c UpdateMsgSection enum specifying a message section
/// for which the number of RRsets is to be returned.
///
/// @return A number of RRsets in the specified message section.
unsigned int getRRCount(const UpdateMsgSection section) const;
/// @name Functions returning iterators to RRsets in message sections.
///
//@{
/// @brief Return iterators pointing to the beginning of the list of RRsets,
/// which belong to the specified section.
///
/// @param section An @c UpdateMsgSection enum specifying a message section
/// for which the iterator should be returned.
///
/// @return An iterator pointing to the beginning of the list of the
/// RRsets, which belong to the specified section.
const dns::RRsetIterator beginSection(const UpdateMsgSection section) const;
/// @brief Return iterators pointing to the end of the list of RRsets,
/// which belong to the specified section.
///
/// @param section An @c UpdateMsgSection enum specifying a message section
/// for which the iterator should be returned.
///
/// @return An iterator pointing to the end of the list of the
/// RRsets, which belong to the specified section.
const dns::RRsetIterator endSection(const UpdateMsgSection section) const;
//@}
/// @brief Sets the Zone record.
///
/// This function creates the @c 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.
///
/// @param zone A name of the zone being updated.
/// @param rrclass A class of the zone record.
void setZone(const dns::Name& zone, const dns::RRClass& rrclass);
/// @brief Returns a pointer to the object representing Zone record.
///
/// @return A pointer to the object representing Zone record.
D2ZonePtr getZone() const;
/// @brief 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 @c D2UpdateMessage::setZone function should be used instead.
/// Also, this function expects that @c rrset argument is non-NULL.
///
/// @param section A message section where the RRset should be added.
/// @param rrset A reference to a RRset which should be added.
void addRRset(const UpdateMsgSection section, const dns::RRsetPtr& rrset);
/// @name Functions to handle message encoding and decoding.
///
//@{
/// @brief 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 @c 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.
///
/// @param renderer A renderer object used to generate the message wire
/// format.
/// @param tsig_ctx A TSIG context that is to be used for signing the
/// message. If NULL the message will not be signed.
void toWire(dns::AbstractMessageRenderer& renderer,
dns::TSIGContext* const tsig_ctx = NULL);
/// @brief 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:
/// @c D2UpdateMessage::getZone, @c D2UpdateMessage::beginSection and
/// @c 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.
///
/// @param received_data buffer holding DNS Update message to be parsed.
/// @param bytes_received the number of bytes in received_data
/// @param tsig_context A TSIG context that is to be used to verify the
/// message. If NULL TSIG verification will not be attempted.
void fromWire(const void* received_data, size_t bytes_received,
dns::TSIGContext* const tsig_context = NULL);
//@}
private:
/// Maps the values of the @c UpdateMessageSection field to the
/// corresponding values in the @c isc::dns::Message class. This
/// mapping is required here because this class uses @c isc::dns::Message
/// class to do the actual processing of the DNS Update message.
///
/// @param section An enum indicating the section for which the
/// corresponding enum value from @c isc::dns::Message will be returned.
///
/// @return The enum value indicating the section in the DNS message
/// represented by the @c isc::dns::Message class.
static
dns::Message::Section ddnsToDnsSection(const UpdateMsgSection section);
/// @brief Checks received response message for correctness.
///
/// This function verifies that the received response from a server is
/// correct. Currently this function checks the following:
/// - Opcode is 'DNS Update',
/// - QR flag is RESPONSE (flag bit is set),
/// - Zone section comprises at most one record.
///
/// The function will throw exception if any of the conditions above are
/// not met.
///
/// @throw isc::d2::NotUpdateMessage if invalid Opcode.
/// @throw isc::d2::InvalidQRFlag if QR flag is not set to RESPONSE
/// @throw isc::d2::InvalidZone section, if Zone section comprises more
/// than one record.
void validateResponse() const;
/// @brief An object representing DNS Message which is used by the
/// implementation of @c D2UpdateMessage to perform low level.
///
/// Declaration of this object pollutes the header with the details
/// of @c D2UpdateMessage implementation. It might be cleaner to use
/// Pimpl idiom to hide this object in an D2UpdateMessageImpl. However,
/// it would bring additional complications to the implementation
/// while the benefit would low - this header is not a part of any
/// common library. Therefore, if implementation is changed, modification of
/// private members of this class in the header has low impact.
dns::Message message_;
/// @brief Holds a pointer to the object, representing Zone in the DNS
/// Update.
D2ZonePtr zone_;
};
} // namespace d2
} // namespace isc
#endif // D2_UPDATE_MESSAGE_H
Mini Shell