From 769741476b85c44edd0f9a13649bd120b8fd4a3c Mon Sep 17 00:00:00 2001 From: drochner Date: Mon, 16 Jan 2012 16:27:59 +0000 Subject: [PATCH] move kame_ipsec.4 almost completely into ipsec.4 because it is valid for fast_ipsec as well --- share/man/man4/ipsec.4 | 413 +++++++++++++++++++++++++++--------- share/man/man4/kame_ipsec.4 | 235 +------------------- 2 files changed, 321 insertions(+), 327 deletions(-) diff --git a/share/man/man4/ipsec.4 b/share/man/man4/ipsec.4 index 3b77bec4fa46..d3731286b4be 100644 --- a/share/man/man4/ipsec.4 +++ b/share/man/man4/ipsec.4 @@ -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 . All rights reserved. -.\" -.\" Copyright (c) 2003 -.\" Sam Leffler . 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 -.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. +.Xr inet6 4 +.Pc . +.Nm +consists of two sub-protocols: .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. +.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 -System configuration requires the -.Xr opencrypto 9 -subsystem. -When the -Fast IPsec -protocols are configured for use, all protocols are included in the system. -To selectively enable/disable protocols, use -.Xr sysctl 8 . -.Sh DIAGNOSTICS -To be added. -.Sh SEE ALSO -.Xr kame_ipsec 4 , -.Xr setkey 8 , -.Xr sysctl 8 , -.Xr opencrypto 9 -.Sh HISTORY -The protocols draw heavily on the -.Ox -implementation of the -.Tn IPsec -protocols. -The policy management code is derived from the -.Tn KAME -implementation found in their -.Tn IPsec -protocols. -The -Fast IPsec -protocols are based on code which appeared in -.Fx 4.7 . -The +.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 -version is a close copy of the -.Fx -original, and first appeared in -.Nx 2.0 . +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 -Support for IPv6 and -.Tn IPcomp -protocols has been added in -.Nx 4.0 . +.Ss Kernel interface +.Nm +is controlled by key management engine and policy engine, +in the operating system kernel. .Pp -Support for IPSEC_NAT_T -(Network Address Translator Traversal as -described in RFCs 3947 and 3948) has been added in -.Nx 5.0 . +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 +.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 +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 +Variables under +.Li net.inet6.ipsec6 +tree has similar meaning as the +.Li net.inet.ipsec +counterpart. +.\" +.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 fast_ipsec 4 , +.Xr kame_ipsec 4 , +.Xr icmp6 4 , +.Xr intro 4 , +.Xr ip6 4 , +.Xr racoon 8 , +.Xr setkey 8 , +.Xr sysctl 8 +.Sh STANDARDS +.Rs +.%A Daniel L. McDonald +.%A Craig Metz +.%A Bao G. Phan +.%T "PF_KEY Key Management API, Version 2" +.%R RFC +.%N 2367 +.Re .Sh BUGS -There still are some issues in the IPv6 support. -In particular -.Tn FAST_IPSEC -does not protect packets with IPv6 extension headers. +The IPsec support is subject to change as the IPsec protocols develop. .Pp -Certain legacy authentication algorithms are not supported because of -issues with the -.Xr opencrypto 9 -subsystem. +There is no single standard for policy engine API, +so the policy engine API described herein is just for KAME implementation. .Pp -This documentation is incomplete. +AH and tunnel mode encapsulation may not work as you might expect. +If you configure inbound +.Dq require +policy against AH tunnel or any IPsec encapsulating policy with AH +.Po +like +.Dq Li esp/tunnel/A-B/use ah/transport/A-B/require +.Pc , +tunneled packets will be rejected. +This is because we enforce policy check on inner packet on reception, +and AH authenticates encapsulating +.Pq outer +packet, not the encapsulated +.Pq inner +packet +.Po +so for the receiving kernel there's no sign of authenticity +.Pc . +The issue will be solved when we revamp our policy engine to keep all the +packet decapsulation history. +.Pp +Under certain condition, +truncated result may be raised from the kernel +against +.Dv SADB_DUMP +and +.Dv SADB_SPDDUMP +operation on +.Dv PF_KEY +socket. +This occurs if there are too many database entries in the kernel +and socket buffer for the +.Dv PF_KEY +socket is insufficient. +If you manipulate many IPsec key/policy database entries, +increase the size of socket buffer or use +.Xr sysctl 8 +interface. diff --git a/share/man/man4/kame_ipsec.4 b/share/man/man4/kame_ipsec.4 index c0a928034fdf..2367d8970bb2 100644 --- a/share/man/man4/kame_ipsec.4 +++ b/share/man/man4/kame_ipsec.4 @@ -1,4 +1,4 @@ -.\" $NetBSD: kame_ipsec.4,v 1.1 2012/01/09 15:16:31 drochner Exp $ +.\" $NetBSD: kame_ipsec.4,v 1.2 2012/01/16 16:27:59 drochner Exp $ .\" $KAME: ipsec.4,v 1.17 2001/06/27 15:25:10 itojun Exp $ .\" .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. @@ -29,7 +29,7 @@ .\" SUCH DAMAGE. .\" .Dd May 16, 2009 -.Dt IPSEC 4 +.Dt KAME_IPSEC 4 .Os .Sh NAME .Nm ipsec @@ -45,39 +45,10 @@ .Cd options IPSEC_DEBUG .Sh DESCRIPTION .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 +is the first implemtation of IPSEC in +.Nx . +It is being replaced by +.Xr fast_ipsec 4 . .Pp The following kernel options are available: .Bl -ohang @@ -133,203 +104,11 @@ and .Em IPSEC_ESP . .El .\" -.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 -.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 -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 -Variables under -.Li net.inet6.ipsec6 -tree has similar meaning as the -.Li net.inet.ipsec -counterpart. -.\" -.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 ipsec 4 , .Xr fast_ipsec 4 , .Xr icmp6 4 , .Xr intro 4 ,