libipsec and IPsec related apps. (and some KAME related man pages)

Reviewed by: freebsd-arch, cvs-committers
Obtained from: KAME project

1 files changed, 228 insertions, 0 deletions

diff --git a/share/man/man4/ipsec.4 b/share/man/man4/ipsec.4
new file mode 100644
index 0000000..6e074fe
--- /dev/null
+++ b/share/man/man4/ipsec.4
@@ -0,0 +1,228 @@
+.\" 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
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 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 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 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.
+.\"
+.\"	$Id: ipsec.4,v 1.2 1999/10/07 03:55:08 itojun Exp $
+.\"     $FreeBSD$
+.\"
+.Dd January 29, 1999
+.Dt IPSEC 4
+.Os KAME
+.Sh NAME
+.Nm ipsec
+.Nd IP security protocol
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <netinet/in.h>
+.Fd #include <netinet6/ipsec.h>
+.Sh DESCRIPTION
+.Nm
+is a security protocol in Internet Protocol layer.
+.Nm
+is defined for both IPv4 and IPv6
+.Po
+.Xr inet 4
+and
+.Xr inet6 4
+.Pc .
+.Nm
+consists of two sub-protocols, namely
+ESP
+.Pq encapsulated security payload
+and AH
+.Pq authentication header .
+ESP protects IP payload from wire-tapping by encrypting it by
+secret key cryptography algorithms.
+AH guarantees integrity of IP packet
+and protects it from intermediate alteration or impersonation,
+by attaching cryptographic checksum computed by one-way hash functions.
+.Nm
+has two operation modes: transport mode and tunnel mode.
+Transport mode is for protecting peer-to-peer commuication between end nodes.
+Tunnel mode includes IP-in-IP encapsulation operation
+and is designed for security gateways, like VPN configurations.
+.\"
+.Sh 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.
+.\"
+.Sh 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 3 .
+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 3 ,
+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
+.Li 2
+means
+.Dq Li require
+in the syntax.
+.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx
+.It Sy Name	Type	Changeable
+.It net.inet.ipsec.esp_trans_deflev	integer	yes
+.It net.inet.ipsec.esp_net_deflev	integer	yes
+.It net.inet.ipsec.ah_trans_deflev	integer	yes
+.It net.inet.ipsec.ah_net_deflev	integer	yes
+.It net.inet6.ipsec6.esp_trans_deflev	integer	yes
+.It net.inet6.ipsec6.esp_net_deflev	integer	yes
+.It net.inet6.ipsec6.ah_trans_deflev	integer	yes
+.It net.inet6.ipsec6.ah_net_deflev	integer	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.def_policy integerxxx
+.It Sy Name	Type	Changeable
+.It net.inet.ipsec.def_policy	integer	yes
+.It net.inet6.ipsec6.def_policy	integer	yes
+.El
+.\"
+.Sh PROTOCOLS
+The
+.Nm
+protocol works like plug-in to
+.Xr inet 4
+and
+.Xr inet6 4
+protocols.
+Therefore,
+.Nm
+supports most of the protocols defined upon those IP-layer protocols.
+Some of the protocols, like 
+.Xr icmp 4
+or
+.Xr icmp6 4 ,
+may behave differently with
+.Nm ipsec .
+This is because
+.Nm
+can prevent
+.Xr icmp 4
+or
+.Xr icmp6 4
+routines from looking into IP payload.
+.\"
+.Sh SEE ALSO
+.Xr ioctl 2 ,
+.Xr socket 2 ,
+.Xr ipsec_set_policy 3 ,
+.Xr icmp6 4 ,
+.Xr intro 4 ,
+.Xr ip6 4 ,
+.Xr setkey 8 ,
+.Xr sysctl 8 ,
+.Xr racoon 8 .
+.Pp
+.Rs
+.%T RFC2367
+.Re
+.Rs
+.%A "D. L. McDonald"
+.%T "A Simple IP Security API Extension to BSD Sockets"
+.%N "draft-mcdonald-simple-ipsec-api-03.txt"
+.%O "internet draft"
+.Re
+.Sh CAVEAT
+The IPsec support is subject to change as the IPsec protocols develop.
+.Pp
+There is no single standard for policy engine API,
+so the policy engine API described herein is just for KAME implementation.
+.\"
+.Sh HISTORY
+The implementation described herein appeared in WIDE/KAME IPv6/IPsec stack.