| blob | bba87a4b7a44686db3c629551219b61118d354d1 |
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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
4 .\" See the License for the specific language governing permissions and limitations under the License. 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
5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH IKECERT 1M "Jun 10, 2009"
7 .SH NAME
8 ikecert \- manipulates the machine's on-filesystem public-key certificate
9 databases
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBikecert\fR certlocal
14 [\fB-a\fR | \fB-e\fR | \fB-h\fR | \fB-k\fR | \fB-l\fR | \fB-r\fR | \fB-U\fR | \fB-C\fR | \fB-L\fR]
15 [[\fB-p\fR] \fB-T\fR \fIPKCS#11 token identifier\fR]
16 [\fIoption_specific_arguments\fR]...
17 .fi
19 .LP
20 .nf
21 \fBikecert\fR certdb [\fB-a\fR | \fB-e\fR | \fB-h\fR | \fB-l\fR | \fB-r\fR | \fB-U\fR | \fB-C\fR | \fB-L\fR]
22 [[\fB-p\fR] \fB-T\fR \fIPKCS#11 token identifier\fR]
23 [\fIoption_specific_arguments\fR]...
24 .fi
26 .LP
27 .nf
28 \fBikecert\fR certrldb [\fB-a\fR | \fB-e\fR | \fB-h\fR | \fB-l\fR | \fB-r\fR]
29 [\fIoption_specific_arguments\fR]...
30 .fi
32 .LP
33 .nf
34 \fBikecert\fR tokens
35 .fi
37 .SH DESCRIPTION
38 .sp
39 .LP
40 The \fBikecert\fR command manipulates the machine's on-filesystem public-key
41 certificate databases. See the "Files" section, below.
42 .sp
43 .LP
44 \fBikecert\fR has three subcommands, one for each of the three major
45 repositories, plus one for listing available hardware tokens:
46 .RS +4
47 .TP
48 .ie t \(bu
49 .el o
50 \fBcertlocal\fR deals with the private-key repository,
51 .RE
52 .RS +4
53 .TP
54 .ie t \(bu
55 .el o
56 \fBcertdb\fR deals with the public-key repository, and:
57 .RE
58 .RS +4
59 .TP
60 .ie t \(bu
61 .el o
62 \fBcertrldb\fR deals with the certificate revocation list (\fBCRL\fR)
63 repository.
64 .RE
65 .RS +4
66 .TP
67 .ie t \(bu
68 .el o
69 \fBtokens\fR shows the available PKCS#11 tokens for a given PKCS#11 library.
70 .RE
71 .sp
72 .LP
73 The only supported PKCS#11 library and hardware is the Sun Cryptographic
74 Accelerator 4000.
75 .SH OPTIONS
76 .sp
77 .LP
78 Except for \fBtokens\fR, each subcommand requires one option, possibly followed
79 by one or more option-specific arguments.
80 .sp
81 .LP
82 The \fBtokens\fR subcommand lists all available tokens in the PKCS#11 library
83 specified in \fB/etc/inet/ike/config\fR.
84 .sp
85 .LP
86 The following options are supported:
87 .sp
88 .ne 2
89 .na
90 \fB\fB-a\fR\fR
91 .ad
92 .sp .6
93 .RS 4n
94 .sp
95 .ne 2
96 .na
97 \fBcertlocal\fR
98 .ad
99 .sp .6
100 .RS 4n
101 When specified with the \fBcertlocal\fR subcommand, this option installs (adds)
102 a private key into the Internet Key Exchange (\fBIKE\fR) local \fBID\fR
103 database. The key data is read from standard input, and is in either
104 Solaris-only format or unencrypted PKCS#8 DER format. Key format is
105 automatically detected. PKCS#8 key files in PEM format and files in password
106 protected, encrypted format are not recognized, but can be converted
107 appropriately using tools available in OpenSSL.
108 .sp
109 This option cannot be used with PKCS#11 hardware objects when the corresponding
110 public certificate is not already present in the \fBIKE\fR database. When
111 importing both a public certificate and a private key, the public portion must
112 be imported first using the \fBcertdb\fR subcommand.
113 .RE
115 .sp
116 .ne 2
117 .na
118 \fBcertdb\fR
119 .ad
120 .sp .6
121 .RS 4n
122 When specified with the \fBcertdb\fR subcommand, this option reads a
123 certificate from standard input and adds it to the \fBIKE\fR certificate
124 database. The certificate must be a \fBX.509\fR certificate in \fBPEM Base64\fR
125 or \fBASN.1 BER\fR encoding. The certificate adopts the name of its identity.
126 .sp
127 This option can import a certificate into a PKCS#11 hardware key store one of
128 two ways: Either a matching public key object \fBand\fR an existing private key
129 object were created using the \fBcertlocal\fR \fB-kc\fR option, or if a PKCS#11
130 token is explicitly specified using the \fB-T\fR option.
131 .RE
133 .sp
134 .ne 2
135 .na
136 \fBcertrldb\fR
137 .ad
138 .sp .6
139 .RS 4n
140 When specified with the \fBcertrldb\fR subcommand, this option installs (adds)
141 a \fBCRL\fR into the \fBIKE\fR database. The \fBCRL\fR reads from standard
142 input.
143 .RE
145 .RE
147 .sp
148 .ne 2
149 .na
150 \fB\fB-e\fR [\fB-f\fR pkcs8] \fIslot\fR\fR
151 .ad
152 .sp .6
153 .RS 4n
154 .sp
155 .ne 2
156 .na
157 \fBcertlocal\fR
158 .ad
159 .sp .6
160 .RS 4n
161 When specified with the \fBcertlocal\fR subcommand, this option extracts a
162 private key from the \fBIKE\fR local \fBID\fR database. The key data are
163 written to standard output. The slot specifies which private key to extract.
164 Private keys are only extracted in binary/ber format.
165 .sp
166 \fBUse this option with extreme caution.\fR See the "Security" section, below.
167 .sp
168 This option will not work with PKCS#11 hardware objects.
169 .sp
170 When used in conjunction with "\fB-f\fR \fBpkcs8\fR", the private key is
171 extracted in unencrypted PKCS#8 format.
172 .RE
174 .RE
176 .sp
177 .ne 2
178 .na
179 \fB\fB-e\fR [\fB-f\fR \fIoutput-format\fR] \fBcertspec\fR\fR
180 .ad
181 .sp .6
182 .RS 4n
183 .sp
184 .ne 2
185 .na
186 \fBcertdb\fR
187 .ad
188 .sp .6
189 .RS 4n
190 When specified with the \fBcertdb\fR subcommand, this option extracts a
191 certificate from the IKE certificate database which matches the certspec and
192 writes it to standard output. The \fIoutput-format\fR option specifies the
193 encoding format. Valid options are \fBPEM\fR and \fBBER\fR. This extracts the
194 first matching identity. The default output format is \fBPEM\fR.
195 .RE
197 .sp
198 .ne 2
199 .na
200 \fBcertrldb\fR
201 .ad
202 .sp .6
203 .RS 4n
204 When specified with the \fBcertrldb\fR subcommand, this option extracts a
205 \fBCRL\fR from the IKE database. The key data are written to standard output.
206 The \fBcertspec\fR specifies which CRL that is extracted. The first one that
207 matches in the database is extracted. See \fBNOTES\fR, below, for details on
208 \fBcertspec\fR patterns.
209 .RE
211 .RE
213 .sp
214 .ne 2
215 .na
216 \fB\fB-kc\fR \fB-m\fR \fIkeysize\fR \fB-t\fR \fIkeytype\fR \fB-D\fR \fIdname\fR
217 \fB-A\fR \fIaltname\fR[ ... ]\fR
218 .ad
219 .br
220 .na
221 \fB[\fB-S\fR \fIvalidity start_time\fR][\fB-F\fR \fIvalidity end_time\fR]\fR
222 .ad
223 .br
224 .na
225 \fB[\fB-T\fR \fIPKCS#11 token identifier\fR]\fR
226 .ad
227 .sp .6
228 .RS 4n
229 .sp
230 .ne 2
231 .na
232 \fBcertlocal\fR
233 .ad
234 .sp .6
235 .RS 4n
236 When specified with the \fBcertlocal\fR subcommand, this option generates a IKE
237 public/private key pair and adds it into the local ID database. It also
238 generates a certificate request and sends that to standard output. For details
239 on the above options see for details on the \fIdname\fR argument and see
240 ALTERNATIVE NAMES for details on the \fIaltname\fR argument(s) to this command.
241 .sp
242 If \fB-T\fR is specified, the hardware token will generate the pair of keys.
243 .sp
244 If \fB-p\fR is specified with \fB-T\fR, the PKCS#11 token pin is stored in the
245 clear on-disk, with root-protected file permissions. If not specified, one must
246 unlock the token with \fBikeadm\fR(1M) once \fBin.iked\fR(1M) is running.
247 .RE
249 .RE
251 .sp
252 .ne 2
253 .na
254 \fB\fB-ks\fR \fB-m\fR \fIkeysize\fR \fB-t\fR \fIkeytype\fR \fB-D\fR \fIdname\fR
255 \fB-A\fR \fIaltname\fR[ ... ]\fR
256 .ad
257 .br
258 .na
259 \fB[\fB-S\fR \fIvalidity start_time\fR][\fB-F\fR \fIvalidity end_time\fR]\fR
260 .ad
261 .br
262 .na
263 \fB[\fB-f\fR \fIoutput-format\fR][[\fB-p\fR] \fB-T\fR \fIPKCS#11 token
264 identifier\fR]\fR
265 .ad
266 .br
267 .na
268 \fB\fR
269 .ad
270 .sp .6
271 .RS 4n
272 .sp
273 .ne 2
274 .na
275 \fBcertlocal\fR
276 .ad
277 .sp .6
278 .RS 4n
279 When specified with the \fBcertlocal\fR subcommand, generates a public/private
280 key pair and adds it into the local ID database. This option also generates a
281 self-signed certificate and installs it into the certificate database. See
282 \fBNOTES\fR, below, for details on the \fIdname\fR and \fIaltname\fR arguments
283 to this command.
284 .sp
285 If \fB-T\fR is specified, the hardware token will generate the pair of keys,
286 and the self-signed certificate will also be stored in the hardware.
287 .RE
289 .RE
291 .sp
292 .ne 2
293 .na
294 \fB\fB-l\fR [\fB-v\fR] [\fIslot\fR]\fR
295 .ad
296 .sp .6
297 .RS 4n
298 .sp
299 .ne 2
300 .na
301 \fBcertlocal\fR
302 .ad
303 .sp .6
304 .RS 4n
305 When specified with the \fBcertlocal\fR subcommand, this option lists private
306 keys in the local ID database. The \fB-v\fR option switches output to a verbose
307 mode where the entire certificate is printed.
308 .sp
309 \fBUse the\fR \fB-v\fR\fBoption with extreme caution.\fR See the "Security"
310 section, below. The \fB-v\fR option will not work with PKCS#11 hardware
311 objects.
312 .RE
314 .RE
316 .sp
317 .ne 2
318 .na
319 \fB\fB-l\fR [\fB-v\fR] [certspec]\fR
320 .ad
321 .sp .6
322 .RS 4n
323 .sp
324 .ne 2
325 .na
326 \fBcertdb\fR
327 .ad
328 .sp .6
329 .RS 4n
330 When specified with the \fBcertdb\fR subcommand, this option lists certificates
331 in the IKE certificate database matching the certspec, if any pattern is given.
332 The list displays the identity string of the certificates, as well as, the
333 private key if in the key database. The \fB-v\fR switches the output to a
334 verbose mode where the entire certificate is printed.
335 .sp
336 If the matching ceritifcate is on a hardware token, the token ID is also
337 listed.
338 .RE
340 .sp
341 .ne 2
342 .na
343 \fBcertrldb\fR
344 .ad
345 .sp .6
346 .RS 4n
347 When specified with the \fBcertrldb\fR subcommand, this option lists the CRLs
348 in the IKE database along with any certificates that reside in the database and
349 match the Issuer Name. \fBcertspec\fR can be used to specify to list a specific
350 CRL. The \fB-v\fR option switches the output to a verbose mode where the entire
351 certificate is printed. See \fBNOTES\fR, below, for details on\fBcertspec\fR
352 patterns.
353 .RE
355 .RE
357 .sp
358 .ne 2
359 .na
360 \fB\fB-r\fR \fIslot\fR\fR
361 .ad
362 .sp .6
363 .RS 4n
364 .sp
365 .ne 2
366 .na
367 \fBcertlocal\fR
368 .ad
369 .sp .6
370 .RS 4n
371 When specified with the \fBcertlocal\fR subcommand, deletes the local ID in the
372 specified slot. If there is a corresponding public key, it is not be deleted.
373 If this slot is deemed as "corrupted" or otherwise unrecognizable, it is
374 deleted as well.
375 .sp
376 If this is invoked on a PKCS#11 hardware object, it will also delete the
377 PKCS#11 public key and private key objects. If the public key object was
378 already deleted by \fBcertdb\fR \fB-r\fR, that is not a problem.
379 .RE
381 .RE
383 .sp
384 .ne 2
385 .na
386 \fB\fB-r\fR certspec\fR
387 .ad
388 .sp .6
389 .RS 4n
390 .sp
391 .ne 2
392 .na
393 \fBcertdb\fR
394 .ad
395 .sp .6
396 .RS 4n
397 Removes certificates from the IKE certificate database. Certificates matching
398 the specified certificate pattern are deleted. Any private keys in the
399 \fBcertlocal\fR database corresponding to these certificates are not deleted.
400 This removes the first matching identity.
401 .sp
402 If the pattern specifies a slot and the slot is deemed as "corrupted" or
403 otherwise unrecognizable, it is deleted as well.
404 .sp
405 If this is invoked on a PKCS#11 hardware object, it will also delete the
406 certificate and the PKCS#11 public key object. If the public key object was
407 already deleted by \fBcertlocal\fR \fB-r\fR, that is not a problem.
408 .RE
410 .sp
411 .ne 2
412 .na
413 \fBcertrldb\fR
414 .ad
415 .sp .6
416 .RS 4n
417 When specified with the \fBcertrldb\fR subcommand, this option deletes the CRL
418 with the given \fBcertspec\fR.
419 .RE
421 .RE
423 .sp
424 .ne 2
425 .na
426 \fB\fB-U\fR slot\fR
427 .ad
428 .sp .6
429 .RS 4n
430 .sp
431 .ne 2
432 .na
433 \fB\fBcertlocal\fR\fR
434 .ad
435 .sp .6
436 .RS 4n
437 When specified with the \fBcertlocal\fR subcommand and the \fB-T\fR flag, this
438 option unlinks a PKCS#11 private key object from the IKE database. There will
439 be no attempt to access the hardware keystore or to validate or remove the
440 on-token private key object. The object is simply disassociated from the IKE
441 database.
442 .RE
444 .sp
445 .ne 2
446 .na
447 \fB\fBcertdb\fR\fR
448 .ad
449 .sp .6
450 .RS 4n
451 When specified with the \fBcertdb\fR subcommand and the \fB-T\fR flag, this
452 option unlinks a PKCS#11 certificate object from the IKE database. There will
453 be no attempt to access the hardware keystore or to validate or remove the
454 on-token certificate or public key objects. The objects are simply
455 disassociated from the IKE database.
456 .RE
458 .RE
460 .sp
461 .ne 2
462 .na
463 \fB\fB-C\fR certspec\fR
464 .ad
465 .sp .6
466 .RS 4n
467 .sp
468 .ne 2
469 .na
470 \fBcertlocal\fR
471 .ad
472 .sp .6
473 .RS 4n
474 When specified with the \fBcertlocal\fR subcommand, this option copies both the
475 private key and its corresponding certificate and the public key from the
476 on-disk keystore to the hardware keystore specified by its PKCS#11 token. This
477 subcommand attempts to create each of these components, even if one part fails.
478 In all cases, the original on-disk private key and public certificate are still
479 retained and must be deleted separately. Some hardware keystores, such as
480 FIPS-140 compliant devices, may not support migration of private key objects in
481 this manner.
482 .RE
484 .sp
485 .ne 2
486 .na
487 \fBcertdb\fR
488 .ad
489 .sp .6
490 .RS 4n
491 When specified with the \fBcertdb\fR subcommand, this option copies the
492 certificate matching the given \fBcertspec\fR and corresponding public key from
493 the on-disk keystore to the hardware keystore specified by its PKCS#11 token.
494 The original public certificate is still retained and must be deleted
495 separately, if desired.
496 .sp
497 If \fB-p\fR is specified, the PKCS#11 token pin is stored in the clear on-disk,
498 with root-protected file permissions. If not specified, one must unlock the
499 token with \fBikeadm\fR(1M) once \fBin.iked\fR(1M) is running.
500 .RE
502 .RE
504 .sp
505 .ne 2
506 .na
507 \fB\fB-L\fR pattern\fR
508 .ad
509 .sp .6
510 .RS 4n
511 .sp
512 .ne 2
513 .na
514 \fBcertlocal\fR
515 .ad
516 .sp .6
517 .RS 4n
518 When specified with the \fBcertlocal\fR subcommand, this option links an
519 existing on-token private key object to the \fBIKE\fR database. The object
520 itself remains on the token. This option simply lets the \fBIKE\fR
521 infrastructure know that the object exists, as if it had been originally
522 created on-token with the Solaris \fBIKE\fR utilities.
523 .RE
525 .sp
526 .ne 2
527 .na
528 \fBcertdb\fR
529 .ad
530 .sp .6
531 .RS 4n
532 When specified with the \fBcertdb\fR subcommand, this option links an existing
533 on-token certificate object to the \fBIKE\fR database. The object itself
534 remains on the token. This option simply lets the \fBIKE\fR infrastructure know
535 that the object exists, as if it had been originally created on-token with the
536 Solaris \fBIKE\fR utilities.
537 .sp
538 If \fB-p\fR is specified, the PKCS#11 token pin is stored in the clear on-disk,
539 with root-protected file permissions. If not specified, one must unlock the
540 token with \fBikeadm\fR(1M) once \fBin.iked\fR(1M) is running.
541 .RE
543 .RE
545 .SH PARAMETERS
546 .sp
547 .LP
548 The following parameters are supported:
549 .sp
550 .ne 2
551 .na
552 \fBcertspec\fR
553 .ad
554 .sp .6
555 .RS 4n
556 Specifies the pattern matching of certificate specifications. Valid
557 \fBcertspec\fRs are the Subject Name, Issuer Name, and Subject Alternative
558 Names.
559 .sp
560 These can be specified as certificates that match the given \fBcertspec\fR
561 values and that do not match other \fBcertspec\fR values. To signify a
562 \fBcertspec\fR value that is not supposed to be present in a certificate, place
563 an \fB!\fR in front of the tag.
564 .sp
565 Valid \fBcertspec\fRs are:
566 .sp
567 .in +2
568 .nf
569 <Subject Names>
570 SUBJECT=<Subject Names>
571 ISSUER=<Issuer Names>
572 SLOT=<Slot Number in the certificate database>
574 Example:"ISSUER=C=US, O=SUN" IP=1.2.3.4 !DNS=example.com
575 Example:"C=US, O=CALIFORNIA" IP=5.4.2.1 DNS=example.com
576 .fi
577 .in -2
578 .sp
580 Valid arguments to the alternative names are as follows:
581 .sp
582 .in +2
583 .nf
584 IP=<IPv4 address>
585 DNS=<Domain Name Server address>
586 EMAIL=<email (RFC 822) address>
587 URI=<Uniform Resource Indicator value>
588 DN=<LDAP Directory Name value>
589 RID=<Registered Identifier value>
590 .fi
591 .in -2
592 .sp
594 Valid Slot numbers can be specified without the keyword tag. Alternative name
595 can also be issued with keyword tags.
596 .RE
598 .sp
599 .ne 2
600 .na
601 \fB\fB-A\fR\fR
602 .ad
603 .sp .6
604 .RS 4n
605 Subject Alternative Names the certificate. The argument that follows the
606 \fB-A\fR option should be in the form of \fItag\fR=\fIvalue\fR. Valid tags are
607 \fBIP\fR, \fBDNS\fR, \fBEMAIL\fR, \fBURI\fR, \fBDN\fR, and \fBRID\fR (See
608 example below).
609 .RE
611 .sp
612 .ne 2
613 .na
614 \fB\fB-D\fR\fR
615 .ad
616 .sp .6
617 .RS 4n
618 \fBX.509\fR distinguished name for the certificate subject. It typically has
619 the form of: \fBC\fR=country, \fBO\fR=organization, \fBOU\fR=organizational
620 unit, \fBCN\fR=common name. Valid tags are: \fBC\fR, \fBO\fR, \fBOU\fR, and
621 \fBCN\fR.
622 .RE
624 .sp
625 .ne 2
626 .na
627 \fB\fB-f\fR\fR
628 .ad
629 .sp .6
630 .RS 4n
631 Encoding output format. \fBpem\fR for \fBPEM Base64\fR or \fBber\fR for
632 \fBASN.1 BER\fR. If \fB-f\fR is not specified, \fBpem\fR is assumed.
633 .RE
635 .sp
636 .ne 2
637 .na
638 \fB\fB-F\fR \fIvalidity end_time\fR\fR
639 .ad
640 .sp .6
641 .RS 4n
642 Finish certificate validity time. If the \fB-F\fR flag is not specified, the
643 validity end time is calculated at four years from the validity start time. See
644 \fBNOTES\fR for an explanation for the validity date and time syntax.
645 .RE
647 .sp
648 .ne 2
649 .na
650 \fB\fB-m\fR\fR
651 .ad
652 .sp .6
653 .RS 4n
654 Key size. It can be \fB512\fR, \fB1024\fR, \fB2048\fR, \fB3072\fR, or
655 \fB4096\fR. Use the following command to determine the key sizes supported by
656 the Solaris Cryptographic Framework:
657 .sp
658 .in +2
659 .nf
660 % \fBcryptoadm list -vm\fR
661 .fi
662 .in -2
663 .sp
665 The mechanisms displayed by the preceding command are described in
666 \fBpkcs11_softtoken\fR(5). If your system has hardware acceleration, the
667 mechanisms supported by the hardware will be listed in a separate section for
668 each provider. Mechanisms can be any of:
669 .sp
670 .in +2
671 .nf
672 CKM_RSA_PKCS_KEY_PAIR_GEN
673 CKM_DSA_KEY_PAIR_GEN
674 CKM_DH_PKCS_KEY_PAIR_GEN
675 .fi
676 .in -2
677 .sp
679 .LP
680 Note -
681 .sp
682 .RS 2
683 Some hardware does not support all key sizes. For example, the Sun
684 Cryptographic Accelerator 4000's keystore (when using the \fB-T\fR option,
685 below), supports only up to 2048-bit keys for RSA and 1024-bit keys for DSA.
686 .RE
687 .RE
689 .sp
690 .ne 2
691 .na
692 \fB\fB-S\fR \fIvalidity start_time\fR\fR
693 .ad
694 .sp .6
695 .RS 4n
696 Start certificate validity time. If the \fB-S\fR flag is not specified, the
697 current date and time is used for the validity start time. See \fBNOTES\fR,
698 below, for an explanation for the validity date and time syntax.
699 .RE
701 .sp
702 .ne 2
703 .na
704 \fB\fB-t\fR\fR
705 .ad
706 .sp .6
707 .RS 4n
708 Key type. It can be \fBrsa-sha1\fR, \fBrsa-md5\fR, or \fBdsa-sha1\fR.
709 .RE
711 .sp
712 .ne 2
713 .na
714 \fB\fB-T\fR\fR
715 .ad
716 .sp .6
717 .RS 4n
718 PKCS#11 token identifier for hardware key storage. This specifies a hardware
719 device instance in conformance to the PKCS#11 standard. A PKCS#11 library must
720 be specified in \fB/etc/inet/ike/config\fR. (See \fBike.config\fR(4).)
721 .sp
722 A token identifier is a 32-character space-filled string. If the token given is
723 less than 32 characters long, it will be automatically padded with spaces.
724 .sp
725 If there is more than one PKCS#11 library on a system, keep in mind that only
726 one can be specified at a time in \fB/etc/inet/ike/config\fR. There can be
727 multiple tokens (each with individual key storage) for a single PKCS#11 library
728 instance.
729 .RE
731 .SH SECURITY
732 .sp
733 .LP
734 This command can save private keys of a public-private key pair into a file.
735 Any exposure of a private key may lead to compromise if the key is somehow
736 obtained by an adversary.
737 .sp
738 .LP
739 The PKCS#11 hardware object functionality can address some of the shortcomings
740 of on-disk private keys. Because IKE is a system service, user intervention at
741 boot is not desireable. The token's PIN, however, is still needed. The PINfor
742 the PKCS#11 token, therefore, is stored where normally the on-disk
743 cryptographic keys would reside. This design decision is deemed acceptable
744 because, with a hardware key store, \fBpossession\fR of the key is still
745 unavailable, only \fBuse\fR of the key is an issue if the host is compromised.
746 Beyond the PIN, the security of \fBikecert\fR then reduces to the security of
747 the PKCS#11 implementation. The PKCS#11 implementation should be scrutinized
748 also.
749 .sp
750 .LP
751 Refer to the afterword by Matt Blaze in Bruce Schneier's \fIApplied
752 Cryptography: Protocols, Algorithms, and Source Code in C\fR for additional
753 information.
754 .SH EXAMPLES
755 .LP
756 \fBExample 1 \fRGenerating a Self-Signed Certificate
757 .sp
758 .LP
759 The following is an example of a self-signed certificate:
761 .sp
762 .in +2
763 .nf
764 example# \fBikecert certlocal -ks -m 512 -t rsa-md5 -D "C=US, O=SUN" -A\fR
765 IP=1.2.3.4
766 Generating, please wait...
767 Certificate generated.
768 Certificate added to database.
769 -----BEGIN X509 CERTIFICATE-----
770 MIIBRDCB76ADAgECAgEBMA0GCSqGSIb3DQEBBAUAMBsxCzAJBgNVBAYTAlVTMQww
771 CgYDVQQKEwNTVU4wHhcNMDEwMzE0MDEzMDM1WhcNMDUwMzE0MDEzMDM1WjAbMQsw
772 CQYDVQQGEwJVUzEMMAoGA1UEChMDU1VOMFowDQYJKoZIhvcNAQEBBQADSQAwRgJB
773 APDhqpKgjgRoRUr6twTMTtSuNsReEnFoReVer!ztpXpQK6ybYlRH18JIqU/uCV/r
774 26R/cVXTy5qc5NbMwA40KzcCASOjIDAeMAsGA1UdDwQEAwIFoDAPBgNVHREECDAG
775 hwQBAgMEMA0GCSqGSIb3DQEBBAUAA0EApTRD23KzN95GMvPD71hwwClukslKLVg8
776 f1xm9ZsHLPJLRxHFwsqqjAad4j4wwwriiUmGAHLTGB0lJMl8xsgxag==
777 -----END X509 CERTIFICATE-----
778 .fi
779 .in -2
780 .sp
782 .LP
783 \fBExample 2 \fRGenerating a CA Request
784 .sp
785 .LP
786 Generating a \fBCA\fR request appears the same as the self-signed certificate.
787 The only differences between the two is the option \fB-c\fR instead of
788 \fB-s\fR, and the certificate data is a \fBCA\fR request.
790 .sp
791 .in +2
792 .nf
793 example# \fBikecert certlocal -kc -m 512 -t rsa-md5 \e
794 -D "C=US, O=SUN" -A IP=1.2.3.4\fR
795 .fi
796 .in -2
797 .sp
799 .LP
800 \fBExample 3 \fRA CA Request Using a Hardware Key Store
801 .sp
802 .LP
803 The following example illustrates the specification of a token using the
804 \fB-T\fR option.
806 .sp
807 .in +2
808 .nf
809 example# \fB# ikecert certlocal -kc -m 1024 -t rsa-md5 -T vca0-keystore \e
810 -D "C=US, O=SUN" -A IP=1.2.3.4\fR
811 .fi
812 .in -2
813 .sp
815 .SH EXIT STATUS
816 .sp
817 .LP
818 The following exit values are returned:
819 .sp
820 .ne 2
821 .na
822 \fB\fB0\fR\fR
823 .ad
824 .sp .6
825 .RS 4n
826 Successful completion.
827 .RE
829 .sp
830 .ne 2
831 .na
832 \fB\fBnon-zero\fR\fR
833 .ad
834 .sp .6
835 .RS 4n
836 An error occurred. Writes an appropriate error message to standard error.
837 .RE
839 .SH FILES
840 .sp
841 .ne 2
842 .na
843 \fB\fB/etc/inet/secret/ike.privatekeys/*\fR\fR
844 .ad
845 .sp .6
846 .RS 4n
847 Private keys. A private key \fBmust\fR have a matching public-key certificate
848 with the same filename in \fB/etc/inet/ike/publickeys/\fR.
849 .RE
851 .sp
852 .ne 2
853 .na
854 \fB\fB/etc/inet/ike/publickeys/*\fR\fR
855 .ad
856 .sp .6
857 .RS 4n
858 Public-key certificates. The names are only important with regard to matching
859 private key names.
860 .RE
862 .sp
863 .ne 2
864 .na
865 \fB\fB/etc/inet/ike/crls/*\fR\fR
866 .ad
867 .sp .6
868 .RS 4n
869 Public key certificate revocation lists.
870 .RE
872 .sp
873 .ne 2
874 .na
875 \fB\fB/etc/inet/ike/config\fR\fR
876 .ad
877 .sp .6
878 .RS 4n
879 Consulted for the pathname of a PKCS#11 library.
880 .RE
882 .SH ATTRIBUTES
883 .sp
884 .LP
885 See \fBattributes\fR(5) for descriptions of the following attributes:
886 .sp
888 .sp
889 .TS
890 box;
891 c | c
892 l | l .
893 ATTRIBUTE TYPE ATTRIBUTE VALUE
894 _
895 Interface Stability Evolving
896 .TE
898 .SH SEE ALSO
899 .sp
900 .LP
901 \fBikeadm\fR(1M), \fBin.iked\fR(1M), \fBgetdate\fR(3C), \fBike.config\fR(4),
902 \fBattributes\fR(5), \fBpkcs11_softtoken\fR(5)
903 .sp
904 .LP
905 Schneier, Bruce. \fIApplied Cryptography: Protocols, Algorithms, and Source
906 Code in C\fR. Second Edition. John Wiley & Sons. New York, NY. 1996.
907 .sp
908 .LP
909 RSA Labs, PKCS#11 v2.11: \fICryptographic Token Interface Standards\fR,
910 November 2001.
911 .SH NOTES
912 .sp
913 .LP
914 The following is the validity date and time syntax when the \fB-F\fR or
915 \fB-S\fR flags are used:
916 .sp
917 .LP
918 For relative dates, the syntax is as follows:
919 .sp
920 .in +2
921 .nf
922 {+,-}[Ns][Nm][Nh][Nd][Nw][NM][Ny]
923 .fi
924 .in -2
925 .sp
927 .sp
928 .LP
929 where:
930 .sp
931 .ne 2
932 .na
933 \fBN\fR
934 .ad
935 .sp .6
936 .RS 4n
937 represents an integer
938 .RE
940 .sp
941 .ne 2
942 .na
943 \fBs\fR
944 .ad
945 .sp .6
946 .RS 4n
947 represents seconds
948 .RE
950 .sp
951 .ne 2
952 .na
953 \fBm\fR
954 .ad
955 .sp .6
956 .RS 4n
957 represents minutes
958 .RE
960 .sp
961 .ne 2
962 .na
963 \fBh\fR
964 .ad
965 .sp .6
966 .RS 4n
967 represents hours
968 .RE
970 .sp
971 .ne 2
972 .na
973 \fBd\fR
974 .ad
975 .sp .6
976 .RS 4n
977 represents days
978 .RE
980 .sp
981 .ne 2
982 .na
983 \fBw\fR
984 .ad
985 .sp .6
986 .RS 4n
987 represents weeks
988 .RE
990 .sp
991 .ne 2
992 .na
993 \fBM\fR
994 .ad
995 .sp .6
996 .RS 4n
997 represents months
998 .RE
1000 .sp
1001 .ne 2
1002 .na
1003 \fBy\fR
1004 .ad
1005 .sp .6
1006 .RS 4n
1007 represents years
1008 .RE
1010 .sp
1011 .LP
1012 These parameters can be given in any order. For example, "+3d12h" is three and
1013 a half days from now, and "-3y2M" is three years and 2 months ago.
1014 .sp
1015 .LP
1016 All parameters with fixed values can be added up in absolute seconds. Months
1017 and years, which have variable numbers of seconds, are calculated using
1018 calendar time. Months and years, which are not of fixed length, are defined
1019 such that adding a year or month means the same day next year or month. For
1020 instance, if it is Jan 26, 2005 and the certificate should expire 3 years and 1
1021 month from today, the expiration (end validity time) date will be Feb 26, 2008.
1022 Overflows are dealt with accordingly. For example, one month from Jan 31, 2005
1023 is March 3, 2005, since February has only 28 days.
1024 .sp
1025 .LP
1026 For absolute dates, the syntax of the date formats included in the file
1027 \fB/etc/datemsk\fR are accepted (See \fBgetdate\fR(3C) for details). Any date
1028 string prepended with a "+" or "-" is treated as a time relative to the current
1029 time, while others are treated as absolute dates. Sanity checking is also done
1030 to ensure that the end validity date is greater than the start validity date.
1031 For example, the following command would create a certificate with start date 1
1032 day and 2 hours ago and an end date of Jan 22nd, 2007 at 12:00:00 local time.
1033 .sp
1034 .in +2
1035 .nf
1036 # ikecert certlocal -ks -t rsa-sha1 -m 1024 \e
1037 -D "CN=mycert, O=Sun, C=US" \e
1038 -S -1d2h -F "01/22/2007 12:00:00"
1039 .fi
1040 .in -2
1041 .sp
1043 .sp
1044 .LP
1045 As \fBin.iked\fR(1M) can run only in the global zone and exclusive-IP zones,
1046 this command is not useful in shared-IP zones.