| blob | 4d23bedc9fba81f60eecc620c56ca3dbe7c5e58b |
1 '\" te
2 .\" Copyright (C) 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH IPSECKEY 8 "Sep 25, 2008"
7 .SH NAME
8 ipseckey \- manually manipulate an IPsec Security Association Database (SADB)
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBipseckey\fR [\fB-nvp\fR]
13 .fi
15 .LP
16 .nf
17 \fBipseckey\fR [\fB-nvp\fR] \fB-f\fR \fIfilename\fR
18 .fi
20 .LP
21 .nf
22 \fBipseckey\fR \fB-c\fR \fIfilename\fR
23 .fi
25 .LP
26 .nf
27 \fBipseckey\fR [\fB-nvp\fR] [delete | delete-pair | get] SA_TYPE {EXTENSION \fIvalue\fR...}
28 .fi
30 .LP
31 .nf
32 \fBipseckey\fR [\fB-np\fR] [monitor | passive_monitor | pmonitor]
33 .fi
35 .LP
36 .nf
37 \fBipseckey\fR [\fB-nvp\fR] flush {SA_TYPE}
38 .fi
40 .LP
41 .nf
42 \fBipseckey\fR [\fB-nvp\fR] dump {SA_TYPE}
43 .fi
45 .LP
46 .nf
47 \fBipseckey\fR [\fB-nvp\fR] save SA_TYPE {\fIfilename\fR}
48 .fi
50 .LP
51 .nf
52 \fBipseckey\fR [\fB-nvp\fR] \fB-s\fR \fIfilename\fR
53 .fi
55 .SH DESCRIPTION
56 .sp
57 .LP
58 The \fBipseckey\fR command is used to manually manipulate the security
59 association databases of the network security services, \fBipsecah\fR(7P) and
60 \fBipsecesp\fR(7P). You can use the \fBipseckey\fR command to set up security
61 associations between communicating parties when automated key management is not
62 available.
63 .sp
64 .LP
65 While the \fBipseckey\fR utility has only a limited number of general options,
66 it supports a rich command language. The user may specify requests to be
67 delivered by means of a programmatic interface specific for manual keying. See
68 \fBpf_key\fR(7P). When \fBipseckey\fR is invoked with no arguments, it will
69 enter an interactive mode which prints a prompt to the standard output and
70 accepts commands from the standard input until the end-of-file is reached. Some
71 commands require an explicit security association ("\fBSA\fR") type, while
72 others permit the \fBSA\fR type to be unspecified and act on all \fBSA\fR
73 types.
74 .sp
75 .LP
76 \fBipseckey\fR uses a \fBPF_KEY\fR socket and the message types \fBSADB_ADD\fR,
77 \fBSADB_DELETE\fR, \fBSADB_GET\fR, \fBSADB_UPDATE\fR, \fBSADB_FLUSH\fR, and
78 \fBSADB_X_PROMISC\fR. Thus, you must be a superuser to use this command.
79 .sp
80 .LP
81 \fBipseckey\fR handles sensitive cryptographic keying information. Please read
82 the \fBSecurity\fR section for details on how to use this command securely.
83 .SH OPTIONS
84 .sp
85 .ne 2
86 .na
87 \fB\fB-c\fR [\fIfilename\fR]\fR
88 .ad
89 .sp .6
90 .RS 4n
91 Analogous to the \fB-f\fR option (see following), except that the input is not
92 executed but only checked for syntactical correctness. Errors are reported to
93 \fBstderr\fR. This option is provided to debug configurations without making
94 changes. See \fBSECURITY\fR and "Service Management Facility" for more
95 information.
96 .RE
98 .sp
99 .ne 2
100 .na
101 \fB\fB-f\fR [\fIfilename\fR]\fR
102 .ad
103 .sp .6
104 .RS 4n
105 Read commands from an input file, \fIfilename\fR. The lines of the input file
106 are identical to the command line language. The \fBload\fR command provides
107 similar functionality. The \fB-s\fR option or the \fBsave\fR command can
108 generate files readable by the \fB-f\fR argument.
109 .RE
111 .sp
112 .ne 2
113 .na
114 \fB\fB-n\fR\fR
115 .ad
116 .sp .6
117 .RS 4n
118 Prevent attempts to print host and network names symbolically when reporting
119 actions. This is useful, for example, when all name servers are down or are
120 otherwise unreachable.
121 .RE
123 .sp
124 .ne 2
125 .na
126 \fB\fB-p\fR\fR
127 .ad
128 .sp .6
129 .RS 4n
130 Paranoid. Do not print any keying material, even if saving \fBSA\fRs. Instead
131 of an actual hexadecimal digit, print an \fBX\fR when this flag is turned on.
132 .RE
134 .sp
135 .ne 2
136 .na
137 \fB\fB-s\fR [\fIfilename\fR]\fR
138 .ad
139 .sp .6
140 .RS 4n
141 The opposite of the \fB-f\fR option. If '\fB-\fR' is given for a
142 \fIfilename\fR, then the output goes to the standard output. A snapshot of all
143 current \fBSA\fR tables will be output in a form readable by the \fB-f\fR
144 option. The output will be a series of \fBadd\fR commands, but with some names
145 not used. This occurs because a single name may often indicate multiple
146 addresses.
147 .RE
149 .sp
150 .ne 2
151 .na
152 \fB\fB-v\fR\fR
153 .ad
154 .sp .6
155 .RS 4n
156 Verbose. Print the messages being sent into the \fBPF_KEY\fR socket, and print
157 raw seconds values for lifetimes.
158 .RE
160 .SH COMMANDS
161 .sp
162 .ne 2
163 .na
164 \fB\fBadd\fR\fR
165 .ad
166 .sp .6
167 .RS 4n
168 Add an \fBSA\fR. Because it involves the transfer of keying material, it cannot
169 be invoked from the shell, lest the keys be visible in \fBps\fR(1) output. It
170 can be used either from the interactive \fBipseckey>\fR prompt or in a command
171 file specified by the \fB-f\fR command. The \fBadd\fR command accepts all
172 extension-value pairs described below.
173 .RE
175 .sp
176 .ne 2
177 .na
178 \fB\fBupdate\fR\fR
179 .ad
180 .sp .6
181 .RS 4n
182 Update \fBSA\fR lifetime, and in the cases of larval \fBSA\fRs (leftover from
183 aborted automated key management), keying material and other extensions. Like
184 \fBadd\fR, this command cannot be invoked from the shell because keying
185 material would be seen by the \fBps\fR(1) command. It can be used either from
186 the interactive \fBipseckey>\fR prompt or in a command file specified by the
187 \fB-f\fR command. The \fBupdate\fR command accepts all extension-value pairs,
188 but normally is only used for \fBSA\fR lifetime updates.
189 .RE
191 .sp
192 .ne 2
193 .na
194 \fB\fBupdate-pair\fR\fR
195 .ad
196 .sp .6
197 .RS 4n
198 As update, but apply the update to the SA and its paired SA, if there is one.
199 .RE
201 .sp
202 .ne 2
203 .na
204 \fB\fBdelete\fR\fR
205 .ad
206 .sp .6
207 .RS 4n
208 Delete a specific \fBSA\fR from a specific \fBSADB\fR. This command requires
209 the \fBspi\fR extension, and the \fBdest\fR extension for IPsec \fBSA\fRs.
210 Other extension-value pairs are superfluous for a delete message. If the SA to
211 be deleted is paired with another SA, the SA is deleted and the paired SA is
212 updated to indicate that it is now unpaired.
213 .RE
215 .sp
216 .ne 2
217 .na
218 \fB\fBdelete-pair\fR\fR
219 .ad
220 .sp .6
221 .RS 4n
222 Delete a specific SA from a specific SADB. If the SA is paired with another SA,
223 delete that SA too. This command requires the \fBspi\fR extension and the
224 \fBdest\fR extension for the IPsec SA, or its pair.
225 .RE
227 .sp
228 .ne 2
229 .na
230 \fB\fBget\fR\fR
231 .ad
232 .sp .6
233 .RS 4n
234 Lookup and display a security association from a specific \fBSADB\fR. Like
235 \fBdelete\fR, this command only requires \fBspi\fR and \fBdest\fR for IPsec.
236 .RE
238 .sp
239 .ne 2
240 .na
241 \fB\fBflush\fR\fR
242 .ad
243 .sp .6
244 .RS 4n
245 Remove all \fBSA\fR for a given \fBSA_TYPE\fR, or all \fBSA\fR for all types.
246 .RE
248 .sp
249 .ne 2
250 .na
251 \fB\fBmonitor\fR\fR
252 .ad
253 .sp .6
254 .RS 4n
255 Continuously report on any \fBPF_KEY\fR messages. This uses the
256 \fBSADB_X_PROMISC\fR message to enable messages that a normal \fBPF_KEY\fR
257 socket would not receive to be received. See \fBpf_key\fR(7P).
258 .RE
260 .sp
261 .ne 2
262 .na
263 \fB\fBpassive_monitor\fR\fR
264 .ad
265 .sp .6
266 .RS 4n
267 Like monitor, except that it does not use the \fBSADB_X_PROMISC\fR message.
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB\fBpmonitor\fR\fR
274 .ad
275 .sp .6
276 .RS 4n
277 Synonym for \fBpassive_monitor\fR.
278 .RE
280 .sp
281 .ne 2
282 .na
283 \fB\fBdump\fR\fR
284 .ad
285 .sp .6
286 .RS 4n
287 Will display all \fBSA\fRs for a given \fBSA\fR type, or will display all
288 \fBSA\fRs. Because of the large amount of data generated by this command, there
289 is no guarantee that all \fBSA\fR information will be successfully delivered,
290 or that this command will even complete.
291 .RE
293 .sp
294 .ne 2
295 .na
296 \fB\fBsave\fR\fR
297 .ad
298 .sp .6
299 .RS 4n
300 Is the command analog of the \fB-s\fR option. It is included as a command to
301 provide a way to snapshot a particular \fBSA\fR type, for example, \fBesp\fR or
302 \fBah\fR.
303 .RE
305 .sp
306 .ne 2
307 .na
308 \fB\fBhelp\fR\fR
309 .ad
310 .sp .6
311 .RS 4n
312 Prints a brief summary of commands.
313 .RE
315 .SS "\fBSA_TYPE\fR"
316 .sp
317 .ne 2
318 .na
319 \fB\fBall\fR\fR
320 .ad
321 .sp .6
322 .RS 4n
323 Specifies all known \fBSA\fR types. This type is only used for the \fBflush\fR
324 and \fBdump\fR commands. This is equivalent to having no \fBSA\fR type for
325 these commands.
326 .RE
328 .sp
329 .ne 2
330 .na
331 \fB\fBah\fR\fR
332 .ad
333 .sp .6
334 .RS 4n
335 Specifies the IPsec Authentication Header ("\fBAH\fR") \fBSA\fR.
336 .RE
338 .sp
339 .ne 2
340 .na
341 \fB\fBesp\fR\fR
342 .ad
343 .sp .6
344 .RS 4n
345 Specifies the IPsec Encapsulating Security Payload ("\fBESP\fR") \fBSA\fR.
346 .RE
348 .SH EXTENSION VALUE TYPES
349 .sp
350 .LP
351 Commands like \fBadd\fR, \fBdelete\fR, \fBget\fR, and \fBupdate\fR require that
352 certain extensions and associated values be specified. The extensions will be
353 listed here, followed by the commands that use them, and the commands that
354 require them. Requirements are currently documented based upon the IPsec
355 definitions of an \fBSA\fR. Required extensions may change in the future.
356 \fB<number>\fR can be in either hex (\fB0xnnn\fR), decimal (\fBnnn\fR) or octal
357 (\fB0nnn\fR).\fB<string>\fR is a text string. \fB<hexstr>\fR is a long
358 hexadecimal number with a bit-length. Extensions are usually paired with
359 values; however, some extensions require two values after them.
360 .sp
361 .ne 2
362 .na
363 \fB\fBspi \fI<number>\fR\fR\fR
364 .ad
365 .sp .6
366 .RS 4n
367 Specifies the security parameters index of the \fBSA\fR. This extension is
368 required for the \fBadd\fR, \fBdelete\fR, \fBget\fR and \fBupdate\fR commands.
369 .RE
371 .sp
372 .ne 2
373 .na
374 \fB\fBpair-spi \fI<number>\fR\fR\fR
375 .ad
376 .sp .6
377 .RS 4n
378 When \fBpair-spi\fR is used with the \fBadd\fR or \fBupdate\fR commands, the SA
379 being added or updated will be paired with the SA defined by \fBpair-spi\fR. A
380 pair of SAs can be updated or deleted with a single command.
381 .sp
382 The two SAs that make up the pair need to be in opposite directions from the
383 same pair of IP addresses. The command will fail if either of the SAs specified
384 are already paired with another SA.
385 .sp
386 If the pair-spi token is used in a command and the SA defined by pair-spi does
387 not exist, the command will fail. If the command was \fBadd\fR and the pairing
388 failed, the SA to be added will instead be removed.
389 .RE
391 .sp
392 .ne 2
393 .na
394 \fB\fBinbound | outbound\fR\fR
395 .ad
396 .sp .6
397 .RS 4n
398 These optional flags specify the direction of the SA. When the \fBinbound\fR or
399 \fBoutbound\fR flag is specified with the \fBadd\fR command, the kernel will
400 insert the new SA into the specified hash table for faster lookups. If the flag
401 is omitted, the kernel will decide into which hash table to insert the new SA
402 based on its knowledge the IP addresses specified with the \fBsrc\fR and
403 \fBdst\fR extensions.
404 .sp
405 When these flags are used with the \fBupdate\fR, \fBdelete\fR,
406 \fBupdate-pair\fR or \fBget\fR commands, the flags provide a hint as to the
407 hash table in which the kernel should find the SA.
408 .RE
410 .sp
411 .ne 2
412 .na
413 \fB\fBreplay\fR \fI<number>\fR\fR
414 .ad
415 .sp .6
416 .RS 4n
417 Specifies the replay window size. If not specified, the replay window size is
418 assumed to be zero. It is not recommended that manually added \fBSA\fRs have a
419 replay window. This extension is used by the \fBadd\fR and \fBupdate\fR
420 commands.
421 .RE
423 .sp
424 .ne 2
425 .na
426 \fB\fBreplay_value\fR \fI<number>\fR\fR
427 .ad
428 .sp .6
429 .RS 4n
430 Specifies the replay value of the SA. This extension is used by the \fBadd\fR
431 and \fBupdate\fR commands.
432 .RE
434 .sp
435 .ne 2
436 .na
437 \fB\fBstate \fI<string>\fR|\fI<number>\fR\fR\fR
438 .ad
439 .sp .6
440 .RS 4n
441 Specifies the \fBSA\fR state, either by numeric value or by the strings
442 "\fBlarval\fR", "\fBmature\fR", "\fBdying\fR" or "\fBdead\fR". If not
443 specified, the value defaults to \fBmature\fR. This extension is used by the
444 \fBadd\fR and \fBupdate\fR commands.
445 .RE
447 .sp
448 .ne 2
449 .na
450 \fB\fBauth_alg \fI<string>\fR|\fI<number>\fR\fR\fR
451 .ad
452 .br
453 .na
454 \fB\fBauthalg <string>|<number>\fR\fR
455 .ad
456 .sp .6
457 .RS 4n
458 Specifies the authentication algorithm for an \fBSA\fR, either by numeric
459 value, or by strings indicating an algorithm name. Current authentication
460 algorithms include:
461 .sp
462 .ne 2
463 .na
464 \fB\fBHMAC-MD5\fR\fR
465 .ad
466 .sp .6
467 .RS 4n
468 \fBmd5\fR, \fBhmac-md5\fR
469 .RE
471 .sp
472 .ne 2
473 .na
474 \fB\fBHMAC-SH-1\fR\fR
475 .ad
476 .sp .6
477 .RS 4n
478 \fBsha\fR, \fBsha-1\fR, \fBhmac-sha1\fR, \fBhmac-sha\fR
479 .RE
481 .sp
482 .ne 2
483 .na
484 \fB\fBHMAC-SHA-256\fR\fR
485 .ad
486 .sp .6
487 .RS 4n
488 \fBsha256\fR, \fBsha-256\fR, \fBhmac-sha256\fR, \fBhmac-sha-256\fR
489 .RE
491 .sp
492 .ne 2
493 .na
494 \fB\fBHMAC-SHA-384\fR\fR
495 .ad
496 .sp .6
497 .RS 4n
498 \fBsha384\fR, \fBsha-384\fR, \fBhmac-sha384\fR, \fBhmac-sha-384\fR
499 .RE
501 .sp
502 .ne 2
503 .na
504 \fB\fBHMAC-SHA-512\fR\fR
505 .ad
506 .sp .6
507 .RS 4n
508 \fBsha512\fR, \fBsha-512\fR, \fBhmac-sha512\fR, \fBhmac-sha-512\fR
509 .RE
511 Often, algorithm names will have several synonyms. This extension is required
512 by the \fBadd\fR command for certain \fBSA\fR types. It is also used by the
513 \fBupdate\fR command.
514 .sp
515 Use the \fBipsecalgs\fR(8) command to obtain the complete list of
516 authentication algorithms.
517 .RE
519 .sp
520 .ne 2
521 .na
522 \fB\fBencr_alg \fI<string>\fR|\fI<number>\fR\fR\fR
523 .ad
524 .br
525 .na
526 \fB\fBencralg \fI<string>\fR|\fI<number>\fR\fR\fR
527 .ad
528 .sp .6
529 .RS 4n
530 Specifies the encryption algorithm for an SA, either by numeric value, or by
531 strings indicating an algorithm name. Current encryption algorithms include DES
532 ("\fBdes\fR"), Triple-DES ("\fB3des\fR"), Blowfish ("blowfish"), and AES
533 ("aes"). This extension is required by the add command for certain \fBSA\fR
534 types. It is also used by the \fBupdate\fR command.
535 .sp
536 Use the \fBipsecalgs\fR(8) command to obtain the complete list of encryption
537 algorithms.
538 .RE
540 .sp
541 .LP
542 The next six extensions are lifetime extensions. There are two varieties,
543 "\fBhard\fR" and "\fBsoft\fR". If a \fBhard\fR lifetime expires, the \fBSA\fR
544 will be deleted automatically by the system. If a \fBsoft\fR lifetime expires,
545 an \fBSADB_EXPIRE\fR message will be transmitted by the system, and its state
546 will be downgraded to \fBdying\fR from \fBmature\fR. See \fBpf_key\fR(7P). The
547 \fBmonitor\fR command to \fBkey\fR allows you to view \fBSADB_EXPIRE\fR
548 messages.
549 .sp
550 .ne 2
551 .na
552 \fB\fBidle_addtime\fR \fI<number>\fR\fR
553 .ad
554 .br
555 .na
556 \fB\fBidle_usetime\fR \fI<number>\fR\fR
557 .ad
558 .sp .6
559 .RS 4n
560 Specifies the number of seconds that this SA can exist if the SA is not used
561 before the SA is revalidated. If this extension is not present, the default
562 value is half of the \fBhard_addtime\fR (see below). This extension is used by
563 the \fBadd\fR and \fBupdate\fR commands.
564 .RE
566 .sp
567 .ne 2
568 .na
569 \fB\fBsoft_bytes \fI<number>\fR\fR\fR
570 .ad
571 .br
572 .na
573 \fB\fBhard_bytes \fI<number>\fR\fR\fR
574 .ad
575 .sp .6
576 .RS 4n
577 Specifies the number of bytes that this \fBSA\fR can protect. If this extension
578 is not present, the default value is zero, which means that the \fBSA\fR will
579 not expire based on the number of bytes protected. This extension is used by
580 the \fBadd\fR and \fBupdate\fR commands.
581 .RE
583 .sp
584 .ne 2
585 .na
586 \fB\fBsoft_addtime \fI<number>\fR\fR\fR
587 .ad
588 .br
589 .na
590 \fB\fBhard_addtime \fI<number>\fR\fR\fR
591 .ad
592 .sp .6
593 .RS 4n
594 Specifies the number of seconds that this \fBSA\fR can exist after being added
595 or updated from a larval \fBSA\fR. An update of a mature \fBSA\fR does not
596 reset the initial time that it was added. If this extension is not present, the
597 default value is zero, which means the \fBSA\fR will not expire based on how
598 long it has been since it was added. This extension is used by the \fBadd\fR
599 and \fBupdate\fR commands.
600 .RE
602 .sp
603 .ne 2
604 .na
605 \fB\fBsoft_usetime \fI<number>\fR\fR\fR
606 .ad
607 .br
608 .na
609 \fB\fBhard_usetime \fI<number>\fR\fR\fR
610 .ad
611 .sp .6
612 .RS 4n
613 Specifies the number of seconds this \fBSA\fR can exist after first being used.
614 If this extension is not present, the default value is zero, which means the
615 \fBSA\fR will not expire based on how long it has been since it was added. This
616 extension is used by the \fBadd\fR and \fBupdate\fR commands.
617 .RE
619 .sp
620 .ne 2
621 .na
622 \fB\fBsaddr \fIaddress\fR | \fIname\fR\fR\fR
623 .ad
624 .br
625 .na
626 \fB\fBsrcaddr \fIaddress\fR | \fIname\fR\fR\fR
627 .ad
628 .br
629 .na
630 \fB\fBsaddr6 \fIIPv6 address\fR\fR\fR
631 .ad
632 .br
633 .na
634 \fB\fBsrcaddr6 \fIIPv6 address\fR\fR\fR
635 .ad
636 .br
637 .na
638 \fB\fBsrc \fIaddress\fR | \fIname\fR\fR\fR
639 .ad
640 .br
641 .na
642 \fB\fBsrc6 \fIIPv6 address\fR\fR\fR
643 .ad
644 .sp .6
645 .RS 4n
646 \fBsrcaddr \fIaddress\fR\fR and \fBsrc \fIaddress\fR\fR are synonyms that
647 indicate the source address of the \fBSA\fR. If unspecified, the source address
648 will either remain unset, or it will be set to a wildcard address if a
649 destination address was supplied. To not specify the source address is valid
650 for IPsec \fBSA\fRs. Future \fBSA\fR types may alter this assumption. This
651 extension is used by the \fBadd\fR, \fBupdate\fR, \fBget\fR and \fBdelete\fR
652 commands.
653 .RE
655 .sp
656 .ne 2
657 .na
658 \fB\fBdaddr \fI<address>\fR|\fI<name>\fR\fR\fR
659 .ad
660 .br
661 .na
662 \fB\fBdstaddr \fI<address>\fR|\fI<name>\fR\fR\fR
663 .ad
664 .br
665 .na
666 \fB\fBdaddr6 \fI<IPv6 address>\fR|\fI<name>\fR\fR\fR
667 .ad
668 .br
669 .na
670 \fB\fBdstaddr6 \fI<IPv6 address>\fR|\fI<name>\fR\fR\fR
671 .ad
672 .br
673 .na
674 \fB\fBdst \fI<addr>\fR|\fI<name>\fR\fR\fR
675 .ad
676 .br
677 .na
678 \fB\fBdst6 \fI<IPv6 address>\fR|\fI<name>\fR\fR\fR
679 .ad
680 .sp .6
681 .RS 4n
682 \fBdstaddr \fI<addr>\fR\fR and \fBdst \fI<addr>\fR\fR are synonyms that
683 indicate the destination address of the \fBSA\fR. If unspecified, the
684 destination address will remain unset. Because IPsec \fBSA\fRs require a
685 specified destination address and \fBspi\fR for identification, this extension,
686 with a specific value, is required for the \fBadd\fR, \fBupdate\fR, \fBget\fR
687 and \fBdelete\fR commands.
688 .sp
689 If a name is given, \fBipseckey\fR will attempt to invoke the command on
690 multiple \fBSA\fRs with all of the destination addresses that the name can
691 identify. This is similar to how \fBipsecconf\fR handles addresses.
692 .sp
693 If \fBdst6\fR or \fBdstaddr6\fR is specified, only the IPv6 addresses
694 identified by a name are used.
695 .RE
697 .sp
698 .ne 2
699 .na
700 \fB\fBsport\fR \fI<portnum>\fR\fR
701 .ad
702 .sp .6
703 .RS 4n
704 \fBsport\fR specifies the source port number for an SA. It should be used in
705 combination with an upper-layer protocol (see below), but it does not have to
706 be.
707 .RE
709 .sp
710 .ne 2
711 .na
712 \fB\fBdport\fR \fI<portnum>\fR\fR
713 .ad
714 .sp .6
715 .RS 4n
716 sport specifies the destination port number for an SA. It should be used in
717 combination with an upper-layer protocol (see below), but it does not have to
718 be.
719 .RE
721 .sp
722 .ne 2
723 .na
724 \fB\fBencap\fR \fI<protocol>\fR\fR
725 .ad
726 .sp .6
727 .RS 4n
728 Identifies the protocol used to encapsulate NAT-traversal IPsec packets. Other
729 NAT-traversal parameters (\fBnat_*\fR) are below. The only acceptable value
730 for \fI<protocol>\fR currently is \fBudp\fR.
731 .RE
733 .sp
734 .ne 2
735 .na
736 \fB\fBproto\fR \fI<protocol number>\fR\fR
737 .ad
738 .br
739 .na
740 \fB\fBulp\fR \fI<protocol number>\fR\fR
741 .ad
742 .sp .6
743 .RS 4n
744 \fBproto\fR, and its synonym \fBulp\fR, specify the IP protocol number of the
745 SA.
746 .RE
748 .sp
749 .ne 2
750 .na
751 \fB\fBnat_loc\fR \fI<address>\fR|\fI<name>\fR\fR
752 .ad
753 .sp .6
754 .RS 4n
755 If the local address in the SA (source or destination) is behind a NAT, this
756 extension indicates the NAT node's globally-routable address. This address can
757 match the SA's local address if there is a \fBnat_lport\fR (see below)
758 specified.
759 .RE
761 .sp
762 .ne 2
763 .na
764 \fB\fBnat_rem\fR \fI<address>\fR|\fI<name>\fR\fR
765 .ad
766 .sp .6
767 .RS 4n
768 If the remote address in the SA (source or destination) is behind a NAT, this
769 extension indicates that node's internal (that is, behind-the-NAT) address.
770 This address can match the SA's local address if there is a \fBnat_rport\fR
771 (see below) specified.
772 .RE
774 .sp
775 .ne 2
776 .na
777 \fB\fBnat_lport\fR \fI<portnum>\fR\fR
778 .ad
779 .sp .6
780 .RS 4n
781 Identifies the local UDP port on which encapsulation of ESP occurs.
782 .RE
784 .sp
785 .ne 2
786 .na
787 \fB\fBnat_rport\fR \fI<portnum>\fR\fR
788 .ad
789 .sp .6
790 .RS 4n
791 Identifies the remote UDP port on which encapsulation of ESP occurs.
792 .RE
794 .sp
795 .ne 2
796 .na
797 \fB\fBisrc\fR \fI<address>\fR | \fI<name>\fR[/\fI<prefix>\fR]\fR
798 .ad
799 .br
800 .na
801 \fB\fBinnersrc\fR \fI<address>\fR | \fI<name>\fR[/\fI<prefix>\fR]\fR
802 .ad
803 .br
804 .na
805 \fB\fBisrc6\fR \fI<address>\fR | \fI<name>\fR[/\fI<prefix>\fR]\fR
806 .ad
807 .br
808 .na
809 \fB\fBinnersrc6\fR \fI<address>\fR | \fI<name>\fR[/\fI<prefix>\fR]\fR
810 .ad
811 .br
812 .na
813 \fB\fBproxyaddr\fR \fI<address>\fR | \fI<name>\fR[/\fI<prefix>\fR]\fR
814 .ad
815 .br
816 .na
817 \fB\fBproxy\fR \fI<address>\fR | \fI<name>\fR[/\fI<prefix>\fR]\fR
818 .ad
819 .sp .6
820 .RS 4n
821 \fBisrc\fR \fI<address>\fR[/\fI<prefix>\fR] and \fBinnersrc\fR
822 \fI<address>\fR[/\fI<prefix>\fR] are synonyms. They indicate the inner source
823 address for a tunnel-mode SA.
824 .sp
825 An inner-source can be a prefix instead of an address. As with other address
826 extensions, there are IPv6-specific forms. In such cases, use only
827 IPv6-specific addresses or prefixes.
828 .sp
829 Previous versions referred to this value as the proxy address. The usage, while
830 deprecated, remains.
831 .RE
833 .sp
834 .ne 2
835 .na
836 \fB\fBidst\fR \fI<address>\fR | \fI<name>\fR[/\fI<prefix>\fR]\fR
837 .ad
838 .br
839 .na
840 \fB\fBinnerdst\fR \fI<address>\fR | \fI<name>\fR[/\fI<prefix>\fR]\fR
841 .ad
842 .br
843 .na
844 \fB\fBidst6\fR \fI<address>\fR | \fI<name>\fR[/\fI<prefix>\fR]\fR
845 .ad
846 .br
847 .na
848 \fB\fBinnerdst6\fR \fI<address>\fR | \fI<name>\fR[/\fI<prefix>\fR]\fR
849 .ad
850 .sp .6
851 .RS 4n
852 \fBidst\fR \fI<address>\fR[/\fI<prefix>\fR] and \fBinnerdst\fR
853 \fI<address>\fR[/\fI<prefix>\fR] are synonyms. They indicate the inner
854 destination address for a tunnel-mode SA.
855 .sp
856 An inner-destination can be a prefix instead of an address. As with other
857 address extensions, there are IPv6-specific forms. In such cases, use only
858 IPv6-specific addresses or prefixes.
859 .RE
861 .sp
862 .ne 2
863 .na
864 \fB\fBinnersport\fR \fI<portnum>\fR\fR
865 .ad
866 .br
867 .na
868 \fB\fBisport\fR \fI<portnum>\fR\fR
869 .ad
870 .sp .6
871 .RS 4n
872 \fBinnersport\fR specifies the source port number of the inner header for a
873 tunnel-mode SA. It should be used in combination with an upper-layer protocol
874 (see below), but it does not have to be.
875 .RE
877 .sp
878 .ne 2
879 .na
880 \fB\fBinnerdport\fR \fI<portnum>\fR\fR
881 .ad
882 .br
883 .na
884 \fB\fBidport\fR \fI<portnum>\fR\fR
885 .ad
886 .sp .6
887 .RS 4n
888 \fBinnerdport\fR specifies the destination port number of the inner header for
889 a tunnel-mode SA. It should be used in combination with an upper-layer protocol
890 (see below), but it does not have to be.
891 .RE
893 .sp
894 .ne 2
895 .na
896 \fB\fBiproto\fR \fI<protocol number>\fR\fBiulp\fR \fI<protocol number>\fR\fR
897 .ad
898 .sp .6
899 .RS 4n
900 \fBiproto\fR, and its synonym \fBiulp\fR, specify the IP protocol number of the
901 inner header of a tunnel-mode SA.
902 .RE
904 .sp
905 .ne 2
906 .na
907 \fB\fBauthkey \fI<hexstring>\fR\fR\fR
908 .ad
909 .sp .6
910 .RS 4n
911 Specifies the authentication key for this \fBSA\fR. The key is expressed as a
912 string of hexadecimal digits, with an optional \fB/\fR at the end, for example,
913 \fB123/12\fR. Bits are counted from the most-significant bits down. For
914 example, to express three '1' bits, the proper syntax is the string
915 "\fBe/3\fR". For multi-key algorithms, the string is the concatenation of the
916 multiple keys. This extension is used by the \fBadd\fR and \fBupdate\fR
917 commands.
918 .RE
920 .sp
921 .ne 2
922 .na
923 \fB\fBencrkey \fI<hexstring>\fR\fR\fR
924 .ad
925 .sp .6
926 .RS 4n
927 Specifies the encryption key for this \fBSA\fR. The syntax of the key is the
928 same as \fBauthkey\fR. A concrete example of a multi-key encryption algorithm
929 is \fB3des\fR, which would express itself as a 192-bit key, which is three
930 64-bit parity-included \fBDES\fR keys. This extension is used by the \fBadd\fR
931 and \fBupdate\fR commands.
932 .RE
934 .sp
935 .LP
936 Certificate identities are very useful in the context of automated key
937 management, as they tie the \fBSA\fR to the public key certificates used in
938 most automated key management protocols. They are less useful for manually
939 added \fBSA\fRs. Unlike other extensions, \fBsrcidtype\fR takes two values, a
940 \fItype\fR, and an actual \fIvalue\fR. The type can be one of the following:
941 .sp
942 .ne 2
943 .na
944 \fB\fBprefix\fR\fR
945 .ad
946 .sp .6
947 .RS 4n
948 An address prefix.
949 .RE
951 .sp
952 .ne 2
953 .na
954 \fB\fBfqdn\fR\fR
955 .ad
956 .sp .6
957 .RS 4n
958 A fully-qualified domain name.
959 .RE
961 .sp
962 .ne 2
963 .na
964 \fB\fBdomain\fR\fR
965 .ad
966 .sp .6
967 .RS 4n
968 Domain name, synonym for \fBfqdn\fR.
969 .RE
971 .sp
972 .ne 2
973 .na
974 \fB\fBuser_fqdn\fR\fR
975 .ad
976 .sp .6
977 .RS 4n
978 User identity of the form \fB\fIuser\fR@\fIfqdn\fR\fR.
979 .RE
981 .sp
982 .ne 2
983 .na
984 \fB\fBmailbox\fR\fR
985 .ad
986 .sp .6
987 .RS 4n
988 Synonym for \fBuser_fqdn\fR.
989 .RE
991 .sp
992 .LP
993 The \fIvalue\fR is an arbitrary text string that should identify the
994 certificate.
995 .sp
996 .ne 2
997 .na
998 \fB\fBsrcidtype \fI<type, value>\fR\fR\fR
999 .ad
1000 .sp .6
1001 .RS 4n
1002 Specifies a source certificate identity for this \fBSA\fR. This extension is
1003 used by the \fBadd\fR and \fBupdate\fR commands.
1004 .RE
1006 .sp
1007 .ne 2
1008 .na
1009 \fB\fBdstidtype \fI<type, value>\fR\fR\fR
1010 .ad
1011 .sp .6
1012 .RS 4n
1013 Specifies a destination certificate identity for this \fBSA\fR. This extension
1014 is used by the \fBadd\fR and \fBupdate\fR commands
1015 .RE
1017 .SS "Tunnel Mode versus Transport Mode SAs"
1018 .sp
1019 .LP
1020 An IPsec SA is a Tunnel Mode SA if the "proto" value is either 4 (\fBipip\fR)
1021 or 41 (\fBipv6\fR) \fBand\fR there is an inner-address or inner-port value
1022 specified. Otherwise, the SA is a Transport Mode SA.
1023 .SH SECURITY
1024 .sp
1025 .LP
1026 Keying material is very sensitive and should be generated as randomly as
1027 possible. Some algorithms have known weak keys. IPsec algorithms have built-in
1028 weak key checks, so that if a weak key is in a newly added \fBSA\fR, the
1029 \fBadd\fR command will fail with an invalid value.
1030 .sp
1031 .LP
1032 The \fBipseckey\fR command allows a privileged user to enter cryptographic
1033 keying information. If an adversary gains access to such information, the
1034 security of IPsec traffic is compromised. The following issues should be taken
1035 into account when using the \fBipseckey\fR command.
1036 .RS +4
1037 .TP
1038 1.
1039 Is the \fBTTY\fR going over a network (interactive mode)?
1040 .RS +4
1041 .TP
1042 .ie t \(bu
1043 .el o
1044 If it is, then the security of the keying material is the security of the
1045 network path for this \fBTTY\fR's traffic. Using \fBipseckey\fR over a
1046 clear-text \fBtelnet\fR or \fBrlogin\fR session is risky.
1047 .RE
1048 .RS +4
1049 .TP
1050 .ie t \(bu
1051 .el o
1052 Even local windows might be vulnerable to attacks where a concealed program
1053 that reads window events is present.
1054 .RE
1055 .RE
1056 .RS +4
1057 .TP
1058 2.
1059 Is the file accessed over the network or readable to the world (\fB-f\fR
1060 option)?
1061 .RS +4
1062 .TP
1063 .ie t \(bu
1064 .el o
1065 A network-mounted file can be sniffed by an adversary as it is being read.
1066 .RE
1067 .RS +4
1068 .TP
1069 .ie t \(bu
1070 .el o
1071 A world-readable file with keying material in it is also risky.
1072 .RE
1073 .RE
1074 .RS +4
1075 .TP
1076 3.
1077 The \fBipseckey\fR command is designed to be managed by the \fBmanual-key\fR
1078 \fBsmf\fR(5) service. Because the \fBsmf\fR(5) log files are world-readable,
1079 the \fBipseckey\fR does not record any syntax errors in the log files, as these
1080 errors might include secret information.
1081 .sp
1082 If a syntax error is found when the \fBmanual-key\fR \fBsmf\fR(5) service is
1083 enabled, the service enters maintenance mode. The log file will indicate that
1084 there was a syntax error, but will not specify what the error was.
1085 .sp
1086 The administrator should use \fBipeckey\fR \fB-c\fR \fIfilename\fR from the
1087 command line to discover the cause of the errors. See \fBOPTIONS\fR.
1088 .RE
1089 .sp
1090 .LP
1091 If your source address is a host that can be looked up over the network and
1092 your naming system itself is compromised, then any names used will not be
1093 trustworthy.
1094 .sp
1095 .LP
1096 Security weaknesses often lie in misapplication of tools, not in the tools
1097 themselves. Administrators are urged to be cautious when using \fBipseckey\fR.
1098 The safest mode of operation is probably on a console or other hard-connected
1099 \fBTTY\fR.
1100 .sp
1101 .LP
1102 For further thoughts on this subject, see the afterward by Matt Blaze in Bruce
1103 Schneier's \fIApplied Cryptography: Protocols, Algorithms, and Source Code in
1104 C\fR.
1105 .SS "Service Management Facility"
1106 .sp
1107 .LP
1108 IPsec manual keys are managed by the service management facility, \fBsmf\fR(5).
1109 The services listed below manage the components of IPsec. These services are
1110 delivered as follows:
1111 .sp
1112 .in +2
1113 .nf
1114 svc:/network/ipsec/policy:default (enabled)
1115 svc:/network/ipsec/ipsecalgs:default (enabled)
1116 svc:/network/ipsec/manual-key:default (disabled)
1117 svc:/network/ipsec/ike:default (disabled)
1118 .fi
1119 .in -2
1120 .sp
1122 .sp
1123 .LP
1124 The manual-key service is delivered disabled. The system administrator must
1125 create manual IPsec Security Associations (SAs), as described in this man page,
1126 before enabling that service.
1127 .sp
1128 .LP
1129 The policy service is delivered enabled, but without a configuration file, so
1130 that, as a starting condition, packets are not protected by IPsec. After you
1131 create the configuration file \fB/etc/inet/ipsecinit.conf\fR and refresh the
1132 service (\fBsvcadm refresh\fR, see below), the policy contained in the
1133 configuration file is applied. If there is an error in this file, the service
1134 enters maintenance mode. See \fBipsecconf\fR(8).
1135 .sp
1136 .LP
1137 Services that are delivered disabled are delivered that way because the system
1138 administrator must create configuration files for those services before
1139 enabling them. See \fBike.config\fR(4) for the \fBike\fR service.
1140 .sp
1141 .LP
1142 See \fBipsecalgs\fR(8) for the \fBipsecalgs\fR service.
1143 .sp
1144 .LP
1145 The correct administrative procedure is to create the configuration file for
1146 each service, then enable each service using \fBsvcadm\fR(8).
1147 .sp
1148 .LP
1149 If the configuration needs to be changed, edit the configuration file then
1150 refresh the service, as follows:
1151 .sp
1152 .in +2
1153 .nf
1154 example# \fBsvcadm refresh manual-key\fR
1155 .fi
1156 .in -2
1157 .sp
1159 .sp
1160 .LP
1161 \fBWarning:\fR To prevent \fBipseckey\fR complaining about duplicate
1162 Associations, the \fBipseckey\fR command flushes the Security Association Data
1163 Base (SADB) when the \fBipseckey\fR command is run from \fBsmf\fR(5), before
1164 adding any new Security Associations defined in the configuration file. This
1165 differs from the command line behavior where the SADB is not flushed before
1166 adding new Security Associations.
1167 .sp
1168 .LP
1169 The \fBsmf\fR(5) framework will record any errors in the service-specific log
1170 file. Use any of the following commands to examine the \fBlogfile\fR property:
1171 .sp
1172 .in +2
1173 .nf
1174 example# \fBsvcs -l manual-key\fR
1175 example# \fBsvcprop manual-key\fR
1176 example# \fBsvccfg -s manual-key listprop\fR
1177 .fi
1178 .in -2
1179 .sp
1181 .sp
1182 .LP
1183 The following property is defined for the \fBmanual-key\fR service:
1184 .sp
1185 .in +2
1186 .nf
1187 config/config_file
1188 .fi
1189 .in -2
1190 .sp
1192 .sp
1193 .LP
1194 This property can be modified using \fBsvccfg\fR(8) by users who have been
1195 assigned the following authorization:
1196 .sp
1197 .in +2
1198 .nf
1199 solaris.smf.value.ipsec
1200 .fi
1201 .in -2
1202 .sp
1204 .sp
1205 .LP
1206 See \fBauths\fR(1), \fBuser_attr\fR(4), \fBrbac\fR(5).
1207 .sp
1208 .LP
1209 The service needs to be refreshed using \fBsvcadm\fR(8) before the new
1210 property is effective. General non-modifiable properties can be viewed with the
1211 \fBsvcprop\fR(1) command.
1212 .sp
1213 .in +2
1214 .nf
1215 # \fBsvccfg -s ipsec/manual-key setprop config/config_file = \e
1216 /new/config_file\fR
1217 # \fBsvcadm refresh manual-key\fR
1218 .fi
1219 .in -2
1220 .sp
1222 .sp
1223 .LP
1224 Administrative actions on this service, such as enabling, disabling,
1225 refreshing, and requesting restart can be performed using \fBsvcadm\fR(8). A
1226 user who has been assigned the authorization shown below can perform these
1227 actions:
1228 .sp
1229 .in +2
1230 .nf
1231 solaris.smf.manage.ipsec
1232 .fi
1233 .in -2
1234 .sp
1236 .sp
1237 .LP
1238 The service's status can be queried using the \fBsvcs\fR(1) command.
1239 .sp
1240 .LP
1241 The \fBipseckey\fR command is designed to be run under \fBsmf\fR(5) management.
1242 While the \fBipsecconf\fR command can be run from the command line, this is
1243 discouraged. If the \fBipseckey\fR command is to be run from the command line,
1244 the \fBmanual-key\fR \fBsmf\fR(5) service should be disabled first. See
1245 \fBsvcadm\fR(8).
1246 .SH EXAMPLES
1247 .LP
1248 \fBExample 1 \fREmptying Out All \fBSA\fRs
1249 .sp
1250 .LP
1251 To empty out all \fBSA\fR:
1253 .sp
1254 .in +2
1255 .nf
1256 example# \fBipseckey flush\fR
1257 .fi
1258 .in -2
1259 .sp
1261 .LP
1262 \fBExample 2 \fRFlushing Out IPsec AH \fBSA\fRs Only
1263 .sp
1264 .LP
1265 To flush out only IPsec \fBAH\fR \fBSA\fRs:
1267 .sp
1268 .in +2
1269 .nf
1270 example# \fBipseckey flush ah\fR
1271 .fi
1272 .in -2
1273 .sp
1275 .LP
1276 \fBExample 3 \fRSaving All \fBSA\fRs To Standard Output
1277 .sp
1278 .LP
1279 To save all \fBSA\fRs to the standard output:
1281 .sp
1282 .in +2
1283 .nf
1284 example# \fBipseckey save all\fR
1285 .fi
1286 .in -2
1287 .sp
1289 .LP
1290 \fBExample 4 \fRSaving \fBESP\fR \fBSA\fRs To The File \fB/tmp/snapshot\fR
1291 .sp
1292 .LP
1293 To save \fBESP\fR \fBSA\fRs to the file \fB/tmp/snapshot\fR:
1295 .sp
1296 .in +2
1297 .nf
1298 example# \fBipseckey save esp /tmp/snapshot\fR
1299 .fi
1300 .in -2
1301 .sp
1303 .LP
1304 \fBExample 5 \fRDeleting an IPsec \fBSA\fR
1305 .sp
1306 .LP
1307 To delete an IPsec \fBSA\fR, only the \fBSPI\fR and the destination address are
1308 needed:
1310 .sp
1311 .in +2
1312 .nf
1313 example# \fBipseckey delete esp spi 0x2112 dst 224.0.0.1\fR
1314 .fi
1315 .in -2
1316 .sp
1318 .sp
1319 .LP
1320 An alternative would be to delete the SA and the SAs pair if it has one:
1322 .sp
1323 .in +2
1324 .nf
1325 example# \fBipseckey delete-pair esp spi 0x2112 dst 224.0.0.1\fR
1326 .fi
1327 .in -2
1328 .sp
1330 .LP
1331 \fBExample 6 \fRGetting Information on an IPsec \fBSA\fR
1332 .sp
1333 .LP
1334 Likewise, getting information on a \fBSA\fR only requires the destination
1335 address and \fBSPI\fR:
1337 .sp
1338 .in +2
1339 .nf
1340 example# \fBipseckey get ah spi 0x5150 dst mypeer\fR
1341 .fi
1342 .in -2
1343 .sp
1345 .LP
1346 \fBExample 7 \fRAdding or Updating IPsec \fBSA\fRs
1347 .sp
1348 .LP
1349 Adding or updating \fBSA\fRs requires entering interactive mode:
1351 .sp
1352 .in +2
1353 .nf
1354 example# \fBipseckey\fR
1355 ipseckey> \fBadd ah spi 0x90125 src me.domain.com dst you.domain.com \e
1356 authalg md5 authkey 1234567890abcdef1234567890abcdef\fR
1357 ipseckey> \fBupdate ah spi 0x90125 dst you.domain.com hard_bytes \e
1358 16000000\fR
1359 ipseckey> \fBexit\fR
1360 .fi
1361 .in -2
1362 .sp
1364 .sp
1365 .LP
1366 Adding two SAs that are linked together as a pair:
1368 .sp
1369 .in +2
1370 .nf
1371 example# \fBipseckey\fR
1372 ipseckey> \fBadd esp spi 0x2345 src me.domain.com dst you.domain.com \e
1373 authalg md5 authkey bde359723576fdea08e56cbe876e24ad \e
1374 encralg des encrkey be02938e7def2839\fR
1375 ipseckey> \fBadd esp spi 0x5432 src me.domain.com dst you.domain.com \e
1376 authalg md5 authkey bde359723576fdea08e56cbe876e24ad \e
1377 encralg des encrkey be02938e7def2839 pair-spi 0x2345\fR
1378 ipseckey> \fBexit\fR
1379 .fi
1380 .in -2
1381 .sp
1383 .LP
1384 \fBExample 8 \fRAdding an \fBSA\fR in the Opposite Direction
1385 .sp
1386 .LP
1387 In the case of IPsec, \fBSA\fRs are unidirectional. To communicate securely, a
1388 second \fBSA\fR needs to be added in the opposite direction. The peer machine
1389 also needs to add both \fBSA\fRs.
1391 .sp
1392 .in +2
1393 .nf
1394 example# \fBipseckey\fR
1395 ipseckey> \fBadd ah spi 0x2112 src you.domain.com dst me.domain.com \e
1396 authalg md5 authkey bde359723576fdea08e56cbe876e24ad \e
1397 hard_bytes 16000000\fR
1398 ipseckey> \fBexit\fR
1399 .fi
1400 .in -2
1401 .sp
1403 .LP
1404 \fBExample 9 \fRMonitoring \fBPF_KEY\fR Messages
1405 .sp
1406 .LP
1407 Monitoring for \fBPF_KEY\fR messages is straightforward:
1409 .sp
1410 .in +2
1411 .nf
1412 example# \fBipseckey monitor\fR
1413 .fi
1414 .in -2
1415 .sp
1417 .LP
1418 \fBExample 10 \fRUsing Commands in a File
1419 .sp
1420 .LP
1421 Commands can be placed in a file that can be parsed with the \fB-f\fR option.
1422 This file may contain comment lines that begin with the "#" symbol. For
1423 example:
1425 .sp
1426 .in +2
1427 .nf
1428 # This is a sample file for flushing out the ESP table and
1429 # adding a pair of SAs.
1431 flush esp
1433 ### Watch out! I have keying material in this file. See the
1434 ### SECURITY section in this manual page for why this can be
1435 ### dangerous .
1437 add esp spi 0x2112 src me.domain.com dst you.domain.com \e
1438 authalg md5 authkey bde359723576fdea08e56cbe876e24ad \e
1439 encralg des encrkey be02938e7def2839 hard_usetime 28800
1440 add esp spi 0x5150 src you.domain.com dst me.domain.com \e
1441 authalg md5 authkey 930987dbe09743ade09d92b4097d9e93 \e
1442 encralg des encrkey 8bd4a52e10127deb hard_usetime 28800
1444 ## End of file - This is a gratuitous comment
1445 .fi
1446 .in -2
1448 .LP
1449 \fBExample 11 \fRAdding SAs for IPv6 Addresses
1450 .sp
1451 .LP
1452 The following commands from the interactive-mode create an SA to protect IPv6
1453 traffic between the site-local addresses
1455 .sp
1456 .in +2
1457 .nf
1458 example # \fBipseckey\fR
1459 ipseckey> \fBadd esp spi 0x6789 src6 fec0:bbbb::4483 dst6 fec0:bbbb::7843\e
1460 authalg md5 authkey bde359723576fdea08e56cbe876e24ad \e
1461 encralg des encrkey be02938e7def2839 hard_usetime 28800\fR
1462 ipseckey>\fBexit\fR
1463 .fi
1464 .in -2
1465 .sp
1467 .LP
1468 \fBExample 12 \fRLinking Two SAs as a Pair
1469 .sp
1470 .LP
1471 The following command links two SAs together, as a pair:
1473 .sp
1474 .in +2
1475 .nf
1476 example# \fBipseckey update esp spi 0x123456 dst 192.168.99.2 \e
1477 pair-spi 0x654321\fR
1478 .fi
1479 .in -2
1480 .sp
1482 .SH FILES
1483 .sp
1484 .ne 2
1485 .na
1486 \fB\fB/etc/inet/secret/ipseckeys\fR\fR
1487 .ad
1488 .sp .6
1489 .RS 4n
1490 Default configuration file used at boot time. See "Service Management Facility"
1491 and \fBSECURITY\fR for more information.
1492 .RE
1494 .SH ATTRIBUTES
1495 .sp
1496 .LP
1497 See \fBattributes\fR(5) for descriptions of the following attributes:
1498 .sp
1500 .sp
1501 .TS
1502 box;
1503 c | c
1504 l | l .
1505 ATTRIBUTE TYPE ATTRIBUTE VALUE
1506 Interface Stability Committed
1507 .TE
1509 .SH SEE ALSO
1510 .sp
1511 .LP
1512 \fBps\fR(1), \fBsvcprop\fR(1), \fBsvcs\fR(1), \fBipsecconf\fR(8),
1513 \fBipsecalgs\fR(8), \fBroute\fR(8), \fBsvcadm\fR(8), \fBsvccfg\fR(8),
1514 \fBike.config\fR(4), \fBattributes\fR(5), \fBsmf\fR(5), \fBipsec\fR(7P),
1515 \fBipsecah\fR(7P), \fBipsecesp\fR(7P), \fBpf_key\fR(7P)
1516 .sp
1517 .LP
1518 Schneier, B., \fIApplied Cryptography: Protocols, Algorithms, and Source Code
1519 in C\fR. Second ed. New York, New York: John Wiley & Sons, 1996.
1520 .SH DIAGNOSTICS
1521 .sp
1522 .LP
1523 The \fBipseckey\fR command parses the configuration file and reports any
1524 errors. In the case of multiple errors, \fBipseckey\fR reports as many of these
1525 as possible.
1526 .sp
1527 .LP
1528 The \fBipseckey\fR command does not attempt to use a \fBCOMMAND\fR that has a
1529 syntax error. A \fBCOMMAND\fR might be syntactically correct but can
1530 nevertheless generate an error because the kernel rejected the request made to
1531 \fBpf_key\fR(7P). This might occur because a key had an invalid length or
1532 because an unsupported algorithm was specified.
1533 .sp
1534 .LP
1535 If there are any errors in the configuration file, ipseckey reports the number
1536 of valid COMMANDS and the total number of COMMANDS parsed.
1537 .sp
1538 .ne 2
1539 .na
1540 \fB\fBParse error on line \fIN\fR.\fR\fR
1541 .ad
1542 .sp .6
1543 .RS 4n
1544 If an interactive use of \fBipseckey\fR would print usage information, this
1545 would print instead. Usually proceeded by another diagnostic. Because
1546 \fBCOMMANDS\fR can cover more than a single line in the configuration file by
1547 using the backslash character to delimit lines, its not always possible to
1548 pinpoint in the configuration file the exact line that caused the error.
1549 .RE
1551 .sp
1552 .ne 2
1553 .na
1554 \fB\fBUnexpected end of command line.\fR\fR
1555 .ad
1556 .sp .6
1557 .RS 4n
1558 An additional argument was expected on the command line.
1559 .RE
1561 .sp
1562 .ne 2
1563 .na
1564 \fBUnknown\fR
1565 .ad
1566 .sp .6
1567 .RS 4n
1568 A value for a specific extension was unknown.
1569 .RE
1571 .sp
1572 .ne 2
1573 .na
1574 \fB\fBAddress type \fIN\fR not supported.\fR\fR
1575 .ad
1576 .sp .6
1577 .RS 4n
1578 A name-to-address lookup returned an unsupported address family.
1579 .RE
1581 .sp
1582 .ne 2
1583 .na
1584 \fB\fB\fIN\fR is not a bit specifier\fR\fR
1585 .ad
1586 .br
1587 .na
1588 \fB\fBbit length \fIN\fR is too big for\fR\fR
1589 .ad
1590 .br
1591 .na
1592 \fB\fBstring is not a hex string\fR\fR
1593 .ad
1594 .sp .6
1595 .RS 4n
1596 Keying material was not entered appropriately.
1597 .RE
1599 .sp
1600 .ne 2
1601 .na
1602 \fB\fBCan only specify single\fR\fR
1603 .ad
1604 .sp .6
1605 .RS 4n
1606 A duplicate extension was entered.
1607 .RE
1609 .sp
1610 .ne 2
1611 .na
1612 \fB\fBDon't use extension for \fI<string>\fR for \fI<command>\fR\&.\fR\fR
1613 .ad
1614 .sp .6
1615 .RS 4n
1616 An extension not used by a command was used.
1617 .RE
1619 .sp
1620 .ne 2
1621 .na
1622 \fB\fBOne of the entered values is incorrect: Diagnostic code \fINN\fR:
1623 \fI<msg>\fR\fR\fR
1624 .ad
1625 .sp .6
1626 .RS 4n
1627 This is a general invalid parameter error. The diagnostic code and message
1628 provides more detail about what precise value was incorrect and why.
1629 .RE
1631 .SH NOTES
1632 .sp
1633 .LP
1634 In spite of its IPsec-specific name, \fBipseckey\fR is analogous to
1635 \fBroute\fR(8), in that it is a command-line interface to a socket-based
1636 administration engine, in this case, \fBPF_KEY\fR. \fBPF_KEY\fR was originally
1637 developed at the United States Naval Research Laboratory.
1638 .sp
1639 .LP
1640 To have machines communicate securely with manual keying, \fBSA\fRs need to be
1641 added by all communicating parties. If two nodes wish to communicate securely,
1642 both nodes need the appropriate \fBSA\fRs added.
1643 .sp
1644 .LP
1645 In the future \fBipseckey\fR may be invoked under additional names as other
1646 security protocols become available to \fBPF_KEY\fR.
1647 .sp
1648 .LP
1649 This command requires \fBsys_ip_config\fR privilege to operate and thus can run
1650 in the global zone and in exclusive-IP zones. The global zone can set up
1651 security associations with \fBipseckey\fR to protect traffic for shared-IP
1652 zones on the system.