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