1.\" $OpenBSD: inet6.4,v 1.22 2001/06/24 19:42:23 itojun Exp $ 2.\" $KAME: inet6.4,v 1.19 2000/11/24 10:13:18 itojun Exp $ 3.\" 4.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the project nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd January 29, 1999 32.Dt INET6 4 33.Os 34.Sh NAME 35.Nm inet6 36.Nd Internet protocol version 6 family 37.Sh SYNOPSIS 38.Fd #include <sys/types.h> 39.Fd #include <netinet/in.h> 40.Sh DESCRIPTION 41The 42.Nm 43family is an updated version of 44.Xr inet 4 45family. 46While 47.Xr inet 4 48implements Internet Protocol version 4, 49.Nm 50implements Internet Protocol version 6. 51.Pp 52.Nm 53is a collection of protocols layered atop the 54.Em Internet Protocol version 6 55.Pq Tn IPv6 56transport layer, and utilizing the IPv6 address format. 57The 58.Nm 59family provides protocol support for the 60.Dv SOCK_STREAM , 61.Dv SOCK_DGRAM , 62and 63.Dv SOCK_RAW 64socket types; the 65.Dv SOCK_RAW 66interface provides access to the 67.Tn IPv6 68protocol. 69.Sh ADDRESSING 70IPv6 addresses are 16 byte quantities, stored in network standard byteorder. 71The include file 72.Aq Pa netinet/in.h 73defines this address 74as a discriminated union. 75.Pp 76Sockets bound to the 77.Nm 78family utilize the following addressing structure: 79.Bd -literal -offset indent 80struct sockaddr_in6 { 81 u_int8_t sin6_len; 82 sa_family_t sin6_family; 83 in_port_t sin6_port; 84 u_int32_t sin6_flowinfo; 85 struct in6_addr sin6_addr; 86 u_int32_t sin6_scope_id; 87}; 88.Ed 89.Pp 90Sockets may be created with the local address 91.Dq Dv :: 92.Po 93which is equal to IPv6 address 94.Dv 0:0:0:0:0:0:0:0 95.Pc 96to effect 97.Dq wildcard 98matching on incoming messages. 99.Pp 100IPv6 specification defines scoped address, 101like link-local or site-local address. 102A scoped address is ambiguous to the kernel, 103if it is specified without scope identifier. 104To manipulate scoped addresses properly from the userland, 105programs must use advanced API defined in RFC2292. 106Compact description on the advanced API is available in 107.Xr ip6 4 . 108If scoped addresses are specified without explicit scope, 109the kernel may raise error. 110Note that scoped addresses are not for daily use at this moment, 111both from specification and implementation point of view. 112.Pp 113KAME implementation supports extended numeric IPv6 address notation 114for link-local addresses, 115like 116.Dq Li fe80::1%de0 117to specify 118.Do 119.Li fe80::1 120on 121.Li de0 122interface 123.Dc . 124The notation is supported by 125.Xr getaddrinfo 3 126and 127.Xr getnameinfo 3 . 128Some of normal userland programs, such as 129.Xr telnet 1 130or 131.Xr ftp 1 , 132are able to use the notation. 133With special programs 134like 135.Xr ping6 8 , 136you can specify outgoing interface by extra command line option 137to disambiguate scoped addresses. 138.Pp 139Scoped addresses are handled specially in the kernel. 140In the kernel structures like routing tables or interface structure, 141scoped addresses will have its interface index embedded into the address. 142Therefore, 143the address on some of the kernel structure is not the same as that on the wire. 144The embedded index will become visible on 145.Dv PF_ROUTE 146socket, kernel memory accesses via 147.Xr kvm 3 148and some other occasions. 149HOWEVER, users should never use the embedded form. 150For details please consult 151.Pa http://www.kame.net/dev/cvsweb.cgi/kame/IMPLEMENTATION . 152Note that the above URL describes the situation with the latest KAME tree, 153not the 154.Ox 155tree. 156.Sh PROTOCOLS 157The 158.Nm 159family is comprised of the 160.Tn IPv6 161network protocol, Internet Control 162Message Protocol version 6 163.Pq Tn ICMPv6 , 164Transmission Control Protocol 165.Pq Tn TCP , 166and User Datagram Protocol 167.Pq Tn UDP . 168.Tn TCP 169is used to support the 170.Dv SOCK_STREAM 171abstraction while 172.Tn UDP 173is used to support the 174.Dv SOCK_DGRAM 175abstraction. 176Note that 177.Tn TCP 178and 179.Tn UDP 180are common to 181.Xr inet 4 182and 183.Nm inet6 . 184A raw interface to 185.Tn IPv6 186is available 187by creating an Internet socket of type 188.Dv SOCK_RAW . 189The 190.Tn ICMPv6 191message protocol is accessible from a raw socket. 192.\" .Pp 193.\" The 128-bit IPv6 address contains both network and host parts. 194.\" However, direct examination of addresses is discouraged. 195.\" For those programs which absolutely need to break addresses 196.\" into their component parts, the following 197.\" .Xr ioctl 2 198.\" commands are provided for a datagram socket in the 199.\" .Nm 200.\" domain; they have the same form as the 201.\" .Dv SIOCIFADDR 202.\" command (see 203.\" .Xr intro 4 ) . 204.\" .Pp 205.\" .Bl -tag -width SIOCSIFNETMASK 206.\" .It Dv SIOCSIFNETMASK 207.\" Set interface network mask. 208.\" The network mask defines the network part of the address; 209.\" if it contains more of the address than the address type would indicate, 210.\" then subnets are in use. 211.\" .It Dv SIOCGIFNETMASK 212.\" Get interface network mask. 213.\" .El 214.\" .Sh ROUTING 215.\" The current implementation of Internet protocols includes some routing-table 216.\" adaptations to provide enhanced caching of certain end-to-end 217.\" information necessary for Transaction TCP and Path MTU Discovery. The 218.\" following changes are the most significant: 219.\" .Bl -enum 220.\" .It 221.\" All IP routes, except those with the 222.\" .Dv RTF_CLONING 223.\" flag and those to multicast destinations, have the 224.\" .Dv RTF_PRCLONING 225.\" flag forcibly enabled (they are thus said to be 226.\" .Dq "protocol cloning" ). 227.\" .It 228.\" When the last reference to an IP route is dropped, the route is 229.\" examined to determine if it was created by cloning such a route. If 230.\" this is the case, the 231.\" .Dv RTF_PROTO3 232.\" flag is turned on, and the expiration timer is initialized to go off 233.\" in net.inet.ip.rtexpire seconds. If such a route is re-referenced, 234.\" the flag and expiration timer are reset. 235.\" .It 236.\" A kernel timeout runs once every ten minutes, or sooner if there are 237.\" soon-to-expire routes in the kernel routing table, and deletes the 238.\" expired routes. 239.\" .El 240.\" .Pp 241.\" A dynamic process is in place to modify the value of 242.\" net.inet.ip.rtexpire if the number of cached routes grows too large. 243.\" If after an expiration run there are still more than 244.\" net.inet.ip.rtmaxcache unreferenced routes remaining, the rtexpire 245.\" value is multiplied by 3/4, and any routes which have longer 246.\" expiration times have those times adjusted. This process is damped 247.\" somewhat by specification of a minimum rtexpire value 248.\" (net.inet.ip.rtminexpire), and by restricting the reduction to once in 249.\" a ten-minute period. 250.\" .Pp 251.\" If some external process deletes the original route from which a 252.\" protocol-cloned route was generated, the ``child route'' is deleted. 253.\" (This is actually a generic mechanism in the routing code support for 254.\" protocol-requested cloning.) 255.\" .Pp 256.\" No attempt is made to manage routes which were not created by protocol 257.\" cloning; these are assumed to be static, under the management of an 258.\" external routing process, or under the management of a link layer 259.\" (e.g., 260.\" .Tn ARP 261.\" for Ethernets). 262.\" .Pp 263.\" Only certain types of network activity will result in the cloning of a 264.\" route using this mechanism. Specifically, those protocols (such as 265.\" .Tn TCP 266.\" and 267.\" .Tn UDP ) 268.\" which themselves cache a long-lasting reference to route for a destination 269.\" will trigger the mechanism; whereas raw 270.\" .Tn IP 271.\" packets, whether locally-generated or forwarded, will not. 272.Ss Interaction between IPv4/v6 sockets 273The behavior of 274.Dv AF_INET6 275TCP/UDP socket is documented in RFC2553. 276Basically, it says as follows: 277.Bl -bullet -compact 278.It 279Specific bind on 280.Dv AF_INET6 281socket 282.Po 283.Xr bind 2 284with address specified 285.Pc 286should accept IPv6 traffic to that address only. 287.It 288If you perform wildcard bind 289on 290.Dv AF_INET6 291socket 292.Po 293.Xr bind 2 294to IPv6 address 295.Li :: 296.Pc , 297and there is no wildcard bind 298.Dv AF_INET 299socket on that TCP/UDP port, IPv6 traffic as well as IPv4 traffic 300should be routed to that 301.Dv AF_INET6 302socket. 303IPv4 traffic should be seen as if it came from IPv6 address like 304.Li ::ffff:10.1.1.1 . 305This is called IPv4 mapped address. 306.It 307If there are both wildcard bind 308.Dv AF_INET 309socket and wildcard bind 310.Dv AF_INET6 311socket on one TCP/UDP port, they should behave separately. 312IPv4 traffic should be routed to 313.Dv AF_INET 314socket and IPv6 should be routed to 315.Dv AF_INET6 316socket. 317.El 318.Pp 319However, RFC2553 does not define the constraint between the order of 320.Xr bind 2 , 321nor how IPv4 TCP/UDP port number and IPv6 TCP/UDP port number 322relate each other 323.Po 324should they be integrated or separated 325.Pc . 326Implemented behavior is very different across kernel to kernel. 327Therefore, it is unwise to rely too much upon the behavior of 328.Dv AF_INET6 329wildcard bind socket. 330It is recommended to listen to two sockets, one for 331.Dv AF_INET 332and another for 333.Dv AF_INET6 , 334when you would like to accept both IPv4 and IPv6 traffic. 335.Pp 336It should also be noted that 337malicious parties can take advantage of the complexity presented above, 338and are able to bypass access control, 339if the target node routes IPv4 traffic to 340.Dv AF_INET6 341socket. 342Users are advised to take caution handling connections 343from IPv4 mapped address to 344.Dv AF_INET6 345sockets. 346.Pp 347Because of the above, 348.Ox 349does not route IPv4 traffic to 350.Dv AF_INET6 351socket. 352The particular behavior in RFC2553 is intentionally omitted for security 353reasons presented above. 354If you need to accept both IPv4 and IPv6 traffic, listen to two sockets. 355.Sh SEE ALSO 356.Xr ioctl 2 , 357.Xr socket 2 , 358.Xr sysctl 3 , 359.Xr icmp6 4 , 360.Xr intro 4 , 361.Xr ip6 4 , 362.Xr tcp 4 , 363.Xr udp 4 364.Sh STANDARDS 365.Rs 366.%A Tatsuya Jinmei 367.%A Atsushi Onoe 368.%T "An Extension of Format for IPv6 Scoped Addresses" 369.%R internet draft 370.%D June 2000 371.%N draft-ietf-ipngwg-scopedaddr-format-02.txt 372.%O work in progress material 373.Re 374.Sh HISTORY 375The 376.Nm 377protocol interface are defined in RFC2553 and RFC2292. 378The implementation described herein appeared in WIDE/KAME project. 379.Sh BUGS 380The IPv6 support is subject to change as the Internet protocols develop. 381Users should not depend on details of the current implementation, 382but rather the services exported. 383.Pp 384Users are suggested to implement 385.Dq version independent 386code as much as possible, as you will need to support both 387.Xr inet 4 388and 389.Nm inet6 . 390