Socket/Protocols/INet/INet6Address.hh

   1 // $Id$
   2 //
   3 // Copyright (C) 2007
   4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
   5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
   6 //     Stefan Bund <g0dil@berlios.de>
   7 //
   8 // This program is free software; you can redistribute it and/or modify
   9 // it under the terms of the GNU General Public License as published by
  10 // the Free Software Foundation; either version 2 of the License, or
  11 // (at your option) any later version.
  12 //
  13 // This program is distributed in the hope that it will be useful,
  14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 // GNU General Public License for more details.
  17 //
  18 // You should have received a copy of the GNU General Public License
  19 // along with this program; if not, write to the
  20 // Free Software Foundation, Inc.,
  21 // 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23 /** \file
  24     \brief INet6Address public header */
  25
  26 #ifndef HH_INet6Address_
  27 #define HH_INet6Address_ 1
  28
  29 // Custom includes
  30 #include <iostream>
  31 #include <string>
  32 #include <netinet/in.h>
  33 #include <boost/cstdint.hpp>
  34 #include <boost/array.hpp>
  35 #include <boost/operators.hpp>
  36 #include "../../../Utils/safe_bool.hh"
  37 #include "../../../Utils/Tags.hh"
  38 #include "INet4Address.hh"
  39 #include "../AddressExceptions.hh"
  40
  41 //#include "INet6Address.mpp"
  42 #include "INet6Address.ih"
  43 ///////////////////////////////hh.p////////////////////////////////////////
  44
  45 namespace senf {
  46
  47     /** \brief INet6 network address
  48
  49         This implementation of an INet6 address is based strictly on
  50         <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>: Internet Protocol
  51         Version 6 (INet6) Addressing Architecture. This class provides accessors to all the
  52         information fields defined in this document.
  53
  54         The INet6 addressing architecture however has several other components defined in other
  55         RFC's. These RFC's should be implemented in additional modules:
  56
  57         \li <a href="http://tools.ietf.org/html/rfc4193">RFC 4193</a>:
  58             Unique Local Addresses (ULA). Defines the fc00::/7 prefix
  59         \li <a href="http://tools.ietf.org/html/rfc3306">RFC 3306</a>:
  60             Unicast-Prefix-based INet6 Multicast Addresses. Defines the ff30::/12 prefix
  61         \li <a href="http://tools.ietf.org/html/rfc3956">RFC 3956</a>:
  62             Embedding the Rendezvous Point (RP) Address in an INet6 Multicast
  63             Address. Defines the ff70::/12 prefix
  64         \li <a href="http://tools.ietf.org/html/rfc3056">RFC 3056</a>:
  65             Connection of INet6 Domains via INet4 Clouds. Defines 6to4 tunneling and the
  66             2002::/16 prefix
  67         \li <a href="http://tools.ietf.org/html/rfc3849">RFC 3849</a>:
  68             INet6 Address Prefix Reserved for Documentation. Defines the 2001:db8::/32 prefix
  69
  70         Here an overview of well-known prefixes:
  71
  72         \htmlonly
  73         <table class="senf">
  74         <tr><th>Prefix</th>                  <th>Description</th>                         <th>Definition</th>  <th>Note</th></tr>
  75         <tr><td><tt>::/96</tt></td>          <td>INet4 compatible INet6 address</td>      <td>RFC4291</td>     <td>deprecated</td></tr>
  76         <tr><td><tt>::ffff:0:0/96</tt></td>  <td>INet6 mapped INet4 address</td>          <td>RFC4291</td>     <td></td></tr>
  77         <tr><td><tt>2000::/3</tt></td>       <td>Global unicast addresses</td>            <td>RFC3587</td>     <td>only noted, not defined</td></tr>
  78         <tr><td><tt>2001:db8::/32</tt></td>  <td>Documentation-only prefix</td>           <td>RFC3849</td>     <td></td></tr>
  79         <tr><td><tt>2002::/16</tt></td>      <td>6to4 addressing</td>                     <td>RFC3056</td>     <td></td></tr>
  80         <tr><td><tt>fc00::/7</tt></td>       <td>ULA</td>                                 <td>RFC4193</td>     <td></td></tr>
  81         <tr><td><tt>fe80::/64</tt></td>      <td>Link-local addresses</td>                <td>RFC4291</td>     <td></td></tr>
  82         <tr><td><tt>fec0::/10</tt></td>      <td>Site-local addresses </td>               <td>RFC4291</td>     <td>deprecated</td></tr>
  83         <tr><td><tt>ff00::/8</tt></td>       <td>Multicast</td>                           <td>RFC4291</td>     <td></td></tr>
  84         <tr><td><tt>ff00::/12</tt></td>      <td>Globally allocated multicast</td>        <td>RFC4291</td>     <td></td></tr>
  85         <tr><td><tt>ff10::/12</tt></td>      <td>Locally allocated multicast</td>         <td>RFC4291</td>     <td></td></tr>
  86         <tr><td><tt>ff30::/12</tt></td>      <td>Unicast prefic based multicast</td>      <td>RFC3306</td>     <td></td></tr>
  87         <tr><td><tt>ff70::/12</tt></td>      <td>Multicast address with embedded RP</td>  <td>RFC3956</td>     <td></td></tr>
  88         </table>
  89         \endhtmlonly
  90
  91         The following statements all create the same INet6 address
  92         <code>2001:db8::a0b1:1a2b:3dff:fe4e:5f00</code>:
  93         \code
  94         // Used to construct constant INet6 addresses
  95         INet6Address(0x2001u,0xDB8u,0x0u,0xA0B1u 0x1A2Bu,0x3DFFu,0xFE4Eu,0x5F00u)
  96
  97         // Construct INet6 address from it's string representation
  98         INet6Address::from_string("2001:db8::a0b1:1a2b:3dff:fe4e:5f00")
  99
 100         // Construct an INet6 address from raw data. 'from_data' takes an arbitrary iterator (e.g. a
 101         // pointer) as argument. Here we use a fixed array but normally you will need this to build
 102         // an INet6 address in a packet parser
 103         char rawBytes[] = { 0x20, 0x01, 0x0D, 0xB8, 0x00, 0x00, 0xA0, 0xB1,
 104                             0x1a, 0x2b, 0x3d, 0xff, 0xfe, 0x4e, 0xff, 0x00 };
 105         INet6Address::from_data(rawBytes)
 106         \endcode
 107
 108         Since INet6Address class is based on \c boost::array and is built as a fixed-size sequence
 109         of 16 bytes, you can access the raw data bytes of the address (in network byte order) using
 110         \c begin(), \c end() or \c operator[]
 111         \code
 112         INet6Address ina = ...;
 113         Packet::iterator i = ...;
 114         std::copy(ina.begin(), ina.end(), i); // Copies 16 bytes
 115         \endcode
 116
 117         \see CheckINet6Network \n INet6Network
 118         \ingroup addr_group
 119
 120         \implementation We awkwardly need to use static named constructors (<tt>from_</tt> members)
 121             instead of ordinarily overloaded constructors for one simple reason: <tt>char *</tt>
 122             doubles as string literal and as arbitrary data iterator. The iterator constructor can
 123             therefore not be distinguished from initialization with a string literal. Therefore we
 124             need to disambiguate using the named constructors.
 125      */
 126     class INet6Address
 127         : public boost::array<boost::uint8_t,16>,
 128           public comparable_safe_bool<INet6Address>
 129     {
 130     public:
 131         ///////////////////////////////////////////////////////////////////////////
 132         // Types
 133
 134         static INet6Address const None;        ///< The empty (::0) address
 135         static INet6Address const Loopback;    ///< The loopback (::1) address
 136         static INet6Address const AllNodes;    ///< The 'all nodes' link-local multicast address
 137         static INet6Address const AllRouters;  ///< The 'all routers' link-local multicast address
 138
 139         enum Resolve_t { ResolveINet6, ResolveINet4 };
 140
 141         /** \brief Possible scope values
 142
 143             List of all possible scope values. This list includes all scope values defined for
 144             multicast addresses in <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>.
 145             The values \ref LinkScope, \ref SiteScope and \ref GlobalScope are also used with
 146             unicast addresses.
 147          */
 148         enum ScopeId {
 149               InterfaceScope    =  1    /**< Interface only scope */
 150             , LinkScope         =  2    /**< Link-local scope */
 151             , AdminScope        =  4    /**< Administration defined local scope */
 152             , SiteScope         =  5    /**< Site-local scope */
 153             , OrganizationScope =  8    /**< Scope covering multiple sites of an organization */
 154             , GlobalScope       = 14    /**< Global Internet scope */
 155
 156             , ReservedScope     =  0    /**< Reserved scope value */
 157             , UnassignedScope   =  6    /**< Unassigned scope, may be defined locally */
 158         };
 159
 160         ///////////////////////////////////////////////////////////////////////////
 161         ///\name Structors and default members
 162         ///@{
 163
 164         explicit INet6Address(senf::NoInit_t); ///< Construct uninitialized (!) address
 165         INet6Address(boost::uint16_t a0=0u, boost::uint16_t a1=0u, boost::uint16_t a2=0u,
 166                      boost::uint16_t a3=0u, boost::uint16_t a4=0u, boost::uint16_t a5=0u,
 167                      boost::uint16_t a6=0u, boost::uint16_t a7=0u);
 168                                         ///< Construct an address constant
 169
 170         INet6Address(in6_addr in6addr); ///< Construct from std c struct
 171
 172         static INet6Address from_string(std::string const & s, Resolve_t resolve = ResolveINet6);
 173                                         ///< Convert string to address
 174                                         /**< This member will try to convert the given string into
 175                                              an IP address. from_string() supports all standard IP
 176                                              literal representations as well es hostnames.
 177                                              \attention This call may block if \a s represents a
 178                                                  hostname which must be looked up via some network
 179                                                  protocol like DNS or NIS
 180                                              \throws AddressSyntaxException if the address cannot be
 181                                                  converted for some reason
 182                                              \param[in] s Address literal or hostname
 183                                              \param[in] resolve If this is set to \c ResolveINet4,
 184                                                  the call will additionally try to interpret \a s as
 185                                                  an INet4 address if no valid INet6 address is
 186                                                  found. The address will be returned as mapped INet6
 187                                                  address. */
 188
 189         template <class InputIterator>
 190         static INet6Address from_data(InputIterator i);
 191                                         ///< Construct address from 16 bytes of raw data
 192                                         /**< from_data will build an address from 16 bytes of raw
 193                                              data as accessed by the iterator. The data must be in
 194                                              network byte order. */
 195
 196         static INet6Address from_inet4address(INet4Address addr);
 197                                         ///< Construct an INet6-mapped INet4 address
 198                                         /**< This will construct an address of the form
 199                                              <tt>::FFFF::w.x.y.z</tt> where <tt>w.x.y.z</tt> is
 200                                              the INet4Address value. This kind of address is called
 201                                              an INet6-mapped INet4 address (see
 202                                              <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>).
 203                                              \par
 204                                              INet4 compatible INet6 addresses are not directly
 205                                              supported, they are deprecated in the RFC. */
 206         ///@}
 207         ///////////////////////////////////////////////////////////////////////////
 208         ///\name Accessors
 209         ///@{
 210
 211         boost::uint64_t network() const; ///< Return 64bit network part
 212         bool hasEuid64() const;         ///< \c true, if address is based on an EUID-64
 213         boost::uint64_t id() const;     ///< Return interface id (EUID-64)
 214         bool universalId() const;       ///< \c true, if the id() is universally assigned
 215         bool groupId() const;           ///< \c true, if the id()'s \a group bit is set
 216
 217         bool unicast() const;           ///< \c true, if address is unicast
 218         bool multicast() const;         ///< \c true, if address is multicast
 219
 220         ScopeId scope() const;          ///< Get address's scope
 221                                         /**< The scope of an address is one of the \ref ScopeId
 222                                              values. We need to differentiate between unicast and
 223                                              multicast addresses: unicast addresses only have local,
 224                                              site or global scope (where site scope is deprecated),
 225                                              multicast address can have a number of scope values of
 226                                              which local, site and global are a few. See the \ref
 227                                              ScopeId enumerators. */
 228         bool globalScope() const;       ///< \c true, if address is global unicast or multicast
 229         bool linkScope() const;         ///< \c true, if address is link-local unicast or multicast
 230
 231         INet4Address inet4address() const; ///< Return embedded INet4 address
 232                                         /**< Returns the INet4 address embedded within an INet4
 233                                              compatible or INet4 mapped unicast address. This address
 234                                              is given by the last 32 bits of the INet6 address. \par
 235                                              The value returned is only a valid INet4 address if
 236                                              either inet4Compatible() or inet4Mapped() return \c
 237                                              true. */
 238         bool inet4Compatible() const;   ///< \c true, if address is INet4 compatible
 239                                         /**< INet4 compatible INet6 addresses are deprecated. */
 240         bool inet4Mapped() const;       ///< \c true, if address is INet4 mapped
 241
 242         bool globalMulticastAddr() const; ///< \c true, if T bit is \e not set
 243                                         /**< Any multicast address with a cleared T bit must be
 244                                              globally assigned. See
 245                                              <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>. */
 246         bool prefixMulticastAddr() const; ///< \c true, if P bit is set
 247                                         /**< In <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>,
 248                                              the P bit is specified as defining a
 249                                              unicast prefix based multicast address. See
 250                                              <a href="http://tools.ietf.org/html/rfc3306">RFC 3306</a>. */
 251         bool embeddedRpAddr() const;    ///< \c true, if R bit is set
 252                                         /**< In <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>,
 253                                              the R bit is specified as defining a multicast address
 254                                              with embedded rendezvous point. See
 255                                              <a href="http://tools.ietf.org/html/rfc3956">RFC 3956</a>. */
 256
 257         bool boolean_test() const;      ///< \c true, if address != '::' (None)
 258
 259         ///@}
 260         ///\name Mutators
 261         ///@{
 262
 263         void network(boost::uint64_t net); ///< Set network part of address
 264         void id(boost::uint64_t id);    ///< Set interface id part of address
 265
 266         ///@}
 267
 268     };
 269
 270     /** \brief Output INet6Address instance as it's string representation
 271         \related INet6Address
 272      */
 273     std::ostream & operator<<(std::ostream & os, INet6Address const & addr);
 274
 275     /** \brief Check INet6Address against a fixed network prefix
 276
 277         This helper allows to easily and efficiently check an INet6Address against an arbitrary but
 278         constant network prefix. It takes from 1 to 8 arguments for the network address and an
 279         additional last argument providing the prefix length. So
 280
 281         \par ""
 282             <tt>senf::CheckINet6Network<</tt> <i>addr_1</i> <tt>,</tt> <i>addr_2</i> <tt>,</tt>
 283             ... <tt>,</tt> <i>prefix_len</i> <tt>></tt>
 284
 285         represents the network
 286
 287         \par ""
 288             <i>addr_1</i> <tt>:</tt> <i>addr_2</i> <tt>:</tt> ... <tt>::/</tt> <i>prefix_len</i> .
 289
 290         The class exposes a single static member <tt>match(</tt> <i>addr</i> <tt>)</tt> which
 291         matches the INet6Address \a addr against the prefix:
 292
 293         \code
 294         if (senf::CheckINet6Network<0x2000u,0xDB8u,32u>::match(addr)) {
 295             // 'addr' is within in the 2001:db8::/32 documentation-only network
 296             ...
 297         }
 298         \endcode
 299
 300         The code generated by this call is highly optimized and probably as efficient as it can get.
 301      */
 302     template <unsigned a0, unsigned a1, unsigned a2=0u, unsigned a3=0u, unsigned a4=0u,
 303               unsigned a5=0u, unsigned a6=0u, unsigned a7=0u, unsigned a8=0u>
 304     struct CheckINet6Network
 305         : public detail::CheckINet6Network_impl<a0,a1,a2,a3,a4,a5,a6,a7,a8>
 306     {};
 307
 308     /** \brief INet6 network prefix
 309
 310         This class represents an INet6 network prefix in CIDR notation.
 311       */
 312     class INet6Network
 313         : public boost::equality_comparable<INet6Network>,
 314           public comparable_safe_bool<INet6Network>
 315     {
 316     public:
 317         ///////////////////////////////////////////////////////////////////////////
 318         ///\name Structors and default members
 319         ///@{
 320
 321         INet6Network();                 ///< Construct empty (::/0) network
 322         INet6Network(INet6Address address, unsigned prefix_len);
 323                                         ///< Construct network from given address and prefix length
 324         explicit INet6Network(std::string s); ///< Construct network from CIDR notation
 325
 326         ///@}
 327         ///////////////////////////////////////////////////////////////////////////
 328
 329         INet6Address const & address() const; ///< Get the network address
 330         unsigned prefix_len() const;    ///< Get the network prefix length
 331
 332         bool boolean_test() const;      ///< \c true, if INet6Network is non-empty
 333         bool operator==(INet6Network const & other) const;
 334                                         ///< Compare two networks for equality
 335
 336         bool match(INet6Address addr) const; ///< \c true, if the network includes \a addr
 337         bool match(INet6Network net) const; ///< \c true, if the network includes \a net
 338                                         /**< The is true, if \a net is sub-network (or the same as)
 339                                              \c this. */
 340         INet6Address host(boost::uint64_t id); ///< Return the host with the given id
 341                                         /**< Returns the host with the given number within the
 342                                              network. This call replaces the lower 64 bits of the
 343                                              network address with the given id. */
 344
 345         INet6Network subnet(boost::uint64_t net, unsigned prefix_len);
 346                                         ///< Return the given subnet of \c this
 347                                         /**< The returned INet6Network will be a subnet of \c this
 348                                              with the given network number. The network number is
 349                                              comprised by the bits above \a prefix_len:
 350                                              \code
 351                                              INet6Network("2001:db8::/32").subnet(0x12u,40u) == INet6Network("2001:db8:1200::/40")
 352                                              INet6Network("2001:db8:1200::/40").subnet(0x2345,64u) == INet6Network("2001:db8:1200:2345::/64")
 353                                              \endcode
 354                                              \param[in] net network number
 355                                              \param[in] prefix_len length of subnet prefix */
 356
 357     protected:
 358
 359     private:
 360         unsigned prefix_len_;
 361         INet6Address address_;
 362     };
 363
 364     /** \brief Output INet6Network instance as it's string representation
 365         \related INet6Network
 366      */
 367     std::ostream & operator<<(std::ostream & os, INet6Network const & addr);
 368 }
 369
 370 ///////////////////////////////hh.e////////////////////////////////////////
 371 #include "INet6Address.cci"
 372 #include "INet6Address.ct"
 373 #include "INet6Address.cti"
 374 #endif
 375
 376 \f
 377 // Local Variables:
 378 // mode: c++
 379 // fill-column: 100
 380 // comment-column: 40
 381 // c-file-style: "senf"
 382 // indent-tabs-mode: nil
 383 // ispell-local-dictionary: "american"
 384 // compile-command: "scons -u test"
 385 // End: