4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
6 // The contents of this file are subject to the Fraunhofer FOKUS Public License
7 // Version 1.0 (the "License"); you may not use this file except in compliance
8 // with the License. You may obtain a copy of the License at
9 // http://senf.berlios.de/license.html
11 // The Fraunhofer FOKUS Public License Version 1.0 is based on,
12 // but modifies the Mozilla Public License Version 1.1.
13 // See the full license text for the amendments.
15 // Software distributed under the License is distributed on an "AS IS" basis,
16 // WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
17 // for the specific language governing rights and limitations under the License.
19 // The Original Code is Fraunhofer FOKUS code.
21 // The Initial Developer of the Original Code is Fraunhofer-Gesellschaft e.V.
22 // (registered association), Hansastraße 27 c, 80686 Munich, Germany.
23 // All Rights Reserved.
26 // Stefan Bund <g0dil@berlios.de>
29 \brief INet6Address public header */
31 #ifndef HH_SENF_Socket_Protocols_INet_INet6Address_
32 #define HH_SENF_Socket_Protocols_INet_INet6Address_ 1
37 #include <netinet/in.h>
38 #include <boost/cstdint.hpp>
39 #include <boost/array.hpp>
40 #include <boost/operators.hpp>
41 #include <senf/Utils/safe_bool.hh>
42 #include <senf/Utils/Tags.hh>
43 #include "INet4Address.hh"
45 //#include "INet6Address.mpp"
46 #include "INet6Address.ih"
47 //-/////////////////////////////////////////////////////////////////////////////////////////////////
55 /** \brief INet6 network address
57 This implementation of an INet6 address is based strictly on
58 <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>: Internet Protocol
59 Version 6 (INet6) Addressing Architecture. This class provides accessors to all the
60 information fields defined in this document.
62 The INet6 addressing architecture however has several other components defined in other
63 RFC's. These RFC's should be implemented in additional modules:
65 \li <a href="http://tools.ietf.org/html/rfc4193">RFC 4193</a>:
66 Unique Local Addresses (ULA). Defines the fc00::/7 prefix
67 \li <a href="http://tools.ietf.org/html/rfc3306">RFC 3306</a>:
68 Unicast-Prefix-based INet6 Multicast Addresses. Defines the ff30::/12 prefix
69 \li <a href="http://tools.ietf.org/html/rfc3956">RFC 3956</a>:
70 Embedding the Rendezvous Point (RP) Address in an INet6 Multicast
71 Address. Defines the ff70::/12 prefix
72 \li <a href="http://tools.ietf.org/html/rfc3056">RFC 3056</a>:
73 Connection of INet6 Domains via INet4 Clouds. Defines 6to4 tunneling and the
75 \li <a href="http://tools.ietf.org/html/rfc3849">RFC 3849</a>:
76 INet6 Address Prefix Reserved for Documentation. Defines the 2001:db8::/32 prefix
78 Here an overview of well-known prefixes:
82 <tr><th>Prefix</th> <th>Description</th> <th>Definition</th> <th>Note</th></tr>
83 <tr><td><tt>::/96</tt></td> <td>INet4 compatible INet6 address</td> <td>RFC4291</td> <td>deprecated</td></tr>
84 <tr><td><tt>::ffff:0:0/96</tt></td> <td>INet6 mapped INet4 address</td> <td>RFC4291</td> <td></td></tr>
85 <tr><td><tt>2000::/3</tt></td> <td>Global unicast addresses</td> <td>RFC3587</td> <td>only noted, not defined</td></tr>
86 <tr><td><tt>2001:db8::/32</tt></td> <td>Documentation-only prefix</td> <td>RFC3849</td> <td></td></tr>
87 <tr><td><tt>2002::/16</tt></td> <td>6to4 addressing</td> <td>RFC3056</td> <td></td></tr>
88 <tr><td><tt>fc00::/7</tt></td> <td>ULA</td> <td>RFC4193</td> <td></td></tr>
89 <tr><td><tt>fe80::/64</tt></td> <td>Link-local addresses</td> <td>RFC4291</td> <td></td></tr>
90 <tr><td><tt>fec0::/10</tt></td> <td>Site-local addresses </td> <td>RFC4291</td> <td>deprecated</td></tr>
91 <tr><td><tt>ff00::/8</tt></td> <td>Multicast</td> <td>RFC4291</td> <td></td></tr>
92 <tr><td><tt>ff00::/12</tt></td> <td>Globally allocated multicast</td> <td>RFC4291</td> <td></td></tr>
93 <tr><td><tt>ff10::/12</tt></td> <td>Locally allocated multicast</td> <td>RFC4291</td> <td></td></tr>
94 <tr><td><tt>ff30::/12</tt></td> <td>Unicast prefix based multicast</td> <td>RFC3306</td> <td></td></tr>
95 <tr><td><tt>ff70::/12</tt></td> <td>Multicast address with embedded RP</td> <td>RFC3956</td> <td></td></tr>
99 The following statements all create the same INet6 address
100 <code>2001:db8::a0b1:1a2b:3dff:fe4e:5f00</code>:
102 // Used to construct constant INet6 addresses
103 INet6Address(0x2001u,0xDB8u,0x0u,0xA0B1u 0x1A2Bu,0x3DFFu,0xFE4Eu,0x5F00u)
105 // Construct INet6 address from it's string representation
106 INet6Address::from_string("2001:db8::a0b1:1a2b:3dff:fe4e:5f00")
108 // Construct an INet6 address from raw data. 'from_data' takes an arbitrary iterator (e.g. a
109 // pointer) as argument. Here we use a fixed array but normally you will need this to build
110 // an INet6 address in a packet parser
111 char rawBytes[] = { 0x20, 0x01, 0x0D, 0xB8, 0x00, 0x00, 0xA0, 0xB1,
112 0x1a, 0x2b, 0x3d, 0xff, 0xfe, 0x4e, 0xff, 0x00 };
113 INet6Address::from_data(rawBytes)
116 Since INet6Address class is based on \c boost::array and is built as a fixed-size sequence
117 of 16 bytes, you can access the raw data bytes of the address (in network byte order) using
118 \c begin(), \c end() or \c operator[]
120 INet6Address ina = ...;
121 Packet::iterator i = ...;
122 std::copy(ina.begin(), ina.end(), i); // Copies 16 bytes
125 \see CheckINet6Network \n INet6Network
128 \implementation We awkwardly need to use static named constructors (<tt>from_</tt> members)
129 instead of ordinarily overloaded constructors for one simple reason: <tt>char *</tt>
130 doubles as string literal and as arbitrary data iterator. The iterator constructor can
131 therefore not be distinguished from initialization with a string literal. Therefore we
132 need to disambiguate using the named constructors.
135 : public boost::array<boost::uint8_t,16>,
136 public comparable_safe_bool<INet6Address>
139 //-////////////////////////////////////////////////////////////////////////
142 static INet6Address const None; ///< The empty (::0) address
143 static INet6Address const Loopback; ///< The loopback (::1) address
144 static INet6Address const AllNodes; ///< The 'all nodes' link-local multicast address
145 static INet6Address const AllRouters; ///< The 'all routers' link-local multicast address
147 enum Resolve_t { ResolveINet6, ResolveINet4 };
149 /** \brief Possible scope values
151 List of all possible scope values. This list includes all scope values defined for
152 multicast addresses in <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>.
153 The values \ref LinkScope, \ref SiteScope and \ref GlobalScope are also used with
157 InterfaceScope = 1 /**< Interface only scope */
158 , LinkScope = 2 /**< Link-local scope */
159 , AdminScope = 4 /**< Administration defined local scope */
160 , SiteScope = 5 /**< Site-local scope */
161 , OrganizationScope = 8 /**< Scope covering multiple sites of an organization */
162 , GlobalScope = 14 /**< Global Internet scope */
164 , ReservedScope = 0 /**< Reserved scope value */
165 , UnassignedScope = 6 /**< Unassigned scope, may be defined locally */
168 //-////////////////////////////////////////////////////////////////////////
169 ///\name Structors and default members
172 explicit INet6Address(senf::NoInit_t); ///< Construct uninitialized (!) address
173 explicit INet6Address(boost::uint16_t a0=0u, boost::uint16_t a1=0u, boost::uint16_t a2=0u,
174 boost::uint16_t a3=0u, boost::uint16_t a4=0u, boost::uint16_t a5=0u,
175 boost::uint16_t a6=0u, boost::uint16_t a7=0u);
176 ///< Construct an address constant
178 static INet6Address from_in6addr(in6_addr const & in6addr); ///< Construct from std C struct
180 static INet6Address from_string(std::string const & s, Resolve_t resolve = ResolveINet6);
181 ///< Convert string to address
182 /**< This member will try to convert the given string into
183 an IP address. from_string() supports all standard IP
184 literal representations as well as hostnames.
185 \attention This call may block if \a s represents a
186 hostname which must be looked up via some network
187 protocol like DNS or NIS
188 \throws AddressSyntaxException if the address cannot be
189 converted for some reason
190 \throws UnknownHostnameException if the hostname cannot
192 \param[in] s Address literal or hostname
193 \param[in] resolve If this is set to \c ResolveINet4,
194 the call will additionally try to interpret \a s as
195 an INet4 address if no valid INet6 address is
196 found. The address will be returned as mapped INet6
199 template <class InputIterator>
200 static INet6Address from_data(InputIterator i);
201 ///< Construct address from 16 bytes of raw data
202 /**< from_data will build an address from 16 bytes of raw
203 data as accessed by the iterator. The data must be in
204 network byte order. */
206 static INet6Address from_inet4address(INet4Address const & addr);
207 ///< Construct an INet6-mapped INet4 address
208 /**< This will construct an address of the form
209 <tt>::FFFF::w.x.y.z</tt> where <tt>w.x.y.z</tt> is
210 the INet4Address value. This kind of address is called
211 an INet6-mapped INet4 address (see
212 <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>).
214 INet4 compatible INet6 addresses are not directly
215 supported, they are deprecated in the RFC. */
216 static INet6Address from_mac(MACAddress const & mac);
217 ///< Construct a link-local INet6 address
218 /**< This will construct a link local address of the form
219 <tt>fe80::xxxx:xxff:fexx:xxxx</tt>. */
221 static INet6Address from_eui64(EUI64 const & eui);
222 ///< Construct link-local INet6 address
223 /**< This will construct a link local address of the form
224 <tt>fe80::xxxx:xxxx:xxxx:xxxx</tt>. */
226 in6_addr toin6_addr() const; ///< get the linux in6_addr struct (convenience only)
229 //-////////////////////////////////////////////////////////////////////////
233 INet6Network network() const; ///< Return <tt>/64</tt> Network of this address
234 bool hasEUI64() const; ///< \c true, if address is based on an EUID-64
235 EUI64 id() const; ///< Return interface id (EUID-64)
236 bool universalId() const; ///< \c true, if the id() is universally assigned
237 bool groupId() const; ///< \c true, if the id()'s \a group bit is set
239 bool unicast() const; ///< \c true, if address is unicast
240 bool multicast() const; ///< \c true, if address is multicast
241 /**< To support a linux specific extension, INet4 multicast
242 addressed mapped to INet6 are also interpreted as
243 multicast addresses. This is NOT part of the standard,
244 however the standard officially only allows unicast v4
245 addresses to be mapped to v6 so this does not collide
246 with any standard conforming use. */
248 ScopeId scope() const; ///< Get address's scope
249 /**< The scope of an address is one of the \ref ScopeId
250 values. We need to differentiate between unicast and
251 multicast addresses: unicast addresses only have local,
252 site or global scope (where site scope is deprecated),
253 multicast address can have a number of scope values of
254 which local, site and global are a few. See the \ref
255 ScopeId enumerators. */
256 bool globalScope() const; ///< \c true, if address is global unicast or multicast
257 bool linkScope() const; ///< \c true, if address is link-local unicast or multicast
259 INet4Address inet4address() const; ///< Return embedded INet4 address
260 /**< Returns the INet4 address embedded within an INet4
261 compatible or INet4 mapped unicast address. This address
262 is given by the last 32 bits of the INet6 address. \par
263 The value returned is only a valid INet4 address if
264 either inet4Compatible() or inet4Mapped() return \c
266 bool inet4Compatible() const; ///< \c true, if address is INet4 compatible
267 /**< INet4 compatible INet6 addresses are deprecated. */
268 bool inet4Mapped() const; ///< \c true, if address is INet4 mapped
270 bool globalMulticastAddr() const; ///< \c true, if T bit is \e not set
271 /**< Any multicast address with a cleared T bit must be
272 globally assigned. See
273 <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>. */
274 bool prefixMulticastAddr() const; ///< \c true, if P bit is set
275 /**< In <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>,
276 the P bit is specified as defining a
277 unicast prefix based multicast address. See
278 <a href="http://tools.ietf.org/html/rfc3306">RFC 3306</a>. */
279 bool embeddedRpAddr() const; ///< \c true, if R bit is set
280 /**< In <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>,
281 the R bit is specified as defining a multicast address
282 with embedded rendezvous point. See
283 <a href="http://tools.ietf.org/html/rfc3956">RFC 3956</a>. */
285 bool boolean_test() const; ///< \c true, if address != '::' (None)
291 void network(boost::uint64_t net); ///< Set network part of address
292 void id(boost::uint64_t id); ///< Set interface id part of address
298 /** \brief Output INet6Address instance as it's string representation
299 \related INet6Address
301 std::ostream & operator<<(std::ostream & os, INet6Address const & addr);
303 /** \brief Try to initialize INet6Address instance from a string representation
305 sets std::ios::failbit on the stream if an error occurred
306 \see INet6Address from_string()
307 \related INet6Address
309 std::istream & operator>>(std::istream & is, INet6Address & addr);
311 /** \brief Check INet6Address against a fixed network prefix
313 This helper allows to easily and efficiently check an INet6Address against an arbitrary but
314 constant network prefix. It takes from 1 to 8 arguments for the network address and an
315 additional last argument providing the prefix length. So
318 <tt>senf::CheckINet6Network<</tt> <i>addr_1</i> <tt>,</tt> <i>addr_2</i> <tt>,</tt>
319 ... <tt>,</tt> <i>prefix_len</i> <tt>></tt>
321 represents the network
324 <i>addr_1</i> <tt>:</tt> <i>addr_2</i> <tt>:</tt> ... <tt>::/</tt> <i>prefix_len</i> .
326 The class exposes a single static member <tt>match(</tt> <i>addr</i> <tt>)</tt> which
327 matches the INet6Address \a addr against the prefix:
330 if (senf::CheckINet6Network<0x2000u,0xDB8u,32u>::match(addr)) {
331 // 'addr' is within in the 2001:db8::/32 documentation-only network
336 The code generated by this call is highly optimized and probably as efficient as it can get.
338 template <unsigned a0, unsigned a1, unsigned a2=0u, unsigned a3=0u, unsigned a4=0u,
339 unsigned a5=0u, unsigned a6=0u, unsigned a7=0u, unsigned a8=0u>
340 struct CheckINet6Network
342 : public detail::CheckINet6Network_impl<a0,a1,a2,a3,a4,a5,a6,a7,a8>
346 /** \brief INet6 network prefix
348 This class represents an INet6 network prefix in CIDR notation.
351 : public boost::equality_comparable<INet6Network>,
352 public comparable_safe_bool<INet6Network>
355 //-////////////////////////////////////////////////////////////////////////
356 ///\name Structors and default members
359 INet6Network(); ///< Construct empty (::/0) network
360 INet6Network(INet6Address const & address, unsigned prefix_len);
361 ///< Construct network from given address and prefix length
362 explicit INet6Network(std::string const & s); ///< Construct network from CIDR notation
365 //-////////////////////////////////////////////////////////////////////////
367 INet6Address const & address() const; ///< Get the network address
368 unsigned prefix_len() const; ///< Get the network prefix length
370 bool boolean_test() const; ///< \c true, if INet6Network is non-empty
371 bool operator==(INet6Network const & other) const;
372 ///< Compare two networks for equality
374 bool match(INet6Address const & addr) const; ///< \c true, if the network includes \a addr
375 bool match(INet6Network const & net) const; ///< \c true, if the network includes \a net
376 /**< The is true, if \a net is sub-network (or the same as)
378 INet6Address host(boost::uint64_t id); ///< Return the host with the given id
379 /**< Returns the host with the given number within the
380 network. This call replaces the lower 64 bits of the
381 network address with the given id. */
383 INet6Network subnet(boost::uint64_t net, unsigned prefix_len);
384 ///< Return the given subnet of \c this
385 /**< The returned INet6Network will be a subnet of \c this
386 with the given network number. The network number is
387 comprised by the bits above \a prefix_len:
389 INet6Network("2001:db8::/32").subnet(0x12u,40u) == INet6Network("2001:db8:1200::/40")
390 INet6Network("2001:db8:1200::/40").subnet(0x2345,64u) == INet6Network("2001:db8:1200:2345::/64")
392 \param[in] net network number
393 \param[in] prefix_len length of subnet prefix */
398 unsigned prefix_len_;
399 INet6Address address_;
401 unsigned prefix_len_checked(unsigned prefix_len) const;
404 /** \brief Output INet6Network instance as it's string representation
405 \related INet6Network
407 std::ostream & operator<<(std::ostream & os, INet6Network const & addr);
409 /** \brief Try to initialize INet6Network instance from a string representation
411 sets std::ios::failbit on the stream if an error occurred
412 \related INet6Network
414 std::istream & operator>>(std::istream & is, INet6Network & addr);
417 //-/////////////////////////////////////////////////////////////////////////////////////////////////
418 #include "INet6Address.cci"
419 #include "INet6Address.ct"
420 #include "INet6Address.cti"
427 // comment-column: 40
428 // c-file-style: "senf"
429 // indent-tabs-mode: nil
430 // ispell-local-dictionary: "american"
431 // compile-command: "scons -u test"