[apple/xnu.git] / bsd / man / man4 / ipsec.4

.\"	$FreeBSD: src/share/man/man4/ipsec.4,v 1.3.2.10 2001/12/17 11:30:12 ru Exp $
.\"	$KAME: ipsec.4,v 1.17 2001/06/27 15:25:10 itojun Exp $
.\"
.\" 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.
.\"
.Dd January 29, 1999
.Dt IPSEC 4
.Os
.Sh NAME
.Nm ipsec
.Nd IP security protocol
.Sh SYNOPSIS
.In sys/types.h
.In netinet/in.h
.In netinet6/ipsec.h
.Sh DESCRIPTION
.Nm
is a security protocol in Internet Protocol layer.
.Nm
is defined for both IPv4 and IPv6
.Xr ( inet 4
and
.Xr inet6 4 ) .
.Nm
consists of two sub-protocols, namely
ESP
(encapsulated security payload)
and AH
(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 communication between end nodes.
Tunnel mode includes IP-in-IP encapsulation operation
and is designed for security gateways, like VPN configurations.
.\"
.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
(Internet Key Exchange).
That should be implemented as userland programs
(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	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
.\"
.Ss Miscellaneous sysctl variables
The following variables are accessible via
.Xr sysctl 8 ,
for tweaking kernel IPsec behavior:
.Bl -column net.inet6.ipsec6.inbonud_call_ike integerxxx
.It Sy "Name	Type	Changeable"
.It "net.inet.ipsec.ah_cleartos	integer	yes"
.It "net.inet.ipsec.ah_offsetmask	integer	yes"
.It "net.inet.ipsec.dfbit	integer	yes"
.It "net.inet.ipsec.ecn	integer	yes"
.It "net.inet.ipsec.debug	integer	yes"
.It "net.inet6.ipsec6.ecn	integer	yes"
.It "net.inet6.ipsec6.debug	integer	yes"
.El
.Pp
The variables are interpreted as follows:
.Bl -tag -width 6n
.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
(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
(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
(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
(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 .
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
.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
.Pp
.Rs
.%A "D. L. McDonald"
.%T "A Simple IP Security API Extension to BSD Sockets"
.%R internet draft
.%N "draft-mcdonald-simple-ipsec-api-03.txt"
.%O work in progress material
.Re
.Sh HISTORY
The implementation described herein appeared in WIDE/KAME IPv6/IPsec stack.
.Sh BUGS
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.
.Pp
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
(like
.Dq Li esp/tunnel/A-B/use ah/transport/A-B/require ) ,
tunnelled packets will be rejected.
This is because we enforce policy check on inner packet on reception,
and AH authenticates encapsulating
(outer)
packet, not the encapsulated
(inner)
packet
(so for the receiving kernel there's no sign of authenticity).
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.
Commit	Line	Data
9bccf70c A	1	.\" $FreeBSD: src/share/man/man4/ipsec.4,v 1.3.2.10 2001/12/17 11:30:12 ru Exp $
	2	.\" $KAME: ipsec.4,v 1.17 2001/06/27 15:25:10 itojun Exp $
	3	.\"
	4	.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
	5	.\" All rights reserved.
	6	.\"
	7	.\" Redistribution and use in source and binary forms, with or without
	8	.\" modification, are permitted provided that the following conditions
	9	.\" are met:
	10	.\" 1. Redistributions of source code must retain the above copyright
	11	.\" notice, this list of conditions and the following disclaimer.
	12	.\" 2. Redistributions in binary form must reproduce the above copyright
	13	.\" notice, this list of conditions and the following disclaimer in the
	14	.\" documentation and/or other materials provided with the distribution.
	15	.\" 3. Neither the name of the project nor the names of its contributors
	16	.\" may be used to endorse or promote products derived from this software
	17	.\" without specific prior written permission.
	18	.\"
	19	.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
	20	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	21	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	22	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
	23	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	24	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	25	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	26	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	27	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	28	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	29	.\" SUCH DAMAGE.
	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	.In sys/types.h
	39	.In netinet/in.h
	40	.In netinet6/ipsec.h
	41	.Sh DESCRIPTION
	42	.Nm
	43	is a security protocol in Internet Protocol layer.
	44	.Nm
	45	is defined for both IPv4 and IPv6
	46	.Xr ( inet 4
	47	and
	48	.Xr inet6 4 ) .
	49	.Nm
	50	consists of two sub-protocols, namely
	51	ESP
	52	(encapsulated security payload)
	53	and AH
	54	(authentication header).
	55	ESP protects IP payload from wire-tapping by encrypting it by
	56	secret key cryptography algorithms.
	57	AH guarantees integrity of IP packet
	58	and protects it from intermediate alteration or impersonation,
	59	by attaching cryptographic checksum computed by one-way hash functions.
	60	.Nm
	61	has two operation modes: transport mode and tunnel mode.
	62	Transport mode is for protecting peer-to-peer communication between end nodes.
	63	Tunnel mode includes IP-in-IP encapsulation operation
	64	and is designed for security gateways, like VPN configurations.
65	.\"
66	.Ss Kernel interface
67	.Nm
68	is controlled by key management engine and policy engine,
69	in the operating system kernel.
70	.Pp
71	Key management engine can be accessed from the userland by using
72	.Dv PF_KEY
73	sockets.
74	The
75	.Dv PF_KEY
76	socket API is defined in RFC2367.
77	.Pp
78	Policy engine can be controlled by extended part of
79	.Dv PF_KEY
80	API,
81	.Xr setsockopt 2
82	operations, and
83	.Xr sysctl 3
84	interface.
85	The kernel implements
86	extended version of
87	.Dv PF_KEY
88	interface, and allows you to define IPsec policy like per-packet filters.
89	.Xr setsockopt 2
90	interface is used to define per-socket behavior, and
91	.Xr sysctl 3
92	interface is used to define host-wide default behavior.
93	.Pp
94	The kernel code does not implement dynamic encryption key exchange protocol
95	like IKE
96	(Internet Key Exchange).
97	That should be implemented as userland programs
98	(usually as daemons),
99	by using the above described APIs.
100	.\"
101	.Ss Policy management
102	The kernel implements experimental policy management code.
103	You can manage the IPsec policy in two ways.
104	One is to configure per-socket policy using
105	.Xr setsockopt 2 .
106	The other is to configure kernel packet filter-based policy using
107	.Dv PF_KEY
108	interface, via
109	.Xr setkey 8 .
110	In both cases, IPsec policy must be specified with syntax described in
111	.Xr ipsec_set_policy 3 .
112	.Pp
113	With
114	.Xr setsockopt 2 ,
115	you can define IPsec policy in per-socket basis.
116	You can enforce particular IPsec policy onto packets that go through
117	particular socket.
118	.Pp
119	With
120	.Xr setkey 8
121	you can define IPsec policy against packets,
122	using sort of packet filtering rule.
123	Refer to
124	.Xr setkey 8
125	on how to use it.
126	.Pp
127	In the latter case,
128	.Dq Li default
129	policy is allowed for use with
130	.Xr setkey 8 .
131	By configuring policy to
132	.Li default ,
133	you can refer system-wide
134	.Xr sysctl 8
135	variable for default settings.
136	The following variables are available.
137	.Li 1
138	means
139	.Dq Li use ,
140	and
141	.Li 2
142	means
143	.Dq Li require
144	in the syntax.
145	.Bl -column net.inet6.ipsec6.esp_trans_deflev integerxxx
146	.It Sy "Name Type Changeable"
147	.It "net.inet.ipsec.esp_trans_deflev integer yes"
148	.It "net.inet.ipsec.esp_net_deflev integer yes"
149	.It "net.inet.ipsec.ah_trans_deflev integer yes"
150	.It "net.inet.ipsec.ah_net_deflev integer yes"
151	.It "net.inet6.ipsec6.esp_trans_deflev integer yes"
152	.It "net.inet6.ipsec6.esp_net_deflev integer yes"
153	.It "net.inet6.ipsec6.ah_trans_deflev integer yes"
154	.It "net.inet6.ipsec6.ah_net_deflev integer yes"
155	.El
156	.Pp
157	If kernel finds no matching policy system wide default value is applied.
158	System wide default is specified by the following
159	.Xr sysctl 8
160	variables.
161	.Li 0
162	means
163	.Dq Li discard
164	which asks the kernel to drop the packet.
165	.Li 1
166	means
167	.Dq Li none .
168	.Bl -column net.inet6.ipsec6.def_policy integerxxx
169	.It Sy "Name Type Changeable"
170	.It "net.inet.ipsec.def_policy integer yes"
171	.It "net.inet6.ipsec6.def_policy integer yes"
172	.El
173	.\"
174	.Ss Miscellaneous sysctl variables
175	The following variables are accessible via
176	.Xr sysctl 8 ,
177	for tweaking kernel IPsec behavior:
178	.Bl -column net.inet6.ipsec6.inbonud_call_ike integerxxx
179	.It Sy "Name Type Changeable"
180	.It "net.inet.ipsec.ah_cleartos integer yes"
181	.It "net.inet.ipsec.ah_offsetmask integer yes"
182	.It "net.inet.ipsec.dfbit integer yes"
183	.It "net.inet.ipsec.ecn integer yes"
184	.It "net.inet.ipsec.debug integer yes"
185	.It "net.inet6.ipsec6.ecn integer yes"
186	.It "net.inet6.ipsec6.debug integer yes"
187	.El
188	.Pp
189	The variables are interpreted as follows:
190	.Bl -tag -width 6n
191	.It Li ipsec.ah_cleartos
192	If set to non-zero, the kernel clears type-of-service field in the IPv4 header
193	during AH authentication data computation.
194	The variable is for tweaking AH behavior to interoperate with devices that
195	implement RFC1826 AH.
196	It should be set to non-zero
197	(clear the type-of-service field)
198	for RFC2402 conformance.
199	.It Li ipsec.ah_offsetmask
200	During AH authentication data computation, the kernel will include
201	16bit fragment offset field
202	(including flag bits)
203	in IPv4 header, after computing logical AND with the variable.
204	The variable is for tweaking AH behavior to interoperate with devices that
205	implement RFC1826 AH.
206	It should be set to zero
207	(clear the fragment offset field during computation)
208	for RFC2402 conformance.
209	.It Li ipsec.dfbit
210	The variable configures the kernel behavior on IPv4 IPsec tunnel encapsulation.
211	If set to 0, DF bit on the outer IPv4 header will be cleared.
212	1 means that the outer DF bit is set regardless from the inner DF bit.
213	2 means that the DF bit is copied from the inner header to the outer.
214	The variable is supplied to conform to RFC2401 chapter 6.1.
215	.It Li ipsec.ecn
216	If set to non-zero, IPv4 IPsec tunnel encapsulation/decapsulation behavior will
217	be friendly to ECN
218	(explicit congestion notification),
219	as documented in
220	.Li draft-ietf-ipsec-ecn-02.txt .
221	.Xr gif 4
222	talks more about the behavior.
223	.It Li ipsec.debug
224	If set to non-zero, debug messages will be generated via
225	.Xr syslog 3 .
226	.El
227	.Pp
228	Variables under
229	.Li net.inet6.ipsec6
230	tree has similar meaning as the
231	.Li net.inet.ipsec
232	counterpart.
233	.\"
234	.Sh PROTOCOLS
235	The
236	.Nm
237	protocol works like plug-in to
238	.Xr inet 4
239	and
240	.Xr inet6 4
241	protocols.
242	Therefore,
243	.Nm
244	supports most of the protocols defined upon those IP-layer protocols.
245	Some of the protocols, like
246	.Xr icmp 4
247	or
248	.Xr icmp6 4 ,
249	may behave differently with
250	.Nm .
251	This is because
252	.Nm
253	can prevent
254	.Xr icmp 4
255	or
256	.Xr icmp6 4
257	routines from looking into IP payload.
258	.\"
259	.Sh SEE ALSO
260	.Xr ioctl 2 ,
261	.Xr socket 2 ,
262	.Xr ipsec_set_policy 3 ,
263	.Xr icmp6 4 ,
264	.Xr intro 4 ,
265	.Xr ip6 4 ,
266	.Xr setkey 8 ,
267	.Xr sysctl 8
268	.\".Xr racoon 8
269	.Sh STANDARDS
270	.Rs
271	.%A Daniel L. McDonald
272	.%A Craig Metz
273	.%A Bao G. Phan
274	.%T "PF_KEY Key Management API, Version 2"
275	.%R RFC
276	.%N 2367
277	.Re
278	.Pp
279	.Rs
280	.%A "D. L. McDonald"
281	.%T "A Simple IP Security API Extension to BSD Sockets"
282	.%R internet draft
283	.%N "draft-mcdonald-simple-ipsec-api-03.txt"
284	.%O work in progress material
285	.Re
286	.Sh HISTORY
287	The implementation described herein appeared in WIDE/KAME IPv6/IPsec stack.
288	.Sh BUGS
289	The IPsec support is subject to change as the IPsec protocols develop.
290	.Pp
291	There is no single standard for policy engine API,
292	so the policy engine API described herein is just for KAME implementation.
293	.Pp
294	AH and tunnel mode encapsulation may not work as you might expect.
295	If you configure inbound
296	.Dq require
297	policy against AH tunnel or any IPsec encapsulating policy with AH
298	(like
299	.Dq Li esp/tunnel/A-B/use ah/transport/A-B/require ) ,
300	tunnelled packets will be rejected.
301	This is because we enforce policy check on inner packet on reception,
302	and AH authenticates encapsulating
303	(outer)
304	packet, not the encapsulated
305	(inner)
306	packet
307	(so for the receiving kernel there's no sign of authenticity).
308	The issue will be solved when we revamp our policy engine to keep all the
309	packet decapsulation history.
310	.Pp
311	Under certain condition,
312	truncated result may be raised from the kernel
313	against
314	.Dv SADB_DUMP
315	and
316	.Dv SADB_SPDDUMP
317	operation on
318	.Dv PF_KEY
319	socket.
320	This occurs if there are too many database entries in the kernel
321	and socket buffer for the
322	.Dv PF_KEY
323	socket is insufficient.
324	If you manipulate many IPsec key/policy database entries,
325	increase the size of socket buffer.