1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
|
.\" $OpenBSD: ipsecadm.8,v 1.21 2000/03/18 22:55:59 aaron Exp $
.\"
.\" Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
.\" 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. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by Niels Provos.
.\" 4. The name of the author may not be used to endorse or promote products
.\" derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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.
.\"
.\" Manual page, using -mandoc macros
.\"
.Dd August 26, 1997
.Dt IPSECADM 8
.Os
.Sh NAME
.Nm ipsecadm
.Nd interface to setup IPSec
.Sh SYNOPSIS
.Nm ipsecadm
.Op command
.Ar modifiers ...
.Sh NOTE
Before
.Xr ipsecadm 8
can be used, IPSec must be enabled by setting one or more of the following
.Xr sysctl 3
variables:
.Bl -tag -width xxxxxxxxxxxxxxxxxxxxx
.It net.inet.esp.enable
Enable the ESP IPSec protocol
.It net.inet.ah.enable
Enable the AH IPSec protocol
.El
.Pp
To enable these operations across reboots, see
.Pa /etc/sysctl.conf .
.Pp
.Sh DESCRIPTION
The
.Nm ipsecadm
utility sets up security associations in the kernel
to be used with
.Xr ipsec 4 .
It can be used to specify the encryption and authentication
algorithms and key material for the network layer security
provided by IPSec.
The possible commands are:
.Bl -tag -width new_esp
.It new esp
Setup a Security Association (SA) which uses the new esp transforms.
A SA consists of the destination address,
a Security Parameter Index (SPI) and a security protocol.
Encryption and authentication algorithms can be applied.
This is the default mode.
Allowed
modifiers are:
.Fl dst ,
.Fl src ,
.Fl proxy ,
.Fl spi ,
.Fl enc ,
.Fl auth ,
.Fl authkey ,
.Fl forcetunnel ,
and
.Fl key .
.It old esp
Setup a SA which uses the old esp transforms.
Only encryption algorithms can be applied.
Allowed modifiers are:
.Fl dst ,
.Fl src ,
.Fl proxy ,
.Fl spi ,
.Fl enc ,
.Fl halfiv ,
.Fl forcetunnel ,
and
.Fl key .
.It new ah
Setup a SA which uses the new ah transforms.
Authentication will be done with HMAC using the specified hash algorithm.
Allowed modifiers are:
.Fl dst ,
.Fl src ,
.Fl proxy ,
.Fl spi ,
.Fl forcetunnel ,
.Fl auth ,
and
.Fl key .
.It old ah
Setup a SA which uses the old ah transforms.
Simple keyed hashes will be used for authentication.
Allowed modifiers are:
.Fl dst ,
.Fl src ,
.Fl proxy ,
.Fl spi ,
.Fl forcetunnel ,
.Fl auth ,
and
.Fl key .
.It ip4
Setup an SA which uses the IP-in-IP encapsulation protocol.
This mode
offers no security services by itself, but can be used to route other
(experimental or otherwise) protocols over an IP network.
The SPI value
is not used for anything other than referencing the information, and
does not appear on the wire.
Unlike other setups, like new esp, there
is no necessary setup in the receiving side.
Allowed modifiers are:
.Fl dst ,
.Fl src ,
and
.Fl spi.
.It delspi
The specified SA will be deleted.
Allowed modifiers are:
.Fl dst ,
.Fl spi ,
.Fl proto ,
and
.Fl chain .
.It group
Group two SAs together.
Allowed modifiers are:
.Fl dst ,
.Fl spi ,
.Fl proto ,
.Fl dst2 ,
.Fl spi2 ,
and
.Fl proto2 .
.It flow
Create a flow determining which packets are routed via which Security
Association, or (for ingress flows) which packets may be received over
an incoming SA.
Allowed modifiers are:
.Fl dst ,
.Fl spi ,
.Fl proto ,
.Fl addr ,
.Fl transport ,
.Fl sport ,
.Fl dport ,
.Fl delete ,
.Fl ingress ,
and
.Fl bypass .
The
.Xr netstat 1
command shows the existing egress (outbound) flows.
A
.Nm bypass
flow is used to specify a flow for which IPSec processing will be
bypassed, i.e packets will not be processed by any SAs.
For
.Nm bypass
flows, additional modifiers are restricted to:
.Fl addr ,
.Fl transport ,
.Fl sport ,
.Fl dport ,
and
.Fl delete .
These flows always have SPI 0, destination 0.0.0.0 and protocol 0.
.It bind
Associate an incoming Security Association with an outgoing Security
Association.
When a socket receives packets secured by the incoming SA all
responses will be processed by the outgoing SA.
Allowed modifiers are:
.Fl dst ,
.Fl spi ,
.Fl proto ,
.Fl dst2 ,
.Fl spi2 ,
and
.Fl proto2 .
The IP address 0.0.0.0 can be used as wildcard for
.Fl src
and
.Fl dst .
This can be useful while travelling where the IP address of potential
clients is not known.
.It flush
Flush SAs from from kernel.
This includes flushing any flows and
routing entries associated with the SAs.
Allowed modifiers are:
.Fl ah ,
.Fl esp ,
.Fl oldah ,
.Fl oldesp ,
and
.Fl ip4 .
Default action is to flush all types of security associations
from the kernel.
.El
.Pp
If no command is given
.Xr ipsecadm 1
defaults to new esp mode.
.Pp
The modifiers have the following meanings:
.Bl -tag -width forcetunnel -offset indent
.It src
The source IP address for the SA.
This is necessary for incoming
SAs to avoid source address spoofing between mutually
suspicious hosts that have established SAs with us.
For outgoing SAs,
this field is used to fill in the source address when doing tunneling.
.It dst
The destination IP address for the SA.
.It proxy
This IP address, if provided, is checked against the inner IP address when
doing tunneling to a firewall, to prevent source spoofing attacks.
It is
strongly recommended that this option is provided when applicable.
It is
applicable in a scenario when host A is using IPsec to communicate with
firewall B, and through that to host C.
In that case, the proxy address for
the incoming SA should be C.
This option is not necessary for outgoing SAs.
.It spi
The Security Parameter Index (SPI).
.It tunnel
This option has been deprecated.
The arguments are ignored, and it otherwise has the same effect as the
.Nm forcetunnel
option.
.It newpadding
This option has been deprecated.
.It forcetunnel
Force IP-inside-IP encapsulation before ESP or AH processing is performed for
outgoing packets.
The source/destination addresses of the outgoing IP packet
will be those provided in the
.Nm src
and
.Nm dst
options.
Notice that the IPsec stack will perform IP-inside-IP encapsulation
when deemed necessary, even if this flag has not been set.
.It enc
The encryption algorithm to be used with the SA.
Possible values are:
.Bl -tag -width skipjack
.It Nm des
This is available for both old and new esp.
Notice that hardware crackers for DES can be (and have been) built for
US$250,000 (in 1998).
Use DES for encryption of critical information at your own risk.
We suggest using 3DES instead.
DES support is kept for interoperability
(with old implementations) purposes only.
See
.Xr des_cipher 3 .
.It Nm 3des
This is available for both old and new esp.
It is considered more secure than straight DES, since it uses larger keys.
.It Nm blf
Blowfish encryption is available only in new esp.
See
.Xr blf_key 3 .
.It Nm cast
CAST encryption is available only in new esp.
.It Nm skipjack
SKIPJACK encryption is available only in new esp.
This algorithm designed by the NSA and is faster than 3DES.
However, since it was designed by the NSA
it is a poor choice.
.El
.Pp
.It auth
The authentication algorithm to be used with the SA.
Possible values are:
.Nm md5
and
.Nm sha1
for both old and new ah and also new esp.
Also
.Nm rmd160
for both new ah and esp.
.It key
The secret symmetric key used for encryption and authentication.
The size for
.Nm des
and
.Nm 3des
is fixed to 8 and 24 respectively.
For other ciphers like
.Nm cast
or
.Nm blf
the key length can be variable.
The
.Nm key
should be given in hexadecimal digits.
The
.Nm key
should be chosen in random (ideally, using some true-random source like
coin flipping).
It is very important that the key is not guessable.
One practical way of generating keys is by using the
.Xr random 4
device (e.g., dd if=/dev/urandom bs=1024 count=1 | sha1)
.It authkey
The secret key material used for authentication
if additional authentication in new esp mode is required.
For old or new ah the key material for authentication is passed with the
.Nm key
option.
The
.Nm key
should be given in hexadecimal digits.
The
.Nm key
should be chosen in random (ideally, using some true-random source like
coin flipping).
It is very important that the key is not guessable.
One practical way of generating keys is by using the
.Xr random 4
device (e.g., dd if=/dev/urandom bs=1024 count=1 | sha1)
.It iv
This option has been deprecated.
The argument is ignored.
When applicable, it has the same behaviour as the
.Nm halfiv
option.
.It halfiv
This option causes use of a 4 byte IV in old ESP (as opposed to 8 bytes).
It may only be used with old ESP.
.It proto
The security protocol needed by
.Nm delspi ,
.Nm flow ,
.Nm group
or
.Nm bind
to uniquely specify the SA.
The default value is 50 which means
.Nm IPPROTO_ESP .
Other accepted values are 51
.Nm ( IPPROTO_AH ),
and 4
.Nm ( IPPROTO_IP ) .
One can also specify the symbolic names "esp", "ah", and "ip4",
case insensitive.
.It chain
Delete the whole SPI chain, otherwise delete only the SPI given.
.It dst2
The second IP destination address used by
.Nm group .
.It spi2
The second SPI used by
.Nm group .
.It proto2
The second security protocol used by
.Nm group .
It defaults to
.Nm IPPROTO_AH .
Other accepted values are 50
.Nm ( IPPROTO_ESP ),
and 4
.Nm ( IPPROTO_IP ) .
One can also specify the symbolic names "esp", "ah", and "ip4",
case insensitive.
.It addr
The source address, source network mask, destination address and destination
network mask against which packets need to match to use the specified
Security Association.
All addresses must be of the same address family
(IPv4 or IPv6).
.It transport
The protocol number which packets need to match to use the specified
Security Association.
By default the protocol number is not used for matching.
Instead of a number, a valid protocol name that appears in
.Xr protocols 5
can be used.
.It sport
The source port which packets have to match for the flow.
By default the source port is not used for matching.
Instead of a number, a valid service name that appears in
.Xr services 5
can be used.
.It dport
The destination port which packets have to match for the flow.
By default the source port is not used for matching.
Instead of a number, a valid service name that appears in
.Xr services 5
can be used.
.It delete
Instead of creating a flow, an existing flow is deleted.
.It ingress
For
.Nm flow ,
create or delete an
.Nm ingress
flow.
An SA's
.Nm ingress
flows specify the types of packets that may be accepted over that SA,
if the sysctl variable
.Bl -tag -width xxxxxxxxxxxxxxxxxxxxx
.It net.inet.ip.ipsec-acl
.El
.Pp
is set to any non-zero value.
.It bypass
For
.Nm flow ,
create or delete a
.Nm bypass
flow.
Packets matching this flow will not be processed by IPSec.
For
.Nm flush ,
only flush SAs of type bypass.
.It ah
For
.Nm flush ,
only flush SAs of type ah.
.It esp
For
.Nm flush ,
only flush SAs of type esp.
.It oldah
For
.Nm flush ,
only flush SAs of type old ah.
.It oldesp
For
.Nm flush ,
only flush SAs of type old esp.
.It ip4
For
.Nm flush ,
only flush SAs of type ip4.
.El
.Sh EXAMPLES
Setup a SA which uses new esp with 3des encryption and HMAC-SHA1
authentication:
.Bd -literal
ipsecadm new esp -enc 3des -auth sha1 -spi 1001 -dst 169.20.12.2 \e\
-src 169.20.12.3 \e\
-key 638063806380638063806380638063806380638063806380 \e\
-authkey 1234123412341234123412341234123412341234
.Ed
.Pp
Setup a SA for authentication with old ah only:
.Bd -literal
ipsecadm old ah -auth md5 -spi 1001 -dst 169.20.12.2 -src 169.20.12.3 \e\
-key 12341234deadbeef
.Ed
.Pp
Setup a flow using the above SA:
.Bd -literal
ipsecadm flow -dst 169.20.12.2 -spi 1001 -proto ah \e\
-addr 10.1.1.0 255.255.255.0 10.0.0.0 255.0.0.0
.Ed
.Pp
Setup an inbound SA:
.Bd -literal
ipsecadm new esp -enc blf -auth md5 -spi 1002 -dst 169.20.12.3 \e\
-src 169.20.12.2 \e\
-key abadbeef15deadbeefabadbeef15deadbeefabadbeef15deadbeef \e\
-authkey 12349876432167890192837465098273
.Ed
.Pp
Setup an ingress flow on for the inbound SA:
.Bd -literal
ipsecadm flow -addr 10.0.0.0 255.0.0.0 10.1.1.0 255.255.255.0 \e\
-dst 10.10.32.1 -spi 1002 -proto esp -ingress
.Ed
.Pp
Setup a bypass flow:
.Bd -literal
ipsecadm flow -bypass \e\
-addr 10.1.1.0 255.255.255.0 10.1.1.0 255.255.255.0
.Ed
.Pp
Delete all esp SAs and their flows and routing information:
.Bd -literal
ipsecadm flush -esp
.Ed
.Sh SEE ALSO
.Xr netstat 1 ,
.Xr enc 4 ,
.Xr ipsec 4 ,
.Xr protocols 5 ,
.Xr services 5 ,
.Xr isakmpd 8 ,
.Xr photurisd 8 ,
.Xr vpn 8
|