1.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the project nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $NetBSD: ipsec.4,v 1.4 2000/01/19 06:59:32 itojun Exp $ 29.\" KAME Id: ipsec.4,v 1.4 2000/01/19 06:56:51 itojun Exp 30.\" 31.Dd January 29, 1999 32.Dt IPSEC 4 33.Os 34.Sh NAME 35.Nm ipsec 36.Nd IP security protocol 37.Sh SYNOPSIS 38.Fd #include <sys/types.h> 39.Fd #include <netinet/in.h> 40.Fd #include <netinet6/ipsec.h> 41.Sh DESCRIPTION 42.Nm 43is a security protocol in Internet Protocol layer. 44.Nm 45is defined for both IPv4 and IPv6 46.Po 47.Xr inet 4 48and 49.Xr inet6 4 50.Pc . 51.Nm 52consists of two sub-protocols, namely 53ESP 54.Pq encapsulated security payload 55and AH 56.Pq authentication header . 57ESP protects IP payload from wire-tapping by encrypting it by 58secret key cryptography algorithms. 59AH guarantees integrity of IP packet 60and protects it from intermediate alteration or impersonation, 61by attaching cryptographic checksum computed by one-way hash functions. 62.Nm 63has two operation modes: transport mode and tunnel mode. 64Transport mode is for protecting peer-to-peer commuication between end nodes. 65Tunnel mode includes IP-in-IP encapsulation operation 66and is designed for security gateways, like VPN configurations. 67.\" 68.Sh KERNEL INTERFACE 69.Nm 70is controlled by key management engine, and policy engine in the 71operating system kernel. 72.Pp 73Key management engine can be accessed from the userland by using 74.Dv PF_KEY 75sockets. 76The 77.Dv PF_KEY 78socket API is defined in RFC2367. 79.Pp 80Policy engine can be controlled by extended part of 81.Dv PF_KEY 82API, 83.Xr setsockopt 2 84operations, and 85.Xr sysctl 3 86interface. 87The kernel implements 88extended version of 89.Dv PF_KEY 90interface, and allows you to define IPsec policy like per-packet filters. 91.Xr setsockopt 2 92interface is used to define per-socket behavior, and 93.Xr sysctl 3 94interface is used to define host-wide default behavior. 95.Pp 96The kernel code does not implement dynamic encryption key exchange protocol 97like IKE 98.Pq Internet Key Exchange . 99That should be implemented as userland programs, or daemons, by using 100the above described APIs. 101.\" 102.Sh POLICY MANAGEMENT 103The policy management code is experimental, but this is almostly 104conformed to RFC2401. You can manage the SPD by two way. One is the way to use 105.Xr setkey 8 , 106and other is the way to use 107.Xr setsockopt 3 . 108.Xr setkey 8 109can define either 110.Nm default , use 111or 112.Nm require 113like filtering rule. 114and 115.Xr setsockopt 3 116can define either 117.Nm entrust , ipsec 118or 119.Nm bypass 120as Security level per socket. 121.Pp 122When 123.Nm default 124(or 125.Nm entrust 126) 127is defined, Policy engine consults to system wide default defined 128.Xr sysctl 8 129.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx 130.It Sy Name Type Changeable 131.It net.inet.ipsec.esp_trans_deflev integer yes 132.It net.inet.ipsec.esp_net_deflev integer yes 133.It net.inet.ipsec.ah_trans_deflev integer yes 134.It net.inet.ipsec.ah_net_deflev integer yes 135.It net.inet6.ipsec6.esp_trans_deflev integer yes 136.It net.inet6.ipsec6.esp_net_deflev integer yes 137.It net.inet6.ipsec6.ah_trans_deflev integer yes 138.It net.inet6.ipsec6.ah_net_deflev integer yes 139.El 140.Pp 141They are 1:use or 2:require. 142.Pp 143If kernel doesn't find out policy entry, then system wide default is applied. 144You can specify the system wide default as discarding packet or not to do IPsec. 145.Bl -column net.inet6.ipsec6.def_policy integerxxx 146.It Sy Name Type Changeable 147.It net.inet.ipsec.def_policy integer yes 148.It net.inet6.ipsec6.def_policy integer yes 149.El 150.Pp 151They are 0:discard or 1:none. 152.\" 153.Sh PROTOCOLS 154The 155.Nm 156protocol works like plug-in to 157.Xr inet 4 158and 159.Xr inet6 4 160protocols. 161Therefore, 162.Nm 163supports most of the protocols defined upon those IP-layer protocols. 164Some of the protocols, like 165.Xr icmp 4 166or 167.Xr icmp6 4 , 168may behave differently with 169.Nm ipsec . 170This is because 171.Nm 172can prevent 173.Xr icmp 4 174or 175.Xr icmp6 4 176routines from looking into IP payload. 177.\" 178.Sh SEE ALSO 179.Xr ioctl 2 , 180.Xr socket 2 , 181.Xr icmp6 4 , 182.Xr intro 4 , 183.Xr ip6 4 , 184.Xr setkey 8 , 185.Xr sysctl 8 , 186.Xr racoon 8 187.Pp 188.Rs 189.%A Daniel L. McDonald 190.%A Craig Metz 191.%A Bao G. Phan 192.%T "PF_KEY Key Management API, Version 2" 193.%R RFC 194.%N 2367 195.Re 196.Rs 197.%A "D. L. McDonald" 198.%T "A Simple IP Security API Extension to BSD Sockets" 199.%R internet draft 200.%N "draft-mcdonald-simple-ipsec-api-03.txt" 201.%O work in progress material 202.Re 203.Sh CAVEAT 204The IPsec support is subject to change as the IPsec protocols develop. 205.Pp 206There is no single standard for policy engine API, 207so the policy engine API described herein is just for KAME implementation. 208.\" 209.Sh HISTORY 210The implementation described herein appeared in WIDE/KAME IPv6/IPsec stack. 211