1 IKEADM(1M) Maintenance Commands IKEADM(1M)
2
3
4
5 NAME
6 ikeadm - manipulate Internet Key Exchange (IKE) parameters and state
7
8 SYNOPSIS
9 ikeadm [-np]
10
11
12 ikeadm [-np] get [debug | priv | stats | defaults]
13
14
15 ikeadm [-np] set [debug | priv] [level] [file]
16
17
18 ikeadm [-np] [get | del] [p1 | rule | preshared] [id]
19
20
21 ikeadm [-np] add [rule | preshared] { description }
22
23
24 ikeadm [-np] token [login | logout] PKCS#11_Token_Object
25
26
27 ikeadm [-np] [read | write] [rule | preshared | certcache] file
28
29
30 ikeadm [-np] [dump | pls | rule | preshared]
31
32
33 ikeadm [-np] flush [p1 | certcache]
34
35
36 ikeadm help
37 [get | set | add | del | read | write | dump | flush | token]
38
39
40 DESCRIPTION
41 The ikeadm utility retrieves information from and manipulates the
42 configuration of the Internet Key Exchange (IKE) protocol daemon,
43 in.iked(1M).
44
45
46 ikeadm supports a set of operations, which may be performed on one or
47 more of the supported object types. When invoked without arguments,
48 ikeadm enters interactive mode which prints a prompt to the standard
49 output and accepts commands from the standard input until the end-of-
50 file is reached.
51
52
53 Because ikeadm manipulates sensitive keying information, you must be
54 superuser to use this command. Additionally, some of the commands
55 available require that the daemon be running in a privileged mode,
56 which is established when the daemon is started.
57
58
59 For details on how to use this command securely see .
60
61 OPTIONS
62 The following options are supported:
63
64 -n
65
66 Prevent attempts to print host and network names symbolically when
67 reporting actions. This is useful, for example, when all name
68 servers are down or are otherwise unreachable.
69
70
71 -p
72
73 Paranoid. Do not print any keying material, even if saving Security
74 Associations. Instead of an actual hexadecimal digit, print an X
75 when this flag is turned on.
76
77
78 USAGE
79 Commands
80 The following commands are supported:
81
82 add
83
84 Add the specified object. This option can be used to add a new
85 policy rule or a new preshared key to the current (running) in.iked
86 configuration. When adding a new preshared key, the command cannot
87 be invoked from the command line, as it will contain keying
88 material. The rule or key being added is specified using
89 appropriate id-value pairs as described in the ID FORMATS section.
90
91
92 del
93
94 Delete a specific object or objects from in.iked's current
95 configuration. This operation is available for IKE (Phase 1) SAs,
96 policy rules, and preshared keys. The object to be deleted is
97 specified as described in the Id Formats.
98
99
100 dump
101
102 Display all objects of the specified type known to in.iked. This
103 option can be used to display all Phase 1 SAs, policy rules,
104 preshared keys, or the certificate cache. A large amount of output
105 may be generated by this command.
106
107
108 flush
109
110 Remove all IKE (Phase 1) SAs or cached certificates from in.iked.
111
112 Note that flushing the certcache will also (as a side-effect)
113 update IKE with any new certificates added or removed.
114
115
116 get
117
118 Lookup and display the specified object. May be used to view the
119 current debug or privilege level, global statistics and default
120 values for the daemon, or a specific IKE (Phase 1) SA, policy rule,
121 or preshared key. The latter three object types require that
122 identifying information be passed in; the appropriate specification
123 for each object type is described below.
124
125
126 help
127
128 Print a brief summary of commands, or, when followed by a command,
129 prints information about that command.
130
131
132 read
133
134 Update the current in.iked configuration by reading the policy
135 rules or preshared keys from either the default location or from
136 the file specified.
137
138
139 set
140
141 Adjust the current debug or privilege level. If the debug level is
142 being modified, an output file may optionally be specified; the
143 output file must be specified if the daemon is running in the
144 background and is not currently printing to a file. When changing
145 the privilege level, adjustments may only be made to lower the
146 access level; it cannot be increased using ikeadm.
147
148
149 write
150
151 Write the current in.iked policy rule set or preshared key set to
152 the specified file. A destination file must be specified. This
153 command should not be used to overwrite the existing configuration
154 files.
155
156
157 token
158
159 Log into a PKCS#11 token object and grant access to keying material
160 or log out and invalidate access to keying material.
161
162 token can be run as a normal user with the following
163 authorizations:
164
165 o token login: solaris.network.ipsec.ike.token.login
166
167 o token logout: solaris.network.ipsec.ike.token.logout
168
169
170 Object Types
171 debug
172
173 Specifies the daemon's debug level. This determines the amount and
174 type of output provided by the daemon about its operations. The
175 debug level is actually a bitmask, with individual bits enabling
176 different types of information.
177
178
179
180
181 Description Flag Nickname
182 -------------------------------------------
183 Certificate management 0x0001 cert
184 Key management 0x0002 key
185 Operational 0x0004 op
186 Phase 1 SA creation 0x0008 phase1
187 Phase 2 SA creation 0x0010 phase2
188 PF_KEY interface 0x0020 pfkey
189 Policy management 0x0040 policy
190 Proposal construction 0x0080 prop
191 Door interface 0x0100 door
192 Config file processing 0x0200 config
193 All debug flags 0x3ff all
194
195 When specifying the debug level, either a number (decimal or
196 hexadecimal) or a string of nicknames may be given. For example,
197 88, 0x58, and phase1+phase2+policy are all equivalent, and will
198 turn on debug for phase 1 sa creation, phase 2 sa creation, and
199 policy management. A string of nicknames may also be used to remove
200 certain types of information; all-op has the effect of turning on
201 all debug except for operational messages; it is equivalent to the
202 numbers 1019 or 0x3fb.
203
204
205 priv
206
207 Specifies the daemon's access privilege level. The possible values
208 are:
209
210 Description Level Nickname
211 Base level 0 base
212 Access to preshared key info 1 modkeys
213 Access to keying material 2 keymat
214
215
216 By default, in.iked is started at the base level. A command-line
217 option can be used to start the daemon at a higher level. ikeadm
218 can be used to lower the level, but it cannot be used to raise the
219 level.
220
221 Either the numerical level or the nickname may be used to specify
222 the target privilege level.
223
224 In order to get, add, delete, dump, read, or write preshared keys,
225 the privilege level must at least give access to preshared key
226 information. However, when viewing preshared keys (either using
227 the get or dump command), the key itself will only be available if
228 the privilege level gives access to keying material. This is also
229 the case when viewing Phase 1 SAs.
230
231
232 stats
233
234 Global statistics from the daemon, covering both successful and
235 failed Phase 1 SA creation.
236
237 Reported statistics include:
238
239 o Count of current P1 SAs which the local entity initiated
240
241 o Count of current P1 SAs where the local entity was the
242 responder
243
244 o Count of all P1 SAs which the local entity initiated
245 since boot
246
247 o Count of all P1 SAs where the local entity was the
248 responder since boot
249
250 o Count of all attempted P1 SAs since boot, where the
251 local entity was the initiator; includes failed attempts
252
253 o Count of all attempted P1 SAs since boot, where the
254 local entity was the responder; includes failed attempts
255
256 o Count of all failed attempts to initiate a P1 SA, where
257 the failure occurred because the peer did not respond
258
259 o Count of all failed attempts to initiate a P1 SA, where
260 the peer responded
261
262 o Count of all failed P1 SAs where the peer was the
263 initiator
264
265 o Whether a PKCS#11 library is in use, and if applicable,
266 the PKCS#11 library that is loaded. See .
267
268
269 defaults
270
271 Display default values used by the in.iked daemon. Some values can
272 be overridden in the daemon configuration file (see ike.config(4));
273 for these values, the token name is displayed in the get defaults
274 output. The output will reflect where a configuration token has
275 changed the default.
276
277 Default values might be ignored in the event a peer system makes a
278 valid alternative proposal or they can be overridden by per-rule
279 values established in ike.config. In such instances, a get defaults
280 command continues to display the default values, not the values
281 used to override the defaults.
282
283
284 p1
285
286 An IKE Phase 1 SA. A p1 object is identified by an IP address pair
287 or a cookie pair; identification formats are described below.
288
289
290 rule
291
292 An IKE policy rule, defining the acceptable security
293 characteristics for Phase 1 SAs between specified local and remote
294 identities. A rule is identified by its label; identification
295 formats are described below.
296
297
298 preshared
299
300 A preshared key, including the local and remote identification and
301 applicable IKE mode. A preshared key is identified by an IP address
302 pair or an identity pair; identification formats are described
303 below.
304
305
306 Id Formats
307 Commands like add, del, and get require that additional information be
308 specified on the command line. In the case of the delete and get
309 commands, all that is required is to minimally identify a given object;
310 for the add command, the full object must be specified.
311
312
313 Minimal identification is accomplished in most cases by a pair of
314 values. For IP addresses, the local addr and then the remote addr are
315 specified, either in dot-notation for IPv4 addresses, colon-separated
316 hexadecimal format for IPv6 addresses, or a host name present in the
317 host name database. If a host name is given that expands to more than
318 one address, the requested operation will be performed multiple times,
319 once for each possible combination of addresses.
320
321
322 Identity pairs are made up of a local type-value pair, followed by the
323 remote type-value pair. Valid types are:
324
325 prefix
326
327 An address prefix.
328
329
330 fqdn
331
332 A fully-qualified domain name.
333
334
335 domain
336
337 Domain name, synonym for fqdn.
338
339
340 user_fqdn
341
342 User identity of the form user@fqdn.
343
344
345 mailbox
346
347 Synonym for user_fqdn.
348
349
350
351 A cookie pair is made up of the two cookies assigned to a Phase 1
352 Security Association (SA) when it is created; first is the initiator's,
353 followed by the responder's. A cookie is a 64-bit number.
354
355
356 Finally, a label (which is used to identify a policy rule) is a
357 character string assigned to the rule when it is created.
358
359
360 Formatting a rule or preshared key for the add command follows the
361 format rules for the in.iked configuration files. Both are made up of a
362 series of id-value pairs, contained in curly braces ({ and }). See
363 ike.config(4) and ike.preshared(4) for details on the formatting of
364 rules and preshared keys.
365
366 SECURITY
367 The ikeadm command allows a privileged user to enter cryptographic
368 keying information. If an adversary gains access to such information,
369 the security of IPsec traffic is compromised. The following issues
370 should be taken into account when using the ikeadm command.
371
372 o Is the TTY going over a network (interactive mode)?
373
374 If it is, then the security of the keying material is the
375 security of the network path for this TTY's traffic. Using
376 ikeadm over a clear-text telnet or rlogin session is risky.
377 Even local windows may be vulnerable to attacks where a
378 concealed program that reads window events is present.
379
380 o Is the file accessed over the network or readable to the
381 world (read/write commands)?
382
383 A network-mounted file can be sniffed by an adversary as it
384 is being read. A world-readable file with keying material in
385 it is also risky.
386
387
388 If your source address is a host that can be looked up over the
389 network, and your naming system itself is compromised, then any names
390 used will no longer be trustworthy.
391
392
393 Security weaknesses often lie in misapplication of tools, not the tools
394 themselves. It is recommended that administrators are cautious when
395 using the ikeadm command. The safest mode of operation is probably on a
396 console, or other hard-connected TTY.
397
398
399 For additional information regarding this subject, see the afterward by
400 Matt Blaze in Bruce Schneier's Applied Cryptography: Protocols,
401 Algorithms, and Source Code in C.
402
403 EXAMPLES
404 Example 1 Emptying out all Phase 1 Security Associations
405
406
407 The following command empties out all Phase 1 Security Associations:
408
409
410 example# ikeadm flush p1
411
412
413
414 Example 2 Displaying all Phase 1 Security Associations
415
416
417 The following command displays all Phase 1 Security Associations:
418
419
420 example# ikeadm dump p1
421
422
423
424 Example 3 Deleting a Specific Phase 1 Security Association
425
426
427 The following command deletes the specified Phase 1 Security
428 Associations:
429
430
431 example# ikeadm del p1 local_ip remote_ip
432
433
434
435 Example 4 Adding a Rule From a File
436
437
438 The following command adds a rule from a file:
439
440
441 example# ikeadm add rule rule_file
442
443
444
445 Example 5 Adding a Preshared Key
446
447
448 The following command adds a preshared key:
449
450
451 example# ikeadm
452 ikeadm> add preshared { localidtype ip localid local_ip
453 remoteidtype ip remoteid remote_ip ike_mode main
454 key 1234567890abcdef1234567890abcdef }
455
456
457
458 Example 6 Saving All Preshared Keys to a File
459
460
461 The following command saves all preshared keys to a file:
462
463
464 example# ikeadm write preshared target_file
465
466
467
468 Example 7 Viewing a Particular Rule
469
470
471 The following command views a particular rule:
472
473
474 example# ikeadm get rule rule_label
475
476
477
478 Example 8 Reading in New Rules from ike.config
479
480
481 The following command reads in new rules from the ike.config file:
482
483
484 example# ikeadm read rules
485
486
487
488 Example 9 Lowering the Privilege Level
489
490
491 The following command lowers the privilege level:
492
493
494 example# ikeadm set priv base
495
496
497
498 Example 10 Viewing the Debug Level
499
500
501 The following command shows the current debug level
502
503
504 example# ikeadm get debug
505
506
507
508 Example 11 Using stats to Verify Hardware Accelerator
509
510
511 The following example shows how stats may include an optional line at
512 the end to indicate if IKE is using a PKCS#11 library to accelerate
513 public-key operations, if applicable.
514
515
516 example# ikeadm get stats
517 Phase 1 SA counts:
518 Current: initiator: 0 responder: 0
519 Total: initiator: 21 responder: 27
520 Attempted:initiator: 21 responder: 27
521 Failed: initiator: 0 responder: 0
522 initiator fails include 0 time-out(s)
523 PKCS#11 library linked in from /opt/SUNWconn/lib/libpkcs11.so
524 example#
525
526
527
528 Example 12 Displaying the Certificate Cache
529
530
531 The following command shows the certificate cache and the status of
532 associated private keys, if applicable:
533
534
535 example# ikeadm dump certcache
536
537
538
539 Example 13 Logging into a PKCS#11 Token
540
541
542 The following command shows logging into a PKCS#11 token object and
543 unlocking private keys:
544
545
546 example# ikeadm token login "Sun Metaslot"
547 Enter PIN for PKCS#11 token:
548 ikeadm: PKCS#11 operation successful
549
550
551
552 EXIT STATUS
553 The following exit values are returned:
554
555 0
556 Successful completion.
557
558
559 non-zero
560 An error occurred. Writes an appropriate error message to
561 standard error.
562
563
564 ATTRIBUTES
565 See attributes(5) for descriptions of the following attributes:
566
567
568
569
570 +--------------------+------------------+
571 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
572 +--------------------+------------------+
573 |Interface Stability | Not an Interface |
574 +--------------------+------------------+
575
576 SEE ALSO
577 in.iked(1M), ike.config(4), ike.preshared(4), attributes(5), ipsec(7P)
578
579
580 Schneier, Bruce, Applied Cryptography: Protocols, Algorithms, and
581 Source Code in C, Second Edition, John Wiley & Sons, New York, NY,
582 1996.
583
584 NOTES
585 As in.iked can run only in the global zone and exclusive-IP zones, this
586 command is not useful in shared-IP zones.
587
588
589
590 January 27, 2009 IKEADM(1M)