From 0737851f1642d613c81b8ae2ee1cb7603cbd837a Mon Sep 17 00:00:00 2001 From: Theo de Raadt Date: Sat, 18 Jan 2003 23:53:50 +0000 Subject: inet6 fixes from jmc@prioris.mini.pw.edu.pl --- share/man/man4/faith.4 | 41 +++++++++++++++++---------------- share/man/man4/icmp6.4 | 29 ++++++++++++----------- share/man/man4/inet6.4 | 57 +++++++++++++++++++++++----------------------- share/man/man4/ip6.4 | 62 ++++++++++++++++++++++++++------------------------ 4 files changed, 96 insertions(+), 93 deletions(-) (limited to 'share/man') diff --git a/share/man/man4/faith.4 b/share/man/man4/faith.4 index 1e982252873..3b9450bb51f 100644 --- a/share/man/man4/faith.4 +++ b/share/man/man4/faith.4 @@ -1,4 +1,4 @@ -.\" $OpenBSD: faith.4,v 1.10 2001/06/30 01:05:23 itojun Exp $ +.\" $OpenBSD: faith.4,v 1.11 2003/01/18 23:53:49 deraadt Exp $ .\" $KAME: faith.4,v 1.10 2001/06/30 00:42:48 itojun Exp $ .\" .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. @@ -41,21 +41,22 @@ The .Nm interface captures IPv6 TCP traffic, for implementing userland IPv6-to-IPv4 TCP relay -like +similar to .Xr faithd 8 . .Pp Special action will be taken when IPv6 TCP traffic is seen on a router, -and routing table suggests to route it to +and the routing table suggests routing it to the .Nm interface. In this case, the packet will be accepted by the router, -regardless of list of IPv6 interface addresses assigned to the router. -The packet will be captured by an IPv6 TCP socket, if it has +regardless of the list of IPv6 interface addresses assigned to the router. +The packet is captured by an IPv6 TCP socket, if it has the .Dv IN6P_FAITH flag turned on and it has matching address/port pairs. -In result, +Thus, .Nm -will let you capture IPv6 TCP traffic to some specific destination addresses. +allows captured IPv6 TCP traffic to be relayed to some +specific destination addresses. Userland programs, such as .Xr faithd 8 can use this behavior to relay IPv6 TCP traffic to IPv4 TCP traffic. @@ -64,44 +65,46 @@ The program can accept some specific IPv6 TCP traffic, perform to get the IPv6 destination address specified by the client, and perform application-specific address mapping to relay IPv6 TCP to IPv4 TCP. .Pp +The .Dv IN6P_FAITH -flag on IPv6 TCP socket can be set by using +flag on an IPv6 TCP socket can be set by using .Xr setsockopt 2 , -with level equals to +with level set to .Dv IPPROTO_IPV6 -and optname equals to +and optname set to .Dv IPv6_FAITH . .Pp -To handle error reports by ICMPv6, some of ICMPv6 packets routed to +To handle error reports by ICMPv6, some of the ICMPv6 packets routed to the .Nm interface will be delivered to IPv6 TCP, as well. .Pp To understand how .Nm -can be used, take a look at source code of +can be used, take a look at the source code of .Xr faithd 8 . .Pp -As +As the .Nm -interface implements potentially dangerous operation, -great care must be taken when configuring +interface implements a potentially dangerous operation, +great care must be taken when configuring the .Nm interface. -To avoid possible misuse, +To avoid possible misuse, the .Xr sysctl 8 variable .Li net.inet6.ip6.keepfaith must be set to .Li 1 -prior to the use of the interface. +prior to use of the interface. When .Li net.inet6.ip6.keepfaith is .Li 0 , -no packet will be captured by +no packet is captured by the .Nm interface. .Pp +The .Nm interface is intended to be used on routers, not on hosts. .\" @@ -118,5 +121,5 @@ interface is intended to be used on routers, not on hosts. .%D June 2001 .Re .Sh HISTORY -The FAITH IPv6-to-IPv4 TCP relay translator was first appeared in +The FAITH IPv6-to-IPv4 TCP relay translator first appeared in WIDE hydrangea IPv6 stack. diff --git a/share/man/man4/icmp6.4 b/share/man/man4/icmp6.4 index 84e095d804e..7760d075302 100644 --- a/share/man/man4/icmp6.4 +++ b/share/man/man4/icmp6.4 @@ -1,4 +1,4 @@ -.\" $OpenBSD: icmp6.4,v 1.10 2002/09/26 07:55:40 miod Exp $ +.\" $OpenBSD: icmp6.4,v 1.11 2003/01/18 23:53:49 deraadt Exp $ .\" $KAME: icmp6.4,v 1.3 2000/11/24 08:44:40 itojun Exp $ .\" .\" Copyright (C) 1999 WIDE Project. @@ -110,16 +110,17 @@ Outgoing packets automatically have an .Tn IPv6 header prepended to them .Pq based on the destination address . +The .Tn ICMPv6 -pseudo header checksum field +pseudo-header checksum field .Pq Li icmp6_cksum -will be filled automatically by the kernel. +is filled automatically by the kernel. Incoming packets are received without the .Tn IPv6 -header nor IPv6 extension headers. -Notice that this behavior is opposite from +header or IPv6 extension headers. +Notice that this behavior is opposite to that of .Tn IPv4 -raw sockets and. +raw sockets and .Tn ICMPv4 sockets. .Ss ICMPv6 type/code filter @@ -172,8 +173,7 @@ The first two macros, .Dv SETPASSALL and .Dv SETBLOCKALL , -let us specify that -all +specify that all .Tn ICMPv6 messages are passed to the application or that all .Tn ICMPv6 messages are blocked from being passed to the application. @@ -182,8 +182,7 @@ The next two macros, .Dv SETPASS and .Dv SETBLOCK , -let us specify that -messages of a given +specify that messages of a given .Tn ICMPv6 type should be passed to the application or not passed to the application @@ -194,7 +193,7 @@ The final two macros, and .Dv WILLBLOCK , return true or false -depending whether the specified message type is passed to the +depending on whether the specified message type is passed to the application or blocked from being passed to the application by the filter pointed to by the second argument. .Pp @@ -211,14 +210,14 @@ A socket operation may fail with one of the following errors returned: .It Bq Er EISCONN when trying to establish a connection on a socket which already has one, or when trying to send a datagram with the destination -address specified and the socket is already connected; +address specified and the socket is already connected. .It Bq Er ENOTCONN when trying to send a datagram, but no destination address is specified, and the socket hasn't been -connected; +connected. .It Bq Er ENOBUFS when the system runs out of memory for -an internal data structure; +an internal data structure. .It Bq Er EADDRNOTAVAIL when an attempt is made to create a socket with a network address for which no network interface exists. @@ -248,7 +247,7 @@ socket with a network address for which no network interface exists. .Sh HISTORY The implementation is based on KAME stack .Po -which is descendant of WIDE hydrangea IPv6 stack kit +which is a descendant of WIDE hydrangea IPv6 stack kit .Pc . .Pp Part of the document was shamelessly copied from RFC2292. diff --git a/share/man/man4/inet6.4 b/share/man/man4/inet6.4 index 97cc21287ba..43317b7d533 100644 --- a/share/man/man4/inet6.4 +++ b/share/man/man4/inet6.4 @@ -1,4 +1,4 @@ -.\" $OpenBSD: inet6.4,v 1.23 2002/06/07 17:33:14 itojun Exp $ +.\" $OpenBSD: inet6.4,v 1.24 2003/01/18 23:53:49 deraadt Exp $ .\" $KAME: inet6.4,v 1.19 2000/11/24 10:13:18 itojun Exp $ .\" .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. @@ -40,7 +40,7 @@ .Sh DESCRIPTION The .Nm -family is an updated version of +family is an updated version of the .Xr inet 4 family. While @@ -97,18 +97,18 @@ to effect .Dq wildcard matching on incoming messages. .Pp -IPv6 specification defines scoped address, +The IPv6 specification defines scoped address, like link-local or site-local address. A scoped address is ambiguous to the kernel, -if it is specified without scope identifier. -To manipulate scoped addresses properly from the userland, -programs must use advanced API defined in RFC2292. -Compact description on the advanced API is available in +if it is specified without a scope identifier. +To manipulate scoped addresses properly from userland, +programs must use the advanced API defined in RFC2292. +A compact description of the advanced API is available in .Xr ip6 4 . If scoped addresses are specified without explicit scope, -the kernel may raise error. +the kernel may raise an error. Note that scoped addresses are not for daily use at this moment, -both from specification and implementation point of view. +both from a specification and an implementation point of view. .Pp KAME implementation supports extended numeric IPv6 address notation for link-local addresses, @@ -125,7 +125,7 @@ The notation is supported by .Xr getaddrinfo 3 and .Xr getnameinfo 3 . -Some of normal userland programs, such as +Some normal userland programs, such as .Xr telnet 1 or .Xr ftp 1 , @@ -133,12 +133,12 @@ are able to use the notation. With special programs like .Xr ping6 8 , -you can specify outgoing interface by extra command line option +an outgoing interface can be specified with an extra command line option to disambiguate scoped addresses. .Pp Scoped addresses are handled specially in the kernel. In the kernel structures like routing tables or interface structure, -scoped addresses will have its interface index embedded into the address. +scoped addresses will have their interface index embedded into the address. Therefore, the address on some of the kernel structure is not the same as that on the wire. The embedded index will become visible on @@ -223,7 +223,7 @@ message protocol is accessible from a raw socket. .\" flag and those to multicast destinations, have the .\" .Dv RTF_PRCLONING .\" flag forcibly enabled (they are thus said to be -.\" .Dq "protocol cloning" ). +.\" .Dq "protocol cloning" . ) .\" .It .\" When the last reference to an IP route is dropped, the route is .\" examined to determine if it was created by cloning such a route. If @@ -271,20 +271,21 @@ message protocol is accessible from a raw socket. .\" packets, whether locally-generated or forwarded, will not. .Ss Interaction between IPv4/v6 sockets .Ox -does not route IPv4 traffic to +does not route IPv4 traffic to an .Dv AF_INET6 socket. The particular behavior in RFC2553 is intentionally omitted for security reasons presented above. -If you need to accept both IPv4 and IPv6 traffic, listen to two sockets. +If both IPv4 and IPv6 traffic need to be accepted, listen to two sockets. .Pp The behavior of .Dv AF_INET6 TCP/UDP socket is documented in RFC2553. -Basically, it says as follows: +Basically, it says the following: +.Pp .Bl -bullet -compact .It -Specific bind on +A specific bind to an .Dv AF_INET6 socket .Po @@ -293,8 +294,7 @@ with address specified .Pc should accept IPv6 traffic to that address only. .It -If you perform wildcard bind -on +If a wildcard bind is performed on an .Dv AF_INET6 socket .Po @@ -326,12 +326,12 @@ socket. .Pp However, RFC2553 does not define the constraint between the order of .Xr bind 2 , -nor how IPv4 TCP/UDP port number and IPv6 TCP/UDP port number -relate each other +nor how IPv4 TCP/UDP port numbers and IPv6 TCP/UDP port numbers +relate to each other .Po should they be integrated or separated .Pc . -Implemented behavior is very different across kernel to kernel. +Implemented behavior is very different from kernel to kernel. Therefore, it is unwise to rely too much upon the behavior of .Dv AF_INET6 wildcard bind socket. @@ -339,7 +339,7 @@ It is recommended to listen to two sockets, one for .Dv AF_INET and another for .Dv AF_INET6 , -when you would like to accept both IPv4 and IPv6 traffic. +if both IPv4 and IPv6 traffic are to be accepted. .Pp It should also be noted that malicious parties can take advantage of the complexity presented above, @@ -347,8 +347,8 @@ and are able to bypass access control, if the target node routes IPv4 traffic to .Dv AF_INET6 socket. -Users are advised to take caution handling connections -from IPv4 mapped address to +Caution should be taken when handling connections +from IPv4 mapped addresses to .Dv AF_INET6 sockets. .Sh SEE ALSO @@ -373,16 +373,15 @@ sockets. .Sh HISTORY The .Nm -protocol interface are defined in RFC2553 and RFC2292. +protocol interface is defined in RFC2553 and RFC2292. The implementation described herein appeared in WIDE/KAME project. .Sh BUGS The IPv6 support is subject to change as the Internet protocols develop. Users should not depend on details of the current implementation, but rather the services exported. .Pp -Users are suggested to implement -.Dq version independent -code as much as possible, as you will need to support both +.Dq Version independent +code should be implemented as much as possible in order to support both .Xr inet 4 and .Nm inet6 . diff --git a/share/man/man4/ip6.4 b/share/man/man4/ip6.4 index bafd30f885d..53573c47088 100644 --- a/share/man/man4/ip6.4 +++ b/share/man/man4/ip6.4 @@ -1,4 +1,4 @@ -.\" $OpenBSD: ip6.4,v 1.12 2002/09/26 07:55:40 miod Exp $ +.\" $OpenBSD: ip6.4,v 1.13 2003/01/18 23:53:49 deraadt Exp $ .\" $KAME: ip6.4,v 1.12 2000/06/08 21:19:39 itojun Exp $ .\" .\" Copyright (C) 1999 WIDE Project. @@ -98,7 +98,7 @@ The basic API looks very similar to the API presented in .Xr ip 4 . Advanced API uses ancillary data and can handle more complex cases. .Pp -To specify some of socket options, certain privilege +To specify some socket options, a certain level of privilege (i.e. root privilege) is required. .\" .Ss Basic IPv6 sockets API @@ -106,7 +106,8 @@ To specify some of socket options, certain privilege may be used to set the hoplimit field in the .Tn IPv6 header. -As symbol name suggests, the option controls hoplimit field on unicast packets. +As the symbol name suggests, the option controls the hoplimit field +on unicast packets. If -1 is specified, the kernel will use a default value. If a value of 0 to 255 is specified, the packet will have the specified value as hoplimit. @@ -142,7 +143,7 @@ Multicast datagrams with a hoplimit of 0 will not be transmitted on any network, but may be delivered locally if the sending host belongs to the destination group and if multicast loopback has not been disabled on the sending socket (see below). -Multicast datagrams with hoplimit greater than 1 may be forwarded +Multicast datagrams with a hoplimit greater than 1 may be forwarded to other networks if a multicast router is attached to the local network. .Pp For hosts with multiple interfaces, each multicast transmission is @@ -174,7 +175,7 @@ setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_LOOP, &loop, sizeof(loop)); .Pp This option improves performance for applications that may have no more than one -instance on a single host (such as a router demon), by eliminating +instance on a single host (such as a router daemon), by eliminating the overhead of receiving their own transmissions. It should generally not be used by applications for which there may be more than one instance on a single host (such as a conferencing @@ -276,34 +277,34 @@ will be available via on ancillary data stream. You can pick the structure by checking for an ancillary data item with .Li cmsg_level -equals to +equal to .Dv IPPROTO_IPV6 , and .Li cmsg_type -equals to +equal to .Dv IPV6_PKTINFO . .Pp If .Dv IPV6_HOPLIMIT -is enabled, hoplimit value on the packet will be made available to the +is enabled, the hoplimit value on the packet will be made available to the userland program. -Ancillary data stream will contain an integer data item with +The ancillary data stream will contain an integer data item with .Li cmsg_level -equals to +equal to .Dv IPPROTO_IPV6 , and .Li cmsg_type -equals to +equal to .Dv IPV6_HOPLIMIT . .Pp .Xr inet6_option_space 3 -and friends will help you parse ancillary data items for +and friends help parse ancillary data items for .Dv IPV6_HOPOPTS and .Dv IPV6_DSTOPTS . Similarly, .Xr inet6_rthdr_space 3 -and friends will help you parse ancillary data items for +and friends help parse ancillary data items for .Dv IPV6_RTHDR . .Pp .Dv IPV6_HOPOPTS @@ -311,19 +312,19 @@ and .Dv IPV6_DSTOPTS may appear multiple times on an ancillary data stream (note that the behavior is slightly different than the specification). -Other ancillary data item will appear no more than once. +Other ancillary data items can appear no more than once. .Pp For outgoing direction, -you can pass ancillary data items with normal payload data, using +ancillary data items with normal payload data can be passed using .Xr sendmsg 2 . Ancillary data items will be parsed by the kernel, and used to construct the IPv6 header and extension headers. For the 5 .Li cmsg_level -values listed above, ancillary data format is the same as inbound case. -Additionally, you can specify +values listed above, the ancillary data format is the same as the inbound case. +Additionally, the .Dv IPV6_NEXTHOP -data object. +data object can also be specified. The .Dv IPV6_NEXTHOP ancillary data object specifies the next hop for the @@ -354,10 +355,11 @@ equivalent to the existing .Dv SO_DONTROUTE socket option. .Pp -For applications that do not, or unable to use +For applications that do not, or are unable to use .Xr sendmsg 2 or .Xr recvmsg 2 , +the .Dv IPV6_PKTOPTIONS socket option is defined. Setting the socket option specifies any of the optional output fields: @@ -441,13 +443,13 @@ it can be manipulated by .Dv IPV6_MULTICAST_IF in basic API, .Dv IPV6_PKTINFO -in advanced API, and +in advanced API, and the .Li sin6_scope_id field of the socket address passed to .Xr sendto 2 . .Pp When conflicting options are given to the kernel, -the kernel will get the value in the following preference: +the kernel will get the value in the following order of preference: (1) options specified by using ancillary data, (2) options specified by a sticky option of the advanced API, (3) options specified by using the basic API, and lastly @@ -490,9 +492,9 @@ Outgoing packets automatically have an .Tn IPv6 header prepended to them (based on the destination address and the protocol number the socket is created with). -Incoming packets are received without +Incoming packets are received without an .Tn IPv6 -header nor extension headers. +header or extension headers. .Pp All data sent via raw sockets MUST be in network byte order and all data received via raw sockets will be in network byte order. @@ -545,15 +547,15 @@ when used as a next-header field). .\" socket option was added. .Pp For ICMPv6 raw sockets, -the kernel will calculate and insert the ICMPv6 checksum for +the kernel will calculate and insert the ICMPv6 checksum since this checksum is mandatory. .Pp For other raw IPv6 sockets (that is, for raw IPv6 sockets created with a third argument other than IPPROTO_ICMPV6), the application must set the new IPV6_CHECKSUM socket option to have the kernel (1) -compute and store a pseudo header checksum for output, +compute and store a pseudo-header checksum for output, and (2) verify the received -pseudo header checksum on input, +pseudo-header checksum on input, discarding the packet if the checksum is in error. This option prevents applications from having to perform source address selection on the packets they send. @@ -583,12 +585,12 @@ A socket operation may fail with one of the following errors returned: .It Bq Er EISCONN when trying to establish a connection on a socket which already has one, or when trying to send a datagram with the destination -address specified and the socket is already connected; +address specified and the socket is already connected. .It Bq Er ENOTCONN when trying to send a datagram, but no destination address is -specified, and the socket hasn't been connected; +specified, and the socket hasn't been connected. .It Bq Er ENOBUFS -when the system runs out of memory for an internal data structure; +when the system runs out of memory for an internal data structure. .It Bq Er EADDRNOTAVAIL when an attempt is made to create a socket with a network address for which no network interface exists. @@ -652,7 +654,7 @@ is not defined in the RFCs and should be considered implementation dependent. .Sh HISTORY The implementation is based on KAME stack .Po -which is descendant of WIDE hydrangea IPv6 stack kit +which is a descendant of WIDE hydrangea IPv6 stack kit .Pc . .Pp Part of the document was shamelessly copied from RFC2553 and RFC2292. -- cgit v1.2.3