duid.h 6.91 KB
Newer Older
1
// Copyright (C) 2012-2014 Internet Systems Consortium, Inc. ("ISC")
2 3 4 5 6 7 8 9 10 11 12 13 14
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

Tomek Mrugalski's avatar
Tomek Mrugalski committed
15 16 17 18
#ifndef DUID_H
#define DUID_H

#include <asiolink/io_address.h>
19

Tomek Mrugalski's avatar
Tomek Mrugalski committed
20
#include <vector>
21

22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37
#include <stdint.h>
#include <unistd.h>

namespace isc {
namespace dhcp {

/// @brief Holds DUID (DHCPv6 Unique Identifier)
///
/// This class holds DUID, that is used in client-id, server-id and
/// several other options. It is used to identify DHCPv6 entity.
class DUID {
 public:
    /// @brief maximum duid size
    /// As defined in RFC3315, section 9.1
    static const size_t MAX_DUID_LEN = 128;

38 39 40 41 42
    /// @brief minimum duid size
    /// There's no explicit minimal DUID size specified in RFC3315,
    /// so let's use absolute minimum
    static const size_t MIN_DUID_LEN = 1;

43 44 45 46 47 48 49 50 51 52
    /// @brief specifies DUID type
    typedef enum {
        DUID_UNKNOWN = 0, ///< invalid/unknown type
        DUID_LLT = 1,     ///< link-layer + time, see RFC3315, section 9.2
        DUID_EN = 2,      ///< enterprise-id, see RFC3315, section 9.3
        DUID_LL = 3,      ///< link-layer, see RFC3315, section 9.4
        DUID_UUID = 4,    ///< UUID, see RFC6355
        DUID_MAX          ///< not a real type, just maximum defined value + 1
    } DUIDType;

Stephen Morris's avatar
Stephen Morris committed
53
    /// @brief Constructor from vector
54 55
    DUID(const std::vector<uint8_t>& duid);

Stephen Morris's avatar
Stephen Morris committed
56
    /// @brief Constructor from array and array size
57
    DUID(const uint8_t* duid, size_t len);
58

Stephen Morris's avatar
Stephen Morris committed
59
    /// @brief Returns a const reference to the actual DUID value
60
    ///
61 62 63 64 65 66 67
    /// @warning Since this function returns a reference to the vector (not a
    /// copy) the returned object must be used with caution because it remains
    /// valid only for the time period when the object which returned it is
    /// valid.
    ///
    /// @return A reference to a vector holding a DUID.
    const std::vector<uint8_t>& getDuid() const;
68

Stephen Morris's avatar
Stephen Morris committed
69
    /// @brief Returns the DUID type
70 71
    DUIDType getType() const;

72 73 74
    /// @brief Create DUID from the textual format.
    ///
    /// This static function parses a DUID specified in the textual format.
75
    /// Internally it uses @c DUID::decode to parse the DUID.
76 77 78 79 80 81 82
    ///
    /// @param text DUID in the hexadecimal format with digits representing
    /// individual bytes separated by colons.
    ///
    /// @throw isc::BadValue if parsing the DUID failed.
    static DUID fromText(const std::string& text);

Stephen Morris's avatar
Stephen Morris committed
83
    /// @brief Returns textual representation of a DUID (e.g. 00:01:02:03:ff)
84 85
    std::string toText() const;

Stephen Morris's avatar
Stephen Morris committed
86
    /// @brief Compares two DUIDs for equality
87
    bool operator==(const DUID& other) const;
88

Stephen Morris's avatar
Stephen Morris committed
89
    /// @brief Compares two DUIDs for inequality
90
    bool operator!=(const DUID& other) const;
91 92

 protected:
93 94 95 96 97 98 99 100

