xref: /openbsd-src/share/man/man4/inet6.4 (revision b2ea75c1b17e1a9a339660e7ed45cd24946b230e)
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