1ikecert(1M) System Administration Commands ikecert(1M)
2
3
4
6 ikecert - manipulates the machine's on-filesystem public-key certifi‐
7 cate databases
8
10 ikecert certlocal
11 [-a | -e | -h | -k | -l | -r | -U | -C | -L]
12 [[-p] -T PKCS#11 token identifier]
13 [option_specific_arguments]...
14
15
16 ikecert certdb [-a | -e | -h | -l | -r | -U | -C | -L]
17 [[-p] -T PKCS#11 token identifier]
18 [option_specific_arguments]...
19
20
21 ikecert certrldb [-a | -e | -h | -l | -r]
22 [option_specific_arguments]...
23
24
25 ikecert tokens
26
27
29 The ikecert command manipulates the machine's on-filesystem public-key
30 certificate databases. See the "Files" section, below.
31
32
33 ikecert has three subcommands, one for each of the three major reposi‐
34 tories, plus one for listing available hardware tokens:
35
36 o certlocal deals with the private-key repository,
37
38 o certdb deals with the public-key repository, and:
39
40 o certrldb deals with the certificate revocation list (CRL)
41 repository.
42
43 o tokens shows the available PKCS#11 tokens for a given
44 PKCS#11 library.
45
46
47 The only supported PKCS#11 library and hardware is the Sun Crypto‐
48 graphic Accelerator 4000.
49
51 Except for tokens, each subcommand requires one option, possibly fol‐
52 lowed by one or more option-specific arguments.
53
54
55 The tokens subcommand lists all available tokens in the PKCS#11 library
56 specified in /etc/inet/ike/config.
57
58
59 The following options are supported:
60
61 -a
62
63
64 certlocal
65
66 When specified with the certlocal subcommand, this option
67 installs (adds) a private key into the Internet Key Exchange
68 (IKE) local ID database. The key data is read from standard
69 input, and is in either Solaris-only format or unencrypted
70 PKCS#8 DER format. Key format is automatically detected. PKCS#8
71 key files in PEM format and files in password protected,
72 encrypted format are not recognized, but can be converted
73 appropriately using tools available in OpenSSL.
74
75 This option cannot be used with PKCS#11 hardware objects when
76 the corresponding public certificate is not already present in
77 the IKE database. When importing both a public certificate and
78 a private key, the public portion must be imported first using
79 the certdb subcommand.
80
81
82 certdb
83
84 When specified with the certdb subcommand, this option reads a
85 certificate from standard input and adds it to the IKE certifi‐
86 cate database. The certificate must be a X.509 certificate in
87 PEM Base64 or ASN.1 BER encoding. The certificate adopts the
88 name of its identity.
89
90 This option can import a certificate into a PKCS#11 hardware
91 key store one of two ways: Either a matching public key object
92 and an existing private key object were created using the cert‐
93 local -kc option, or if a PKCS#11 token is explicitly specified
94 using the -T option.
95
96
97 certrldb
98
99 When specified with the certrldb subcommand, this option
100 installs (adds) a CRL into the IKE database. The CRL reads from
101 standard input.
102
103
104
105 -e [-f pkcs8] slot
106
107
108 certlocal
109
110 When specified with the certlocal subcommand, this option
111 extracts a private key from the IKE local ID database. The key
112 data are written to standard output. The slot specifies which
113 private key to extract. Private keys are only extracted in
114 binary/ber format.
115
116 Use this option with extreme caution. See the "Security" sec‐
117 tion, below.
118
119 This option will not work with PKCS#11 hardware objects.
120
121 When used in conjunction with "-f pkcs8", the private key is
122 extracted in unencrypted PKCS#8 format.
123
124
125
126 -e [-f output-format] certspec
127
128
129 certdb
130
131 When specified with the certdb subcommand, this option extracts
132 a certificate from the IKE certificate database which matches
133 the certspec and writes it to standard output. The output-for‐
134 mat option specifies the encoding format. Valid options are PEM
135 and BER. This extracts the first matching identity. The default
136 output format is PEM.
137
138
139 certrldb
140
141 When specified with the certrldb subcommand, this option
142 extracts a CRL from the IKE database. The key data are written
143 to standard output. The certspec specifies which CRL that is
144 extracted. The first one that matches in the database is
145 extracted. See NOTES, below, for details on certspec patterns.
146
147
148
149 -kc -m keysize -t keytype -D dname -A altname[ ... ]
150 [-S validity start_time][-F validity end_time]
151 [-T PKCS#11 token identifier]
152
153
154 certlocal
155
156 When specified with the certlocal subcommand, this option gen‐
157 erates a IKE public/private key pair and adds it into the local
158 ID database. It also generates a certificate request and sends
159 that to standard output. For details on the above options see
160 for details on the dname argument and see ALTERNATIVE NAMES for
161 details on the altname argument(s) to this command.
162
163 If -T is specified, the hardware token will generate the pair
164 of keys.
165
166 If -p is specified with -T, the PKCS#11 token pin is stored in
167 the clear on-disk, with root-protected file permissions. If not
168 specified, one must unlock the token with ikeadm(1M) once
169 in.iked(1M) is running.
170
171
172
173 -ks -m keysize -t keytype -D dname -A altname[ ... ]
174 [-S validity start_time][-F validity end_time]
175 [-f output-format][[-p] -T PKCS#11 token identifier]
176
177
178
179 certlocal
180
181 When specified with the certlocal subcommand, generates a pub‐
182 lic/private key pair and adds it into the local ID database.
183 This option also generates a self-signed certificate and
184 installs it into the certificate database. See NOTES, below,
185 for details on the dname and altname arguments to this command.
186
187 If -T is specified, the hardware token will generate the pair
188 of keys, and the self-signed certificate will also be stored in
189 the hardware.
190
191
192
193 -l [-v] [slot]
194
195
196 certlocal
197
198 When specified with the certlocal subcommand, this option lists
199 private keys in the local ID database. The -v option switches
200 output to a verbose mode where the entire certificate is
201 printed.
202
203 Use the -voption with extreme caution. See the "Security" sec‐
204 tion, below. The -v option will not work with PKCS#11 hardware
205 objects.
206
207
208
209 -l [-v] [certspec]
210
211
212 certdb
213
214 When specified with the certdb subcommand, this option lists
215 certificates in the IKE certificate database matching the cert‐
216 spec, if any pattern is given. The list displays the identity
217 string of the certificates, as well as, the private key if in
218 the key database. The -v switches the output to a verbose mode
219 where the entire certificate is printed.
220
221 If the matching ceritifcate is on a hardware token, the token
222 ID is also listed.
223
224
225 certrldb
226
227 When specified with the certrldb subcommand, this option lists
228 the CRLs in the IKE database along with any certificates that
229 reside in the database and match the Issuer Name. certspec can
230 be used to specify to list a specific CRL. The -v option
231 switches the output to a verbose mode where the entire certifi‐
232 cate is printed. See NOTES, below, for details oncertspec pat‐
233 terns.
234
235
236
237 -r slot
238
239
240 certlocal
241
242 When specified with the certlocal subcommand, deletes the local
243 ID in the specified slot. If there is a corresponding public
244 key, it is not be deleted. If this slot is deemed as "cor‐
245 rupted" or otherwise unrecognizable, it is deleted as well.
246
247 If this is invoked on a PKCS#11 hardware object, it will also
248 delete the PKCS#11 public key and private key objects. If the
249 public key object was already deleted by certdb -r, that is not
250 a problem.
251
252
253
254 -r certspec
255
256
257 certdb
258
259 Removes certificates from the IKE certificate database. Cer‐
260 tificates matching the specified certificate pattern are
261 deleted. Any private keys in the certlocal database correspond‐
262 ing to these certificates are not deleted. This removes the
263 first matching identity.
264
265 If the pattern specifies a slot and the slot is deemed as "cor‐
266 rupted" or otherwise unrecognizable, it is deleted as well.
267
268 If this is invoked on a PKCS#11 hardware object, it will also
269 delete the certificate and the PKCS#11 public key object. If
270 the public key object was already deleted by certlocal -r, that
271 is not a problem.
272
273
274 certrldb
275
276 When specified with the certrldb subcommand, this option
277 deletes the CRL with the given certspec.
278
279
280
281 -U slot
282
283
284 certlocal
285
286 When specified with the certlocal subcommand and the -T flag,
287 this option unlinks a PKCS#11 private key object from the IKE
288 database. There will be no attempt to access the hardware key‐
289 store or to validate or remove the on-token private key object.
290 The object is simply disassociated from the IKE database.
291
292
293 certdb
294
295 When specified with the certdb subcommand and the -T flag, this
296 option unlinks a PKCS#11 certificate object from the IKE data‐
297 base. There will be no attempt to access the hardware keystore
298 or to validate or remove the on-token certificate or public key
299 objects. The objects are simply disassociated from the IKE
300 database.
301
302
303
304 -C certspec
305
306
307 certlocal
308
309 When specified with the certlocal subcommand, this option
310 copies both the private key and its corresponding certificate
311 and the public key from the on-disk keystore to the hardware
312 keystore specified by its PKCS#11 token. This subcommand
313 attempts to create each of these components, even if one part
314 fails. In all cases, the original on-disk private key and pub‐
315 lic certificate are still retained and must be deleted sepa‐
316 rately. Some hardware keystores, such as FIPS-140 compliant
317 devices, may not support migration of private key objects in
318 this manner.
319
320
321 certdb
322
323 When specified with the certdb subcommand, this option copies
324 the certificate matching the given certspec and corresponding
325 public key from the on-disk keystore to the hardware keystore
326 specified by its PKCS#11 token. The original public certificate
327 is still retained and must be deleted separately, if desired.
328
329 If -p is specified, the PKCS#11 token pin is stored in the
330 clear on-disk, with root-protected file permissions. If not
331 specified, one must unlock the token with ikeadm(1M) once
332 in.iked(1M) is running.
333
334
335
336 -L pattern
337
338
339 certlocal
340
341 When specified with the certlocal subcommand, this option links
342 an existing on-token private key object to the IKE database.
343 The object itself remains on the token. This option simply lets
344 the IKE infrastructure know that the object exists, as if it
345 had been originally created on-token with the Solaris IKE util‐
346 ities.
347
348
349 certdb
350
351 When specified with the certdb subcommand, this option links an
352 existing on-token certificate object to the IKE database. The
353 object itself remains on the token. This option simply lets the
354 IKE infrastructure know that the object exists, as if it had
355 been originally created on-token with the Solaris IKE utili‐
356 ties.
357
358 If -p is specified, the PKCS#11 token pin is stored in the
359 clear on-disk, with root-protected file permissions. If not
360 specified, one must unlock the token with ikeadm(1M) once
361 in.iked(1M) is running.
362
363
364
366 The following parameters are supported:
367
368 certspec
369
370 Specifies the pattern matching of certificate specifications. Valid
371 certspecs are the Subject Name, Issuer Name, and Subject Alterna‐
372 tive Names.
373
374 These can be specified as certificates that match the given cert‐
375 spec values and that do not match other certspec values. To signify
376 a certspec value that is not supposed to be present in a certifi‐
377 cate, place an ! in front of the tag.
378
379 Valid certspecs are:
380
381 <Subject Names>
382 SUBJECT=<Subject Names>
383 ISSUER=<Issuer Names>
384 SLOT=<Slot Number in the certificate database>
385
386 Example:"ISSUER=C=US, O=SUN" IP=1.2.3.4 !DNS=example.com
387 Example:"C=US, O=CALIFORNIA" IP=5.4.2.1 DNS=example.com
388
389
390 Valid arguments to the alternative names are as follows:
391
392 IP=<IPv4 address>
393 DNS=<Domain Name Server address>
394 EMAIL=<email (RFC 822) address>
395 URI=<Uniform Resource Indicator value>
396 DN=<LDAP Directory Name value>
397 RID=<Registered Identifier value>
398
399
400 Valid Slot numbers can be specified without the keyword tag. Alter‐
401 native name can also be issued with keyword tags.
402
403
404 -A
405
406 Subject Alternative Names the certificate. The argument that fol‐
407 lows the -A option should be in the form of tag=value. Valid tags
408 are IP, DNS, EMAIL, URI, DN, and RID (See example below).
409
410
411 -D
412
413 X.509 distinguished name for the certificate subject. It typically
414 has the form of: C=country, O=organization, OU=organizational unit,
415 CN=common name. Valid tags are: C, O, OU, and CN.
416
417
418 -f
419
420 Encoding output format. pem for PEM Base64 or ber for ASN.1 BER. If
421 -f is not specified, pem is assumed.
422
423
424 -F validity end_time
425
426 Finish certificate validity time. If the -F flag is not specified,
427 the validity end time is calculated at four years from the validity
428 start time. See NOTES for an explanation for the validity date and
429 time syntax.
430
431
432 -m
433
434 Key size. It can be 512, 1024, 2048, 3072, or 4096. Use the follow‐
435 ing command to determine the key sizes supported by the Solaris
436 Cryptographic Framework:
437
438 % cryptoadm list -vm
439
440
441 The mechanisms displayed by the preceding command are described in
442 pkcs11_softtoken(5). If your system has hardware acceleration, the
443 mechanisms supported by the hardware will be listed in a separate
444 section for each provider. Mechanisms can be any of:
445
446 CKM_RSA_PKCS_KEY_PAIR_GEN
447 CKM_DSA_KEY_PAIR_GEN
448 CKM_DH_PKCS_KEY_PAIR_GEN
449
450
451
452 Note -
453
454 Some hardware does not support all key sizes. For example, the
455 Sun Cryptographic Accelerator 4000's keystore (when using the -T
456 option, below), supports only up to 2048-bit keys for RSA and
457 1024-bit keys for DSA.
458
459
460 -S validity start_time
461
462 Start certificate validity time. If the -S flag is not specified,
463 the current date and time is used for the validity start time. See
464 NOTES, below, for an explanation for the validity date and time
465 syntax.
466
467
468 -t
469
470 Key type. It can be rsa-sha1, rsa-md5, or dsa-sha1.
471
472
473 -T
474
475 PKCS#11 token identifier for hardware key storage. This specifies a
476 hardware device instance in conformance to the PKCS#11 standard. A
477 PKCS#11 library must be specified in /etc/inet/ike/config. (See
478 ike.config(4).)
479
480 A token identifier is a 32-character space-filled string. If the
481 token given is less than 32 characters long, it will be automati‐
482 cally padded with spaces.
483
484 If there is more than one PKCS#11 library on a system, keep in mind
485 that only one can be specified at a time in /etc/inet/ike/config.
486 There can be multiple tokens (each with individual key storage) for
487 a single PKCS#11 library instance.
488
489
491 This command can save private keys of a public-private key pair into a
492 file. Any exposure of a private key may lead to compromise if the key
493 is somehow obtained by an adversary.
494
495
496 The PKCS#11 hardware object functionality can address some of the
497 shortcomings of on-disk private keys. Because IKE is a system service,
498 user intervention at boot is not desireable. The token's PIN, however,
499 is still needed. The PINfor the PKCS#11 token, therefore, is stored
500 where normally the on-disk cryptographic keys would reside. This design
501 decision is deemed acceptable because, with a hardware key store, pos‐
502 session of the key is still unavailable, only use of the key is an
503 issue if the host is compromised. Beyond the PIN, the security of ike‐
504 cert then reduces to the security of the PKCS#11 implementation. The
505 PKCS#11 implementation should be scrutinized also.
506
507
508 Refer to the afterword by Matt Blaze in Bruce Schneier's Applied Cryp‐
509 tography: Protocols, Algorithms, and Source Code in C for additional
510 information.
511
513 Example 1 Generating a Self-Signed Certificate
514
515
516 The following is an example of a self-signed certificate:
517
518
519 example# ikecert certlocal -ks -m 512 -t rsa-md5 -D "C=US, O=SUN" -A
520 IP=1.2.3.4
521 Generating, please wait...
522 Certificate generated.
523 Certificate added to database.
524 -----BEGIN X509 CERTIFICATE-----
525 MIIBRDCB76ADAgECAgEBMA0GCSqGSIb3DQEBBAUAMBsxCzAJBgNVBAYTAlVTMQww
526 CgYDVQQKEwNTVU4wHhcNMDEwMzE0MDEzMDM1WhcNMDUwMzE0MDEzMDM1WjAbMQsw
527 CQYDVQQGEwJVUzEMMAoGA1UEChMDU1VOMFowDQYJKoZIhvcNAQEBBQADSQAwRgJB
528 APDhqpKgjgRoRUr6twTMTtSuNsReEnFoReVer!ztpXpQK6ybYlRH18JIqU/uCV/r
529 26R/cVXTy5qc5NbMwA40KzcCASOjIDAeMAsGA1UdDwQEAwIFoDAPBgNVHREECDAG
530 hwQBAgMEMA0GCSqGSIb3DQEBBAUAA0EApTRD23KzN95GMvPD71hwwClukslKLVg8
531 f1xm9ZsHLPJLRxHFwsqqjAad4j4wwwriiUmGAHLTGB0lJMl8xsgxag==
532 -----END X509 CERTIFICATE-----
533
534
535
536 Example 2 Generating a CA Request
537
538
539 Generating a CA request appears the same as the self-signed certifi‐
540 cate. The only differences between the two is the option -c instead of
541 -s, and the certificate data is a CA request.
542
543
544 example# ikecert certlocal -kc -m 512 -t rsa-md5 \
545 -D "C=US, O=SUN" -A IP=1.2.3.4
546
547
548
549 Example 3 A CA Request Using a Hardware Key Store
550
551
552 The following example illustrates the specification of a token using
553 the -T option.
554
555
556 example# # ikecert certlocal -kc -m 1024 -t rsa-md5 -T vca0-keystore \
557 -D "C=US, O=SUN" -A IP=1.2.3.4
558
559
560
562 The following exit values are returned:
563
564 0
565
566 Successful completion.
567
568
569 non-zero
570
571 An error occurred. Writes an appropriate error message to standard
572 error.
573
574
576 /etc/inet/secret/ike.privatekeys/*
577
578 Private keys. A private key must have a matching public-key cer‐
579 tificate with the same filename in /etc/inet/ike/publickeys/.
580
581
582 /etc/inet/ike/publickeys/*
583
584 Public-key certificates. The names are only important with regard
585 to matching private key names.
586
587
588 /etc/inet/ike/crls/*
589
590 Public key certificate revocation lists.
591
592
593 /etc/inet/ike/config
594
595 Consulted for the pathname of a PKCS#11 library.
596
597
599 See attributes(5) for descriptions of the following attributes:
600
601
602
603
604 ┌─────────────────────────────┬─────────────────────────────┐
605 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
606 ├─────────────────────────────┼─────────────────────────────┤
607 │Availability │SUNWcsu │
608 ├─────────────────────────────┼─────────────────────────────┤
609 │Interface Stability │Evolving │
610 └─────────────────────────────┴─────────────────────────────┘
611
613 ikeadm(1M), in.iked(1M), getdate(3C), ike.config(4), attributes(5),
614 pkcs11_softtoken(5)
615
616
617 Schneier, Bruce. Applied Cryptography: Protocols, Algorithms, and
618 Source Code in C. Second Edition. John Wiley & Sons. New York, NY.
619 1996.
620
621
622 RSA Labs, PKCS#11 v2.11: Cryptographic Token Interface Standards, No‐
623 vember 2001.
624
626 The following is the validity date and time syntax when the -F or -S
627 flags are used:
628
629
630 For relative dates, the syntax is as follows:
631
632 {+,-}[Ns][Nm][Nh][Nd][Nw][NM][Ny]
633
634
635
636
637 where:
638
639 N
640
641 represents an integer
642
643
644 s
645
646 represents seconds
647
648
649 m
650
651 represents minutes
652
653
654 h
655
656 represents hours
657
658
659 d
660
661 represents days
662
663
664 w
665
666 represents weeks
667
668
669 M
670
671 represents months
672
673
674 y
675
676 represents years
677
678
679
680 These parameters can be given in any order. For example, "+3d12h" is
681 three and a half days from now, and "-3y2M" is three years and 2 months
682 ago.
683
684
685 All parameters with fixed values can be added up in absolute seconds.
686 Months and years, which have variable numbers of seconds, are calcu‐
687 lated using calendar time. Months and years, which are not of fixed
688 length, are defined such that adding a year or month means the same day
689 next year or month. For instance, if it is Jan 26, 2005 and the cer‐
690 tificate should expire 3 years and 1 month from today, the expiration
691 (end validity time) date will be Feb 26, 2008. Overflows are dealt with
692 accordingly. For example, one month from Jan 31, 2005 is March 3, 2005,
693 since February has only 28 days.
694
695
696 For absolute dates, the syntax of the date formats included in the file
697 /etc/datemsk are accepted (See getdate(3C) for details). Any date
698 string prepended with a "+" or "-" is treated as a time relative to the
699 current time, while others are treated as absolute dates. Sanity check‐
700 ing is also done to ensure that the end validity date is greater than
701 the start validity date. For example, the following command would cre‐
702 ate a certificate with start date 1 day and 2 hours ago and an end date
703 of Jan 22nd, 2007 at 12:00:00 local time.
704
705 # ikecert certlocal -ks -t rsa-sha1 -m 1024 \
706 -D "CN=mycert, O=Sun, C=US" \
707 -S -1d2h -F "01/22/2007 12:00:00"
708
709
710
711
712 As in.iked(1M) can run only in the global zone and exclusive-IP zones,
713 this command is not useful in shared-IP zones.
714
715
716
717SunOS 5.11 10 Jun 2009 ikecert(1M)