    /// @brief Decodes the textual format of the DUID.
    ///
    /// The format being parsed should match the DUID representation returned
    /// by the @c DUID::toText method, i.e. the pairs of hexadecimal digits
    /// representing bytes of DUID must be separated by colons. Usually the
    /// single byte is represented by two hexadecimal digits. However, this
    /// function allows one digit per byte. In this case, a zero is prepended
101 102
    /// before the conversion. For example, a DUID 0:1:2:3:4:5 equals to
    /// 00:01:02:03:04:05.
103 104 105 106 107 108 109
    ///
    /// @param text DUID in the hexadecimal format with digits representing
    /// individual bytes separated by colons.
    ///
    /// @throw isc::BadValue if parsing the DUID failed.
    static std::vector<uint8_t> decode(const std::string& text);

Stephen Morris's avatar
Stephen Morris committed
110
    /// The actual content of the DUID
111 112 113
    std::vector<uint8_t> duid_;
};

Stephen Morris's avatar
Stephen Morris committed
114
/// @brief Shared pointer to a DUID
Tomek Mrugalski's avatar
Tomek Mrugalski committed
115 116
typedef boost::shared_ptr<DUID> DuidPtr;

117 118 119 120
/// @brief Forward declaration to the @c ClientId class.
class ClientId;
/// @brief Shared pointer to a Client ID.
typedef boost::shared_ptr<ClientId> ClientIdPtr;
Stephen Morris's avatar
Stephen Morris committed
121

122 123 124 125
/// @brief Holds Client identifier or client IPv4 address
///
/// This class is intended to be a generic IPv4 client identifier. It can hold
/// a client-id
126
class ClientId : public DUID {
127
public:
128 129 130 131 132 133 134

    /// @brief Minimum size of a client ID
    ///
    /// Excerpt from RFC2132, section 9.14.
    /// The code for this option is 61, and its minimum length is 2.
    static const size_t MIN_CLIENT_ID_LEN = 2;

Stephen Morris's avatar
Stephen Morris committed
135 136 137
    /// @brief Maximum size of a client ID
    ///
    /// This is the same as the maximum size of the underlying DUID.
138 139 140 141 142
    ///
    /// @note RFC 2131 does not specify an upper length of a client ID, the
    ///       value chosen here just being that of the underlying DUID.  For
    ///       some backend database, there may be a possible (minor)
    ///       performance enhancement if this were smaller.
143
    static const size_t MAX_CLIENT_ID_LEN = DUID::MAX_DUID_LEN;
144

Stephen Morris's avatar
Stephen Morris committed
145
    /// @brief Constructor based on vector<uint8_t>
146 147
    ClientId(const std::vector<uint8_t>& clientid);

Stephen Morris's avatar
Stephen Morris committed
148
    /// @brief Constructor based on array and array size
149
    ClientId(const uint8_t* clientid, size_t len);
150

151 152 153 154 155 156
    /// @brief Returns reference to the client-id data.
    ///
    /// @warning Since this function returns a reference to the vector (not a
    /// copy) the returned object must be used with caution because it remains
    /// valid only for the time period when the object which returned it is
    /// valid.
157 158
    ///
    /// @return A reference to a vector holding a client identifier.
159
    const std::vector<uint8_t>& getClientId() const;
160

161 162 163
    /// @brief Returns textual representation of a DUID (e.g. 00:01:02:03:ff)
    std::string toText() const;

164 165 166 167 168 169 170 171 172 173 174 175 176
    /// @brief Create client identifier from the textual format.
    ///
    /// This static function creates the instance of the @c ClientId from the
    /// textual format. Internally it calls @c DUID::fromText. The format of
    /// the input must match the format of the DUID in @c DUID::fromText.
    ///
    /// @param text Client identifier in the textual format.
    ///
    /// @return Pointer to the instance of the @c ClientId.
    /// @throw isc::BadValue if parsing the client identifier failed.
    /// @throw isc::OutOfRange if the client identifier is truncated.
    static ClientIdPtr fromText(const std::string& text);

Stephen Morris's avatar
Stephen Morris committed
177
    /// @brief Compares two client-ids for equality
178
    bool operator==(const ClientId& other) const;
179

Stephen Morris's avatar
Stephen Morris committed
180
    /// @brief Compares two client-ids for inequality
181
    bool operator!=(const ClientId& other) const;
182 183
};

184 185
}; // end of isc::dhcp namespace
}; // end of isc namespace
Tomek Mrugalski's avatar
Tomek Mrugalski committed
186 187

#endif /* DUID_H */