4 // Fraunhofer Institute for Open Communication Systems (FOKUS)
5 // Competence Center NETwork research (NET), St. Augustin, GERMANY
6 // Stefan Bund <g0dil@berlios.de>
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.
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.
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.
24 \brief INet6Address public header */
26 #ifndef HH_SENF_Socket_Protocols_INet_INet6Address_
27 #define HH_SENF_Socket_Protocols_INet_INet6Address_ 1
32 #include <netinet/in.h>
33 #include <boost/cstdint.hpp>
34 #include <boost/array.hpp>
35 #include <boost/operators.hpp>
36 #include <senf/Utils/safe_bool.hh>
37 #include <senf/Utils/Tags.hh>
38 #include "INet4Address.hh"
39 #include <senf/Socket/Protocols/Raw/MACAddress.hh>
40 #include <senf/Socket/Protocols/Raw/EUI64.hh>
42 //#include "INet6Address.mpp"
43 #include "INet6Address.ih"
44 ///////////////////////////////hh.p////////////////////////////////////////
50 /** \brief INet6 network address
52 This implementation of an INet6 address is based strictly on
53 <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>: Internet Protocol
54 Version 6 (INet6) Addressing Architecture. This class provides accessors to all the
55 information fields defined in this document.
57 The INet6 addressing architecture however has several other components defined in other
58 RFC's. These RFC's should be implemented in additional modules:
60 \li <a href="http://tools.ietf.org/html/rfc4193">RFC 4193</a>:
61 Unique Local Addresses (ULA). Defines the fc00::/7 prefix
62 \li <a href="http://tools.ietf.org/html/rfc3306">RFC 3306</a>:
63 Unicast-Prefix-based INet6 Multicast Addresses. Defines the ff30::/12 prefix
64 \li <a href="http://tools.ietf.org/html/rfc3956">RFC 3956</a>:
65 Embedding the Rendezvous Point (RP) Address in an INet6 Multicast
66 Address. Defines the ff70::/12 prefix
67 \li <a href="http://tools.ietf.org/html/rfc3056">RFC 3056</a>:
68 Connection of INet6 Domains via INet4 Clouds. Defines 6to4 tunneling and the
70 \li <a href="http://tools.ietf.org/html/rfc3849">RFC 3849</a>:
71 INet6 Address Prefix Reserved for Documentation. Defines the 2001:db8::/32 prefix
73 Here an overview of well-known prefixes:
77 <tr><th>Prefix</th> <th>Description</th> <th>Definition</th> <th>Note</th></tr>
78 <tr><td><tt>::/96</tt></td> <td>INet4 compatible INet6 address</td> <td>RFC4291</td> <td>deprecated</td></tr>
79 <tr><td><tt>::ffff:0:0/96</tt></td> <td>INet6 mapped INet4 address</td> <td>RFC4291</td> <td></td></tr>
80 <tr><td><tt>2000::/3</tt></td> <td>Global unicast addresses</td> <td>RFC3587</td> <td>only noted, not defined</td></tr>
81 <tr><td><tt>2001:db8::/32</tt></td> <td>Documentation-only prefix</td> <td>RFC3849</td> <td></td></tr>
82 <tr><td><tt>2002::/16</tt></td> <td>6to4 addressing</td> <td>RFC3056</td> <td></td></tr>
83 <tr><td><tt>fc00::/7</tt></td> <td>ULA</td> <td>RFC4193</td> <td></td></tr>
84 <tr><td><tt>fe80::/64</tt></td> <td>Link-local addresses</td> <td>RFC4291</td> <td></td></tr>
85 <tr><td><tt>fec0::/10</tt></td> <td>Site-local addresses </td> <td>RFC4291</td> <td>deprecated</td></tr>
86 <tr><td><tt>ff00::/8</tt></td> <td>Multicast</td> <td>RFC4291</td> <td></td></tr>
87 <tr><td><tt>ff00::/12</tt></td> <td>Globally allocated multicast</td> <td>RFC4291</td> <td></td></tr>
88 <tr><td><tt>ff10::/12</tt></td> <td>Locally allocated multicast</td> <td>RFC4291</td> <td></td></tr>
89 <tr><td><tt>ff30::/12</tt></td> <td>Unicast prefic based multicast</td> <td>RFC3306</td> <td></td></tr>
90 <tr><td><tt>ff70::/12</tt></td> <td>Multicast address with embedded RP</td> <td>RFC3956</td> <td></td></tr>
94 The following statements all create the same INet6 address
95 <code>2001:db8::a0b1:1a2b:3dff:fe4e:5f00</code>:
97 // Used to construct constant INet6 addresses
98 INet6Address(0x2001u,0xDB8u,0x0u,0xA0B1u 0x1A2Bu,0x3DFFu,0xFE4Eu,0x5F00u)
100 // Construct INet6 address from it's string representation
101 INet6Address::from_string("2001:db8::a0b1:1a2b:3dff:fe4e:5f00")
103 // Construct an INet6 address from raw data. 'from_data' takes an arbitrary iterator (e.g. a
104 // pointer) as argument. Here we use a fixed array but normally you will need this to build
105 // an INet6 address in a packet parser
106 char rawBytes[] = { 0x20, 0x01, 0x0D, 0xB8, 0x00, 0x00, 0xA0, 0xB1,
107 0x1a, 0x2b, 0x3d, 0xff, 0xfe, 0x4e, 0xff, 0x00 };
108 INet6Address::from_data(rawBytes)
111 Since INet6Address class is based on \c boost::array and is built as a fixed-size sequence
112 of 16 bytes, you can access the raw data bytes of the address (in network byte order) using
113 \c begin(), \c end() or \c operator[]
115 INet6Address ina = ...;
116 Packet::iterator i = ...;
117 std::copy(ina.begin(), ina.end(), i); // Copies 16 bytes
120 \see CheckINet6Network \n INet6Network
123 \implementation We awkwardly need to use static named constructors (<tt>from_</tt> members)
124 instead of ordinarily overloaded constructors for one simple reason: <tt>char *</tt>
125 doubles as string literal and as arbitrary data iterator. The iterator constructor can
126 therefore not be distinguished from initialization with a string literal. Therefore we
127 need to disambiguate using the named constructors.
130 : public boost::array<boost::uint8_t,16>,
131 public comparable_safe_bool<INet6Address>
134 ///////////////////////////////////////////////////////////////////////////
137 static INet6Address const None; ///< The empty (::0) address
138 static INet6Address const Loopback; ///< The loopback (::1) address
139 static INet6Address const AllNodes; ///< The 'all nodes' link-local multicast address
140 static INet6Address const AllRouters; ///< The 'all routers' link-local multicast address
142 enum Resolve_t { ResolveINet6, ResolveINet4 };
144 /** \brief Possible scope values
146 List of all possible scope values. This list includes all scope values defined for
147 multicast addresses in <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>.
148 The values \ref LinkScope, \ref SiteScope and \ref GlobalScope are also used with
152 InterfaceScope = 1 /**< Interface only scope */
153 , LinkScope = 2 /**< Link-local scope */
154 , AdminScope = 4 /**< Administration defined local scope */
155 , SiteScope = 5 /**< Site-local scope */
156 , OrganizationScope = 8 /**< Scope covering multiple sites of an organization */
157 , GlobalScope = 14 /**< Global Internet scope */
159 , ReservedScope = 0 /**< Reserved scope value */
160 , UnassignedScope = 6 /**< Unassigned scope, may be defined locally */
163 ///////////////////////////////////////////////////////////////////////////
164 ///\name Structors and default members
167 explicit INet6Address(senf::NoInit_t); ///< Construct uninitialized (!) address
168 explicit INet6Address(boost::uint16_t a0=0u, boost::uint16_t a1=0u, boost::uint16_t a2=0u,
169 boost::uint16_t a3=0u, boost::uint16_t a4=0u, boost::uint16_t a5=0u,
170 boost::uint16_t a6=0u, boost::uint16_t a7=0u);
171 ///< Construct an address constant
173 static INet6Address from_in6addr(in6_addr const & in6addr); ///< Construct from std C struct
175 static INet6Address from_string(std::string const & s, Resolve_t resolve = ResolveINet6);
176 ///< Convert string to address
177 /**< This member will try to convert the given string into
178 an IP address. from_string() supports all standard IP
179 literal representations as well es hostnames.
180 \attention This call may block if \a s represents a
181 hostname which must be looked up via some network
182 protocol like DNS or NIS
183 \throws AddressSyntaxException if the address cannot be
184 converted for some reason
185 \param[in] s Address literal or hostname
186 \param[in] resolve If this is set to \c ResolveINet4,
187 the call will additionally try to interpret \a s as
188 an INet4 address if no valid INet6 address is
189 found. The address will be returned as mapped INet6
192 template <class InputIterator>
193 static INet6Address from_data(InputIterator i);
194 ///< Construct address from 16 bytes of raw data
195 /**< from_data will build an address from 16 bytes of raw
196 data as accessed by the iterator. The data must be in
197 network byte order. */
199 static INet6Address from_inet4address(INet4Address const & addr);
200 ///< Construct an INet6-mapped INet4 address
201 /**< This will construct an address of the form
202 <tt>::FFFF::w.x.y.z</tt> where <tt>w.x.y.z</tt> is
203 the INet4Address value. This kind of address is called
204 an INet6-mapped INet4 address (see
205 <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>).
207 INet4 compatible INet6 addresses are not directly
208 supported, they are deprecated in the RFC. */
209 static INet6Address from_mac(senf::MACAddress const & mac);
210 ///< Construct a link-local INet6 address
211 /**< This will construct a link local address of the form
212 <tt>fe80::xxxx:xxff:fexx:xxxx</tt>. */
214 static INet6Address from_eui64(senf::EUI64 const & eui);
215 ///< Construct link-local INet6 address
216 /**< This will construct a link local address of the form
217 <tt>fe80::xxxx:xxxx:xxxx:xxxx</tt>. */
219 in6_addr toin6_addr() const; ///< get the linux in6_addr struct (convinience only)
222 ///////////////////////////////////////////////////////////////////////////
226 INet6Network network() const; ///< Return <tt>/64</tt> Network of this address
227 bool hasEUI64() const; ///< \c true, if address is based on an EUID-64
228 EUI64 id() const; ///< Return interface id (EUID-64)
229 bool universalId() const; ///< \c true, if the id() is universally assigned
230 bool groupId() const; ///< \c true, if the id()'s \a group bit is set
232 bool unicast() const; ///< \c true, if address is unicast
233 bool multicast() const; ///< \c true, if address is multicast
234 /**< To support a linux specific extension, INet4 multicast
235 addressed mapped to INet6 are also interpreted as
236 multicast addresses. This is NOT part of the standard,
237 however the standard officially only allows unicast v4
238 addresses to be mapped to v6 so this does not collide
239 with any standard conforming use. */
241 ScopeId scope() const; ///< Get address's scope
242 /**< The scope of an address is one of the \ref ScopeId
243 values. We need to differentiate between unicast and
244 multicast addresses: unicast addresses only have local,
245 site or global scope (where site scope is deprecated),
246 multicast address can have a number of scope values of
247 which local, site and global are a few. See the \ref
248 ScopeId enumerators. */
249 bool globalScope() const; ///< \c true, if address is global unicast or multicast
250 bool linkScope() const; ///< \c true, if address is link-local unicast or multicast
252 INet4Address inet4address() const; ///< Return embedded INet4 address
253 /**< Returns the INet4 address embedded within an INet4
254 compatible or INet4 mapped unicast address. This address
255 is given by the last 32 bits of the INet6 address. \par
256 The value returned is only a valid INet4 address if
257 either inet4Compatible() or inet4Mapped() return \c
259 bool inet4Compatible() const; ///< \c true, if address is INet4 compatible
260 /**< INet4 compatible INet6 addresses are deprecated. */
261 bool inet4Mapped() const; ///< \c true, if address is INet4 mapped
263 bool globalMulticastAddr() const; ///< \c true, if T bit is \e not set
264 /**< Any multicast address with a cleared T bit must be
265 globally assigned. See
266 <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>. */
267 bool prefixMulticastAddr() const; ///< \c true, if P bit is set
268 /**< In <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>,
269 the P bit is specified as defining a
270 unicast prefix based multicast address. See
271 <a href="http://tools.ietf.org/html/rfc3306">RFC 3306</a>. */
272 bool embeddedRpAddr() const; ///< \c true, if R bit is set
273 /**< In <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>,
274 the R bit is specified as defining a multicast address
275 with embedded rendezvous point. See
276 <a href="http://tools.ietf.org/html/rfc3956">RFC 3956</a>. */
278 bool boolean_test() const; ///< \c true, if address != '::' (None)
284 void network(boost::uint64_t net); ///< Set network part of address
285 void id(boost::uint64_t id); ///< Set interface id part of address
291 /** \brief Output INet6Address instance as it's string representation
292 \related INet6Address
294 std::ostream & operator<<(std::ostream & os, INet6Address const & addr);
295 /** \brief Try to initialize INet6Address instance from a string representation
296 sets std::ios::failbit on the stream if an error occurred
297 \see INet6Address from_string()
298 \related INet6Address
300 std::istream & operator>>(std::istream & is, INet6Address & addr);
302 /** \brief Check INet6Address against a fixed network prefix
304 This helper allows to easily and efficiently check an INet6Address against an arbitrary but
305 constant network prefix. It takes from 1 to 8 arguments for the network address and an
306 additional last argument providing the prefix length. So
309 <tt>senf::CheckINet6Network<</tt> <i>addr_1</i> <tt>,</tt> <i>addr_2</i> <tt>,</tt>
310 ... <tt>,</tt> <i>prefix_len</i> <tt>></tt>
312 represents the network
315 <i>addr_1</i> <tt>:</tt> <i>addr_2</i> <tt>:</tt> ... <tt>::/</tt> <i>prefix_len</i> .
317 The class exposes a single static member <tt>match(</tt> <i>addr</i> <tt>)</tt> which
318 matches the INet6Address \a addr against the prefix:
321 if (senf::CheckINet6Network<0x2000u,0xDB8u,32u>::match(addr)) {
322 // 'addr' is within in the 2001:db8::/32 documentation-only network
327 The code generated by this call is highly optimized and probably as efficient as it can get.
329 template <unsigned a0, unsigned a1, unsigned a2=0u, unsigned a3=0u, unsigned a4=0u,
330 unsigned a5=0u, unsigned a6=0u, unsigned a7=0u, unsigned a8=0u>
331 struct CheckINet6Network
333 : public detail::CheckINet6Network_impl<a0,a1,a2,a3,a4,a5,a6,a7,a8>
337 /** \brief INet6 network prefix
339 This class represents an INet6 network prefix in CIDR notation.
342 : public boost::equality_comparable<INet6Network>,
343 public comparable_safe_bool<INet6Network>
346 ///////////////////////////////////////////////////////////////////////////
347 ///\name Structors and default members
350 INet6Network(); ///< Construct empty (::/0) network
351 INet6Network(INet6Address const & address, unsigned prefix_len);
352 ///< Construct network from given address and prefix length
353 explicit INet6Network(std::string const & s); ///< Construct network from CIDR notation
356 ///////////////////////////////////////////////////////////////////////////
358 INet6Address const & address() const; ///< Get the network address
359 unsigned prefix_len() const; ///< Get the network prefix length
361 bool boolean_test() const; ///< \c true, if INet6Network is non-empty
362 bool operator==(INet6Network const & other) const;
363 ///< Compare two networks for equality
365 bool match(INet6Address const & addr) const; ///< \c true, if the network includes \a addr
366 bool match(INet6Network const & net) const; ///< \c true, if the network includes \a net
367 /**< The is true, if \a net is sub-network (or the same as)
369 INet6Address host(boost::uint64_t id); ///< Return the host with the given id
370 /**< Returns the host with the given number within the
371 network. This call replaces the lower 64 bits of the
372 network address with the given id. */
374 INet6Network subnet(boost::uint64_t net, unsigned prefix_len);
375 ///< Return the given subnet of \c this
376 /**< The returned INet6Network will be a subnet of \c this
377 with the given network number. The network number is
378 comprised by the bits above \a prefix_len:
380 INet6Network("2001:db8::/32").subnet(0x12u,40u) == INet6Network("2001:db8:1200::/40")
381 INet6Network("2001:db8:1200::/40").subnet(0x2345,64u) == INet6Network("2001:db8:1200:2345::/64")
383 \param[in] net network number
384 \param[in] prefix_len length of subnet prefix */
389 unsigned prefix_len_;
390 INet6Address address_;
393 /** \brief Output INet6Network instance as it's string representation
394 \related INet6Network
396 std::ostream & operator<<(std::ostream & os, INet6Network const & addr);
399 ///////////////////////////////hh.e////////////////////////////////////////
400 #include "INet6Address.cci"
401 #include "INet6Address.ct"
402 #include "INet6Address.cti"
409 // comment-column: 40
410 // c-file-style: "senf"
411 // indent-tabs-mode: nil
412 // ispell-local-dictionary: "american"
413 // compile-command: "scons -u test"