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_INet6Address_
27 #define HH_INet6Address_ 1
32 #include <boost/cstdint.hpp>
33 #include <boost/array.hpp>
34 #include <boost/operators.hpp>
35 #include "../../../Utils/safe_bool.hh"
36 #include "../../../Utils/Tags.hh"
37 #include "INet4Address.hh"
39 //#include "INet6Address.mpp"
40 #include "INet6Address.ih"
41 ///////////////////////////////hh.p////////////////////////////////////////
45 /** \brief IPv6 network address
47 This implementation of an IPv6 address is based strictly on
48 <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>: Internet Protocol
49 Version 6 (IPv6) Addressing Architecture. This class provides accessors to all the
50 information fields defined in this document.
52 The IPv6 addressing architecture however has several other components defined in other
53 RFC's. These RFC's should be implemented in additional modules:
55 \li <a href="http://tools.ietf.org/html/rfc4193">RFC 4193</a>:
56 Unique Local Addresses (ULA). Defines the fc00::/7 prefix
57 \li <a href="http://tools.ietf.org/html/rfc3306">RFC 3306</a>:
58 Unicast-Prefix-based IPv6 Multicast Addresses. Defines the ff30::/12 prefix
59 \li <a href="http://tools.ietf.org/html/rfc3956">RFC 3956</a>:
60 Embedding the Rendezvous Point (RP) Address in an IPv6 Multicast
61 Address. Defines the ff70::/12 prefix
62 \li <a href="http://tools.ietf.org/html/rfc3056">RFC 3056</a>:
63 Connection of IPv6 Domains via IPv4 Clouds. Defines 6to4 tunneling and the
65 \li <a href="http://tools.ietf.org/html/rfc3849">RFC 3849</a>:
66 IPv6 Address Prefix Reserved for Documentation. Defines the 2001:db8::/32 prefix
68 Here an overview of well-known prefixes:
71 <tr><th>Prefix</th> <th>Description</th> <th>Definition</th> <th>Note</th></tr>
72 <tr><td><tt>::/96</tt></td> <td>IPv4 compatible IPv6 address</td> <td>RFC4291</td> <td>deprecated</td></tr>
73 <tr><td><tt>::ffff:0:0/96</tt></td> <td>IPv6 mapped IPv4 address</td> <td>RFC4291</td> <td></td></tr>
74 <tr><td><tt>2000::/3</tt></td> <td>Global unicast addresses</td> <td>RFC3587</td> <td>only noted, not defined</td></tr>
75 <tr><td><tt>2001:db8::/32</tt></td> <td>Documentation-only prefix</td> <td>RFC3849</td> <td></td></tr>
76 <tr><td><tt>2002::/16</tt></td> <td>6to4 addressing</td> <td>RFC3056</td> <td></td></tr>
77 <tr><td><tt>fc00::/7</tt></td> <td>ULA</td> <td>RFC4193</td> <td></td></tr>
78 <tr><td><tt>fe80::/64</tt></td> <td>Link-local addresses</td> <td>RFC4291</td> <td></td></tr>
79 <tr><td><tt>fec0::/10</tt></td> <td>Site-local addresses </td> <td>RFC4291</td> <td>deprecated</td></tr>
80 <tr><td><tt>ff00::/8</tt></td> <td>Multicast</td> <td>RFC4291</td> <td></td></tr>
81 <tr><td><tt>ff00::/12</tt></td> <td>Globally allocated multicast</td> <td>RFC4291</td> <td></td></tr>
82 <tr><td><tt>ff10::/12</tt></td> <td>Locally allocated multicast</td> <td>RFC4291</td> <td></td></tr>
83 <tr><td><tt>ff30::/12</tt></td> <td>Unicast prefic based multicast</td> <td>RFC3306</td> <td></td></tr>
84 <tr><td><tt>ff70::/12</tt></td> <td>Multicast address with embedded RP</td> <td>RFC3956</td> <td></td></tr>
87 The INet6Address class is based on \c boost::array and is built as a fixed-size sequence of
90 \see CheckINet6Network \n INet6Network
93 \implementation We awkwardly need to use static named constructors (<tt>from_</tt> members)
94 instead of ordinarily overloaded constructors for one simple reason: <tt>char *</tt>
95 doubles as string literal and as arbitrary data iterator. The iterator constructor can
96 therefore not be distinguished from initialization with a string literal. Therefore we
97 need to disambiguate using the named constructors.
100 : public boost::array<boost::uint8_t,16>,
101 public comparable_safe_bool<INet6Address>
104 ///////////////////////////////////////////////////////////////////////////
107 static INet6Address const None; ///< The empty (::0) address
108 static INet6Address const Loopback; ///< The loopback (::1) address
109 static INet6Address const AllNodes; ///< The 'all nodes' link-local multicast address
110 static INet6Address const AllRouters; ///< The 'all routers' link-local multicast address
112 enum Resolve_t { ResolveINet6, ResolveINet4 };
114 /** \brief Possible scope values
116 List of all possible scope values. This list includes all scope values defined for
117 multicast addresses in <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>.
118 The values \ref LinkScope, \ref SiteScope and \ref GlobalScope are also used with
122 InterfaceScope = 1 /**< Interface only scope */
123 , LinkScope = 2 /**< Link-local scope */
124 , AdminScope = 4 /**< Administration defined local scope */
125 , SiteScope = 5 /**< Site-local scope */
126 , OrganizationScope = 8 /**< Scope covering multiple sites of an organization */
127 , GlobalScope = 14 /**< Global Internet scope */
129 , ReservedScope = 0 /**< Reserved scope value */
130 , UnassignedScope = 6 /**< Unassigned scope, may be defined locally */
133 ///////////////////////////////////////////////////////////////////////////
134 ///\name Structors and default members
137 explicit INet6Address(senf::NoInit_t); ///< Construct uninitialized (!) address
138 INet6Address(boost::uint16_t a0=0u, boost::uint16_t a1=0u, boost::uint16_t a2=0u,
139 boost::uint16_t a3=0u, boost::uint16_t a4=0u, boost::uint16_t a5=0u,
140 boost::uint16_t a6=0u, boost::uint16_t a7=0u);
141 ///< Construct an address constant
143 static INet6Address from_string(std::string const & s, Resolve_t resolve = ResolveINet6);
144 ///< Convert string to address
145 /**< This member will try to convert the given string into
146 an IP address. from_string() supports all standard IP
147 literal representations as well es hostnames.
148 \attention This call may block if \a s represents a
149 hostname which must be looked up via some network
150 protocol like DNS or NIS
151 \throws SyntaxException if the address cannot be
152 converted for some reason
153 \param[in] s Address literal or hostname
154 \param[in] resolve If this is set to \c ResolveINet4,
155 the call will additionally try to interpret \a s as
156 an IPv4 address if no valid IPv6 address is
157 found. The address will be returned as mapped IPv6
160 template <class InputIterator>
161 static INet6Address from_data(InputIterator i);
162 ///< Construct address from 16 bytes of raw data
163 /**< from_data will build an address from 16 bytes of raw
164 data as accessed by the iterator. The data must be in
165 network byte order. */
167 static INet6Address from_inet4address(INet4Address addr);
168 ///< Construct an IPv6-mapped IPv4 address
169 /**< This will construct an address of the form
170 <tt>::FFFF::w.x.y.z</tt> where <tt>w.x.y.z</tt> is
171 the INet4Address value. This kind of address is called
172 an IPv6-mapped IPv4 address (see
173 <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>).
175 IPv4 compatible IPv6 addresses are not directly
176 supported, they are deprecated in the RFC. */
178 ///////////////////////////////////////////////////////////////////////////
182 boost::uint64_t network() const; ///< Return 64bit network part
183 bool hasEuid64() const; ///< \c true, if address is based on an EUID-64
184 boost::uint64_t id() const; ///< Return interface id (EUID-64)
185 bool universalId() const; ///< \c true, if the id() is universally assigned
186 bool groupId() const; ///< \c true, if the id()'s \a group bit is set
188 bool unicast() const; ///< \c true, if address is unicast
189 bool multicast() const; ///< \c true, if address is multicast
191 ScopeId scope() const; ///< Get address's scope
192 /**< The scope of an address is one of the \ref ScopeId
193 values. We need to differentiate between unicast and
194 multicast addresses: unicast addresses only have local,
195 site or global scope (where site scope is deprecated),
196 multicast address can have a number of scope values of
197 which local, site and global are a few. See the \ref
198 ScopeId enumerators. */
199 bool globalScope() const; ///< \c true, if address is global unicast or multicast
200 bool linkScope() const; ///< \c true, if address is link-local unicast or multicast
202 INet4Address inet4address() const; ///< Return embedded IPv4 address
203 /**< Returns the IPv4 address embedded within an IPv4
204 compatible or IPv4 mapped unicast address. This address
205 is given by the last 32 bits of the IPv6 address. \par
206 The value returned is only a valid IPv4 address if
207 either ipv4Compatible() or ipv4Mapped() return \c
209 bool ipv4Compatible() const; ///< \c true, if address is IPv4 compatible
210 /**< IPv4 compatible IPv6 addresses are deprecated. */
211 bool ipv4Mapped() const; ///< \c true, if address is IPv4 mapped
213 bool globalMulticastAddr() const; ///< \c true, if T bit is \e not set
214 /**< Any multicast address with a cleared T bit must be
215 globally assigned. See
216 <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>. */
217 bool prefixMulticastAddr() const; ///< \c true, if P bit is set
218 /**< In <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>,
219 the P bit is specified as defining a
220 unicast prefix based multicast address. See
221 <a href="http://tools.ietf.org/html/rfc3306">RFC 3306</a>. */
222 bool embeddedRpAddr() const; ///< \c true, if R bit is set
223 /**< In <a href="http://tools.ietf.org/html/rfc4291">RFC 4291</a>,
224 the R bit is specified as defining a multicast address
225 with embedded rendezvous point. See
226 <a href="http://tools.ietf.org/html/rfc3956">RFC 3956</a>. */
228 bool boolean_test() const; ///< \c true, if address != '::' (None)
234 void network(boost::uint64_t net); ///< Set network part of address
235 void id(boost::uint64_t id); ///< Set interface id part of address
239 /** \brief Base-class for INet6Address exceptions */
240 struct AddressException : public std::exception {};
242 /** \brief Invalid INet4 address syntax */
243 struct SyntaxException : public AddressException
244 { virtual char const * what() const throw()
245 { return "invalid INet6 address syntax"; } };
247 /** \brief Resolver failure */
248 struct UnknownHostnameException : public AddressException
249 { virtual char const * what() const throw()
250 { return "failed to resolve INet6 hostname"; } };
253 /** \brief Output INet6Address instance as it's string representation
254 \related INet6Address
256 std::ostream & operator<<(std::ostream & os, INet6Address const & addr);
258 /** \brief Check INet6Address against a fixed network prefix
260 This helper allows to easily and efficiently check an INet6Address against an arbitrary but
261 constant network prefix. It takes from 1 to 8 arguments for the network address and an
262 additional last argument providing the prefix length. So
265 <tt>senf::CheckINet6Network<</tt> <i>addr_1</i> <tt>,</tt> <i>addr_2</i> <tt>,</tt>
266 ... <tt>,</tt> <i>prefix_len</i> <tt>></tt>
268 represents the network
271 <i>addr_1</i> <tt>:</tt> <i>addr_2</i> <tt>:</tt> ... <tt>::/</tt> <i>prefix_len</i> .
273 The class exposes a single static member <tt>match(</tt> <i>addr</i> <tt>)</tt> which
274 matches the INet6Address \a addr against the prefix:
277 if (senf::CheckINet6Network<0x2000u,0xDB8u,32u>::match(addr)) {
278 // 'addr' is within in the 2001:db8::/32 documentation-only network
283 The code generated by this call is highly optimized and probably as efficient as it can get.
285 template <unsigned a0, unsigned a1, unsigned a2=0u, unsigned a3=0u, unsigned a4=0u,
286 unsigned a5=0u, unsigned a6=0u, unsigned a7=0u, unsigned a8=0u>
287 struct CheckINet6Network
288 : public detail::CheckINet6Network_impl<a0,a1,a2,a3,a4,a5,a6,a7,a8>
291 /** \brief IPv6 network prefix
293 This class represents an IPv6 network prefix in CIDR notation.
296 : public boost::equality_comparable<INet6Network>,
297 public comparable_safe_bool<INet6Network>
300 ///////////////////////////////////////////////////////////////////////////
301 ///\name Structors and default members
304 INet6Network(); ///< Construct empty (::/0) network
305 INet6Network(INet6Address address, unsigned prefix_len);
306 ///< Construct network from given address and prefix length
307 explicit INet6Network(std::string s); ///< Construct network from CIDR notation
310 ///////////////////////////////////////////////////////////////////////////
312 INet6Address const & address() const; ///< Get the network address
313 unsigned prefix_len() const; ///< Get the network prefix length
315 bool boolean_test() const; ///< \c true, if INet6Network is non-empty
316 bool operator==(INet6Network const & other) const;
317 ///< Compare two networks for equality
319 bool match(INet6Address addr) const; ///< \c true, if the network includes \a addr
320 bool match(INet6Network net) const; ///< \c true, if the network includes \a net
321 /**< The is true, if \a net is sub-network (or the same as)
323 INet6Address host(boost::uint64_t id); ///< Return the host with the given id
324 /**< Returns the host with the given number within the
325 network. This call replaces the lower 64 bits of the
326 network address with the given id. */
328 INet6Network subnet(boost::uint64_t net, unsigned prefix_len);
329 ///< Return the given subnet of \c this
330 /**< The returned INet6Network will be a subnet of \c this
331 with the given network number. The network number is
332 comprised by the bits above \a prefix_len:
334 INet6Network("2001:db8::/32").subnet(0x12u,40u) == INet6Network("2001:db8:1200::/40")
335 INet6Network("2001:db8:1200::/40").subnet(0x2345,64u) == INet6Network("2001:db8:1200:2345::/64")
337 \param[in] net network number
338 \param[in] prefix_len length of subnet prefix */
343 unsigned prefix_len_;
344 INet6Address address_;
347 /** \brief Output INet6Network instance as it's string representation
348 \related INet6Network
350 std::ostream & operator<<(std::ostream & os, INet6Network const & addr);
353 ///////////////////////////////hh.e////////////////////////////////////////
354 #include "INet6Address.cci"
355 #include "INet6Address.ct"
356 #include "INet6Address.cti"
363 // comment-column: 40
364 // c-file-style: "senf"
365 // indent-tabs-mode: nil
366 // ispell-local-dictionary: "american"
367 // compile-command: "scons -u test"