[src/trunk]: src/share/man/man4 move kame_ipsec.4 almost completely into ipse...

[drochner <drochner%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/92e9184eb3c6
branches:  trunk
changeset: 772786:92e9184eb3c6
user:      drochner <drochner%NetBSD.org@localhost>
date:      Mon Jan 16 16:27:59 2012 +0000

description:
move kame_ipsec.4 almost completely into ipsec.4 because it is valid
for fast_ipsec as well

diffstat:

 share/man/man4/ipsec.4      |  415 +++++++++++++++++++++++++++++++++----------
 share/man/man4/kame_ipsec.4 |  235 +------------------------
 2 files changed, 322 insertions(+), 328 deletions(-)

diffs (truncated from 710 to 300 lines):

diff -r 73e114226ae4 -r 92e9184eb3c6 share/man/man4/ipsec.4
--- a/share/man/man4/ipsec.4    Mon Jan 16 15:33:50 2012 +0000
+++ b/share/man/man4/ipsec.4    Mon Jan 16 16:27:59 2012 +0000
@@ -1,11 +1,8 @@
-.\"    $NetBSD: ipsec.4,v 1.34 2012/01/09 16:35:20 wiz Exp $
-.\"    $FreeBSD: fast_ipsec.4,v 1.2 2003/03/03 11:51:30 ru Exp $
+.\"    $NetBSD: ipsec.4,v 1.35 2012/01/16 16:27:59 drochner Exp $
+.\"    $KAME: ipsec.4,v 1.17 2001/06/27 15:25:10 itojun Exp $
 .\"
-.\" Copyright (c) 2004
-.\"    Jonathan Stone <jonathan%dsg.stanford.edu@localhost>. All rights reserved.
-.\"
-.\" Copyright (c) 2003
-.\"    Sam Leffler <sam%errno.com@localhost>. All rights reserved.
+.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
+.\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -15,112 +12,330 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the project nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
 .\"
-.\" THIS SOFTWARE IS PROVIDED BY Sam Leffler AND CONTRIBUTORS ``AS IS'' AND
+.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL Bill Paul OR THE VOICES IN HIS HEAD
-.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
-.\" THE POSSIBILITY OF SUCH DAMAGE.
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
 .\"
-.Dd January 9, 2012
+.Dd May 16, 2009
 .Dt IPSEC 4
 .Os
 .Sh NAME
-.Nm fast_ipsec
-.Nd Fast IPsec hardware-accelerated IP Security Protocols
-.Sh SYNOPSIS
-.Cd "options IPSEC"
-.Cd "options IPSEC_DEBUG"
-.Cd "options IPSEC_NAT_T"
+.Nm ipsec
+.Nd IP security protocol
 .Sh DESCRIPTION
-.Tn IPsec
-is a set of protocols,
-.Tn ESP
-(for Encapsulating Security Payload)
-.Tn AH
-(for Authentication Header),
+.Nm
+is a security protocol in Internet Protocol (IP) layer.
+.Nm
+is defined for both IPv4 and IPv6
+.Po
+.Xr inet 4
+and
+.Xr inet6 4
+.Pc .
+.Nm
+consists of two sub-protocols:
+.Pp
+.Bl -hang
+.It Em Encapsulated Security Payload Pq ESP
+protects IP payload from wire-tapping (interception) by encrypting it with
+secret key cryptography algorithms.
+.It Em Authentication Header Pq AH
+guarantees integrity of IP packet
+and protects it from intermediate alteration or impersonation,
+by attaching cryptographic checksum computed by one-way hash functions.
+.El
+.Pp
+.Nm
+has two operation modes:
+.Pp
+.Bl -hang
+.It Em Transport mode
+is for protecting peer-to-peer communication between end nodes.
+.It Em Tunnel mode
+includes IP-in-IP encapsulation operation
+and is designed for security gateways, as in Virtual Private Network
+.Pq Tn VPN
+configurations.
+.El
+.Pp
+Since version 6,
+.Nx
+uses the IPSEC implementation formerly known as FAST_IPSEC.
+Its specifics and kernel options are describes in the
+.Xr fast_ipsec 4
+manual page.
+The previous implementation is still supported for a transition
+period. See
+.Xr kame_ipsec 4
+for details.
+.Pp
+.Ss Kernel interface
+.Nm
+is controlled by key management engine and policy engine,
+in the operating system kernel.
+.Pp
+Key management engine can be accessed from the userland by using
+.Dv PF_KEY
+sockets.
+The
+.Dv PF_KEY
+socket API is defined in RFC2367.
+.Pp
+Policy engine can be controlled by extended part of
+.Dv PF_KEY
+API,
+.Xr setsockopt 2
+operations, and
+.Xr sysctl 3
+interface.
+The kernel implements
+extended version of
+.Dv PF_KEY
+interface, and allows you to define IPsec policy like per-packet filters.
+.Xr setsockopt 2
+interface is used to define per-socket behavior, and
+.Xr sysctl 3
+interface is used to define host-wide default behavior.
+.Pp
+The kernel code does not implement dynamic encryption key exchange protocol
+like IKE
+.Pq Internet Key Exchange .
+That should be implemented as userland programs
+.Pq usually as daemons ,
+by using the above described APIs.
+.\"
+.Ss Policy management
+The kernel implements experimental policy management code.
+You can manage the IPsec policy in two ways.
+One is to configure per-socket policy using
+.Xr setsockopt 2 .
+The other is to configure kernel packet filter-based policy using
+.Dv PF_KEY
+interface, via
+.Xr setkey 8 .
+In both cases, IPsec policy must be specified with syntax described in
+.Xr ipsec_set_policy 3 .
+.Pp
+With
+.Xr setsockopt 2 ,
+you can define IPsec policy in per-socket basis.
+You can enforce particular IPsec policy onto packets that go through
+particular socket.
+.Pp
+With
+.Xr setkey 8
+you can define IPsec policy against packets,
+using sort of packet filtering rule.
+Refer to
+.Xr setkey 8
+on how to use it.
+.Pp
+In the latter case,
+.Dq Li default
+policy is allowed for use with
+.Xr setkey 8 .
+By configuring policy to
+.Li default ,
+you can refer system-wide
+.Xr sysctl 8
+variable for default settings.
+The following variables are available.
+.Li 1
+means
+.Dq Li use ,
 and
-.Tn IPComp
-(for IP Payload Compression Protocol)
-that provide security services for IP datagrams.
-Fast IPsec
-is an implementation of these protocols that uses the
-.Xr opencrypto 9
-subsystem to carry out cryptographic operations.
-This means, in particular, that cryptographic hardware devices are
-employed whenever possible to optimize the performance of these protocols.
+.Li 2
+means
+.Dq Li require
+in the syntax.
+.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx
+.It Sy Name Ta Sy Type Ta Sy Changeable
+.It net.inet.ipsec.esp_trans_deflev Ta integer Ta yes
+.It net.inet.ipsec.esp_net_deflev Ta integer Ta yes
+.It net.inet.ipsec.ah_trans_deflev Ta integer Ta yes
+.It net.inet.ipsec.ah_net_deflev Ta integer Ta yes
+.It net.inet6.ipsec6.esp_trans_deflev Ta integer Ta yes
+.It net.inet6.ipsec6.esp_net_deflev Ta integer Ta yes
+.It net.inet6.ipsec6.ah_trans_deflev Ta integer Ta yes
+.It net.inet6.ipsec6.ah_net_deflev Ta integer Ta yes
+.El
+.Pp
+If kernel finds no matching policy system wide default value is applied.
+System wide default is specified by the following
+.Xr sysctl 8
+variables.
+.Li 0
+means
+.Dq Li discard
+which asks the kernel to drop the packet.
+.Li 1
+means
+.Dq Li none .
+.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx
+.It Sy Name Ta Sy Type Ta Sy Changeable
+.It net.inet.ipsec.def_policy Ta integer Ta yes
+.It net.inet6.ipsec6.def_policy Ta integer Ta yes
+.El
+.\"
+.Ss Miscellaneous sysctl variables
+The following variables are accessible via
+.Xr sysctl 8 ,
+for tweaking kernel IPsec behavior:
+.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx
+.It Sy Name Ta Sy Type Ta Sy Changeable
+.It net.inet.ipsec.ah_cleartos Ta integer Ta yes
+.It net.inet.ipsec.ah_offsetmask Ta integer Ta yes
+.It net.inet.ipsec.dfbit Ta integer Ta yes
+.It net.inet.ipsec.ecn Ta integer Ta yes
+.It net.inet.ipsec.debug Ta integer Ta yes
+.It net.inet6.ipsec6.ecn Ta integer Ta yes
+.It net.inet6.ipsec6.debug Ta integer Ta yes
+.El
 .Pp
-In general, the
-Fast IPsec
-implementation is intended to be compatible with the
-.Tn KAME IPsec
-implementation.
-This documentation concentrates on differences from that software.
-The user should refer to
-.Xr kame_ipsec 4
-for basic information on setting up and using these protocols.
+The variables are interpreted as follows:
+.Bl -tag -width "123456"
+.It Li ipsec.ah_cleartos
+If set to non-zero, the kernel clears type-of-service field in the IPv4 header
+during AH authentication data computation.
+The variable is for tweaking AH behavior to interoperate with devices that
+implement RFC1826 AH.
+It should be set to non-zero
+.Pq clear the type-of-service field
+for RFC2402 conformance.
+.It Li ipsec.ah_offsetmask
+During AH authentication data computation, the kernel will include
+16bit fragment offset field
+.Pq including flag bits
+in IPv4 header, after computing logical AND with the variable.
+The variable is for tweaking AH behavior to interoperate with devices that
+implement RFC1826 AH.
+It should be set to zero
+.Pq clear the fragment offset field during computation
+for RFC2402 conformance.
+.It Li ipsec.dfbit
+The variable configures the kernel behavior on IPv4 IPsec tunnel encapsulation.
+If set to 0, DF bit on the outer IPv4 header will be cleared.
+1 means that the outer DF bit is set regardless from the inner DF bit.
+2 means that the DF bit is copied from the inner header to the outer.
+The variable is supplied to conform to RFC2401 chapter 6.1.
+.It Li ipsec.ecn
+If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior will
+be friendly to ECN
+.Pq explicit congestion notification ,
+as documented in
+.Li draft-ietf-ipsec-ecn-02.txt .
+.Xr gif 4
+talks more about the behavior.
+.It Li ipsec.debug
+If set to non-zero, debug messages will be generated via
+.Xr syslog 3 .
+.El
 .Pp
-System configuration requires the
-.Xr opencrypto 9
-subsystem.
-When the
-Fast IPsec
-protocols are configured for use, all protocols are included in the system.