| blob | 40a4cfd42a4e39daf28568fec90ab3779797b82a |
1 '\" te
2 .\" Copyright (c) 2009, 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 IKEADM 1M "Jan 27, 2009"
7 .SH NAME
8 ikeadm \- manipulate Internet Key Exchange (IKE) parameters and state
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBikeadm\fR [\fB-np\fR]
13 .fi
15 .LP
16 .nf
17 \fBikeadm\fR [\fB-np\fR] get [debug | priv | stats | defaults]
18 .fi
20 .LP
21 .nf
22 \fBikeadm\fR [\fB-np\fR] set [debug | priv] [level] [file]
23 .fi
25 .LP
26 .nf
27 \fBikeadm\fR [\fB-np\fR] [get | del] [p1 | rule | preshared] [id]
28 .fi
30 .LP
31 .nf
32 \fBikeadm\fR [\fB-np\fR] add [rule | preshared] { \fIdescription\fR }
33 .fi
35 .LP
36 .nf
37 ikeadm [\fB-np\fR] token [login | logout] \fIPKCS#11_Token_Object\fR
38 .fi
40 .LP
41 .nf
42 \fBikeadm\fR [\fB-np\fR] [read | write] [rule | preshared | certcache] \fIfile\fR
43 .fi
45 .LP
46 .nf
47 \fBikeadm\fR [\fB-np\fR] [dump | pls | rule | preshared]
48 .fi
50 .LP
51 .nf
52 \fBikeadm\fR [\fB-np\fR] flush [p1 | certcache]
53 .fi
55 .LP
56 .nf
57 \fBikeadm\fR help
58 [get | set | add | del | read | write | dump | flush | token]
59 .fi
61 .SH DESCRIPTION
62 .sp
63 .LP
64 The \fBikeadm\fR utility retrieves information from and manipulates the
65 configuration of the Internet Key Exchange (\fBIKE\fR) protocol daemon,
66 \fBin.iked\fR(1M).
67 .sp
68 .LP
69 \fBikeadm\fR supports a set of operations, which may be performed on one or
70 more of the supported object types. When invoked without arguments,
71 \fBikeadm\fR enters interactive mode which prints a prompt to the standard
72 output and accepts commands from the standard input until the end-of-file is
73 reached.
74 .sp
75 .LP
76 Because \fBikeadm\fR manipulates sensitive keying information, you must be
77 superuser to use this command. Additionally, some of the commands available
78 require that the daemon be running in a privileged mode, which is established
79 when the daemon is started.
80 .sp
81 .LP
82 For details on how to use this command securely see .
83 .SH OPTIONS
84 .sp
85 .LP
86 The following options are supported:
87 .sp
88 .ne 2
89 .na
90 \fB\fB-n\fR\fR
91 .ad
92 .sp .6
93 .RS 4n
94 Prevent attempts to print host and network names symbolically when reporting
95 actions. This is useful, for example, when all name servers are down or are
96 otherwise unreachable.
97 .RE
99 .sp
100 .ne 2
101 .na
102 \fB\fB-p\fR\fR
103 .ad
104 .sp .6
105 .RS 4n
106 Paranoid. Do not print any keying material, even if saving Security
107 Associations. Instead of an actual hexadecimal digit, print an \fBX\fR when
108 this flag is turned on.
109 .RE
111 .SH USAGE
112 .SS "Commands"
113 .sp
114 .LP
115 The following commands are supported:
116 .sp
117 .ne 2
118 .na
119 \fB\fBadd\fR\fR
120 .ad
121 .sp .6
122 .RS 4n
123 Add the specified object. This option can be used to add a new policy rule or a
124 new preshared key to the current (running) in.iked configuration. When adding a
125 new preshared key, the command cannot be invoked from the command line, as it
126 will contain keying material. The rule or key being added is specified using
127 appropriate id-value pairs as described in the \fBID FORMATS\fR section.
128 .RE
130 .sp
131 .ne 2
132 .na
133 \fB\fBdel\fR\fR
134 .ad
135 .sp .6
136 .RS 4n
137 Delete a specific object or objects from \fBin.iked\fR's current configuration.
138 This operation is available for \fBIKE\fR (Phase 1) \fBSA\fRs, policy rules,
139 and preshared keys. The object to be deleted is specified as described in the
140 \fBId Formats\fR.
141 .RE
143 .sp
144 .ne 2
145 .na
146 \fB\fBdump\fR\fR
147 .ad
148 .sp .6
149 .RS 4n
150 Display all objects of the specified type known to \fBin.iked\fR. This option
151 can be used to display all Phase 1 \fBSA\fRs, policy rules, preshared keys, or
152 the certificate cache. A large amount of output may be generated by this
153 command.
154 .RE
156 .sp
157 .ne 2
158 .na
159 \fB\fBflush\fR\fR
160 .ad
161 .sp .6
162 .RS 4n
163 Remove all \fBIKE\fR (Phase 1) \fBSA\fRs or cached certificates from
164 \fBin.iked\fR.
165 .sp
166 Note that flushing the \fBcertcache\fR will also (as a side-effect) update IKE
167 with any new certificates added or removed.
168 .RE
170 .sp
171 .ne 2
172 .na
173 \fB\fBget\fR\fR
174 .ad
175 .sp .6
176 .RS 4n
177 Lookup and display the specified object. May be used to view the current debug
178 or privilege level, global statistics and default values for the daemon, or a
179 specific \fBIKE\fR (Phase 1) \fBSA\fR, policy rule, or preshared key. The
180 latter three object types require that identifying information be passed in;
181 the appropriate specification for each object type is described below.
182 .RE
184 .sp
185 .ne 2
186 .na
187 \fB\fBhelp\fR\fR
188 .ad
189 .sp .6
190 .RS 4n
191 Print a brief summary of commands, or, when followed by a command, prints
192 information about that command.
193 .RE
195 .sp
196 .ne 2
197 .na
198 \fB\fBread\fR\fR
199 .ad
200 .sp .6
201 .RS 4n
202 Update the current \fBin.iked\fR configuration by reading the policy rules or
203 preshared keys from either the default location or from the file specified.
204 .RE
206 .sp
207 .ne 2
208 .na
209 \fB\fBset\fR\fR
210 .ad
211 .sp .6
212 .RS 4n
213 Adjust the current debug or privilege level. If the debug level is being
214 modified, an output file may optionally be specified; the output file
215 \fBmust\fR be specified if the daemon is running in the background and is not
216 currently printing to a file. When changing the privilege level, adjustments
217 may only be made to lower the access level; it cannot be increased using
218 ikeadm.
219 .RE
221 .sp
222 .ne 2
223 .na
224 \fB\fBwrite\fR\fR
225 .ad
226 .sp .6
227 .RS 4n
228 Write the current \fBin.iked\fR policy rule set or preshared key set to the
229 specified file. A destination file must be specified. This command should not
230 be used to overwrite the existing configuration files.
231 .RE
233 .sp
234 .ne 2
235 .na
236 \fB\fBtoken\fR\fR
237 .ad
238 .sp .6
239 .RS 4n
240 Log into a PKCS#11 token object and grant access to keying material or log out
241 and invalidate access to keying material.
242 .sp
243 \fBtoken\fR can be run as a normal user with the following authorizations:
244 .RS +4
245 .TP
246 .ie t \(bu
247 .el o
248 \fBtoken\fR login: \fBsolaris.network.ipsec.ike.token.login\fR
249 .RE
250 .RS +4
251 .TP
252 .ie t \(bu
253 .el o
254 \fBtoken\fR logout: \fBsolaris.network.ipsec.ike.token.logout\fR
255 .RE
256 .RE
258 .SS "Object Types"
259 .sp
260 .ne 2
261 .na
262 \fBdebug\fR
263 .ad
264 .sp .6
265 .RS 4n
266 Specifies the daemon's debug level. This determines the amount and type of
267 output provided by the daemon about its operations. The debug level is actually
268 a bitmask, with individual bits enabling different types of information.
269 .sp
271 .sp
272 .TS
273 c c c
274 l l l .
275 Description Flag Nickname
276 _
277 Certificate management 0x0001 cert
278 Key management 0x0002 key
279 Operational 0x0004 op
280 Phase 1 SA creation 0x0008 phase1
281 Phase 2 SA creation 0x0010 phase2
282 PF_KEY interface 0x0020 pfkey
283 Policy management 0x0040 policy
284 Proposal construction 0x0080 prop
285 Door interface 0x0100 door
286 Config file processing 0x0200 config
287 All debug flags 0x3ff all
288 .TE
290 When specifying the debug level, either a number (decimal or hexadecimal) or a
291 string of nicknames may be given. For example, \fB88\fR, \fB0x58\fR, and
292 \fBphase1\fR+\fBphase2\fR+\fBpolicy\fR are all equivalent, and will turn on
293 debug for \fBphase 1\fR \fBsa\fR creation, \fBphase 2 sa\fR creation, and
294 policy management. A string of nicknames may also be used to remove certain
295 types of information; \fBall-op\fR has the effect of turning on all debug
296 \fBexcept\fR for operational messages; it is equivalent to the numbers
297 \fB1019\fR or \fB0x3fb\fR.
298 .RE
300 .sp
301 .ne 2
302 .na
303 \fBpriv\fR
304 .ad
305 .sp .6
306 .RS 4n
307 Specifies the daemon's access privilege level. The possible values are:
308 .sp
309 .in +2
310 .nf
311 Description Level Nickname
312 Base level 0 base
313 Access to preshared key info 1 modkeys
314 Access to keying material 2 keymat
315 .fi
316 .in -2
317 .sp
319 By default, \fBin.iked\fR is started at the base level. A command-line option
320 can be used to start the daemon at a higher level. \fBikeadm\fR can be used to
321 lower the level, but it cannot be used to raise the level.
322 .sp
323 Either the numerical level or the nickname may be used to specify the target
324 privilege level.
325 .sp
326 In order to get, add, delete, dump, read, or write preshared keys, the
327 privilege level must at least give access to preshared key information.
328 However, when viewing preshared keys (either using the get or dump command),
329 the key itself will only be available if the privilege level gives access to
330 keying material. This is also the case when viewing Phase 1 \fBSA\fRs.
331 .RE
333 .sp
334 .ne 2
335 .na
336 \fBstats\fR
337 .ad
338 .sp .6
339 .RS 4n
340 Global statistics from the daemon, covering both successful and failed Phase 1
341 \fBSA\fR creation.
342 .sp
343 Reported statistics include:
344 .RS +4
345 .TP
346 .ie t \(bu
347 .el o
348 Count of current P1 \fBSA\fRs which the local entity initiated
349 .RE
350 .RS +4
351 .TP
352 .ie t \(bu
353 .el o
354 Count of current P1 \fBSA\fRs where the local entity was the responder
355 .RE
356 .RS +4
357 .TP
358 .ie t \(bu
359 .el o
360 Count of all P1 \fBSA\fRs which the local entity initiated since boot
361 .RE
362 .RS +4
363 .TP
364 .ie t \(bu
365 .el o
366 Count of all P1 \fBSA\fRs where the local entity was the responder since boot
367 .RE
368 .RS +4
369 .TP
370 .ie t \(bu
371 .el o
372 Count of all attempted \fBP1\fR \fBSA\fRs since boot, where the local entity
373 was the initiator; includes failed attempts
374 .RE
375 .RS +4
376 .TP
377 .ie t \(bu
378 .el o
379 Count of all attempted P1 \fBSA\fRs since boot, where the local entity was the
380 responder; includes failed attempts
381 .RE
382 .RS +4
383 .TP
384 .ie t \(bu
385 .el o
386 Count of all failed attempts to initiate a \fBP1\fR \fBSA\fR, where the failure
387 occurred because the peer did not respond
388 .RE
389 .RS +4
390 .TP
391 .ie t \(bu
392 .el o
393 Count of all failed attempts to initiate a P1 \fBSA\fR, where the peer
394 responded
395 .RE
396 .RS +4
397 .TP
398 .ie t \(bu
399 .el o
400 Count of all failed \fBP1\fR \fBSA\fRs where the peer was the initiator
401 .RE
402 .RS +4
403 .TP
404 .ie t \(bu
405 .el o
406 Whether a PKCS#11 library is in use, and if applicable, the PKCS#11 library
407 that is loaded. See .
408 .RE
409 .RE
411 .sp
412 .ne 2
413 .na
414 \fBdefaults\fR
415 .ad
416 .sp .6
417 .RS 4n
418 Display default values used by the \fBin.iked\fR daemon. Some values can be
419 overriden in the daemon configuration file (see \fBike.config\fR(4)); for these
420 values, the token name is displayed in the \fBget defaults\fR output. The
421 output will reflect where a configuration token has changed the default.
422 .sp
423 Default values might be ignored in the event a peer system makes a valid
424 alternative proposal or they can be overriden by per-rule values established in
425 \fBike.config\fR. In such instances, a \fBget defaults\fR command continues to
426 display the default values, not the values used to override the defaults.
427 .RE
429 .sp
430 .ne 2
431 .na
432 \fBp1\fR
433 .ad
434 .sp .6
435 .RS 4n
436 An \fBIKE\fR Phase 1 \fBSA\fR. A \fBp1\fR object is identified by an \fBIP\fR
437 address pair or a cookie pair; identification formats are described below.
438 .RE
440 .sp
441 .ne 2
442 .na
443 \fBrule\fR
444 .ad
445 .sp .6
446 .RS 4n
447 An \fBIKE\fR policy rule, defining the acceptable security characteristics for
448 Phase 1 \fBSA\fRs between specified local and remote identities. A rule is
449 identified by its label; identification formats are described below.
450 .RE
452 .sp
453 .ne 2
454 .na
455 \fBpreshared\fR
456 .ad
457 .sp .6
458 .RS 4n
459 A preshared key, including the local and remote identification and applicable
460 \fBIKE\fR mode. A preshared key is identified by an \fBIP\fR address pair or an
461 identity pair; identification formats are described below.
462 .RE
464 .SS "Id Formats"
465 .sp
466 .LP
467 Commands like \fBadd\fR, \fBdel\fR, and \fBget\fR require that additional
468 information be specified on the command line. In the case of the delete and get
469 commands, all that is required is to minimally identify a given object; for the
470 add command, the full object must be specified.
471 .sp
472 .LP
473 Minimal identification is accomplished in most cases by a pair of values. For
474 \fBIP\fR addresses, the local addr and then the remote addr are specified,
475 either in dot-notation for IPv4 addresses, colon-separated hexadecimal format
476 for IPv6 addresses, or a host name present in the host name database. If a host
477 name is given that expands to more than one address, the requested operation
478 will be performed multiple times, once for each possible combination of
479 addresses.
480 .sp
481 .LP
482 Identity pairs are made up of a local type-value pair, followed by the remote
483 type-value pair. Valid types are:
484 .sp
485 .ne 2
486 .na
487 \fBprefix\fR
488 .ad
489 .sp .6
490 .RS 4n
491 An address prefix.
492 .RE
494 .sp
495 .ne 2
496 .na
497 \fBfqdn\fR
498 .ad
499 .sp .6
500 .RS 4n
501 A fully-qualified domain name.
502 .RE
504 .sp
505 .ne 2
506 .na
507 \fBdomain\fR
508 .ad
509 .sp .6
510 .RS 4n
511 Domain name, synonym for fqdn.
512 .RE
514 .sp
515 .ne 2
516 .na
517 \fBuser_fqdn\fR
518 .ad
519 .sp .6
520 .RS 4n
521 User identity of the form \fIuser\fR@fqdn.
522 .RE
524 .sp
525 .ne 2
526 .na
527 \fBmailbox\fR
528 .ad
529 .sp .6
530 .RS 4n
531 Synonym for \fBuser_fqdn\fR.
532 .RE
534 .sp
535 .LP
536 A cookie pair is made up of the two cookies assigned to a Phase 1 Security
537 Association (\fBSA\fR) when it is created; first is the initiator's, followed
538 by the responder's. A cookie is a 64-bit number.
539 .sp
540 .LP
541 Finally, a label (which is used to identify a policy rule) is a character
542 string assigned to the rule when it is created.
543 .sp
544 .LP
545 Formatting a rule or preshared key for the add command follows the format rules
546 for the in.iked configuration files. Both are made up of a series of id-value
547 pairs, contained in curly braces (\fB{\fR and \fB}\fR). See \fBike.config\fR(4)
548 and \fBike.preshared\fR(4) for details on the formatting of rules and preshared
549 keys.
550 .SH SECURITY
551 .sp
552 .LP
553 The \fBikeadm\fR command allows a privileged user to enter cryptographic keying
554 information. If an adversary gains access to such information, the security of
555 IPsec traffic is compromised. The following issues should be taken into account
556 when using the \fBikeadm\fR command.
557 .RS +4
558 .TP
559 .ie t \(bu
560 .el o
561 Is the \fBTTY\fR going over a network (interactive mode)?
562 .sp
563 If it is, then the security of the keying material is the security of the
564 network path for this \fBTTY\fR's traffic. Using \fBikeadm\fR over a clear-text
565 telnet or rlogin session is risky. Even local windows may be vulnerable to
566 attacks where a concealed program that reads window events is present.
567 .RE
568 .RS +4
569 .TP
570 .ie t \(bu
571 .el o
572 Is the file accessed over the network or readable to the world (read/write
573 commands)?
574 .sp
575 A network-mounted file can be sniffed by an adversary as it is being read. A
576 world-readable file with keying material in it is also risky.
577 .RE
578 .sp
579 .LP
580 If your source address is a host that can be looked up over the network, and
581 your naming system itself is compromised, then any names used will no longer be
582 trustworthy.
583 .sp
584 .LP
585 Security weaknesses often lie in misapplication of tools, not the tools
586 themselves. It is recommended that administrators are cautious when using the
587 \fBikeadm\fR command. The safest mode of operation is probably on a console, or
588 other hard-connected \fBTTY\fR.
589 .sp
590 .LP
591 For additional information regarding this subject, see the afterward by Matt
592 Blaze in Bruce Schneier's \fIApplied Cryptography: Protocols, Algorithms, and
593 Source Code in C.\fR
594 .SH EXAMPLES
595 .LP
596 \fBExample 1 \fREmptying out all Phase 1 Security Associations
597 .sp
598 .LP
599 The following command empties out all Phase 1 Security Associations:
601 .sp
602 .in +2
603 .nf
604 example# \fBikeadm flush p1\fR
605 .fi
606 .in -2
607 .sp
609 .LP
610 \fBExample 2 \fRDisplaying all Phase 1 Security Associations
611 .sp
612 .LP
613 The following command displays all Phase 1 Security Associations:
615 .sp
616 .in +2
617 .nf
618 example# \fBikeadm dump p1\fR
619 .fi
620 .in -2
621 .sp
623 .LP
624 \fBExample 3 \fRDeleting a Specific Phase 1 Security Association
625 .sp
626 .LP
627 The following command deletes the specified Phase 1 Security Associations:
629 .sp
630 .in +2
631 .nf
632 example# \fBikeadm del p1 local_ip remote_ip\fR
633 .fi
634 .in -2
635 .sp
637 .LP
638 \fBExample 4 \fRAdding a Rule From a File
639 .sp
640 .LP
641 The following command adds a rule from a file:
643 .sp
644 .in +2
645 .nf
646 example# \fBikeadm add rule rule_file\fR
647 .fi
648 .in -2
649 .sp
651 .LP
652 \fBExample 5 \fRAdding a Preshared Key
653 .sp
654 .LP
655 The following command adds a preshared key:
657 .sp
658 .in +2
659 .nf
660 example# \fBikeadm\fR
661 ikeadm> \fBadd preshared { localidtype ip localid local_ip
662 remoteidtype ip remoteid remote_ip ike_mode main
663 key 1234567890abcdef1234567890abcdef }\fR
664 .fi
665 .in -2
666 .sp
668 .LP
669 \fBExample 6 \fRSaving All Preshared Keys to a File
670 .sp
671 .LP
672 The following command saves all preshared keys to a file:
674 .sp
675 .in +2
676 .nf
677 example# \fBikeadm write preshared target_file\fR
678 .fi
679 .in -2
680 .sp
682 .LP
683 \fBExample 7 \fRViewing a Particular Rule
684 .sp
685 .LP
686 The following command views a particular rule:
688 .sp
689 .in +2
690 .nf
691 example# \fBikeadm get rule rule_label\fR
692 .fi
693 .in -2
694 .sp
696 .LP
697 \fBExample 8 \fRReading in New Rules from \fBike.config\fR
698 .sp
699 .LP
700 The following command reads in new rules from the ike.config file:
702 .sp
703 .in +2
704 .nf
705 example# \fBikeadm read rules\fR
706 .fi
707 .in -2
708 .sp
710 .LP
711 \fBExample 9 \fRLowering the Privilege Level
712 .sp
713 .LP
714 The following command lowers the privilege level:
716 .sp
717 .in +2
718 .nf
719 example# \fBikeadm set priv base\fR
720 .fi
721 .in -2
722 .sp
724 .LP
725 \fBExample 10 \fRViewing the Debug Level
726 .sp
727 .LP
728 The following command shows the current debug level
730 .sp
731 .in +2
732 .nf
733 example# \fBikeadm get debug\fR
734 .fi
735 .in -2
736 .sp
738 .LP
739 \fBExample 11 \fRUsing stats to Verify Hardware Accelerator
740 .sp
741 .LP
742 The following example shows how stats may include an optional line at the end
743 to indicate if IKE is using a PKCS#11 library to accelerate public-key
744 operations, if applicable.
746 .sp
747 .in +2
748 .nf
749 example# \fBikeadm get stats\fR
750 Phase 1 SA counts:
751 Current: initiator: 0 responder: 0
752 Total: initiator: 21 responder: 27
753 Attempted:initiator: 21 responder: 27
754 Failed: initiator: 0 responder: 0
755 initiator fails include 0 time-out(s)
756 PKCS#11 library linked in from /opt/SUNWconn/lib/libpkcs11.so
757 example#
758 .fi
759 .in -2
760 .sp
762 .LP
763 \fBExample 12 \fRDisplaying the Certificate Cache
764 .sp
765 .LP
766 The following command shows the certificate cache and the status of associated
767 private keys, if applicable:
769 .sp
770 .in +2
771 .nf
772 example# \fBikeadm dump certcache\fR
773 .fi
774 .in -2
775 .sp
777 .LP
778 \fBExample 13 \fRLogging into a PKCS#11 Token
779 .sp
780 .LP
781 The following command shows logging into a PKCS#11 token object and unlocking
782 private keys:
784 .sp
785 .in +2
786 .nf
787 example# \fBikeadm token login "Sun Metaslot"\fR
788 Enter PIN for PKCS#11 token:
789 ikeadm: PKCS#11 operation successful
790 .fi
791 .in -2
792 .sp
794 .SH EXIT STATUS
795 .sp
796 .LP
797 The following exit values are returned:
798 .sp
799 .ne 2
800 .na
801 \fB\fB0\fR\fR
802 .ad
803 .RS 12n
804 Successful completion.
805 .RE
807 .sp
808 .ne 2
809 .na
810 \fB\fBnon-zero\fR\fR
811 .ad
812 .RS 12n
813 An error occurred. Writes an appropriate error message to standard error.
814 .RE
816 .SH ATTRIBUTES
817 .sp
818 .LP
819 See \fBattributes\fR(5) for descriptions of the following attributes:
820 .sp
822 .sp
823 .TS
824 box;
825 c | c
826 l | l .
827 ATTRIBUTE TYPE ATTRIBUTE VALUE
828 _
829 Interface Stability Not an Interface
830 .TE
832 .SH SEE ALSO
833 .sp
834 .LP
835 \fBin.iked\fR(1M), \fBike.config\fR(4), \fBike.preshared\fR(4),
836 \fBattributes\fR(5), \fBipsec\fR(7P)
837 .sp
838 .LP
839 Schneier, Bruce, \fIApplied Cryptography: Protocols, Algorithms, and Source
840 Code in C\fR, Second Edition, John Wiley & Sons, New York, NY, 1996.
841 .SH NOTES
842 .sp
843 .LP
844 As \fBin.iked\fR can run only in the global zone and exclusive-IP zones, this
845 command is not useful in shared-IP zones.