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