Annotation of src/usr.bin/openssl/openssl.1, Revision 1.49
1.49 ! jmc 1: .\" $OpenBSD: openssl.1,v 1.48 2016/08/10 17:41:08 jmc Exp $
1.1 jsing 2: .\" ====================================================================
3: .\" Copyright (c) 1998-2002 The OpenSSL Project. All rights reserved.
4: .\"
5: .\" Redistribution and use in source and binary forms, with or without
6: .\" modification, are permitted provided that the following conditions
7: .\" are met:
8: .\"
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\"
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in
14: .\" the documentation and/or other materials provided with the
15: .\" distribution.
16: .\"
17: .\" 3. All advertising materials mentioning features or use of this
18: .\" software must display the following acknowledgment:
19: .\" "This product includes software developed by the OpenSSL Project
20: .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
21: .\"
22: .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
23: .\" endorse or promote products derived from this software without
24: .\" prior written permission. For written permission, please contact
25: .\" openssl-core@openssl.org.
26: .\"
27: .\" 5. Products derived from this software may not be called "OpenSSL"
28: .\" nor may "OpenSSL" appear in their names without prior written
29: .\" permission of the OpenSSL Project.
30: .\"
31: .\" 6. Redistributions of any form whatsoever must retain the following
32: .\" acknowledgment:
33: .\" "This product includes software developed by the OpenSSL Project
34: .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
35: .\"
36: .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
37: .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
38: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
39: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
40: .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41: .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
42: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
43: .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
44: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
45: .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
46: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
47: .\" OF THE POSSIBILITY OF SUCH DAMAGE.
48: .\" ====================================================================
49: .\"
50: .\" This product includes cryptographic software written by Eric Young
51: .\" (eay@cryptsoft.com). This product includes software written by Tim
52: .\" Hudson (tjh@cryptsoft.com).
53: .\"
54: .\"
55: .\" Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
56: .\" All rights reserved.
57: .\"
58: .\" This package is an SSL implementation written
59: .\" by Eric Young (eay@cryptsoft.com).
60: .\" The implementation was written so as to conform with Netscapes SSL.
61: .\"
62: .\" This library is free for commercial and non-commercial use as long as
63: .\" the following conditions are aheared to. The following conditions
64: .\" apply to all code found in this distribution, be it the RC4, RSA,
65: .\" lhash, DES, etc., code; not just the SSL code. The SSL documentation
66: .\" included with this distribution is covered by the same copyright terms
67: .\" except that the holder is Tim Hudson (tjh@cryptsoft.com).
68: .\"
69: .\" Copyright remains Eric Young's, and as such any Copyright notices in
70: .\" the code are not to be removed.
71: .\" If this package is used in a product, Eric Young should be given attribution
72: .\" as the author of the parts of the library used.
73: .\" This can be in the form of a textual message at program startup or
74: .\" in documentation (online or textual) provided with the package.
75: .\"
76: .\" Redistribution and use in source and binary forms, with or without
77: .\" modification, are permitted provided that the following conditions
78: .\" are met:
79: .\" 1. Redistributions of source code must retain the copyright
80: .\" notice, this list of conditions and the following disclaimer.
81: .\" 2. Redistributions in binary form must reproduce the above copyright
82: .\" notice, this list of conditions and the following disclaimer in the
83: .\" documentation and/or other materials provided with the distribution.
84: .\" 3. All advertising materials mentioning features or use of this software
85: .\" must display the following acknowledgement:
86: .\" "This product includes cryptographic software written by
87: .\" Eric Young (eay@cryptsoft.com)"
88: .\" The word 'cryptographic' can be left out if the rouines from the library
89: .\" being used are not cryptographic related :-).
90: .\" 4. If you include any Windows specific code (or a derivative thereof) from
91: .\" the apps directory (application code) you must include an
92: .\" acknowledgement:
93: .\" "This product includes software written by Tim Hudson
94: .\" (tjh@cryptsoft.com)"
95: .\"
96: .\" THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
97: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
98: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
99: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
100: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
101: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
102: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
103: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
104: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
105: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
106: .\" SUCH DAMAGE.
107: .\"
108: .\" The licence and distribution terms for any publically available version or
109: .\" derivative of this code cannot be changed. i.e. this code cannot simply be
110: .\" copied and put under another distribution licence
111: .\" [including the GNU Public Licence.]
112: .\"
113: .\" OPENSSL
114: .\"
1.49 ! jmc 115: .Dd $Mdocdate: August 10 2016 $
1.1 jsing 116: .Dt OPENSSL 1
117: .Os
118: .Sh NAME
119: .Nm openssl
120: .Nd OpenSSL command line tool
121: .Sh SYNOPSIS
122: .Nm
123: .Cm command
124: .Op Ar command_opts
125: .Op Ar command_args
126: .Pp
127: .Nm
1.13 bentley 128: .Cm list-standard-commands |
129: .Cm list-message-digest-commands |
130: .Cm list-cipher-commands |
131: .Cm list-cipher-algorithms |
132: .Cm list-message-digest-algorithms |
1.1 jsing 133: .Cm list-public-key-algorithms
134: .Pp
135: .Nm
1.39 jmc 136: .Cm no- Ns Ar command
1.1 jsing 137: .Sh DESCRIPTION
138: .Nm OpenSSL
1.31 jmc 139: is a cryptography toolkit implementing the
140: Transport Layer Security
1.1 jsing 141: .Pq TLS v1
1.31 jmc 142: network protocol,
143: as well as related cryptography standards.
1.1 jsing 144: .Pp
145: The
146: .Nm
147: program is a command line tool for using the various
148: cryptography functions of
1.39 jmc 149: .Nm openssl Ns 's
1.33 jmc 150: crypto library from the shell.
1.1 jsing 151: .Pp
152: The pseudo-commands
153: .Cm list-standard-commands , list-message-digest-commands ,
154: and
155: .Cm list-cipher-commands
156: output a list
157: .Pq one entry per line
158: of the names of all standard commands, message digest commands,
159: or cipher commands, respectively, that are available in the present
160: .Nm
161: utility.
162: .Pp
163: The pseudo-commands
164: .Cm list-cipher-algorithms
165: and
166: .Cm list-message-digest-algorithms
167: list all cipher and message digest names,
168: one entry per line.
169: Aliases are listed as:
170: .Pp
1.33 jmc 171: .D1 from => to
1.1 jsing 172: .Pp
173: The pseudo-command
174: .Cm list-public-key-algorithms
175: lists all supported public key algorithms.
176: .Pp
177: The pseudo-command
1.39 jmc 178: .Cm no- Ns Ar command
1.1 jsing 179: tests whether a command of the
180: specified name is available.
1.39 jmc 181: If
182: .Ar command
183: does not exist,
1.1 jsing 184: it returns 0
185: and prints
1.39 jmc 186: .Cm no- Ns Ar command ;
1.1 jsing 187: otherwise it returns 1 and prints
1.39 jmc 188: .Ar command .
189: In both cases, the output goes to stdout and nothing is printed to stderr.
1.1 jsing 190: Additional command line arguments are always ignored.
191: Since for each cipher there is a command of the same name,
192: this provides an easy way for shell scripts to test for the
193: availability of ciphers in the
194: .Nm
195: program.
196: .Pp
197: .Sy Note :
1.39 jmc 198: .Cm no- Ns Ar command
1.1 jsing 199: is not able to detect pseudo-commands such as
200: .Cm quit ,
201: .Cm list- Ns Ar ... Ns Cm -commands ,
202: or
1.39 jmc 203: .Cm no- Ns Ar command
1.1 jsing 204: itself.
205: .Sh ASN1PARSE
206: .nr nS 1
207: .Nm "openssl asn1parse"
208: .Op Fl i
209: .Op Fl dlimit Ar number
210: .Op Fl dump
211: .Op Fl genconf Ar file
212: .Op Fl genstr Ar str
213: .Op Fl in Ar file
1.34 jmc 214: .Op Fl inform Cm der | pem | txt
1.1 jsing 215: .Op Fl length Ar number
216: .Op Fl noout
217: .Op Fl offset Ar number
218: .Op Fl oid Ar file
219: .Op Fl out Ar file
220: .Op Fl strparse Ar offset
221: .nr nS 0
222: .Pp
223: The
224: .Nm asn1parse
225: command is a diagnostic utility that can parse ASN.1 structures.
226: It can also be used to extract data from ASN.1 formatted data.
227: .Pp
228: The options are as follows:
229: .Bl -tag -width Ds
230: .It Fl dlimit Ar number
231: Dump the first
232: .Ar number
233: bytes of unknown data in hex form.
234: .It Fl dump
235: Dump unknown data in hex form.
236: .It Fl genconf Ar file , Fl genstr Ar str
237: Generate encoded data based on string
238: .Ar str ,
239: file
240: .Ar file ,
1.34 jmc 241: or both, using the format described in
242: .Xr ASN1_generate_nconf 3 .
1.1 jsing 243: If only
244: .Ar file
245: is present then the string is obtained from the default section
246: using the name
247: .Dq asn1 .
248: The encoded data is passed through the ASN1 parser and printed out as
249: though it came from a file;
250: the contents can thus be examined and written to a file using the
251: .Fl out
252: option.
253: .It Fl i
1.34 jmc 254: Indent the output according to the
1.1 jsing 255: .Qq depth
256: of the structures.
257: .It Fl in Ar file
1.41 jmc 258: The input file to read from, or standard input if not specified.
1.34 jmc 259: .It Fl inform Cm der | pem | txt
1.1 jsing 260: The input format.
261: .It Fl length Ar number
1.34 jmc 262: Number of bytes to parse; the default is until end of file.
1.1 jsing 263: .It Fl noout
1.46 jmc 264: Do not output the parsed version of the input file.
1.1 jsing 265: .It Fl offset Ar number
1.34 jmc 266: Starting offset to begin parsing; the default is start of file.
1.1 jsing 267: .It Fl oid Ar file
268: A file containing additional object identifiers
269: .Pq OIDs .
270: If an OID
271: .Pq object identifier
272: is not part of
1.34 jmc 273: .Nm openssl Ns 's
1.1 jsing 274: internal table it will be represented in
275: numerical form
276: .Pq for example 1.2.3.4 .
1.34 jmc 277: .Pp
1.1 jsing 278: Each line consists of three columns:
279: the first column is the OID in numerical format and should be followed by
280: whitespace.
281: The second column is the
1.34 jmc 282: .Qq short name ,
1.1 jsing 283: which is a single word followed by whitespace.
284: The final column is the rest of the line and is the
285: .Qq long name .
286: .Nm asn1parse
287: displays the long name.
1.34 jmc 288: .It Fl out Ar file
289: The DER-encoded output file; the default is no encoded output
290: (useful when combined with
291: .Fl strparse ) .
292: .It Fl strparse Ar offset
293: Parse the content octets of the ASN.1 object starting at
294: .Ar offset .
295: This option can be used multiple times to
296: .Qq drill down
297: into a nested structure.
298: .El
1.1 jsing 299: .Sh CA
300: .nr nS 1
301: .Nm "openssl ca"
302: .Op Fl batch
303: .Op Fl cert Ar file
304: .Op Fl config Ar file
305: .Op Fl crl_CA_compromise Ar time
306: .Op Fl crl_compromise Ar time
307: .Op Fl crl_hold Ar instruction
308: .Op Fl crl_reason Ar reason
309: .Op Fl crldays Ar days
310: .Op Fl crlexts Ar section
311: .Op Fl crlhours Ar hours
312: .Op Fl days Ar arg
313: .Op Fl enddate Ar date
314: .Op Fl extensions Ar section
315: .Op Fl extfile Ar section
316: .Op Fl gencrl
317: .Op Fl in Ar file
318: .Op Fl infiles
319: .Op Fl key Ar keyfile
320: .Op Fl keyfile Ar arg
1.22 bcook 321: .Op Fl keyform Ar PEM
1.1 jsing 322: .Op Fl md Ar arg
323: .Op Fl msie_hack
324: .Op Fl name Ar section
325: .Op Fl noemailDN
326: .Op Fl notext
327: .Op Fl out Ar file
328: .Op Fl outdir Ar dir
329: .Op Fl passin Ar arg
330: .Op Fl policy Ar arg
331: .Op Fl preserveDN
332: .Op Fl revoke Ar file
333: .Op Fl spkac Ar file
334: .Op Fl ss_cert Ar file
335: .Op Fl startdate Ar date
336: .Op Fl status Ar serial
337: .Op Fl subj Ar arg
338: .Op Fl updatedb
339: .Op Fl verbose
340: .nr nS 0
341: .Pp
342: The
343: .Nm ca
1.35 jmc 344: command is a minimal certificate authority (CA) application.
1.1 jsing 345: It can be used to sign certificate requests in a variety of forms
1.35 jmc 346: and generate certificate revocation lists (CRLs).
1.1 jsing 347: It also maintains a text database of issued certificates and their status.
348: .Pp
1.35 jmc 349: The options relevant to CAs are as follows:
1.1 jsing 350: .Bl -tag -width "XXXX"
351: .It Fl batch
1.41 jmc 352: Batch mode.
1.1 jsing 353: In this mode no questions will be asked
354: and all certificates will be certified automatically.
355: .It Fl cert Ar file
356: The CA certificate file.
357: .It Fl config Ar file
358: Specifies the configuration file to use.
359: .It Fl days Ar arg
360: The number of days to certify the certificate for.
361: .It Fl enddate Ar date
1.41 jmc 362: Set the expiry date.
1.1 jsing 363: The format of the date is YYMMDDHHMMSSZ
364: .Pq the same as an ASN1 UTCTime structure .
365: .It Fl extensions Ar section
366: The section of the configuration file containing certificate extensions
367: to be added when a certificate is issued (defaults to
1.35 jmc 368: .Cm x509_extensions
1.1 jsing 369: unless the
370: .Fl extfile
371: option is used).
372: If no extension section is present, a V1 certificate is created.
373: If the extension section is present
374: .Pq even if it is empty ,
375: then a V3 certificate is created.
376: .It Fl extfile Ar file
377: An additional configuration
378: .Ar file
379: to read certificate extensions from
380: (using the default section unless the
381: .Fl extensions
382: option is also used).
383: .It Fl in Ar file
384: An input
385: .Ar file
386: containing a single certificate request to be signed by the CA.
387: .It Fl infiles
388: If present, this should be the last option; all subsequent arguments
389: are assumed to be the names of files containing certificate requests.
390: .It Fl key Ar keyfile
391: The password used to encrypt the private key.
1.35 jmc 392: Since on some systems the command line arguments are visible,
393: this option should be used with caution.
1.1 jsing 394: .It Fl keyfile Ar file
395: The private key to sign requests with.
1.22 bcook 396: .It Fl keyform Ar PEM
1.1 jsing 397: Private key file format.
398: .It Fl md Ar alg
399: The message digest to use.
400: Possible values include
401: .Ar md5
402: and
403: .Ar sha1 .
404: This option also applies to CRLs.
405: .It Fl msie_hack
406: This is a legacy option to make
407: .Nm ca
408: work with very old versions of the IE certificate enrollment control
409: .Qq certenr3 .
410: It used UniversalStrings for almost everything.
411: Since the old control has various security bugs,
412: its use is strongly discouraged.
413: The newer control
414: .Qq Xenroll
415: does not need this option.
416: .It Fl name Ar section
417: Specifies the configuration file
418: .Ar section
419: to use (overrides
420: .Cm default_ca
421: in the
422: .Cm ca
423: section).
424: .It Fl noemailDN
425: The DN of a certificate can contain the EMAIL field if present in the
1.30 mmcc 426: request DN, however it is good policy just having the email set into
1.1 jsing 427: the
1.35 jmc 428: .Cm altName
1.1 jsing 429: extension of the certificate.
430: When this option is set, the EMAIL field is removed from the certificate's
431: subject and set only in the, eventually present, extensions.
432: The
433: .Ar email_in_dn
434: keyword can be used in the configuration file to enable this behaviour.
435: .It Fl notext
436: Don't output the text form of a certificate to the output file.
437: .It Fl out Ar file
438: The output file to output certificates to.
439: The default is standard output.
440: The certificate details will also be printed out to this file.
441: .It Fl outdir Ar directory
442: The
443: .Ar directory
444: to output certificates to.
445: The certificate will be written to a file consisting of the
446: serial number in hex with
447: .Qq .pem
448: appended.
449: .It Fl passin Ar arg
450: The key password source.
451: .It Fl policy Ar arg
1.41 jmc 452: Define the CA
1.1 jsing 453: .Qq policy
454: to use.
1.35 jmc 455: The policy section in the configuration file
456: consists of a set of variables corresponding to certificate DN fields.
457: The values may be one of
458: .Qq match
459: (the value must match the same field in the CA certificate),
460: .Qq supplied
461: (the value must be present), or
462: .Qq optional
463: (the value may be present).
464: Any fields not mentioned in the policy section
465: are silently deleted, unless the
466: .Fl preserveDN
467: option is set,
468: but this can be regarded more of a quirk than intended behaviour.
1.1 jsing 469: .It Fl preserveDN
470: Normally, the DN order of a certificate is the same as the order of the
471: fields in the relevant policy section.
472: When this option is set, the order is the same as the request.
473: This is largely for compatibility with the older IE enrollment control
474: which would only accept certificates if their DNs matched the order of the
475: request.
476: This is not needed for Xenroll.
477: .It Fl spkac Ar file
478: A file containing a single Netscape signed public key and challenge,
479: and additional field values to be signed by the CA.
1.35 jmc 480: This will usually come from the
481: KEYGEN tag in an HTML form to create a new private key.
482: It is, however, possible to create SPKACs using the
483: .Nm spkac
484: utility.
485: .Pp
486: The file should contain the variable SPKAC set to the value of
487: the SPKAC and also the required DN components as name value pairs.
488: If it's necessary to include the same component twice,
489: then it can be preceded by a number and a
490: .Sq \&. .
1.1 jsing 491: .It Fl ss_cert Ar file
492: A single self-signed certificate to be signed by the CA.
493: .It Fl startdate Ar date
1.41 jmc 494: Set the start date.
1.1 jsing 495: The format of the date is YYMMDDHHMMSSZ
496: .Pq the same as an ASN1 UTCTime structure .
497: .It Fl status Ar serial
1.35 jmc 498: Show the status of the certificate with serial number
1.1 jsing 499: .Ar serial .
500: .It Fl updatedb
501: Update database for expired certificates.
502: .It Fl verbose
1.41 jmc 503: Print extra details about the operations being performed.
1.1 jsing 504: .El
1.35 jmc 505: .Pp
506: The options relevant to CRLs are as follows:
1.1 jsing 507: .Bl -tag -width "XXXX"
508: .It Fl crl_CA_compromise Ar time
509: This is the same as
510: .Fl crl_compromise ,
511: except the revocation reason is set to CACompromise.
512: .It Fl crl_compromise Ar time
1.41 jmc 513: Set the revocation reason to keyCompromise and the compromise time to
1.1 jsing 514: .Ar time .
515: .Ar time
516: should be in GeneralizedTime format, i.e. YYYYMMDDHHMMSSZ.
517: .It Fl crl_hold Ar instruction
1.41 jmc 518: Set the CRL revocation reason code to certificateHold and the hold
1.1 jsing 519: instruction to
520: .Ar instruction
521: which must be an OID.
522: Although any OID can be used, only holdInstructionNone
523: (the use of which is discouraged by RFC 2459), holdInstructionCallIssuer or
524: holdInstructionReject will normally be used.
525: .It Fl crl_reason Ar reason
526: Revocation reason, where
527: .Ar reason
528: is one of:
529: unspecified, keyCompromise, CACompromise, affiliationChanged, superseded,
530: cessationOfOperation, certificateHold or removeFromCRL.
531: The matching of
532: .Ar reason
533: is case insensitive.
534: Setting any revocation reason will make the CRL v2.
535: In practice, removeFromCRL is not particularly useful because it is only used
536: in delta CRLs which are not currently implemented.
537: .It Fl crldays Ar num
538: The number of days before the next CRL is due.
539: This is the days from now to place in the CRL
1.35 jmc 540: .Cm nextUpdate
1.1 jsing 541: field.
542: .It Fl crlexts Ar section
543: The
544: .Ar section
545: of the configuration file containing CRL extensions to include.
546: If no CRL extension section is present then a V1 CRL is created;
547: if the CRL extension section is present
548: .Pq even if it is empty
549: then a V2 CRL is created.
550: The CRL extensions specified are CRL extensions and
551: .Em not
552: CRL entry extensions.
553: It should be noted that some software
554: .Pq for example Netscape
555: can't handle V2 CRLs.
556: .It Fl crlhours Ar num
557: The number of hours before the next CRL is due.
558: .It Fl gencrl
1.41 jmc 559: Generate a CRL based on information in the index file.
1.1 jsing 560: .It Fl revoke Ar file
561: A
562: .Ar file
563: containing a certificate to revoke.
564: .It Fl subj Ar arg
565: Supersedes the subject name given in the request.
566: The
567: .Ar arg
568: must be formatted as
569: .Ar /type0=value0/type1=value1/type2=... ;
570: characters may be escaped by
571: .Sq \e
572: .Pq backslash ,
573: no spaces are skipped.
574: .El
575: .Pp
1.35 jmc 576: Many of the options can be set in the
577: .Cm ca
578: section of the configuration file
579: (or in the default section of the configuration file),
580: specified using
581: .Cm default_ca
582: or
583: .Fl name .
584: The options
585: .Cm preserve
586: and
587: .Cm msie_hack
588: are read directly from the
589: .Cm ca
590: section.
1.1 jsing 591: .Pp
592: Many of the configuration file options are identical to command line
593: options.
594: Where the option is present in the configuration file and the command line,
595: the command line value is used.
596: Where an option is described as mandatory, then it must be present in
597: the configuration file or the command line equivalent
598: .Pq if any
599: used.
600: .Bl -tag -width "XXXX"
1.35 jmc 601: .It Cm certificate
1.1 jsing 602: The same as
603: .Fl cert .
604: It gives the file containing the CA certificate.
605: Mandatory.
1.35 jmc 606: .It Cm copy_extensions
1.1 jsing 607: Determines how extensions in certificate requests should be handled.
608: If set to
1.35 jmc 609: .Cm none
1.1 jsing 610: or this option is not present, then extensions are
611: ignored and not copied to the certificate.
612: If set to
1.35 jmc 613: .Cm copy ,
1.1 jsing 614: then any extensions present in the request that are not already present
615: are copied to the certificate.
616: If set to
1.35 jmc 617: .Cm copyall ,
1.1 jsing 618: then all extensions in the request are copied to the certificate:
619: if the extension is already present in the certificate it is deleted first.
1.35 jmc 620: .Pp
621: The
622: .Cm copy_extensions
623: option should be used with caution.
624: If care is not taken, it can be a security risk.
625: For example, if a certificate request contains a
626: .Cm basicConstraints
627: extension with CA:TRUE and the
628: .Cm copy_extensions
629: value is set to
630: .Cm copyall
631: and the user does not spot
632: this when the certificate is displayed, then this will hand the requestor
633: a valid CA certificate.
634: .Pp
635: This situation can be avoided by setting
636: .Cm copy_extensions
637: to
638: .Cm copy
639: and including
640: .Cm basicConstraints
641: with CA:FALSE in the configuration file.
642: Then if the request contains a
643: .Cm basicConstraints
644: extension, it will be ignored.
1.1 jsing 645: .Pp
646: The main use of this option is to allow a certificate request to supply
647: values for certain extensions such as
1.35 jmc 648: .Cm subjectAltName .
649: .It Cm crl_extensions
1.1 jsing 650: The same as
651: .Fl crlexts .
1.35 jmc 652: .It Cm crlnumber
1.1 jsing 653: A text file containing the next CRL number to use in hex.
654: The CRL number will be inserted in the CRLs only if this file exists.
655: If this file is present, it must contain a valid CRL number.
1.35 jmc 656: .It Cm database
1.1 jsing 657: The text database file to use.
658: Mandatory.
659: This file must be present, though initially it will be empty.
1.35 jmc 660: .It Cm default_crl_hours , default_crl_days
1.1 jsing 661: The same as the
662: .Fl crlhours
663: and
664: .Fl crldays
665: options.
666: These will only be used if neither command line option is present.
667: At least one of these must be present to generate a CRL.
1.35 jmc 668: .It Cm default_days
1.1 jsing 669: The same as the
670: .Fl days
671: option.
672: The number of days to certify a certificate for.
1.35 jmc 673: .It Cm default_enddate
1.1 jsing 674: The same as the
675: .Fl enddate
676: option.
677: Either this option or
1.35 jmc 678: .Cm default_days
1.1 jsing 679: .Pq or the command line equivalents
680: must be present.
1.35 jmc 681: .It Cm default_md
1.1 jsing 682: The same as the
683: .Fl md
684: option.
685: The message digest to use.
686: Mandatory.
1.35 jmc 687: .It Cm default_startdate
1.1 jsing 688: The same as the
689: .Fl startdate
690: option.
691: The start date to certify a certificate for.
692: If not set, the current time is used.
1.35 jmc 693: .It Cm email_in_dn
1.1 jsing 694: The same as
695: .Fl noemailDN .
696: If the EMAIL field is to be removed from the DN of the certificate,
697: simply set this to
698: .Qq no .
699: If not present, the default is to allow for the EMAIL field in the
700: certificate's DN.
1.35 jmc 701: .It Cm msie_hack
1.1 jsing 702: The same as
703: .Fl msie_hack .
1.35 jmc 704: .It Cm name_opt , cert_opt
1.1 jsing 705: These options allow the format used to display the certificate details
706: when asking the user to confirm signing.
707: All the options supported by the
708: .Nm x509
709: utilities'
710: .Fl nameopt
711: and
712: .Fl certopt
713: switches can be used here, except that
1.35 jmc 714: .Cm no_signame
1.1 jsing 715: and
1.35 jmc 716: .Cm no_sigdump
1.1 jsing 717: are permanently set and cannot be disabled
718: (this is because the certificate signature cannot be displayed because
719: the certificate has not been signed at this point).
720: .Pp
721: For convenience, the value
1.35 jmc 722: .Cm ca_default
1.1 jsing 723: is accepted by both to produce a reasonable output.
724: .Pp
725: If neither option is present, the format used in earlier versions of
1.35 jmc 726: .Nm openssl
1.1 jsing 727: is used.
728: Use of the old format is
729: .Em strongly
730: discouraged because it only displays fields mentioned in the
1.35 jmc 731: .Cm policy
1.1 jsing 732: section,
733: mishandles multicharacter string types and does not display extensions.
1.35 jmc 734: .It Cm new_certs_dir
1.1 jsing 735: The same as the
736: .Fl outdir
737: command line option.
738: It specifies the directory where new certificates will be placed.
739: Mandatory.
1.35 jmc 740: .It Cm oid_file
1.1 jsing 741: This specifies a file containing additional object identifiers.
742: Each line of the file should consist of the numerical form of the
743: object identifier followed by whitespace, then the short name followed
744: by whitespace and finally the long name.
1.35 jmc 745: .It Cm oid_section
1.1 jsing 746: This specifies a section in the configuration file containing extra
747: object identifiers.
748: Each line should consist of the short name of the object identifier
749: followed by
750: .Sq =
751: and the numerical form.
752: The short and long names are the same when this option is used.
1.35 jmc 753: .It Cm policy
1.1 jsing 754: The same as
755: .Fl policy .
756: Mandatory.
1.35 jmc 757: .It Cm preserve
1.1 jsing 758: The same as
759: .Fl preserveDN .
1.35 jmc 760: .It Cm private_key
1.1 jsing 761: Same as the
762: .Fl keyfile
763: option.
764: The file containing the CA private key.
765: Mandatory.
1.35 jmc 766: .It Cm serial
1.1 jsing 767: A text file containing the next serial number to use in hex.
768: Mandatory.
769: This file must be present and contain a valid serial number.
1.35 jmc 770: .It Cm unique_subject
1.1 jsing 771: If the value
1.35 jmc 772: .Cm yes
1.1 jsing 773: is given, the valid certificate entries in the
774: database must have unique subjects.
775: If the value
1.35 jmc 776: .Cm no
1.1 jsing 777: is given,
778: several valid certificate entries may have the exact same subject.
779: The default value is
1.35 jmc 780: .Cm yes .
781: .It Cm x509_extensions
1.1 jsing 782: The same as
783: .Fl extensions .
784: .El
785: .Sh CIPHERS
786: .Nm openssl ciphers
787: .Op Fl hVv
1.18 jmc 788: .Op Fl tls1
1.1 jsing 789: .Op Ar cipherlist
790: .Pp
791: The
792: .Nm ciphers
793: command converts
1.36 jmc 794: .Nm openssl
1.1 jsing 795: cipher lists into ordered SSL cipher preference lists.
1.41 jmc 796: It can be used as a way to determine the appropriate cipher list.
1.1 jsing 797: .Pp
798: The options are as follows:
799: .Bl -tag -width Ds
800: .It Fl h , \&?
801: Print a brief usage message.
802: .It Fl tls1
803: Only include TLS v1 ciphers.
804: .It Fl V
1.36 jmc 805: Verbose.
806: List ciphers with a complete description of protocol version,
807: key exchange, authentication, encryption and mac algorithms,
808: any key size restrictions,
809: and cipher suite codes (hex format).
810: .It Fl v
1.1 jsing 811: Like
1.36 jmc 812: .Fl V ,
813: but without cipher suite codes.
1.1 jsing 814: .It Ar cipherlist
815: A cipher list to convert to a cipher preference list.
816: If it is not included, the default cipher list will be used.
1.36 jmc 817: .Pp
818: The cipher list consists of one or more cipher strings
1.1 jsing 819: separated by colons.
820: Commas or spaces are also acceptable separators, but colons are normally used.
821: .Pp
1.36 jmc 822: The actual cipher string can take several different forms:
1.1 jsing 823: .Pp
1.36 jmc 824: It can consist of a single cipher suite, such as RC4-SHA.
1.1 jsing 825: .Pp
826: It can represent a list of cipher suites containing a certain algorithm,
827: or cipher suites of a certain type.
1.36 jmc 828: For example SHA1 represents all cipher suites using the digest algorithm SHA1.
829: .Pp
830: Lists of cipher suites can be combined in a single cipher string using the
1.1 jsing 831: .Sq +
1.36 jmc 832: character
833: (logical AND operation).
834: For example, SHA1+DES represents all cipher suites
835: containing the SHA1 and DES algorithms.
1.1 jsing 836: .Pp
837: Each cipher string can be optionally preceded by the characters
838: .Sq \&! ,
839: .Sq - ,
840: or
841: .Sq + .
842: If
843: .Sq !\&
844: is used, then the ciphers are permanently deleted from the list.
845: The ciphers deleted can never reappear in the list even if they are
846: explicitly stated.
847: If
848: .Sq -
849: is used, then the ciphers are deleted from the list, but some or
850: all of the ciphers can be added again by later options.
851: If
852: .Sq +
853: is used, then the ciphers are moved to the end of the list.
854: This option doesn't add any new ciphers, it just moves matching existing ones.
855: .Pp
856: If none of these characters is present, the string is just interpreted
857: as a list of ciphers to be appended to the current preference list.
858: If the list includes any ciphers already present, they will be ignored;
859: that is, they will not be moved to the end of the list.
860: .Pp
861: Additionally, the cipher string
1.36 jmc 862: .Cm @STRENGTH
1.1 jsing 863: can be used at any point to sort the current cipher list in order of
864: encryption algorithm key length.
1.36 jmc 865: .El
866: .Pp
1.1 jsing 867: The following is a list of all permitted cipher strings and their meanings.
868: .Bl -tag -width "XXXX"
1.36 jmc 869: .It Cm DEFAULT
1.1 jsing 870: The default cipher list.
871: This is determined at compile time and is currently
1.36 jmc 872: .Cm ALL:!aNULL:!eNULL:!SSLv2 .
873: This must be the first cipher string specified.
874: .It Cm COMPLEMENTOFDEFAULT
1.1 jsing 875: The ciphers included in
1.36 jmc 876: .Cm ALL ,
1.1 jsing 877: but not enabled by default.
878: Currently this is
1.36 jmc 879: .Cm ADH .
1.1 jsing 880: Note that this rule does not cover
1.36 jmc 881: .Cm eNULL ,
1.1 jsing 882: which is not included by
1.36 jmc 883: .Cm ALL
1.1 jsing 884: (use
1.36 jmc 885: .Cm COMPLEMENTOFALL
1.1 jsing 886: if necessary).
1.36 jmc 887: .It Cm ALL
1.1 jsing 888: All cipher suites except the
1.36 jmc 889: .Cm eNULL
890: ciphers, which must be explicitly enabled.
891: .It Cm COMPLEMENTOFALL
1.1 jsing 892: The cipher suites not enabled by
1.36 jmc 893: .Cm ALL ,
1.1 jsing 894: currently being
1.36 jmc 895: .Cm eNULL .
896: .It Cm HIGH
1.1 jsing 897: .Qq High
898: encryption cipher suites.
899: This currently means those with key lengths larger than 128 bits.
1.36 jmc 900: .It Cm MEDIUM
1.1 jsing 901: .Qq Medium
902: encryption cipher suites, currently those using 128-bit encryption.
1.36 jmc 903: .It Cm LOW
1.1 jsing 904: .Qq Low
905: encryption cipher suites, currently those using 64- or 56-bit encryption
1.9 lteo 906: algorithms.
1.36 jmc 907: .It Cm eNULL , NULL
1.1 jsing 908: The
909: .Qq NULL
910: ciphers; that is, those offering no encryption.
911: Because these offer no encryption at all and are a security risk,
912: they are disabled unless explicitly included.
1.36 jmc 913: .It Cm aNULL
1.1 jsing 914: The cipher suites offering no authentication.
915: This is currently the anonymous DH algorithms.
916: These cipher suites are vulnerable to a
917: .Qq man in the middle
918: attack, so their use is normally discouraged.
1.36 jmc 919: .It Cm kRSA , RSA
1.1 jsing 920: Cipher suites using RSA key exchange.
1.36 jmc 921: .It Cm kEDH
1.1 jsing 922: Cipher suites using ephemeral DH key agreement.
1.36 jmc 923: .It Cm aRSA
1.1 jsing 924: Cipher suites using RSA authentication, i.e. the certificates carry RSA keys.
1.36 jmc 925: .It Cm aDSS , DSS
1.1 jsing 926: Cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
1.36 jmc 927: .It Cm TLSv1
1.18 jmc 928: TLS v1.0 cipher suites.
1.36 jmc 929: .It Cm DH
1.1 jsing 930: Cipher suites using DH, including anonymous DH.
1.36 jmc 931: .It Cm ADH
1.1 jsing 932: Anonymous DH cipher suites.
1.36 jmc 933: .It Cm AES
1.1 jsing 934: Cipher suites using AES.
1.36 jmc 935: .It Cm 3DES
1.1 jsing 936: Cipher suites using triple DES.
1.36 jmc 937: .It Cm DES
1.1 jsing 938: Cipher suites using DES
939: .Pq not triple DES .
1.36 jmc 940: .It Cm RC4
1.1 jsing 941: Cipher suites using RC4.
1.36 jmc 942: .It Cm CAMELLIA
1.9 lteo 943: Cipher suites using Camellia.
1.36 jmc 944: .It Cm CHACHA20
1.9 lteo 945: Cipher suites using ChaCha20.
1.36 jmc 946: .It Cm IDEA
1.9 lteo 947: Cipher suites using IDEA.
1.36 jmc 948: .It Cm MD5
1.1 jsing 949: Cipher suites using MD5.
1.36 jmc 950: .It Cm SHA1 , SHA
1.1 jsing 951: Cipher suites using SHA1.
952: .El
953: .Sh CRL
954: .nr nS 1
955: .Nm "openssl crl"
956: .Op Fl CAfile Ar file
957: .Op Fl CApath Ar dir
958: .Op Fl fingerprint
959: .Op Fl hash
960: .Op Fl in Ar file
1.38 jmc 961: .Op Fl inform Cm der | pem
1.1 jsing 962: .Op Fl issuer
963: .Op Fl lastupdate
964: .Op Fl nextupdate
965: .Op Fl noout
966: .Op Fl out Ar file
1.38 jmc 967: .Op Fl outform Cm der | pem
1.1 jsing 968: .Op Fl text
969: .nr nS 0
970: .Pp
971: The
972: .Nm crl
973: command processes CRL files in DER or PEM format.
1.37 jmc 974: The PEM CRL format uses the header and footer lines:
975: .Bd -unfilled -offset indent
976: -----BEGIN X509 CRL-----
977: -----END X509 CRL-----
978: .Ed
979: .Pp
1.1 jsing 980: The options are as follows:
981: .Bl -tag -width Ds
982: .It Fl CAfile Ar file
983: Verify the signature on a CRL by looking up the issuing certificate in
984: .Ar file .
985: .It Fl CApath Ar directory
986: Verify the signature on a CRL by looking up the issuing certificate in
987: .Ar dir .
988: This directory must be a standard certificate directory,
989: i.e. a hash of each subject name (using
990: .Cm x509 Fl hash )
991: should be linked to each certificate.
992: .It Fl fingerprint
993: Print the CRL fingerprint.
994: .It Fl hash
995: Output a hash of the issuer name.
996: This can be used to look up CRLs in a directory by issuer name.
997: .It Fl in Ar file
1.37 jmc 998: The input file to read from, or standard input if not specified.
1.38 jmc 999: .It Fl inform Cm der | pem
1.37 jmc 1000: The input format.
1.1 jsing 1001: .It Fl issuer
1002: Output the issuer name.
1003: .It Fl lastupdate
1004: Output the
1.37 jmc 1005: .Cm lastUpdate
1.1 jsing 1006: field.
1007: .It Fl nextupdate
1008: Output the
1.37 jmc 1009: .Cm nextUpdate
1.1 jsing 1010: field.
1011: .It Fl noout
1.46 jmc 1012: Do not output the encoded version of the CRL.
1.1 jsing 1013: .It Fl out Ar file
1.37 jmc 1014: The output file to write to, or standard output if not specified.
1.38 jmc 1015: .It Fl outform Cm der | pem
1.37 jmc 1016: The output format.
1.1 jsing 1017: .It Fl text
1.48 jmc 1018: Print the CRL in text form.
1.1 jsing 1019: .El
1020: .Sh CRL2PKCS7
1021: .nr nS 1
1022: .Nm "openssl crl2pkcs7"
1023: .Op Fl certfile Ar file
1024: .Op Fl in Ar file
1.40 jmc 1025: .Op Fl inform Cm der | pem
1.1 jsing 1026: .Op Fl nocrl
1027: .Op Fl out Ar file
1.40 jmc 1028: .Op Fl outform Cm der | pem
1.1 jsing 1029: .nr nS 0
1030: .Pp
1031: The
1032: .Nm crl2pkcs7
1033: command takes an optional CRL and one or more
1034: certificates and converts them into a PKCS#7 degenerate
1035: .Qq certificates only
1036: structure.
1037: .Pp
1038: The options are as follows:
1039: .Bl -tag -width Ds
1040: .It Fl certfile Ar file
1.40 jmc 1041: Add the certificates in PEM
1.1 jsing 1042: .Ar file
1.40 jmc 1043: to the PKCS#7 structure.
1044: This option can be used more than once
1045: to read certificates from multiple files.
1.1 jsing 1046: .It Fl in Ar file
1.40 jmc 1047: Read the CRL from
1048: .Ar file ,
1049: or standard input if not specified.
1050: .It Fl inform Cm der | pem
1051: Specify the CRL input format.
1.1 jsing 1052: .It Fl nocrl
1053: Normally, a CRL is included in the output file.
1054: With this option, no CRL is
1055: included in the output file and a CRL is not read from the input file.
1056: .It Fl out Ar file
1.40 jmc 1057: Write the PKCS#7 structure to
1058: .Ar file ,
1059: or standard output if not specified.
1060: .It Fl outform Cm der | pem
1061: Specify the PKCS#7 structure output format.
1.1 jsing 1062: .El
1063: .Sh DGST
1064: .nr nS 1
1065: .Nm "openssl dgst"
1.43 jmc 1066: .Op Fl cd
1.1 jsing 1067: .Op Fl binary
1.43 jmc 1068: .Op Fl Ar digest
1.1 jsing 1069: .Op Fl hex
1070: .Op Fl hmac Ar key
1.43 jmc 1071: .Op Fl keyform Cm pem
1.1 jsing 1072: .Op Fl mac Ar algorithm
1073: .Op Fl macopt Ar nm : Ns Ar v
1074: .Op Fl out Ar file
1075: .Op Fl passin Ar arg
1076: .Op Fl prverify Ar file
1077: .Op Fl sign Ar file
1078: .Op Fl signature Ar file
1079: .Op Fl sigopt Ar nm : Ns Ar v
1080: .Op Fl verify Ar file
1081: .Op Ar
1082: .nr nS 0
1083: .Pp
1084: The digest functions output the message digest of a supplied
1085: .Ar file
1086: or
1087: .Ar files
1088: in hexadecimal form.
1089: They can also be used for digital signing and verification.
1090: .Pp
1091: The options are as follows:
1092: .Bl -tag -width Ds
1093: .It Fl binary
1094: Output the digest or signature in binary form.
1095: .It Fl c
1.48 jmc 1096: Print the digest in two-digit groups separated by colons.
1.1 jsing 1097: .It Fl d
1.48 jmc 1098: Print BIO debugging information.
1.43 jmc 1099: .It Fl Ar digest
1100: Use the specified message
1101: .Ar digest .
1102: The default is MD5.
1103: The available digests can be displayed using
1104: .Nm openssl
1105: .Cm list-message-digest-commands .
1106: The following are equivalent:
1107: .Nm openssl dgst
1108: .Fl md5
1109: and
1110: .Nm openssl
1111: .Cm md5 .
1.1 jsing 1112: .It Fl hex
1113: Digest is to be output as a hex dump.
1114: This is the default case for a
1115: .Qq normal
1116: digest as opposed to a digital signature.
1117: .It Fl hmac Ar key
1118: Create a hashed MAC using
1119: .Ar key .
1.43 jmc 1120: .It Fl keyform Cm pem
1.1 jsing 1121: Specifies the key format to sign the digest with.
1122: .It Fl mac Ar algorithm
1123: Create a keyed Message Authentication Code (MAC).
1124: The most popular MAC algorithm is HMAC (hash-based MAC),
1125: but there are other MAC algorithms which are not based on hash.
1126: MAC keys and other options should be set via the
1127: .Fl macopt
1128: parameter.
1129: .It Fl macopt Ar nm : Ns Ar v
1130: Passes options to the MAC algorithm, specified by
1131: .Fl mac .
1132: The following options are supported by HMAC:
1133: .Bl -tag -width Ds
1.43 jmc 1134: .It Cm key : Ns Ar string
1.1 jsing 1135: Specifies the MAC key as an alphanumeric string
1136: (use if the key contain printable characters only).
1137: String length must conform to any restrictions of the MAC algorithm.
1.43 jmc 1138: .It Cm hexkey : Ns Ar string
1.1 jsing 1139: Specifies the MAC key in hexadecimal form (two hex digits per byte).
1140: Key length must conform to any restrictions of the MAC algorithm.
1141: .El
1142: .It Fl out Ar file
1.43 jmc 1143: The output file to write to,
1144: or standard output if not specified.
1.1 jsing 1145: .It Fl passin Ar arg
1146: The key password source.
1147: .It Fl prverify Ar file
1148: Verify the signature using the private key in
1149: .Ar file .
1150: The output is either
1151: .Qq Verification OK
1152: or
1153: .Qq Verification Failure .
1154: .It Fl sign Ar file
1155: Digitally sign the digest using the private key in
1156: .Ar file .
1157: .It Fl signature Ar file
1158: The actual signature to verify.
1159: .It Fl sigopt Ar nm : Ns Ar v
1160: Pass options to the signature algorithm during sign or verify operations.
1161: The names and values of these options are algorithm-specific.
1162: .It Fl verify Ar file
1163: Verify the signature using the public key in
1164: .Ar file .
1165: The output is either
1166: .Qq Verification OK
1167: or
1168: .Qq Verification Failure .
1169: .It Ar
1170: File or files to digest.
1171: If no files are specified then standard input is used.
1172: .El
1173: .Sh DHPARAM
1174: .nr nS 1
1175: .Nm "openssl dhparam"
1176: .Op Fl 2 | 5
1177: .Op Fl C
1178: .Op Fl check
1179: .Op Fl dsaparam
1180: .Op Fl in Ar file
1.44 jmc 1181: .Op Fl inform Cm der | pem
1.1 jsing 1182: .Op Fl noout
1183: .Op Fl out Ar file
1.44 jmc 1184: .Op Fl outform Cm der | pem
1.1 jsing 1185: .Op Fl text
1186: .Op Ar numbits
1187: .nr nS 0
1188: .Pp
1189: The
1190: .Nm dhparam
1191: command is used to manipulate DH parameter files.
1.44 jmc 1192: Only the older PKCS#3 DH is supported,
1193: not the newer X9.42 DH.
1.1 jsing 1194: .Pp
1195: The options are as follows:
1196: .Bl -tag -width Ds
1197: .It Fl 2 , 5
1.44 jmc 1198: The generator to use;
1.1 jsing 1199: 2 is the default.
1200: If present, the input file is ignored and parameters are generated instead.
1201: .It Fl C
1.44 jmc 1202: Convert the parameters into C code.
1.1 jsing 1203: The parameters can then be loaded by calling the
1.44 jmc 1204: .No get_dh Ns Ar numbits
1.1 jsing 1205: function.
1206: .It Fl check
1207: Check the DH parameters.
1208: .It Fl dsaparam
1.44 jmc 1209: Read or create DSA parameters,
1210: converted to DH format on output.
1.1 jsing 1211: Otherwise,
1212: .Qq strong
1213: primes
1214: .Pq such that (p-1)/2 is also prime
1215: will be used for DH parameter generation.
1216: .Pp
1217: DH parameter generation with the
1218: .Fl dsaparam
1219: option is much faster,
1220: and the recommended exponent length is shorter,
1221: which makes DH key exchange more efficient.
1222: Beware that with such DSA-style DH parameters,
1223: a fresh DH key should be created for each use to
1224: avoid small-subgroup attacks that may be possible otherwise.
1225: .It Fl in Ar file
1.44 jmc 1226: The input file to read from,
1227: or standard input if not specified.
1228: .It Fl inform Cm der | pem
1229: The input format.
1230: .Cm der
1.1 jsing 1231: uses an ASN1 DER-encoded form compatible with the PKCS#3 DHparameter
1232: structure.
1.44 jmc 1233: .Cm pem
1234: is the default:
1.1 jsing 1235: it consists of the DER format base64-encoded with
1.44 jmc 1236: additional header and footer lines:
1237: .Bd -unfilled -offset indent
1238: -----BEGIN DH PARAMETERS-----
1239: -----END DH PARAMETERS-----
1240: .Ed
1.1 jsing 1241: .It Fl noout
1.46 jmc 1242: Do not output the encoded version of the parameters.
1.44 jmc 1243: .It Fl out Ar file
1244: The output file to write to,
1245: or standard output if not specified.
1246: .It Fl outform Cm der | pem
1247: The output format.
1248: .It Fl text
1.48 jmc 1249: Print the DH parameters in human readable form.
1.1 jsing 1250: .It Ar numbits
1.44 jmc 1251: Generate a parameter set of size
1.1 jsing 1252: .Ar numbits .
1253: It must be the last option.
1.16 sthen 1254: If not present, a value of 2048 is used.
1.1 jsing 1255: If this value is present, the input file is ignored and
1256: parameters are generated instead.
1257: .El
1258: .Sh DSA
1259: .nr nS 1
1260: .Nm "openssl dsa"
1261: .Oo
1262: .Fl aes128 | aes192 | aes256 |
1263: .Fl des | des3
1264: .Oc
1265: .Op Fl in Ar file
1.45 jmc 1266: .Op Fl inform Cm der | pem
1.1 jsing 1267: .Op Fl modulus
1268: .Op Fl noout
1269: .Op Fl out Ar file
1.45 jmc 1270: .Op Fl outform Cm der | pem
1.1 jsing 1271: .Op Fl passin Ar arg
1272: .Op Fl passout Ar arg
1273: .Op Fl pubin
1274: .Op Fl pubout
1275: .Op Fl text
1276: .nr nS 0
1277: .Pp
1278: The
1279: .Nm dsa
1280: command processes DSA keys.
1281: They can be converted between various forms and their components printed out.
1282: .Pp
1283: .Sy Note :
1284: This command uses the traditional
1285: .Nm SSLeay
1286: compatible format for private key encryption:
1287: newer applications should use the more secure PKCS#8 format using the
1288: .Nm pkcs8
1289: command.
1290: .Pp
1.45 jmc 1291: The PEM private key format uses the header and footer lines:
1292: .Bd -unfilled -offset indent
1293: -----BEGIN DSA PRIVATE KEY-----
1294: -----END DSA PRIVATE KEY-----
1295: .Ed
1296: .Pp
1297: The PEM public key format uses the header and footer lines:
1298: .Bd -unfilled -offset indent
1299: -----BEGIN PUBLIC KEY-----
1300: -----END PUBLIC KEY-----
1301: .Ed
1302: .Pp
1.1 jsing 1303: The options are as follows:
1304: .Bl -tag -width Ds
1305: .It Xo
1306: .Fl aes128 | aes192 | aes256 |
1307: .Fl des | des3
1308: .Xc
1.45 jmc 1309: Encrypt the private key with the AES, DES, or the triple DES
1.1 jsing 1310: ciphers, respectively, before outputting it.
1311: A pass phrase is prompted for.
1.45 jmc 1312: If none of these options are specified, the key is written in plain text.
1.1 jsing 1313: This means that using the
1314: .Nm dsa
1.45 jmc 1315: utility to read an encrypted key with no encryption option can be used to
1.1 jsing 1316: remove the pass phrase from a key,
1.45 jmc 1317: or by setting the encryption options it can be used to add or change
1.1 jsing 1318: the pass phrase.
1319: These options can only be used with PEM format output files.
1320: .It Fl in Ar file
1.45 jmc 1321: The input file to read from,
1322: or standard input if not specified.
1.1 jsing 1323: If the key is encrypted, a pass phrase will be prompted for.
1.45 jmc 1324: .It Fl inform Cm der | pem
1325: The input format.
1326: .Cm der
1327: with a private key uses an ASN1 DER-encoded form of an ASN.1
1.1 jsing 1328: SEQUENCE consisting of the values of version
1329: .Pq currently zero ,
1330: P, Q, G,
1331: and the public and private key components, respectively, as ASN.1 INTEGERs.
1332: When used with a public key it uses a
1333: .Em SubjectPublicKeyInfo
1334: structure: it is an error if the key is not DSA.
1335: .Pp
1.45 jmc 1336: .Cm pem
1337: is the default format:
1.1 jsing 1338: it consists of the DER format base64-encoded with additional header and footer
1339: lines.
1340: In the case of a private key, PKCS#8 format is also accepted.
1341: .It Fl modulus
1.45 jmc 1342: Print the value of the public key component of the key.
1.1 jsing 1343: .It Fl noout
1.46 jmc 1344: Do not output the encoded version of the key.
1.1 jsing 1345: .It Fl out Ar file
1.45 jmc 1346: The output file to write to,
1347: or standard output if not specified.
1.1 jsing 1348: If any encryption options are set then a pass phrase will be
1349: prompted for.
1.45 jmc 1350: .It Fl outform Cm der | pem
1351: The output format.
1.1 jsing 1352: .It Fl passin Ar arg
1353: The key password source.
1354: .It Fl passout Ar arg
1355: The output file password source.
1356: .It Fl pubin
1357: By default, a private key is read from the input file.
1358: With this option a public key is read instead.
1359: .It Fl pubout
1360: By default, a private key is output.
1361: With this option a public key will be output instead.
1362: This option is automatically set if the input is a public key.
1363: .It Fl text
1.48 jmc 1364: Print the public/private key components and parameters.
1.1 jsing 1365: .El
1366: .Sh DSAPARAM
1367: .nr nS 1
1368: .Nm "openssl dsaparam"
1369: .Op Fl C
1370: .Op Fl genkey
1371: .Op Fl in Ar file
1.46 jmc 1372: .Op Fl inform Cm der | pem
1.1 jsing 1373: .Op Fl noout
1374: .Op Fl out Ar file
1.46 jmc 1375: .Op Fl outform Cm der | pem
1.1 jsing 1376: .Op Fl text
1377: .Op Ar numbits
1378: .nr nS 0
1379: .Pp
1380: The
1381: .Nm dsaparam
1382: command is used to manipulate or generate DSA parameter files.
1383: .Pp
1.46 jmc 1384: PEM format DSA parameters use the header and footer lines:
1385: .Bd -unfilled -offset indent
1386: -----BEGIN DSA PARAMETERS-----
1387: -----END DSA PARAMETERS-----
1388: .Ed
1389: .Pp
1.1 jsing 1390: The options are as follows:
1391: .Bl -tag -width Ds
1392: .It Fl C
1.46 jmc 1393: Convert the parameters into C code.
1.1 jsing 1394: The parameters can then be loaded by calling the
1.46 jmc 1395: .No get_dsa Ns Ar XXX
1.1 jsing 1396: function.
1397: .It Fl genkey
1.46 jmc 1398: Generate a DSA key either using the specified or generated
1.1 jsing 1399: parameters.
1400: .It Fl in Ar file
1.46 jmc 1401: The input file to read from,
1402: or standard input if not specified.
1.1 jsing 1403: If the
1404: .Ar numbits
1.46 jmc 1405: parameter is included, then this option is ignored.
1406: .It Fl inform Cm der | pem
1407: The input format.
1408: .Cm der
1409: uses an ASN1 DER-encoded form compatible with RFC 2459
1.1 jsing 1410: .Pq PKIX
1411: DSS-Parms that is a SEQUENCE consisting of p, q and g, respectively.
1.46 jmc 1412: .Cm pem
1413: is the default format:
1.1 jsing 1414: it consists of the DER format base64-encoded with additional header
1415: and footer lines.
1416: .It Fl noout
1.46 jmc 1417: Do not output the encoded version of the parameters.
1418: .It Fl out Ar file
1419: The output file to write to,
1420: or standard output if not specified.
1421: .It Fl outform Cm der | pem
1422: The output format.
1423: .It Fl text
1424: Print the DSA parameters in human readable form.
1.1 jsing 1425: .It Ar numbits
1.46 jmc 1426: Generate a parameter set of size
1.1 jsing 1427: .Ar numbits .
1.46 jmc 1428: If this option is included, the input file is ignored.
1.1 jsing 1429: .El
1430: .Sh EC
1431: .nr nS 1
1432: .Nm "openssl ec"
1433: .Op Fl conv_form Ar arg
1434: .Op Fl des
1435: .Op Fl des3
1436: .Op Fl in Ar file
1.47 jmc 1437: .Op Fl inform Cm der | pem
1.1 jsing 1438: .Op Fl noout
1439: .Op Fl out Ar file
1.47 jmc 1440: .Op Fl outform Cm der | pem
1.1 jsing 1441: .Op Fl param_enc Ar arg
1442: .Op Fl param_out
1443: .Op Fl passin Ar arg
1444: .Op Fl passout Ar arg
1445: .Op Fl pubin
1446: .Op Fl pubout
1447: .Op Fl text
1448: .nr nS 0
1449: .Pp
1450: The
1451: .Nm ec
1452: command processes EC keys.
1453: They can be converted between various
1454: forms and their components printed out.
1.47 jmc 1455: .Nm openssl
1.1 jsing 1456: uses the private key format specified in
1457: .Dq SEC 1: Elliptic Curve Cryptography
1458: .Pq Lk http://www.secg.org/ .
1459: To convert an
1460: EC private key into the PKCS#8 private key format use the
1461: .Nm pkcs8
1462: command.
1463: .Pp
1.47 jmc 1464: The PEM private key format uses the header and footer lines:
1465: .Bd -literal -offset indent
1466: -----BEGIN EC PRIVATE KEY-----
1467: -----END EC PRIVATE KEY-----
1468: .Ed
1469: .Pp
1470: The PEM public key format uses the header and footer lines:
1471: .Bd -literal -offset indent
1472: -----BEGIN PUBLIC KEY-----
1473: -----END PUBLIC KEY-----
1474: .Ed
1475: .Pp
1.1 jsing 1476: The options are as follows:
1477: .Bl -tag -width Ds
1478: .It Fl conv_form Ar arg
1.47 jmc 1479: Specify how the points on the elliptic curve are converted
1.1 jsing 1480: into octet strings.
1481: Possible values are:
1482: .Cm compressed
1.47 jmc 1483: (the default),
1.1 jsing 1484: .Cm uncompressed ,
1485: and
1486: .Cm hybrid .
1487: For more information regarding
1.47 jmc 1488: the point conversion forms see the X9.62 standard.
1.1 jsing 1489: Note:
1490: Due to patent issues the
1491: .Cm compressed
1492: option is disabled by default for binary curves
1493: and can be enabled by defining the preprocessor macro
1.47 jmc 1494: .Dv OPENSSL_EC_BIN_PT_COMP
1.1 jsing 1495: at compile time.
1496: .It Fl des | des3
1.47 jmc 1497: Encrypt the private key with DES, triple DES, or
1.1 jsing 1498: any other cipher supported by
1.47 jmc 1499: .Nm openssl .
1.1 jsing 1500: A pass phrase is prompted for.
1501: If none of these options is specified the key is written in plain text.
1502: This means that using the
1503: .Nm ec
1504: utility to read in an encrypted key with no
1505: encryption option can be used to remove the pass phrase from a key,
1506: or by setting the encryption options
1507: it can be use to add or change the pass phrase.
1508: These options can only be used with PEM format output files.
1509: .It Fl in Ar file
1.47 jmc 1510: The input file to read a key from,
1511: or standard input if not specified.
1.1 jsing 1512: If the key is encrypted a pass phrase will be prompted for.
1.47 jmc 1513: .It Fl inform Cm der | pem
1514: The input format.
1515: .Cm der
1516: with a private key uses
1.1 jsing 1517: an ASN.1 DER-encoded SEC1 private key.
1518: When used with a public key it
1519: uses the SubjectPublicKeyInfo structure as specified in RFC 3280.
1.47 jmc 1520: .Cm pem
1521: is the default format:
1.48 jmc 1522: it consists of the DER format base64-encoded
1523: with additional header and footer lines.
1.1 jsing 1524: In the case of a private key
1525: PKCS#8 format is also accepted.
1526: .It Fl noout
1.47 jmc 1527: Do not output the encoded version of the key.
1.1 jsing 1528: .It Fl out Ar file
1.47 jmc 1529: The output filename to write to,
1530: or standard output if not specified.
1.1 jsing 1531: If any encryption options are set then a pass phrase will be prompted for.
1.47 jmc 1532: .It Fl outform Cm der | pem
1533: The output format.
1.1 jsing 1534: .It Fl param_enc Ar arg
1.47 jmc 1535: Specify how the elliptic curve parameters are encoded.
1.1 jsing 1536: Possible value are:
1537: .Cm named_curve ,
1538: i.e. the EC parameters are specified by an OID; or
1539: .Cm explicit ,
1540: where the EC parameters are explicitly given
1541: (see RFC 3279 for the definition of the EC parameter structures).
1542: The default value is
1543: .Cm named_curve .
1544: Note: the
1545: .Cm implicitlyCA
1546: alternative,
1547: as specified in RFC 3279,
1.47 jmc 1548: is currently not implemented.
1.1 jsing 1549: .It Fl passin Ar arg
1550: The key password source.
1551: .It Fl passout Ar arg
1552: The output file password source.
1553: .It Fl pubin
1554: By default a private key is read from the input file;
1555: with this option a public key is read instead.
1556: .It Fl pubout
1557: By default a private key is output;
1558: with this option a public key is output instead.
1559: This option is automatically set if the input is a public key.
1560: .It Fl text
1.48 jmc 1561: Print the public/private key components and parameters.
1.1 jsing 1562: .El
1563: .Sh ECPARAM
1564: .nr nS 1
1565: .Nm "openssl ecparam"
1566: .Op Fl C
1567: .Op Fl check
1568: .Op Fl conv_form Ar arg
1569: .Op Fl genkey
1570: .Op Fl in Ar file
1.48 jmc 1571: .Op Fl inform Cm der | pem
1.1 jsing 1572: .Op Fl list_curves
1573: .Op Fl name Ar arg
1574: .Op Fl no_seed
1575: .Op Fl noout
1576: .Op Fl out Ar file
1.48 jmc 1577: .Op Fl outform Cm der | pem
1.1 jsing 1578: .Op Fl param_enc Ar arg
1579: .Op Fl text
1580: .nr nS 0
1581: .Pp
1.48 jmc 1582: The
1583: .Nm ecparam
1584: command is used to manipulate or generate EC parameter files.
1585: .Nm openssl
1586: is not able to generate new groups so
1587: .Nm ecparam
1588: can only create EC parameters from known (named) curves.
1589: .Pp
1590: PEM format EC parameters use the header and footer lines:
1591: .Bd -literal -offset indent
1592: -----BEGIN EC PARAMETERS-----
1593: -----END EC PARAMETERS-----
1594: .Ed
1.1 jsing 1595: .Pp
1596: The options are as follows:
1597: .Bl -tag -width Ds
1598: .It Fl C
1599: Convert the EC parameters into C code.
1600: The parameters can then be loaded by calling the
1.48 jmc 1601: .No get_ec_group_ Ns Ar XXX
1.1 jsing 1602: function.
1603: .It Fl check
1604: Validate the elliptic curve parameters.
1605: .It Fl conv_form Ar arg
1606: Specify how the points on the elliptic curve are converted
1607: into octet strings.
1608: Possible values are:
1609: .Cm compressed
1.48 jmc 1610: (the default),
1.1 jsing 1611: .Cm uncompressed ,
1612: and
1613: .Cm hybrid .
1614: For more information regarding
1.48 jmc 1615: the point conversion forms see the X9.62 standard.
1.1 jsing 1616: Note:
1617: Due to patent issues the
1618: .Cm compressed
1619: option is disabled by default for binary curves
1620: and can be enabled by defining the preprocessor macro
1.48 jmc 1621: .Dv OPENSSL_EC_BIN_PT_COMP
1.1 jsing 1622: at compile time.
1623: .It Fl genkey
1624: Generate an EC private key using the specified parameters.
1625: .It Fl in Ar file
1.48 jmc 1626: The input file to read from,
1627: or standard input if not specified.
1628: .It Fl inform Cm der | pem
1629: The input format.
1630: .Cm der
1631: uses an ASN.1 DER-encoded
1.1 jsing 1632: form compatible with RFC 3279 EcpkParameters.
1.48 jmc 1633: .Cm pem
1634: is the default format:
1635: it consists of the DER format base64-encoded with additional
1.1 jsing 1636: header and footer lines.
1637: .It Fl list_curves
1.48 jmc 1638: Print a list of all
1.1 jsing 1639: currently implemented EC parameter names and exit.
1640: .It Fl name Ar arg
1.48 jmc 1641: Use the EC parameters with the specified "short" name.
1.1 jsing 1642: .It Fl no_seed
1.48 jmc 1643: Do not include the seed for the parameter generation
1644: in the ECParameters structure (see RFC 3279).
1.1 jsing 1645: .It Fl noout
1.48 jmc 1646: Do not output the encoded version of the parameters.
1.1 jsing 1647: .It Fl out Ar file
1.48 jmc 1648: The output file to write to,
1649: or standard output if not specified.
1650: .It Fl outform Cm der | pem
1651: The output format.
1.1 jsing 1652: .It Fl param_enc Ar arg
1.48 jmc 1653: Specify how the elliptic curve parameters are encoded.
1.1 jsing 1654: Possible value are:
1655: .Cm named_curve ,
1656: i.e. the EC parameters are specified by an OID, or
1657: .Cm explicit ,
1658: where the EC parameters are explicitly given
1659: (see RFC 3279 for the definition of the EC parameter structures).
1660: The default value is
1661: .Cm named_curve .
1662: Note: the
1663: .Cm implicitlyCA
1664: alternative, as specified in RFC 3279,
1.48 jmc 1665: is currently not implemented.
1.1 jsing 1666: .It Fl text
1.48 jmc 1667: Print the EC parameters in human readable form.
1.1 jsing 1668: .El
1669: .Sh ENC
1670: .nr nS 1
1671: .Nm "openssl enc"
1672: .Fl ciphername
1673: .Op Fl AadePp
1674: .Op Fl base64
1675: .Op Fl bufsize Ar number
1676: .Op Fl debug
1677: .Op Fl in Ar file
1678: .Op Fl iv Ar IV
1679: .Op Fl K Ar key
1680: .Op Fl k Ar password
1681: .Op Fl kfile Ar file
1682: .Op Fl md Ar digest
1683: .Op Fl none
1684: .Op Fl nopad
1685: .Op Fl nosalt
1686: .Op Fl out Ar file
1687: .Op Fl pass Ar arg
1688: .Op Fl S Ar salt
1689: .Op Fl salt
1690: .nr nS 0
1691: .Pp
1692: The symmetric cipher commands allow data to be encrypted or decrypted
1693: using various block and stream ciphers using keys based on passwords
1694: or explicitly provided.
1695: Base64 encoding or decoding can also be performed either by itself
1696: or in addition to the encryption or decryption.
1.49 ! jmc 1697: The program can be called either as
! 1698: .Nm openssl Ar ciphername
! 1699: or
! 1700: .Nm openssl enc - Ns Ar ciphername .
! 1701: .Pp
! 1702: Some of the ciphers do not have large keys and others have security
! 1703: implications if not used correctly.
! 1704: All the block ciphers normally use PKCS#5 padding,
! 1705: also known as standard block padding.
! 1706: If padding is disabled, the input data must be a multiple of the cipher
! 1707: block length.
1.1 jsing 1708: .Pp
1709: The options are as follows:
1710: .Bl -tag -width Ds
1711: .It Fl A
1712: If the
1713: .Fl a
1714: option is set, then base64 process the data on one line.
1715: .It Fl a , base64
1716: Base64 process the data.
1717: This means that if encryption is taking place, the data is base64-encoded
1718: after encryption.
1.49 ! jmc 1719: If decryption is set, the input data is base64-decoded before
1.1 jsing 1720: being decrypted.
1721: .It Fl bufsize Ar number
1722: Set the buffer size for I/O.
1723: .It Fl d
1724: Decrypt the input data.
1725: .It Fl debug
1726: Debug the BIOs used for I/O.
1727: .It Fl e
1.49 ! jmc 1728: Encrypt the input data.
! 1729: This is the default.
1.1 jsing 1730: .It Fl in Ar file
1.49 ! jmc 1731: The input file to read from,
! 1732: or standard input if none is specified.
1.1 jsing 1733: .It Fl iv Ar IV
1734: The actual
1735: .Ar IV
1736: .Pq initialisation vector
1737: to use:
1738: this must be represented as a string comprised only of hex digits.
1739: When only the
1740: .Ar key
1741: is specified using the
1742: .Fl K
1.49 ! jmc 1743: option,
! 1744: the IV must explicitly be defined.
1.1 jsing 1745: When a password is being specified using one of the other options,
1.49 ! jmc 1746: the IV is generated from this password.
1.1 jsing 1747: .It Fl K Ar key
1748: The actual
1749: .Ar key
1750: to use:
1751: this must be represented as a string comprised only of hex digits.
1.49 ! jmc 1752: If only the key is specified,
! 1753: the IV must also be specified using the
1.1 jsing 1754: .Fl iv
1755: option.
1756: When both a
1757: .Ar key
1758: and a
1759: .Ar password
1760: are specified, the
1761: .Ar key
1762: given with the
1763: .Fl K
1.49 ! jmc 1764: option will be used and the IV generated from the password will be taken.
1.1 jsing 1765: It probably does not make much sense to specify both
1766: .Ar key
1767: and
1768: .Ar password .
1769: .It Fl k Ar password
1770: The
1771: .Ar password
1772: to derive the key from.
1773: Superseded by the
1774: .Fl pass
1775: option.
1776: .It Fl kfile Ar file
1777: Read the password to derive the key from the first line of
1778: .Ar file .
1779: Superseded by the
1780: .Fl pass
1781: option.
1782: .It Fl md Ar digest
1783: Use
1784: .Ar digest
1785: to create a key from a pass phrase.
1786: .Ar digest
1787: may be one of
1.49 ! jmc 1788: .Cm md5
1.1 jsing 1789: or
1.49 ! jmc 1790: .Cm sha1 .
1.1 jsing 1791: .It Fl none
1792: Use NULL cipher (no encryption or decryption of input).
1793: .It Fl nopad
1794: Disable standard block padding.
1795: .It Fl nosalt
1.49 ! jmc 1796: Don't use a salt in the key derivation routines.
1.1 jsing 1797: This option should
1798: .Em NEVER
1.49 ! jmc 1799: be used
! 1800: since it makes it possible to perform efficient dictionary
! 1801: attacks on the password and to attack stream cipher encrypted data.
1.1 jsing 1802: .It Fl out Ar file
1.49 ! jmc 1803: The output file to read from,
! 1804: or standard output if none is specified.
1.1 jsing 1805: .It Fl P
1.49 ! jmc 1806: Print out the salt, key, and IV used, then immediately exit;
1.1 jsing 1807: don't do any encryption or decryption.
1808: .It Fl p
1.49 ! jmc 1809: Print out the salt, key, and IV used.
1.1 jsing 1810: .It Fl pass Ar arg
1811: The password source.
1812: .It Fl S Ar salt
1813: The actual
1814: .Ar salt
1815: to use:
1816: this must be represented as a string comprised only of hex digits.
1817: .It Fl salt
1.49 ! jmc 1818: Use a salt in the key derivation routines (the default).
! 1819: When the salt is being used
! 1820: the first eight bytes of the encrypted data are reserved for the salt:
! 1821: it is randomly generated when encrypting a file and read from the
! 1822: encrypted file when it is decrypted.
1.1 jsing 1823: .El
1824: .\"
1825: .\" ERRSTR
1826: .\"
1827: .Sh ERRSTR
1828: .Nm openssl errstr
1829: .Op Fl stats
1830: .Ar errno ...
1831: .Pp
1832: The
1833: .Nm errstr
1834: command performs error number to error string conversion,
1835: generating a human-readable string representing the error code
1836: .Ar errno .
1837: The string is obtained through the
1838: .Xr ERR_error_string_n 3
1839: function and has the following format:
1840: .Pp
1841: .Dl error:[error code]:[library name]:[function name]:[reason string]
1842: .Pp
1843: .Bq error code
1844: is an 8-digit hexadecimal number.
1845: The remaining fields
1846: .Bq library name ,
1847: .Bq function name ,
1848: and
1849: .Bq reason string
1850: are all ASCII text.
1851: .Pp
1852: The options are as follows:
1853: .Bl -tag -width Ds
1854: .It Fl stats
1855: Print debugging statistics about various aspects of the hash table.
1856: .El
1857: .Sh ERRSTR EXAMPLES
1858: The following error code:
1859: .Pp
1860: .Dl 27594:error:2006D080:lib(32):func(109):reason(128):bss_file.c:107:
1861: .Pp
1862: \&...can be displayed with:
1863: .Pp
1864: .Dl $ openssl errstr 2006D080
1865: .Pp
1866: \&...to produce the error message:
1867: .Pp
1868: .Dl error:2006D080:BIO routines:BIO_new_file:no such file
1869: .\"
1870: .\" GENDH
1871: .\"
1872: .Sh GENDH
1873: Generation of Diffie-Hellman Parameters.
1874: Replaced by
1875: .Nm dhparam .
1876: See
1877: .Sx DHPARAM
1878: above.
1879: .\"
1880: .\" GENDSA
1881: .\"
1882: .Sh GENDSA
1883: .nr nS 1
1884: .Nm "openssl gendsa"
1885: .Bk -words
1886: .Oo
1887: .Fl aes128 | aes192 | aes256 |
1888: .Fl des | des3
1889: .Oc
1890: .Op Fl out Ar file
1891: .Op Ar paramfile
1892: .Ek
1893: .nr nS 0
1894: .Pp
1895: The
1896: .Nm gendsa
1897: command generates a DSA private key from a DSA parameter file
1898: (which will typically be generated by the
1899: .Nm openssl dsaparam
1900: command).
1901: .Pp
1902: The options are as follows:
1903: .Bl -tag -width Ds
1904: .It Xo
1905: .Fl aes128 | aes192 | aes256 |
1906: .Fl des | des3
1907: .Xc
1908: These options encrypt the private key with the AES, DES,
1909: or the triple DES ciphers, respectively, before outputting it.
1910: A pass phrase is prompted for.
1911: If none of these options are specified, no encryption is used.
1912: .It Fl out Ar file
1913: The output
1914: .Ar file .
1915: If this argument is not specified, standard output is used.
1916: .It Ar paramfile
1917: This option specifies the DSA parameter file to use.
1918: The parameters in this file determine the size of the private key.
1919: DSA parameters can be generated and examined using the
1920: .Nm openssl dsaparam
1921: command.
1922: .El
1923: .Sh GENDSA NOTES
1924: DSA key generation is little more than random number generation so it is
1925: much quicker than RSA key generation, for example.
1926: .\"
1927: .\" GENPKEY
1928: .\"
1929: .Sh GENPKEY
1930: .nr nS 1
1931: .Nm "openssl genpkey"
1932: .Bk -words
1933: .Op Fl algorithm Ar alg
1934: .Op Ar cipher
1935: .Op Fl genparam
1936: .Op Fl out Ar file
1937: .Op Fl outform Ar DER | PEM
1938: .Op Fl paramfile Ar file
1939: .Op Fl pass Ar arg
1940: .Op Fl pkeyopt Ar opt : Ns Ar value
1941: .Op Fl text
1942: .Ek
1943: .nr nS 0
1944: .Pp
1945: The
1946: .Nm genpkey
1947: command generates private keys.
1948: The use of this
1949: program is encouraged over the algorithm specific utilities
1.22 bcook 1950: because additional algorithm options can be used.
1.1 jsing 1951: .Pp
1952: The options are as follows:
1953: .Bl -tag -width Ds
1954: .It Fl algorithm Ar alg
1955: The public key algorithm to use,
1956: such as RSA, DSA, or DH.
1957: If used this option must precede any
1958: .Fl pkeyopt
1959: options.
1960: The options
1961: .Fl paramfile
1962: and
1963: .Fl algorithm
1964: are mutually exclusive.
1965: .It Ar cipher
1966: Encrypt the private key with the supplied cipher.
1967: Any algorithm name accepted by
1968: .Fn EVP_get_cipherbyname
1969: is acceptable, such as
1970: .Cm des3 .
1971: .It Fl genparam
1972: Generate a set of parameters instead of a private key.
1973: If used this option must precede any
1974: .Fl algorithm ,
1975: .Fl paramfile ,
1976: or
1977: .Fl pkeyopt
1978: options.
1979: .It Fl out Ar file
1980: The output filename.
1981: If this argument is not specified then standard output is used.
1982: .It Fl outform Ar DER | PEM
1983: This specifies the output format, DER or PEM.
1984: .It Fl paramfile Ar file
1985: Some public key algorithms generate a private key based on a set of parameters.
1986: They can be supplied using this option.
1987: If this option is used the public key
1988: algorithm used is determined by the parameters.
1989: If used this option must precede any
1990: .Fl pkeyopt
1991: options.
1992: The options
1993: .Fl paramfile
1994: and
1995: .Fl algorithm
1996: are mutually exclusive.
1997: .It Fl pass Ar arg
1998: The output file password source.
1999: .It Fl pkeyopt Ar opt : Ns Ar value
2000: Set the public key algorithm option
2001: .Ar opt
2002: to
2003: .Ar value .
2004: The precise set of options supported
2005: depends on the public key algorithm used and its implementation.
2006: See
2007: .Sx GENPKEY KEY GENERATION OPTIONS
2008: below for more details.
2009: .It Fl text
2010: Print an (unencrypted) text representation of private and public keys and
2011: parameters along with the DER or PEM structure.
2012: .El
2013: .Sh GENPKEY KEY GENERATION OPTIONS
2014: The options supported by each algorithm
2015: and indeed each implementation of an algorithm can vary.
2016: The options for the
2017: .Nm OpenSSL
2018: implementations are detailed below.
2019: .Bl -tag -width Ds -offset indent
2020: .It rsa_keygen_bits : Ns Ar numbits
2021: (RSA)
2022: The number of bits in the generated key.
2023: If not specified 2048 is used.
2024: .It rsa_keygen_pubexp : Ns Ar value
2025: (RSA)
2026: The RSA public exponent value.
2027: This can be a large decimal or hexadecimal value if preceded by 0x.
2028: The default value is 65537.
2029: .It dsa_paramgen_bits : Ns Ar numbits
2030: (DSA)
2031: The number of bits in the generated parameters.
2032: If not specified 1024 is used.
2033: .It dh_paramgen_prime_len : Ns Ar numbits
2034: (DH)
2035: The number of bits in the prime parameter
2036: .Ar p .
2037: .It dh_paramgen_generator : Ns Ar value
2038: (DH)
2039: The value to use for the generator
2040: .Ar g .
2041: .It ec_paramgen_curve : Ns Ar curve
2042: (EC)
2043: The EC curve to use.
2044: .El
2045: .Sh GENPKEY EXAMPLES
2046: Generate an RSA private key using default parameters:
2047: .Bd -literal -offset indent
2048: $ openssl genpkey -algorithm RSA -out key.pem
2049: .Ed
2050: .Pp
2051: Encrypt and output a private key using 128-bit AES and the passphrase "hello":
2052: .Bd -literal -offset indent
2053: $ openssl genpkey -algorithm RSA -out key.pem \e
2054: -aes-128-cbc -pass pass:hello
2055: .Ed
2056: .Pp
2057: Generate a 2048-bit RSA key using 3 as the public exponent:
2058: .Bd -literal -offset indent
2059: $ openssl genpkey -algorithm RSA -out key.pem \e
2060: -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:3
2061: .Ed
2062: .Pp
2063: Generate 1024-bit DSA parameters:
2064: .Bd -literal -offset indent
2065: $ openssl genpkey -genparam -algorithm DSA \e
2066: -out dsap.pem -pkeyopt dsa_paramgen_bits:1024
2067: .Ed
2068: .Pp
2069: Generate a DSA key from parameters:
2070: .Bd -literal -offset indent
2071: $ openssl genpkey -paramfile dsap.pem -out dsakey.pem
2072: .Ed
2073: .Pp
2074: Generate 1024-bit DH parameters:
2075: .Bd -literal -offset indent
2076: $ openssl genpkey -genparam -algorithm DH \e
2077: -out dhp.pem -pkeyopt dh_paramgen_prime_len:1024
2078: .Ed
2079: .Pp
2080: Generate a DH key from parameters:
2081: .Bd -literal -offset indent
2082: $ openssl genpkey -paramfile dhp.pem -out dhkey.pem
2083: .Ed
2084: .\"
2085: .\" GENRSA
2086: .\"
2087: .Sh GENRSA
2088: .nr nS 1
2089: .Nm "openssl genrsa"
2090: .Bk -words
2091: .Op Fl 3 | f4
2092: .Oo
2093: .Fl aes128 | aes192 | aes256 |
2094: .Fl des | des3
2095: .Oc
2096: .Op Fl out Ar file
2097: .Op Fl passout Ar arg
2098: .Op Ar numbits
2099: .Ek
2100: .nr nS 0
2101: .Pp
2102: The
2103: .Nm genrsa
2104: command generates an RSA private key.
2105: .Pp
2106: The options are as follows:
2107: .Bl -tag -width Ds
2108: .It Fl 3 | f4
2109: The public exponent to use, either 3 or 65537.
2110: The default is 65537.
2111: .It Xo
2112: .Fl aes128 | aes192 | aes256 |
2113: .Fl des | des3
2114: .Xc
2115: These options encrypt the private key with the AES, DES,
2116: or the triple DES ciphers, respectively, before outputting it.
2117: If none of these options are specified, no encryption is used.
2118: If encryption is used, a pass phrase is prompted for,
2119: if it is not supplied via the
2120: .Fl passout
2121: option.
2122: .It Fl out Ar file
2123: The output
2124: .Ar file .
2125: If this argument is not specified, standard output is used.
2126: .It Fl passout Ar arg
2127: The output file password source.
2128: .It Ar numbits
2129: The size of the private key to generate in bits.
2130: This must be the last option specified.
2131: The default is 2048.
2132: .El
2133: .Sh GENRSA NOTES
2134: RSA private key generation essentially involves the generation of two prime
2135: numbers.
2136: When generating a private key, various symbols will be output to
2137: indicate the progress of the generation.
2138: A
2139: .Sq \&.
2140: represents each number which has passed an initial sieve test;
2141: .Sq +
2142: means a number has passed a single round of the Miller-Rabin primality test.
2143: A newline means that the number has passed all the prime tests
2144: .Pq the actual number depends on the key size .
2145: .Pp
2146: Because key generation is a random process,
2147: the time taken to generate a key may vary somewhat.
2148: .Sh GENRSA BUGS
2149: A quirk of the prime generation algorithm is that it cannot generate small
2150: primes.
2151: Therefore the number of bits should not be less that 64.
2152: For typical private keys this will not matter because for security reasons
2153: they will be much larger
2154: .Pq typically 2048 bits .
2155: .\"
2156: .\" NSEQ
2157: .\"
2158: .Sh NSEQ
2159: .Nm openssl nseq
2160: .Op Fl in Ar file
2161: .Op Fl out Ar file
2162: .Op Fl toseq
2163: .Pp
2164: The
2165: .Nm nseq
2166: command takes a file containing a Netscape certificate
2167: sequence and prints out the certificates contained in it or takes a
2168: file of certificates and converts it into a Netscape certificate
2169: sequence.
2170: .Pp
2171: The options are as follows:
2172: .Bl -tag -width Ds
2173: .It Fl in Ar file
2174: This specifies the input
2175: .Ar file
2176: to read, or standard input if this option is not specified.
2177: .It Fl out Ar file
2178: Specifies the output
2179: .Ar file ,
2180: or standard output by default.
2181: .It Fl toseq
2182: Normally, a Netscape certificate sequence will be input and the output
2183: is the certificates contained in it.
2184: With the
2185: .Fl toseq
2186: option the situation is reversed:
2187: a Netscape certificate sequence is created from a file of certificates.
2188: .El
2189: .Sh NSEQ EXAMPLES
2190: Output the certificates in a Netscape certificate sequence:
2191: .Bd -literal -offset indent
2192: $ openssl nseq -in nseq.pem -out certs.pem
2193: .Ed
2194: .Pp
2195: Create a Netscape certificate sequence:
2196: .Bd -literal -offset indent
2197: $ openssl nseq -in certs.pem -toseq -out nseq.pem
2198: .Ed
2199: .Sh NSEQ NOTES
2200: The PEM-encoded form uses the same headers and footers as a certificate:
2201: .Bd -unfilled -offset indent
2202: -----BEGIN CERTIFICATE-----
2203: -----END CERTIFICATE-----
2204: .Ed
2205: .Pp
2206: A Netscape certificate sequence is a Netscape specific form that can be sent
2207: to browsers as an alternative to the standard PKCS#7 format when several
2208: certificates are sent to the browser:
2209: for example during certificate enrollment.
2210: It is used by the Netscape certificate server, for example.
2211: .Sh NSEQ BUGS
2212: This program needs a few more options,
2213: like allowing DER or PEM input and output files
2214: and allowing multiple certificate files to be used.
2215: .\"
2216: .\" OCSP
2217: .\"
2218: .Sh OCSP
2219: .nr nS 1
2220: .Nm "openssl ocsp"
2221: .Bk -words
2222: .Op Fl CA Ar file
2223: .Op Fl CAfile Ar file
2224: .Op Fl CApath Ar directory
2225: .Op Fl cert Ar file
2226: .Op Fl dgst Ar alg
2227: .Oo
2228: .Fl host
2229: .Ar hostname : Ns Ar port
2230: .Oc
2231: .Op Fl index Ar indexfile
2232: .Op Fl issuer Ar file
2233: .Op Fl ndays Ar days
2234: .Op Fl nmin Ar minutes
2235: .Op Fl no_cert_checks
2236: .Op Fl no_cert_verify
2237: .Op Fl no_certs
2238: .Op Fl no_chain
2239: .Op Fl no_intern
2240: .Op Fl no_nonce
2241: .Op Fl no_signature_verify
2242: .Op Fl nonce
2243: .Op Fl noverify
2244: .Op Fl nrequest Ar number
2245: .Op Fl out Ar file
2246: .Op Fl path Ar path
2247: .Op Fl port Ar portnum
2248: .Op Fl req_text
2249: .Op Fl reqin Ar file
2250: .Op Fl reqout Ar file
2251: .Op Fl resp_key_id
2252: .Op Fl resp_no_certs
2253: .Op Fl resp_text
2254: .Op Fl respin Ar file
2255: .Op Fl respout Ar file
2256: .Op Fl rkey Ar file
2257: .Op Fl rother Ar file
2258: .Op Fl rsigner Ar file
2259: .Op Fl serial Ar number
2260: .Op Fl sign_other Ar file
2261: .Op Fl signer Ar file
2262: .Op Fl signkey Ar file
2263: .Op Fl status_age Ar age
2264: .Op Fl text
2265: .Op Fl trust_other
2266: .Op Fl url Ar responder_url
2267: .Op Fl VAfile Ar file
2268: .Op Fl validity_period Ar nsec
2269: .Op Fl verify_other Ar file
2270: .Ek
2271: .nr nS 0
2272: .Pp
2273: The Online Certificate Status Protocol
2274: .Pq OCSP
2275: enables applications to determine the
2276: .Pq revocation
2277: state of an identified certificate
2278: .Pq RFC 2560 .
2279: .Pp
2280: The
2281: .Nm ocsp
2282: command performs many common OCSP tasks.
2283: It can be used to print out requests and responses,
2284: create requests and send queries to an OCSP responder,
2285: and behave like a mini OCSP server itself.
2286: .Pp
2287: The options are as follows:
2288: .Bl -tag -width Ds
2289: .It Fl CAfile Ar file , Fl CApath Ar directory
2290: .Ar file
2291: or
2292: .Ar path
2293: containing trusted CA certificates.
2294: These are used to verify the signature on the OCSP response.
2295: .It Fl cert Ar file
2296: Add the certificate
2297: .Ar file
2298: to the request.
2299: The issuer certificate is taken from the previous
2300: .Fl issuer
2301: option, or an error occurs if no issuer certificate is specified.
2302: .It Fl dgst Ar alg
2303: Sets the digest algorithm to use for certificate identification
2304: in the OCSP request.
2305: By default SHA-1 is used.
2306: .It Xo
2307: .Fl host Ar hostname : Ns Ar port ,
2308: .Fl path Ar path
2309: .Xc
2310: If the
2311: .Fl host
2312: option is present, then the OCSP request is sent to the host
2313: .Ar hostname
2314: on port
2315: .Ar port .
2316: .Fl path
2317: specifies the HTTP path name to use, or
2318: .Sq /
2319: by default.
2320: .It Fl issuer Ar file
2321: This specifies the current issuer certificate.
2322: This option can be used multiple times.
2323: The certificate specified in
2324: .Ar file
2325: must be in PEM format.
2326: This option
2327: .Em must
2328: come before any
2329: .Fl cert
2330: options.
2331: .It Fl no_cert_checks
2332: Don't perform any additional checks on the OCSP response signer's certificate.
2333: That is, do not make any checks to see if the signer's certificate is
2334: authorised to provide the necessary status information:
2335: as a result this option should only be used for testing purposes.
2336: .It Fl no_cert_verify
2337: Don't verify the OCSP response signer's certificate at all.
2338: Since this option allows the OCSP response to be signed by any certificate,
2339: it should only be used for testing purposes.
2340: .It Fl no_certs
2341: Don't include any certificates in signed request.
2342: .It Fl no_chain
2343: Do not use certificates in the response as additional untrusted CA
2344: certificates.
2345: .It Fl no_intern
2346: Ignore certificates contained in the OCSP response
2347: when searching for the signer's certificate.
2348: With this option, the signer's certificate must be specified with either the
2349: .Fl verify_other
2350: or
2351: .Fl VAfile
2352: options.
2353: .It Fl no_signature_verify
2354: Don't check the signature on the OCSP response.
2355: Since this option tolerates invalid signatures on OCSP responses,
2356: it will normally only be used for testing purposes.
2357: .It Fl nonce , no_nonce
2358: Add an OCSP
2359: .Em nonce
2360: extension to a request or disable an OCSP
2361: .Em nonce
2362: addition.
2363: Normally, if an OCSP request is input using the
2364: .Fl respin
2365: option no
2366: .Em nonce
2367: is added:
2368: using the
2369: .Fl nonce
2370: option will force addition of a
2371: .Em nonce .
2372: If an OCSP request is being created (using the
2373: .Fl cert
2374: and
2375: .Fl serial
2376: options)
2377: a
2378: .Em nonce
2379: is automatically added; specifying
2380: .Fl no_nonce
2381: overrides this.
2382: .It Fl noverify
2383: Don't attempt to verify the OCSP response signature or the
2384: .Em nonce
2385: values.
2386: This option will normally only be used for debugging
2387: since it disables all verification of the responder's certificate.
2388: .It Fl out Ar file
2389: Specify output
2390: .Ar file ;
2391: default is standard output.
2392: .It Fl req_text , resp_text , text
2393: Print out the text form of the OCSP request, response, or both, respectively.
2394: .It Fl reqin Ar file , Fl respin Ar file
2395: Read an OCSP request or response file from
2396: .Ar file .
2397: These options are ignored
2398: if an OCSP request or response creation is implied by other options
2399: (for example with the
2400: .Fl serial , cert ,
2401: and
2402: .Fl host
2403: options).
2404: .It Fl reqout Ar file , Fl respout Ar file
2405: Write out the DER-encoded certificate request or response to
2406: .Ar file .
2407: .It Fl serial Ar num
2408: Same as the
2409: .Fl cert
2410: option except the certificate with serial number
2411: .Ar num
2412: is added to the request.
2413: The serial number is interpreted as a decimal integer unless preceded by
2414: .Sq 0x .
2415: Negative integers can also be specified by preceding the value with a
2416: .Sq -
2417: sign.
2418: .It Fl sign_other Ar file
2419: Additional certificates to include in the signed request.
2420: .It Fl signer Ar file , Fl signkey Ar file
2421: Sign the OCSP request using the certificate specified in the
2422: .Fl signer
2423: option and the private key specified by the
2424: .Fl signkey
2425: option.
2426: If the
2427: .Fl signkey
2428: option is not present, then the private key is read from the same file
2429: as the certificate.
2430: If neither option is specified, the OCSP request is not signed.
2431: .It Fl trust_other
2432: The certificates specified by the
2433: .Fl verify_other
2434: option should be explicitly trusted and no additional checks will be
2435: performed on them.
2436: This is useful when the complete responder certificate chain is not available
2437: or trusting a root CA is not appropriate.
2438: .It Fl url Ar responder_url
2439: Specify the responder URL.
2440: Both HTTP and HTTPS
2441: .Pq SSL/TLS
2442: URLs can be specified.
2443: .It Fl VAfile Ar file
2444: .Ar file
2445: containing explicitly trusted responder certificates.
2446: Equivalent to the
2447: .Fl verify_other
2448: and
2449: .Fl trust_other
2450: options.
2451: .It Fl validity_period Ar nsec , Fl status_age Ar age
2452: These options specify the range of times, in seconds, which will be tolerated
2453: in an OCSP response.
2454: Each certificate status response includes a
2455: .Em notBefore
2456: time and an optional
2457: .Em notAfter
2458: time.
2459: The current time should fall between these two values,
2460: but the interval between the two times may be only a few seconds.
2461: In practice the OCSP responder and clients' clocks may not be precisely
2462: synchronised and so such a check may fail.
2463: To avoid this the
2464: .Fl validity_period
2465: option can be used to specify an acceptable error range in seconds,
2466: the default value is 5 minutes.
2467: .Pp
2468: If the
2469: .Em notAfter
2470: time is omitted from a response, then this means that new status
2471: information is immediately available.
2472: In this case the age of the
2473: .Em notBefore
2474: field is checked to see it is not older than
2475: .Ar age
2476: seconds old.
2477: By default, this additional check is not performed.
2478: .It Fl verify_other Ar file
2479: .Ar file
2480: containing additional certificates to search when attempting to locate
2481: the OCSP response signing certificate.
2482: Some responders omit the actual signer's certificate from the response;
2483: this option can be used to supply the necessary certificate in such cases.
2484: .El
2485: .Sh OCSP SERVER OPTIONS
2486: .Bl -tag -width "XXXX"
2487: .It Fl CA Ar file
2488: CA certificate corresponding to the revocation information in
2489: .Ar indexfile .
2490: .It Fl index Ar indexfile
2491: .Ar indexfile
2492: is a text index file in
2493: .Nm ca
2494: format containing certificate revocation information.
2495: .Pp
2496: If the
2497: .Fl index
2498: option is specified, the
2499: .Nm ocsp
2500: utility is in
2501: .Em responder
2502: mode, otherwise it is in
2503: .Em client
2504: mode.
2505: The request(s) the responder processes can be either specified on
2506: the command line (using the
2507: .Fl issuer
2508: and
2509: .Fl serial
2510: options), supplied in a file (using the
2511: .Fl respin
2512: option) or via external OCSP clients (if
2513: .Ar port
2514: or
2515: .Ar url
2516: is specified).
2517: .Pp
2518: If the
2519: .Fl index
2520: option is present, then the
2521: .Fl CA
2522: and
2523: .Fl rsigner
2524: options must also be present.
2525: .It Fl nmin Ar minutes , Fl ndays Ar days
2526: Number of
2527: .Ar minutes
2528: or
2529: .Ar days
2530: when fresh revocation information is available: used in the
2531: .Ar nextUpdate
2532: field.
2533: If neither option is present, the
2534: .Em nextUpdate
2535: field is omitted, meaning fresh revocation information is immediately available.
2536: .It Fl nrequest Ar number
2537: The OCSP server will exit after receiving
2538: .Ar number
2539: requests, default unlimited.
2540: .It Fl port Ar portnum
2541: Port to listen for OCSP requests on.
2542: The port may also be specified using the
2543: .Fl url
2544: option.
2545: .It Fl resp_key_id
2546: Identify the signer certificate using the key ID;
2547: default is to use the subject name.
2548: .It Fl resp_no_certs
2549: Don't include any certificates in the OCSP response.
2550: .It Fl rkey Ar file
2551: The private key to sign OCSP responses with;
2552: if not present, the file specified in the
2553: .Fl rsigner
2554: option is used.
2555: .It Fl rother Ar file
2556: Additional certificates to include in the OCSP response.
2557: .It Fl rsigner Ar file
2558: The certificate to sign OCSP responses with.
2559: .El
2560: .Sh OCSP RESPONSE VERIFICATION
2561: OCSP Response follows the rules specified in RFC 2560.
2562: .Pp
2563: Initially the OCSP responder certificate is located and the signature on
2564: the OCSP request checked using the responder certificate's public key.
2565: .Pp
2566: Then a normal certificate verify is performed on the OCSP responder certificate
2567: building up a certificate chain in the process.
2568: The locations of the trusted certificates used to build the chain can be
2569: specified by the
2570: .Fl CAfile
2571: and
2572: .Fl CApath
2573: options or they will be looked for in the standard
2574: .Nm OpenSSL
2575: certificates
2576: directory.
2577: .Pp
2578: If the initial verify fails, the OCSP verify process halts with an
2579: error.
2580: .Pp
2581: Otherwise the issuing CA certificate in the request is compared to the OCSP
2582: responder certificate: if there is a match then the OCSP verify succeeds.
2583: .Pp
2584: Otherwise the OCSP responder certificate's CA is checked against the issuing
2585: CA certificate in the request.
2586: If there is a match and the OCSPSigning extended key usage is present
2587: in the OCSP responder certificate, then the OCSP verify succeeds.
2588: .Pp
2589: Otherwise the root CA of the OCSP responder's CA is checked to see if it
2590: is trusted for OCSP signing.
2591: If it is, the OCSP verify succeeds.
2592: .Pp
2593: If none of these checks is successful, the OCSP verify fails.
2594: .Pp
2595: What this effectively means is that if the OCSP responder certificate is
2596: authorised directly by the CA it is issuing revocation information about
2597: .Pq and it is correctly configured ,
2598: then verification will succeed.
2599: .Pp
2600: If the OCSP responder is a
2601: .Em global responder
2602: which can give details about multiple CAs and has its own separate
2603: certificate chain, then its root CA can be trusted for OCSP signing.
2604: For example:
2605: .Bd -literal -offset indent
2606: $ openssl x509 -in ocspCA.pem -addtrust OCSPSigning \e
2607: -out trustedCA.pem
2608: .Ed
2609: .Pp
2610: Alternatively, the responder certificate itself can be explicitly trusted
2611: with the
2612: .Fl VAfile
2613: option.
2614: .Sh OCSP NOTES
2615: As noted, most of the verify options are for testing or debugging purposes.
2616: Normally, only the
2617: .Fl CApath , CAfile
2618: and
2619: .Pq if the responder is a `global VA'
2620: .Fl VAfile
2621: options need to be used.
2622: .Pp
2623: The OCSP server is only useful for test and demonstration purposes:
2624: it is not really usable as a full OCSP responder.
2625: It contains only a very simple HTTP request handling and can only handle
2626: the POST form of OCSP queries.
2627: It also handles requests serially, meaning it cannot respond to
2628: new requests until it has processed the current one.
2629: The text index file format of revocation is also inefficient for large
2630: quantities of revocation data.
2631: .Pp
2632: It is possible to run the
2633: .Nm ocsp
2634: application in
2635: .Em responder
2636: mode via a CGI script using the
2637: .Fl respin
2638: and
2639: .Fl respout
2640: options.
2641: .Sh OCSP EXAMPLES
2642: Create an OCSP request and write it to a file:
2643: .Bd -literal -offset indent
2644: $ openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \e
2645: -reqout req.der
2646: .Ed
2647: .Pp
2648: Send a query to an OCSP responder with URL
2649: .Pa http://ocsp.myhost.com/ ,
2650: save the response to a file and print it out in text form:
2651: .Bd -literal -offset indent
2652: $ openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \e
2653: -url http://ocsp.myhost.com/ -resp_text -respout resp.der
2654: .Ed
2655: .Pp
2656: Read in an OCSP response and print out in text form:
2657: .Pp
2658: .Dl $ openssl ocsp -respin resp.der -text
2659: .Pp
2660: OCSP server on port 8888 using a standard
2661: .Nm ca
2662: configuration, and a separate responder certificate.
2663: All requests and responses are printed to a file:
2664: .Bd -literal -offset indent
2665: $ openssl ocsp -index demoCA/index.txt -port 8888 -rsigner \e
2666: rcert.pem -CA demoCA/cacert.pem -text -out log.txt
2667: .Ed
2668: .Pp
2669: As above, but exit after processing one request:
2670: .Bd -literal -offset indent
2671: $ openssl ocsp -index demoCA/index.txt -port 8888 -rsigner \e
2672: rcert.pem -CA demoCA/cacert.pem -nrequest 1
2673: .Ed
2674: .Pp
2675: Query status information using internally generated request:
2676: .Bd -literal -offset indent
2677: $ openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA \e
2678: demoCA/cacert.pem -issuer demoCA/cacert.pem -serial 1
2679: .Ed
2680: .Pp
2681: Query status information using request read from a file and write
2682: the response to a second file:
2683: .Bd -literal -offset indent
2684: $ openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA \e
2685: demoCA/cacert.pem -reqin req.der -respout resp.der
2686: .Ed
2687: .\"
2688: .\" PASSWD
2689: .\"
2690: .Sh PASSWD
2691: .nr nS 1
2692: .Nm "openssl passwd"
2693: .Op Fl 1 | apr1 | crypt
2694: .Op Fl in Ar file
2695: .Op Fl noverify
2696: .Op Fl quiet
2697: .Op Fl reverse
2698: .Op Fl salt Ar string
2699: .Op Fl stdin
2700: .Op Fl table
2701: .Op Ar password
2702: .nr nS 0
2703: .Pp
2704: The
2705: .Nm passwd
2706: command computes the hash of a password typed at run-time
2707: or the hash of each password in a list.
2708: The password list is taken from the named
2709: .Ar file
2710: for option
2711: .Fl in ,
2712: from stdin for option
2713: .Fl stdin ,
2714: or from the command line, or from the terminal otherwise.
2715: The
2716: .Ux
2717: standard algorithm
2718: .Em crypt
2719: and the MD5-based
2720: .Bx
2721: password algorithm
2722: .Em 1
2723: and its Apache variant
2724: .Em apr1
2725: are available.
2726: .Pp
2727: The options are as follows:
2728: .Bl -tag -width Ds
2729: .It Fl 1
2730: Use the MD5 based
2731: .Bx
2732: password algorithm
2733: .Em 1 .
2734: .It Fl apr1
2735: Use the
2736: .Em apr1
2737: algorithm
2738: .Pq Apache variant of the
2739: .Bx
2740: algorithm.
2741: .It Fl crypt
2742: Use the
2743: .Em crypt
2744: algorithm
2745: .Pq default .
2746: .It Fl in Ar file
2747: Read passwords from
2748: .Ar file .
2749: .It Fl noverify
2750: Don't verify when reading a password from the terminal.
2751: .It Fl quiet
2752: Don't output warnings when passwords given on the command line are truncated.
2753: .It Fl reverse
2754: Switch table columns.
2755: This only makes sense in conjunction with the
2756: .Fl table
2757: option.
2758: .It Fl salt Ar string
2759: Use the specified
2760: .Ar salt .
2761: When reading a password from the terminal, this implies
2762: .Fl noverify .
2763: .It Fl stdin
2764: Read passwords from
2765: .Em stdin .
2766: .It Fl table
2767: In the output list, prepend the cleartext password and a TAB character
2768: to each password hash.
2769: .El
2770: .Sh PASSWD EXAMPLES
2771: .Dl $ openssl passwd -crypt -salt xx password
2772: prints
2773: .Qq xxj31ZMTZzkVA .
2774: .Pp
2775: .Dl $ openssl passwd -1 -salt xxxxxxxx password
2776: prints
2777: .Qq $1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a. .
2778: .Pp
2779: .Dl $ openssl passwd -apr1 -salt xxxxxxxx password
2780: prints
2781: .Qq $apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0 .
2782: .\"
2783: .\" PKCS7
2784: .\"
2785: .Sh PKCS7
2786: .nr nS 1
2787: .Nm "openssl pkcs7"
2788: .Bk -words
2789: .Op Fl in Ar file
2790: .Op Fl inform Ar DER | PEM
2791: .Op Fl noout
2792: .Op Fl out Ar file
2793: .Op Fl outform Ar DER | PEM
2794: .Op Fl print_certs
2795: .Op Fl text
2796: .Ek
2797: .nr nS 0
2798: .Pp
2799: The
2800: .Nm pkcs7
2801: command processes PKCS#7 files in DER or PEM format.
2802: .Pp
2803: The options are as follows:
2804: .Bl -tag -width Ds
2805: .It Fl in Ar file
2806: This specifies the input
2807: .Ar file
2808: to read from, or standard input if this option is not specified.
2809: .It Fl inform Ar DER | PEM
2810: This specifies the input format.
2811: .Ar DER
2812: format is a DER-encoded PKCS#7 v1.5 structure.
2813: .Ar PEM
2814: .Pq the default
2815: is a base64-encoded version of the DER form with header and footer lines.
2816: .It Fl noout
2817: Don't output the encoded version of the PKCS#7 structure
2818: (or certificates if
2819: .Fl print_certs
2820: is set).
2821: .It Fl out Ar file
2822: Specifies the output
2823: .Ar file
2824: to write to, or standard output by default.
2825: .It Fl outform Ar DER | PEM
2826: This specifies the output format; the options have the same meaning as the
2827: .Fl inform
2828: option.
2829: .It Fl print_certs
2830: Prints out any certificates or CRLs contained in the file.
2831: They are preceded by their subject and issuer names in a one-line format.
2832: .It Fl text
2833: Prints out certificate details in full rather than just subject and
2834: issuer names.
2835: .El
2836: .Sh PKCS7 EXAMPLES
2837: Convert a PKCS#7 file from PEM to DER:
2838: .Pp
2839: .Dl $ openssl pkcs7 -in file.pem -outform DER -out file.der
2840: .Pp
2841: Output all certificates in a file:
2842: .Pp
2843: .Dl $ openssl pkcs7 -in file.pem -print_certs -out certs.pem
2844: .Sh PKCS7 NOTES
2845: The PEM PKCS#7 format uses the header and footer lines:
2846: .Bd -unfilled -offset indent
2847: -----BEGIN PKCS7-----
2848: -----END PKCS7-----
2849: .Ed
2850: .Pp
2851: For compatibility with some CAs it will also accept:
2852: .Bd -unfilled -offset indent
2853: -----BEGIN CERTIFICATE-----
2854: -----END CERTIFICATE-----
2855: .Ed
2856: .Sh PKCS7 RESTRICTIONS
2857: There is no option to print out all the fields of a PKCS#7 file.
2858: .Pp
2859: The PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC 2315.
2860: They cannot currently parse, for example, the new CMS as described in RFC 2630.
2861: .\"
2862: .\" PKCS8
2863: .\"
2864: .Sh PKCS8
2865: .nr nS 1
2866: .Nm "openssl pkcs8"
2867: .Bk -words
2868: .Op Fl embed
2869: .Op Fl in Ar file
2870: .Op Fl inform Ar DER | PEM
2871: .Op Fl nocrypt
2872: .Op Fl noiter
2873: .Op Fl nooct
2874: .Op Fl nsdb
2875: .Op Fl out Ar file
2876: .Op Fl outform Ar DER | PEM
2877: .Op Fl passin Ar arg
2878: .Op Fl passout Ar arg
2879: .Op Fl topk8
2880: .Op Fl v1 Ar alg
2881: .Op Fl v2 Ar alg
2882: .Ek
2883: .nr nS 0
2884: .Pp
2885: The
2886: .Nm pkcs8
2887: command processes private keys in PKCS#8 format.
2888: It can handle both unencrypted PKCS#8 PrivateKeyInfo format
2889: and EncryptedPrivateKeyInfo format with a variety of PKCS#5
2890: .Pq v1.5 and v2.0
2891: and PKCS#12 algorithms.
2892: .Pp
2893: The options are as follows:
2894: .Bl -tag -width Ds
2895: .It Fl embed
2896: This option generates DSA keys in a broken format.
2897: The DSA parameters are embedded inside the
2898: .Em PrivateKey
2899: structure.
2900: In this form the OCTET STRING contains an ASN1 SEQUENCE consisting of
2901: two structures:
2902: a SEQUENCE containing the parameters and an ASN1 INTEGER containing
2903: the private key.
2904: .It Fl in Ar file
2905: This specifies the input
2906: .Ar file
2907: to read a key from, or standard input if this option is not specified.
2908: If the key is encrypted, a pass phrase will be prompted for.
2909: .It Fl inform Ar DER | PEM
2910: This specifies the input format.
2911: If a PKCS#8 format key is expected on input,
2912: then either a
2913: DER- or PEM-encoded version of a PKCS#8 key will be expected.
2914: Otherwise the DER or PEM format of the traditional format private key is used.
2915: .It Fl nocrypt
2916: PKCS#8 keys generated or input are normally PKCS#8
2917: .Em EncryptedPrivateKeyInfo
2918: structures using an appropriate password-based encryption algorithm.
2919: With this option, an unencrypted
2920: .Em PrivateKeyInfo
2921: structure is expected or output.
2922: This option does not encrypt private keys at all and should only be used
2923: when absolutely necessary.
2924: Certain software such as some versions of Java code signing software use
2925: unencrypted private keys.
2926: .It Fl noiter
2927: Use an iteration count of 1.
2928: See the
2929: .Sx PKCS12
2930: section below for a detailed explanation of this option.
2931: .It Fl nooct
2932: This option generates RSA private keys in a broken format that some software
2933: uses.
2934: Specifically the private key should be enclosed in an OCTET STRING,
2935: but some software just includes the structure itself without the
2936: surrounding OCTET STRING.
2937: .It Fl nsdb
2938: This option generates DSA keys in a broken format compatible with Netscape
2939: private key databases.
2940: The
2941: .Em PrivateKey
2942: contains a SEQUENCE consisting of the public and private keys, respectively.
2943: .It Fl out Ar file
2944: This specifies the output
2945: .Ar file
2946: to write a key to, or standard output by default.
2947: If any encryption options are set, a pass phrase will be prompted for.
2948: The output filename should
2949: .Em not
2950: be the same as the input filename.
2951: .It Fl outform Ar DER | PEM
2952: This specifies the output format; the options have the same meaning as the
2953: .Fl inform
2954: option.
2955: .It Fl passin Ar arg
2956: The key password source.
2957: .It Fl passout Ar arg
2958: The output file password source.
2959: .It Fl topk8
2960: Normally, a PKCS#8 private key is expected on input and a traditional format
2961: private key will be written.
2962: With the
2963: .Fl topk8
2964: option the situation is reversed:
2965: it reads a traditional format private key and writes a PKCS#8 format key.
2966: .It Fl v1 Ar alg
2967: This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use.
2968: A complete list of possible algorithms is included below.
2969: .It Fl v2 Ar alg
2970: This option enables the use of PKCS#5 v2.0 algorithms.
2971: Normally, PKCS#8 private keys are encrypted with the password-based
2972: encryption algorithm called
2973: .Em pbeWithMD5AndDES-CBC ;
2974: this uses 56-bit DES encryption but it was the strongest encryption
2975: algorithm supported in PKCS#5 v1.5.
2976: Using the
2977: .Fl v2
2978: option PKCS#5 v2.0 algorithms are used which can use any
2979: encryption algorithm such as 168-bit triple DES or 128-bit RC2, however
2980: not many implementations support PKCS#5 v2.0 yet.
2981: If using private keys with
2982: .Nm OpenSSL
2983: then this doesn't matter.
2984: .Pp
2985: The
2986: .Ar alg
2987: argument is the encryption algorithm to use; valid values include
2988: .Ar des , des3 ,
2989: and
2990: .Ar rc2 .
2991: It is recommended that
2992: .Ar des3
2993: is used.
2994: .El
2995: .Sh PKCS8 NOTES
2996: The encrypted form of a PEM-encoded PKCS#8 file uses the following
2997: headers and footers:
2998: .Bd -unfilled -offset indent
2999: -----BEGIN ENCRYPTED PRIVATE KEY-----
3000: -----END ENCRYPTED PRIVATE KEY-----
3001: .Ed
3002: .Pp
3003: The unencrypted form uses:
3004: .Bd -unfilled -offset indent
3005: -----BEGIN PRIVATE KEY-----
3006: -----END PRIVATE KEY-----
3007: .Ed
3008: .Pp
3009: Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
3010: counts are more secure than those encrypted using the traditional
3011: .Nm SSLeay
3012: compatible formats.
3013: So if additional security is considered important, the keys should be converted.
3014: .Pp
3015: The default encryption is only 56 bits because this is the encryption
3016: that most current implementations of PKCS#8 support.
3017: .Pp
3018: Some software may use PKCS#12 password-based encryption algorithms
3019: with PKCS#8 format private keys: these are handled automatically
3020: but there is no option to produce them.
3021: .Pp
3022: It is possible to write out
3023: DER-encoded encrypted private keys in PKCS#8 format because the encryption
3024: details are included at an ASN1
3025: level whereas the traditional format includes them at a PEM level.
3026: .Sh PKCS#5 V1.5 AND PKCS#12 ALGORITHMS
3027: Various algorithms can be used with the
3028: .Fl v1
3029: command line option, including PKCS#5 v1.5 and PKCS#12.
3030: These are described in more detail below.
3031: .Pp
3032: .Bl -tag -width "XXXX" -compact
1.29 bcook 3033: .It Ar PBE-MD5-DES
1.1 jsing 3034: These algorithms were included in the original PKCS#5 v1.5 specification.
3035: They only offer 56 bits of protection since they both use DES.
3036: .Pp
1.29 bcook 3037: .It Ar PBE-SHA1-RC2-64 | PBE-MD5-RC2-64 | PBE-SHA1-DES
1.1 jsing 3038: These algorithms are not mentioned in the original PKCS#5 v1.5 specification
3039: but they use the same key derivation algorithm and are supported by some
3040: software.
3041: They are mentioned in PKCS#5 v2.0.
3042: They use either 64-bit RC2 or 56-bit DES.
3043: .Pp
3044: .It Ar PBE-SHA1-RC4-128 | PBE-SHA1-RC4-40 | PBE-SHA1-3DES | PBE-SHA1-2DES
3045: .It Ar PBE-SHA1-RC2-128 | PBE-SHA1-RC2-40
3046: These algorithms use the PKCS#12 password-based encryption algorithm and
3047: allow strong encryption algorithms like triple DES or 128-bit RC2 to be used.
3048: .El
3049: .Sh PKCS8 EXAMPLES
3050: Convert a private key from traditional to PKCS#5 v2.0 format using triple DES:
3051: .Pp
3052: .Dl "$ openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem"
3053: .Pp
3054: Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
3055: .Pq DES :
3056: .Pp
3057: .Dl $ openssl pkcs8 -in key.pem -topk8 -out enckey.pem
3058: .Pp
3059: Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
3060: .Pq 3DES :
3061: .Bd -literal -offset indent
3062: $ openssl pkcs8 -in key.pem -topk8 -out enckey.pem \e
3063: -v1 PBE-SHA1-3DES
3064: .Ed
3065: .Pp
3066: Read a DER-unencrypted PKCS#8 format private key:
3067: .Pp
3068: .Dl "$ openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem"
3069: .Pp
3070: Convert a private key from any PKCS#8 format to traditional format:
3071: .Pp
3072: .Dl $ openssl pkcs8 -in pk8.pem -out key.pem
3073: .Sh PKCS8 STANDARDS
3074: Test vectors from this PKCS#5 v2.0 implementation were posted to the
3075: pkcs-tng mailing list using triple DES, DES and RC2 with high iteration counts;
3076: several people confirmed that they could decrypt the private
3077: keys produced and therefore it can be assumed that the PKCS#5 v2.0
3078: implementation is reasonably accurate at least as far as these
3079: algorithms are concerned.
3080: .Pp
3081: The format of PKCS#8 DSA
3082: .Pq and other
3083: private keys is not well documented:
3084: it is hidden away in PKCS#11 v2.01, section 11.9;
3085: .Nm OpenSSL Ns Li 's
3086: default DSA PKCS#8 private key format complies with this standard.
3087: .Sh PKCS8 BUGS
3088: There should be an option that prints out the encryption algorithm
3089: in use and other details such as the iteration count.
3090: .Pp
3091: PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private
3092: key format; for
3093: .Nm OpenSSL
3094: compatibility, several of the utilities use the old format at present.
3095: .\"
3096: .\" PKCS12
3097: .\"
3098: .Sh PKCS12
3099: .nr nS 1
3100: .Nm "openssl pkcs12"
3101: .Bk -words
3102: .Oo
3103: .Fl aes128 | aes192 | aes256 |
3104: .Fl des | des3
3105: .Oc
3106: .Op Fl cacerts
3107: .Op Fl CAfile Ar file
3108: .Op Fl caname Ar name
3109: .Op Fl CApath Ar directory
3110: .Op Fl certfile Ar file
3111: .Op Fl certpbe Ar alg
3112: .Op Fl chain
3113: .Op Fl clcerts
3114: .Op Fl CSP Ar name
3115: .Op Fl descert
3116: .Op Fl export
3117: .Op Fl in Ar file
3118: .Op Fl info
3119: .Op Fl inkey Ar file
3120: .Op Fl keyex
3121: .Op Fl keypbe Ar alg
3122: .Op Fl keysig
3123: .Op Fl macalg Ar alg
3124: .Op Fl maciter
3125: .Op Fl name Ar name
3126: .Op Fl nocerts
3127: .Op Fl nodes
3128: .Op Fl noiter
3129: .Op Fl nokeys
3130: .Op Fl nomac
3131: .Op Fl nomaciter
3132: .Op Fl nomacver
3133: .Op Fl noout
3134: .Op Fl out Ar file
3135: .Op Fl passin Ar arg
3136: .Op Fl passout Ar arg
3137: .Op Fl twopass
3138: .Ek
3139: .nr nS 0
3140: .Pp
3141: The
3142: .Nm pkcs12
3143: command allows PKCS#12 files
3144: .Pq sometimes referred to as PFX files
3145: to be created and parsed.
3146: PKCS#12 files are used by several programs including Netscape, MSIE
3147: and MS Outlook.
3148: .Pp
3149: There are a lot of options; the meaning of some depends on whether a
3150: PKCS#12 file is being created or parsed.
3151: By default, a PKCS#12 file is parsed;
3152: a PKCS#12 file can be created by using the
3153: .Fl export
3154: option
3155: .Pq see below .
3156: .Sh PKCS12 PARSING OPTIONS
3157: .Bl -tag -width "XXXX"
3158: .It Xo
3159: .Fl aes128 | aes192 | aes256 |
3160: .Fl des | des3
3161: .Xc
3162: Use AES, DES, or triple DES, respectively,
3163: to encrypt private keys before outputting.
3164: The default is triple DES.
3165: .It Fl cacerts
3166: Only output CA certificates
3167: .Pq not client certificates .
3168: .It Fl clcerts
3169: Only output client certificates
3170: .Pq not CA certificates .
3171: .It Fl in Ar file
3172: This specifies the
3173: .Ar file
3174: of the PKCS#12 file to be parsed.
3175: Standard input is used by default.
3176: .It Fl info
3177: Output additional information about the PKCS#12 file structure,
3178: algorithms used, and iteration counts.
3179: .It Fl nocerts
3180: No certificates at all will be output.
3181: .It Fl nodes
3182: Don't encrypt the private keys at all.
3183: .It Fl nokeys
3184: No private keys will be output.
3185: .It Fl nomacver
3186: Don't attempt to verify the integrity MAC before reading the file.
3187: .It Fl noout
3188: This option inhibits output of the keys and certificates to the output file
3189: version of the PKCS#12 file.
3190: .It Fl out Ar file
3191: The
3192: .Ar file
3193: to write certificates and private keys to, standard output by default.
3194: They are all written in PEM format.
3195: .It Fl passin Ar arg
3196: The key password source.
3197: .It Fl passout Ar arg
3198: The output file password source.
3199: .It Fl twopass
3200: Prompt for separate integrity and encryption passwords: most software
3201: always assumes these are the same so this option will render such
3202: PKCS#12 files unreadable.
3203: .El
3204: .Sh PKCS12 FILE CREATION OPTIONS
3205: .Bl -tag -width "XXXX"
3206: .It Fl CAfile Ar file
3207: CA storage as a file.
3208: .It Fl CApath Ar directory
3209: CA storage as a directory.
3210: This directory must be a standard certificate directory:
3211: that is, a hash of each subject name (using
3212: .Cm x509 -hash )
3213: should be linked to each certificate.
3214: .It Fl caname Ar name
3215: This specifies the
3216: .Qq friendly name
3217: for other certificates.
3218: This option may be used multiple times to specify names for all certificates
3219: in the order they appear.
3220: Netscape ignores friendly names on other certificates,
3221: whereas MSIE displays them.
3222: .It Fl certfile Ar file
3223: A file to read additional certificates from.
3224: .It Fl certpbe Ar alg , Fl keypbe Ar alg
3225: These options allow the algorithm used to encrypt the private key and
3226: certificates to be selected.
3227: Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name can be used (see the
3228: .Sx PKCS12 NOTES
3229: section for more information).
3230: If a cipher name
3231: (as output by the
3232: .Cm list-cipher-algorithms
3233: command) is specified then it
3234: is used with PKCS#5 v2.0.
3235: For interoperability reasons it is advisable to only use PKCS#12 algorithms.
3236: .It Fl chain
3237: If this option is present, an attempt is made to include the entire
3238: certificate chain of the user certificate.
3239: The standard CA store is used for this search.
3240: If the search fails, it is considered a fatal error.
3241: .It Fl CSP Ar name
3242: Write
3243: .Ar name
3244: as a Microsoft CSP name.
3245: .It Fl descert
3246: Encrypt the certificate using triple DES; this may render the PKCS#12
3247: file unreadable by some
3248: .Qq export grade
3249: software.
3250: By default, the private key is encrypted using triple DES and the
3251: certificate using 40-bit RC2.
3252: .It Fl export
3253: This option specifies that a PKCS#12 file will be created rather than
3254: parsed.
3255: .It Fl in Ar file
3256: The
3257: .Ar file
3258: to read certificates and private keys from, standard input by default.
3259: They must all be in PEM format.
3260: The order doesn't matter but one private key and its corresponding
3261: certificate should be present.
3262: If additional certificates are present, they will also be included
3263: in the PKCS#12 file.
3264: .It Fl inkey Ar file
3265: File to read private key from.
3266: If not present, a private key must be present in the input file.
3267: .It Fl keyex | keysig
3268: Specifies that the private key is to be used for key exchange or just signing.
3269: This option is only interpreted by MSIE and similar MS software.
3270: Normally,
3271: .Qq export grade
3272: software will only allow 512-bit RSA keys to be
3273: used for encryption purposes, but arbitrary length keys for signing.
3274: The
3275: .Fl keysig
3276: option marks the key for signing only.
3277: Signing only keys can be used for S/MIME signing, authenticode
3278: .Pq ActiveX control signing
3279: and SSL client authentication;
3280: however, due to a bug only MSIE 5.0 and later support
3281: the use of signing only keys for SSL client authentication.
3282: .It Fl macalg Ar alg
3283: Specify the MAC digest algorithm.
3284: If not included then SHA1 is used.
3285: .It Fl maciter
3286: This option is included for compatibility with previous versions; it used
3287: to be needed to use MAC iterations counts but they are now used by default.
3288: .It Fl name Ar name
3289: This specifies the
3290: .Qq friendly name
3291: for the certificate and private key.
3292: This name is typically displayed in list boxes by software importing the file.
3293: .It Fl nomac
3294: Don't attempt to provide the MAC integrity.
3295: .It Fl nomaciter , noiter
3296: These options affect the iteration counts on the MAC and key algorithms.
3297: Unless you wish to produce files compatible with MSIE 4.0, you should leave
3298: these options alone.
3299: .Pp
3300: To discourage attacks by using large dictionaries of common passwords,
3301: the algorithm that derives keys from passwords can have an iteration count
3302: applied to it: this causes a certain part of the algorithm to be repeated
3303: and slows it down.
3304: The MAC is used to check the file integrity but since it will normally
3305: have the same password as the keys and certificates it could also be attacked.
3306: By default, both MAC and encryption iteration counts are set to 2048;
3307: using these options the MAC and encryption iteration counts can be set to 1.
3308: Since this reduces the file security you should not use these options
3309: unless you really have to.
3310: Most software supports both MAC and key iteration counts.
3311: MSIE 4.0 doesn't support MAC iteration counts, so it needs the
3312: .Fl nomaciter
3313: option.
3314: .It Fl out Ar file
3315: This specifies
3316: .Ar file
3317: to write the PKCS#12 file to.
3318: Standard output is used by default.
3319: .It Fl passin Ar arg
3320: The key password source.
3321: .It Fl passout Ar arg
3322: The output file password source.
3323: .El
3324: .Sh PKCS12 NOTES
3325: Although there are a large number of options,
3326: most of them are very rarely used.
3327: For PKCS#12 file parsing, only
3328: .Fl in
3329: and
3330: .Fl out
3331: need to be used for PKCS#12 file creation.
3332: .Fl export
3333: and
3334: .Fl name
3335: are also used.
3336: .Pp
3337: If none of the
3338: .Fl clcerts , cacerts ,
3339: or
3340: .Fl nocerts
3341: options are present, then all certificates will be output in the order
3342: they appear in the input PKCS#12 files.
3343: There is no guarantee that the first certificate present is
3344: the one corresponding to the private key.
3345: Certain software which requires a private key and certificate and assumes
3346: the first certificate in the file is the one corresponding to the private key:
3347: this may not always be the case.
3348: Using the
3349: .Fl clcerts
3350: option will solve this problem by only outputting the certificate
3351: corresponding to the private key.
3352: If the CA certificates are required, they can be output to a separate
3353: file using the
3354: .Fl nokeys
3355: and
3356: .Fl cacerts
3357: options to just output CA certificates.
3358: .Pp
3359: The
3360: .Fl keypbe
3361: and
3362: .Fl certpbe
3363: algorithms allow the precise encryption algorithms for private keys
3364: and certificates to be specified.
3365: Normally, the defaults are fine but occasionally software can't handle
3366: triple DES encrypted private keys;
3367: then the option
3368: .Fl keypbe Ar PBE-SHA1-RC2-40
3369: can be used to reduce the private key encryption to 40-bit RC2.
3370: A complete description of all algorithms is contained in the
3371: .Sx PKCS8
3372: section above.
3373: .Sh PKCS12 EXAMPLES
3374: Parse a PKCS#12 file and output it to a file:
3375: .Pp
3376: .Dl $ openssl pkcs12 -in file.p12 -out file.pem
3377: .Pp
3378: Output only client certificates to a file:
3379: .Pp
3380: .Dl $ openssl pkcs12 -in file.p12 -clcerts -out file.pem
3381: .Pp
3382: Don't encrypt the private key:
3383: .Pp
3384: .Dl $ openssl pkcs12 -in file.p12 -out file.pem -nodes
3385: .Pp
3386: Print some info about a PKCS#12 file:
3387: .Pp
3388: .Dl $ openssl pkcs12 -in file.p12 -info -noout
3389: .Pp
3390: Create a PKCS#12 file:
3391: .Bd -literal -offset indent
3392: $ openssl pkcs12 -export -in file.pem -out file.p12 \e
3393: -name "My Certificate"
3394: .Ed
3395: .Pp
3396: Include some extra certificates:
3397: .Bd -literal -offset indent
3398: $ openssl pkcs12 -export -in file.pem -out file.p12 \e
3399: -name "My Certificate" -certfile othercerts.pem
3400: .Ed
3401: .Sh PKCS12 BUGS
3402: Some would argue that the PKCS#12 standard is one big bug :\-)
3403: .Pp
3404: Versions of
3405: .Nm OpenSSL
3406: before 0.9.6a had a bug in the PKCS#12 key generation routines.
3407: Under rare circumstances this could produce a PKCS#12 file encrypted
3408: with an invalid key.
3409: As a result some PKCS#12 files which triggered this bug
3410: from other implementations
3411: .Pq MSIE or Netscape
3412: could not be decrypted by
3413: .Nm OpenSSL
3414: and similarly
3415: .Nm OpenSSL
3416: could produce PKCS#12 files which could not be decrypted by other
3417: implementations.
3418: The chances of producing such a file are relatively small: less than 1 in 256.
3419: .Pp
3420: A side effect of fixing this bug is that any old invalidly encrypted PKCS#12
3421: files can no longer be parsed by the fixed version.
3422: Under such circumstances the
3423: .Nm pkcs12
3424: utility will report that the MAC is OK but fail with a decryption
3425: error when extracting private keys.
3426: .Pp
3427: This problem can be resolved by extracting the private keys and certificates
3428: from the PKCS#12 file using an older version of
3429: .Nm OpenSSL
3430: and recreating
3431: the PKCS#12 file from the keys and certificates using a newer version of
3432: .Nm OpenSSL .
3433: For example:
3434: .Bd -literal -offset indent
3435: $ old-openssl -in bad.p12 -out keycerts.pem
3436: $ openssl -in keycerts.pem -export -name "My PKCS#12 file" \e
3437: -out fixed.p12
3438: .Ed
3439: .\"
3440: .\" PKEY
3441: .\"
3442: .Sh PKEY
3443: .nr nS 1
3444: .Nm "openssl pkey"
3445: .Bk -words
3446: .Op Ar cipher
3447: .Op Fl in Ar file
3448: .Op Fl inform Ar DER | PEM
3449: .Op Fl noout
3450: .Op Fl out Ar file
3451: .Op Fl outform Ar DER | PEM
3452: .Op Fl passin Ar arg
3453: .Op Fl passout Ar arg
3454: .Op Fl pubin
3455: .Op Fl pubout
3456: .Op Fl text
3457: .Op Fl text_pub
3458: .Ek
3459: .nr nS 0
3460: .Pp
3461: The
3462: .Nm pkey
3463: command processes public or private keys.
3464: They can be converted between various forms
3465: and their components printed out.
3466: .Pp
3467: The options are as follows:
3468: .Bl -tag -width Ds
3469: .It Ar cipher
3470: These options encrypt the private key with the supplied cipher.
3471: Any algorithm name accepted by
3472: .Fn EVP_get_cipherbyname
3473: is acceptable, such as
3474: .Cm des3 .
3475: .It Fl in Ar file
3476: This specifies the input filename to read a key from,
3477: or standard input if this option is not specified.
3478: If the key is encrypted a pass phrase will be prompted for.
3479: .It Fl inform Ar DER | PEM
3480: This specifies the input format, DER or PEM.
3481: .It Fl noout
3482: Do not output the encoded version of the key.
3483: .It Fl out Ar file
3484: This specifies the output filename to write a key to,
3485: or standard output if this option is not specified.
3486: If any encryption options are set then a pass phrase
3487: will be prompted for.
3488: The output filename should
3489: .Em not
3490: be the same as the input filename.
3491: .It Fl outform Ar DER | PEM
3492: This specifies the output format;
3493: the options have the same meaning as the
3494: .Fl inform
3495: option.
3496: .It Fl passin Ar arg
3497: The key password source.
3498: .It Fl passout Ar arg
3499: The output file password source.
3500: .It Fl pubin
3501: By default a private key is read from the input file:
3502: with this option a public key is read instead.
3503: .It Fl pubout
3504: By default a private key is output:
3505: with this option a public key will be output instead.
3506: This option is automatically set if
3507: the input is a public key.
3508: .It Fl text
3509: Print out the various public or private key components in
3510: plain text in addition to the encoded version.
3511: .It Fl text_pub
3512: Print out only public key components
3513: even if a private key is being processed.
3514: .El
3515: .Sh PKEY EXAMPLES
3516: To remove the pass phrase on an RSA private key:
3517: .Bd -literal -offset indent
3518: $ openssl pkey -in key.pem -out keyout.pem
3519: .Ed
3520: .Pp
3521: To encrypt a private key using triple DES:
3522: .Bd -literal -offset indent
3523: $ openssl pkey -in key.pem -des3 -out keyout.pem
3524: .Ed
3525: .Pp
3526: To convert a private key from PEM to DER format:
3527: .Bd -literal -offset indent
3528: $ openssl pkey -in key.pem -outform DER -out keyout.der
3529: .Ed
3530: .Pp
3531: To print the components of a private key to standard output:
3532: .Bd -literal -offset indent
3533: $ openssl pkey -in key.pem -text -noout
3534: .Ed
3535: .Pp
3536: To print the public components of a private key to standard output:
3537: .Bd -literal -offset indent
3538: $ openssl pkey -in key.pem -text_pub -noout
3539: .Ed
3540: .Pp
3541: To just output the public part of a private key:
3542: .Bd -literal -offset indent
3543: $ openssl pkey -in key.pem -pubout -out pubkey.pem
3544: .Ed
3545: .\"
3546: .\" PKEYPARAM
3547: .\"
3548: .Sh PKEYPARAM
3549: .Cm openssl pkeyparam
3550: .Op Fl in Ar file
3551: .Op Fl noout
3552: .Op Fl out Ar file
3553: .Op Fl text
3554: .Pp
3555: The
3556: .Nm pkey
3557: command processes public or private keys.
3558: They can be converted between various forms and their components printed out.
3559: .Pp
3560: The options are as follows:
3561: .Bl -tag -width Ds
3562: .It Fl in Ar file
3563: This specifies the input filename to read parameters from,
3564: or standard input if this option is not specified.
3565: .It Fl noout
3566: Do not output the encoded version of the parameters.
3567: .It Fl out Ar file
3568: This specifies the output filename to write parameters to,
3569: or standard output if this option is not specified.
3570: .It Fl text
3571: Prints out the parameters in plain text in addition to the encoded version.
3572: .El
3573: .Sh PKEYPARAM EXAMPLES
3574: Print out text version of parameters:
3575: .Bd -literal -offset indent
3576: $ openssl pkeyparam -in param.pem -text
3577: .Ed
3578: .Sh PKEYPARAM NOTES
3579: There are no
3580: .Fl inform
3581: or
3582: .Fl outform
3583: options for this command because only PEM format is supported
3584: because the key type is determined by the PEM headers.
3585: .\"
3586: .\" PKEYUTL
3587: .\"
3588: .Sh PKEYUTL
3589: .nr nS 1
3590: .Nm "openssl pkeyutl"
3591: .Bk -words
3592: .Op Fl asn1parse
3593: .Op Fl certin
3594: .Op Fl decrypt
3595: .Op Fl derive
3596: .Op Fl encrypt
3597: .Op Fl hexdump
3598: .Op Fl in Ar file
3599: .Op Fl inkey Ar file
1.22 bcook 3600: .Op Fl keyform Ar DER | PEM
1.1 jsing 3601: .Op Fl out Ar file
3602: .Op Fl passin Ar arg
1.22 bcook 3603: .Op Fl peerform Ar DER | PEM
1.1 jsing 3604: .Op Fl peerkey Ar file
3605: .Op Fl pkeyopt Ar opt : Ns Ar value
3606: .Op Fl pubin
3607: .Op Fl rev
3608: .Op Fl sigfile Ar file
3609: .Op Fl sign
3610: .Op Fl verify
3611: .Op Fl verifyrecover
3612: .Ek
3613: .nr nS 0
3614: .Pp
3615: The
3616: .Nm pkeyutl
3617: command can be used to perform public key operations using
3618: any supported algorithm.
3619: .Pp
3620: The options are as follows:
3621: .Bl -tag -width Ds
3622: .It Fl asn1parse
3623: ASN1parse the output data.
3624: This is useful when combined with the
3625: .Fl verifyrecover
3626: option when an ASN1 structure is signed.
3627: .It Fl certin
3628: The input is a certificate containing a public key.
3629: .It Fl decrypt
3630: Decrypt the input data using a private key.
3631: .It Fl derive
3632: Derive a shared secret using the peer key.
3633: .It Fl encrypt
3634: Encrypt the input data using a public key.
3635: .It Fl hexdump
3636: Hex dump the output data.
3637: .It Fl in Ar file
3638: Specify the input filename to read data from,
3639: or standard input if this option is not specified.
3640: .It Fl inkey Ar file
3641: The input key file.
3642: By default it should be a private key.
1.22 bcook 3643: .It Fl keyform Ar DER | PEM
3644: The key format DER or PEM.
1.1 jsing 3645: .It Fl out Ar file
3646: Specify the output filename to write to,
3647: or standard output by default.
3648: .It Fl passin Ar arg
3649: The key password source.
1.22 bcook 3650: .It Fl peerform Ar DER | PEM
3651: The peer key format DER or PEM.
1.1 jsing 3652: .It Fl peerkey Ar file
3653: The peer key file, used by key derivation (agreement) operations.
3654: .It Fl pkeyopt Ar opt : Ns Ar value
3655: Public key options.
3656: .It Fl pubin
3657: The input file is a public key.
3658: .It Fl rev
3659: Reverse the order of the input buffer.
3660: This is useful for some libraries (such as CryptoAPI)
3661: which represent the buffer in little endian format.
3662: .It Fl sigfile Ar file
3663: Signature file (verify operation only).
3664: .It Fl sign
3665: Sign the input data and output the signed result.
3666: This requires a private key.
3667: .It Fl verify
3668: Verify the input data against the signature file and indicate if the
3669: verification succeeded or failed.
3670: .It Fl verifyrecover
3671: Verify the input data and output the recovered data.
3672: .El
3673: .Sh PKEYUTL NOTES
3674: The operations and options supported vary according to the key algorithm
3675: and its implementation.
3676: The
3677: .Nm OpenSSL
3678: operations and options are indicated below.
3679: .Pp
3680: Unless otherwise mentioned all algorithms support the
3681: .Ar digest : Ns Ar alg
3682: option which specifies the digest in use
3683: for sign, verify, and verifyrecover operations.
3684: The value
3685: .Ar alg
3686: should represent a digest name as used in the
3687: .Fn EVP_get_digestbyname
3688: function, for example
3689: .Cm sha1 .
3690: .Ss RSA algorithm
3691: The RSA algorithm supports the
3692: encrypt, decrypt, sign, verify, and verifyrecover operations in general.
3693: Some padding modes only support some of these
3694: operations however.
3695: .Bl -tag -width Ds
3696: .It rsa_padding_mode : Ns Ar mode
3697: This sets the RSA padding mode.
3698: Acceptable values for
3699: .Ar mode
3700: are
3701: .Cm pkcs1
3702: for PKCS#1 padding;
3703: .Cm none
3704: for no padding;
3705: .Cm oaep
3706: for OAEP mode;
3707: .Cm x931
3708: for X9.31 mode;
3709: and
3710: .Cm pss
3711: for PSS.
3712: .Pp
3713: In PKCS#1 padding if the message digest is not set then the supplied data is
3714: signed or verified directly instead of using a DigestInfo structure.
3715: If a digest is set then a DigestInfo
3716: structure is used and its length
3717: must correspond to the digest type.
3718: .Pp
3719: For oeap mode only encryption and decryption is supported.
3720: .Pp
3721: For x931 if the digest type is set it is used to format the block data;
3722: otherwise the first byte is used to specify the X9.31 digest ID.
3723: Sign, verify, and verifyrecover can be performed in this mode.
3724: .Pp
3725: For pss mode only sign and verify are supported and the digest type must be
3726: specified.
3727: .It rsa_pss_saltlen : Ns Ar len
3728: For pss
3729: mode only this option specifies the salt length.
3730: Two special values are supported:
3731: -1 sets the salt length to the digest length.
3732: When signing -2 sets the salt length to the maximum permissible value.
3733: When verifying -2 causes the salt length to be automatically determined
3734: based on the PSS block structure.
3735: .El
3736: .Ss DSA algorithm
3737: The DSA algorithm supports the sign and verify operations.
3738: Currently there are no additional options other than
3739: .Ar digest .
3740: Only the SHA1 digest can be used and this digest is assumed by default.
3741: .Ss DH algorithm
3742: The DH algorithm supports the derive operation
3743: and no additional options.
3744: .Ss EC algorithm
3745: The EC algorithm supports the sign, verify, and derive operations.
3746: The sign and verify operations use ECDSA and derive uses ECDH.
3747: Currently there are no additional options other than
3748: .Ar digest .
3749: Only the SHA1 digest can be used and this digest is assumed by default.
3750: .Sh PKEYUTL EXAMPLES
3751: Sign some data using a private key:
3752: .Bd -literal -offset indent
3753: $ openssl pkeyutl -sign -in file -inkey key.pem -out sig
3754: .Ed
3755: .Pp
3756: Recover the signed data (e.g. if an RSA key is used):
3757: .Bd -literal -offset indent
3758: $ openssl pkeyutl -verifyrecover -in sig -inkey key.pem
3759: .Ed
3760: .Pp
3761: Verify the signature (e.g. a DSA key):
3762: .Bd -literal -offset indent
3763: $ openssl pkeyutl -verify -in file -sigfile sig \e
3764: -inkey key.pem
3765: .Ed
3766: .Pp
3767: Sign data using a message digest value (this is currently only valid for RSA):
3768: .Bd -literal -offset indent
3769: $ openssl pkeyutl -sign -in file -inkey key.pem \e
3770: -out sig -pkeyopt digest:sha256
3771: .Ed
3772: .Pp
3773: Derive a shared secret value:
3774: .Bd -literal -offset indent
3775: $ openssl pkeyutl -derive -inkey key.pem \e
3776: -peerkey pubkey.pem -out secret
3777: .Ed
3778: .\"
3779: .\" PRIME
3780: .\"
3781: .Sh PRIME
3782: .Cm openssl prime
3783: .Op Fl bits Ar n
3784: .Op Fl checks Ar n
3785: .Op Fl generate
3786: .Op Fl hex
3787: .Op Fl safe
3788: .Ar p
3789: .Pp
3790: The
3791: .Nm prime
3792: command is used to generate prime numbers,
3793: or to check numbers for primality.
3794: Results are probabilistic:
3795: they have an exceedingly high likelihood of being correct,
3796: but are not guaranteed.
3797: .Pp
3798: The options are as follows:
3799: .Bl -tag -width Ds
3800: .It Fl bits Ar n
3801: Specify the number of bits in the generated prime number.
3802: Must be used in conjunction with
3803: .Fl generate .
3804: .It Fl checks Ar n
3805: Perform a Miller-Rabin probabilistic primality test with
3806: .Ar n
3807: iterations.
3808: The default is 20.
3809: .It Fl generate
3810: Generate a pseudo-random prime number.
3811: Must be used in conjunction with
3812: .Fl bits .
3813: .It Fl hex
3814: Output in hex format.
3815: .It Fl safe
3816: Generate only
3817: .Qq safe
3818: prime numbers
3819: (i.e. a prime p so that (p-1)/2 is also prime).
3820: .It Ar p
3821: Test if number
3822: .Ar p
3823: is prime.
3824: .El
3825: .\"
3826: .\" RAND
3827: .\"
3828: .Sh RAND
3829: .nr nS 1
3830: .Nm "openssl rand"
3831: .Op Fl base64
3832: .Op Fl hex
3833: .Op Fl out Ar file
3834: .Ar num
3835: .nr nS 0
3836: .Pp
3837: The
3838: .Nm rand
3839: command outputs
3840: .Ar num
3841: pseudo-random bytes.
3842: .Pp
3843: The options are as follows:
3844: .Bl -tag -width Ds
3845: .It Fl base64
3846: Perform
3847: .Em base64
3848: encoding on the output.
3849: .It Fl hex
3850: Specify hexadecimal output.
3851: .It Fl out Ar file
3852: Write to
3853: .Ar file
3854: instead of standard output.
3855: .El
3856: .\"
3857: .\" REQ
3858: .\"
3859: .Sh REQ
3860: .nr nS 1
3861: .Nm "openssl req"
3862: .Bk -words
3863: .Op Fl asn1-kludge
3864: .Op Fl batch
3865: .Op Fl config Ar file
3866: .Op Fl days Ar n
3867: .Op Fl extensions Ar section
3868: .Op Fl in Ar file
3869: .Op Fl inform Ar DER | PEM
3870: .Op Fl key Ar keyfile
3871: .Op Fl keyform Ar DER | PEM
3872: .Op Fl keyout Ar file
1.28 doug 3873: .Op Fl md4 | md5 | sha1
1.1 jsing 3874: .Op Fl modulus
3875: .Op Fl nameopt Ar option
3876: .Op Fl new
3877: .Op Fl newhdr
3878: .Op Fl newkey Ar arg
3879: .Op Fl no-asn1-kludge
3880: .Op Fl nodes
3881: .Op Fl noout
3882: .Op Fl out Ar file
3883: .Op Fl outform Ar DER | PEM
3884: .Op Fl passin Ar arg
3885: .Op Fl passout Ar arg
3886: .Op Fl pubkey
3887: .Op Fl reqexts Ar section
3888: .Op Fl reqopt Ar option
3889: .Op Fl set_serial Ar n
3890: .Op Fl subj Ar arg
3891: .Op Fl subject
3892: .Op Fl text
3893: .Op Fl utf8
3894: .Op Fl verbose
3895: .Op Fl verify
3896: .Op Fl x509
3897: .Ek
3898: .nr nS 0
3899: .Pp
3900: The
3901: .Nm req
3902: command primarily creates and processes certificate requests
3903: in PKCS#10 format.
3904: It can additionally create self-signed certificates,
3905: for use as root CAs, for example.
3906: .Pp
3907: The options are as follows:
3908: .Bl -tag -width Ds
3909: .It Fl asn1-kludge
3910: By default, the
3911: .Nm req
3912: command outputs certificate requests containing
3913: no attributes in the correct PKCS#10 format.
3914: However certain CAs will only
3915: accept requests containing no attributes in an invalid form: this
3916: option produces this invalid format.
3917: .Pp
3918: More precisely, the
3919: .Em Attributes
3920: in a PKCS#10 certificate request are defined as a SET OF Attribute.
3921: They are
3922: .Em not
3923: optional, so if no attributes are present then they should be encoded as an
3924: empty SET OF.
3925: The invalid form does not include the empty
3926: SET OF, whereas the correct form does.
3927: .Pp
3928: It should be noted that very few CAs still require the use of this option.
3929: .It Fl batch
3930: Non-interactive mode.
3931: .It Fl config Ar file
3932: This allows an alternative configuration file to be specified;
3933: this overrides the compile time filename or any specified in
3934: the
3935: .Ev OPENSSL_CONF
3936: environment variable.
3937: .It Fl days Ar n
3938: When the
3939: .Fl x509
3940: option is being used, this specifies the number of
3941: days to certify the certificate for.
3942: The default is 30 days.
3943: .It Fl extensions Ar section , Fl reqexts Ar section
3944: These options specify alternative sections to include certificate
3945: extensions (if the
3946: .Fl x509
3947: option is present) or certificate request extensions.
3948: This allows several different sections to
3949: be used in the same configuration file to specify requests for
3950: a variety of purposes.
3951: .It Fl in Ar file
3952: This specifies the input
3953: .Ar file
3954: to read a request from, or standard input
3955: if this option is not specified.
3956: A request is only read if the creation options
3957: .Fl new
3958: and
3959: .Fl newkey
3960: are not specified.
3961: .It Fl inform Ar DER | PEM
3962: This specifies the input format.
3963: The
3964: .Ar DER
3965: argument uses an ASN1 DER-encoded form compatible with the PKCS#10.
3966: The
3967: .Ar PEM
3968: form is the default format:
3969: it consists of the DER format base64-encoded with additional header and
3970: footer lines.
3971: .It Fl key Ar keyfile
3972: This specifies the file to read the private key from.
3973: It also accepts PKCS#8 format private keys for PEM format files.
3974: .It Fl keyform Ar DER | PEM
3975: The format of the private key file specified in the
3976: .Fl key
3977: argument.
3978: .Ar PEM
3979: is the default.
3980: .It Fl keyout Ar file
3981: This gives the
3982: .Ar file
3983: to write the newly created private key to.
3984: If this option is not specified, the filename present in the
3985: configuration file is used.
1.4 sthen 3986: .It Fl md5 | sha1 | sha256
1.1 jsing 3987: This specifies the message digest to sign the request with.
3988: This overrides the digest algorithm specified in the configuration file.
3989: .Pp
3990: Some public key algorithms may override this choice.
3991: For instance, DSA signatures always use SHA1.
3992: .It Fl modulus
3993: This option prints out the value of the modulus of the public key
3994: contained in the request.
3995: .It Fl nameopt Ar option , Fl reqopt Ar option
3996: These options determine how the subject or issuer names are displayed.
3997: The
3998: .Ar option
3999: argument can be a single option or multiple options separated by commas.
4000: Alternatively, these options may be used more than once to set multiple options.
4001: See the
4002: .Sx X509
4003: section below for details.
4004: .It Fl new
4005: This option generates a new certificate request.
4006: It will prompt the user for the relevant field values.
4007: The actual fields prompted for and their maximum and minimum sizes
4008: are specified in the configuration file and any requested extensions.
4009: .Pp
4010: If the
4011: .Fl key
4012: option is not used, it will generate a new RSA private
4013: key using information specified in the configuration file.
4014: .It Fl newhdr
4015: Adds the word NEW to the PEM file header and footer lines
4016: on the outputed request.
4017: Some software
4018: .Pq Netscape certificate server
4019: and some CAs need this.
4020: .It Fl newkey Ar arg
4021: This option creates a new certificate request and a new private key.
4022: The argument takes one of several forms.
4023: .Ar rsa : Ns Ar nbits ,
4024: where
4025: .Ar nbits
4026: is the number of bits, generates an RSA key
4027: .Ar nbits
4028: in size.
4029: If
4030: .Ar nbits
4031: is omitted, i.e.\&
4032: .Cm -newkey rsa
4033: specified,
4034: the default key size, specified in the configuration file, is used.
4035: .Pp
4036: All other algorithms support the
4037: .Ar alg : Ns Ar file
4038: form,
4039: where file may be an algorithm parameter file,
4040: created by the
4041: .Cm genpkey -genparam
1.14 jmc 4042: command or an X.509 certificate for a key with appropriate algorithm.
1.1 jsing 4043: .Pp
4044: .Ar param : Ns Ar file
4045: generates a key using the parameter file or certificate
4046: .Ar file ;
4047: the algorithm is determined by the parameters.
4048: .Ar algname : Ns Ar file
4049: use algorithm
4050: .Ar algname
4051: and parameter file
4052: .Ar file :
4053: the two algorithms must match or an error occurs.
4054: .Ar algname
4055: just uses algorithm
4056: .Ar algname ,
4057: and parameters, if necessary,
4058: should be specified via the
4059: .Fl pkeyopt
4060: option.
4061: .Pp
4062: .Ar dsa : Ns Ar file
4063: generates a DSA key using the parameters in the file
4064: .Ar file .
4065: .It Fl no-asn1-kludge
4066: Reverses the effect of
4067: .Fl asn1-kludge .
4068: .It Fl nodes
4069: If this option is specified and a private key is created, it
4070: will not be encrypted.
4071: .It Fl noout
4072: This option prevents output of the encoded version of the request.
4073: .It Fl out Ar file
4074: This specifies the output
4075: .Ar file
4076: to write to, or standard output by default.
4077: .It Fl outform Ar DER | PEM
4078: This specifies the output format; the options have the same meaning as the
4079: .Fl inform
4080: option.
4081: .It Fl passin Ar arg
4082: The key password source.
4083: .It Fl passout Ar arg
4084: The output file password source.
4085: .It Fl pubkey
4086: Outputs the public key.
4087: .It Fl reqopt Ar option
4088: Customise the output format used with
4089: .Fl text .
4090: The
4091: .Ar option
4092: argument can be a single option or multiple options separated by commas.
4093: .Pp
4094: See the discussion of the
4095: .Fl certopt
4096: option in the
4097: .Nm x509
4098: command.
4099: .It Fl set_serial Ar n
4100: Serial number to use when outputting a self-signed certificate.
4101: This may be specified as a decimal value or a hex value if preceded by
4102: .Sq 0x .
4103: It is possible to use negative serial numbers but this is not recommended.
4104: .It Fl subj Ar arg
4105: Replaces subject field of input request with specified data and outputs
4106: modified request.
4107: The arg must be formatted as
4108: .Em /type0=value0/type1=value1/type2=... ;
4109: characters may be escaped by
4110: .Sq \e
4111: .Pq backslash ;
4112: no spaces are skipped.
4113: .It Fl subject
4114: Prints out the request subject (or certificate subject if
4115: .Fl x509
4116: is specified.
4117: .It Fl text
4118: Prints out the certificate request in text form.
4119: .It Fl utf8
4120: This option causes field values to be interpreted as UTF8 strings;
4121: by default they are interpreted as ASCII.
4122: This means that the field values, whether prompted from a terminal or
4123: obtained from a configuration file, must be valid UTF8 strings.
4124: .It Fl verbose
4125: Print extra details about the operations being performed.
4126: .It Fl verify
4127: Verifies the signature on the request.
4128: .It Fl x509
4129: This option outputs a self-signed certificate instead of a certificate
4130: request.
4131: This is typically used to generate a test certificate or
4132: a self-signed root CA.
4133: The extensions added to the certificate
4134: .Pq if any
4135: are specified in the configuration file.
4136: Unless specified using the
4137: .Fl set_serial
4138: option, 0 will be used for the serial number.
4139: .El
4140: .Sh REQ CONFIGURATION FILE FORMAT
4141: The configuration options are specified in the
4142: .Em req
4143: section of the configuration file.
4144: As with all configuration files, if no value is specified in the specific
4145: section (i.e.\&
4146: .Em req )
4147: then the initial unnamed or
4148: .Em default
4149: section is searched too.
4150: .Pp
4151: The options available are described in detail below.
4152: .Bl -tag -width "XXXX"
4153: .It Ar attributes
4154: This specifies the section containing any request attributes: its format
4155: is the same as
4156: .Ar distinguished_name .
4157: Typically these may contain the
4158: .Em challengePassword
4159: or
4160: .Em unstructuredName
4161: types.
4162: They are currently ignored by
4163: .Nm OpenSSL Ns Li 's
4164: request signing utilities, but some CAs might want them.
4165: .It Ar default_bits
4166: This specifies the default key size in bits.
1.4 sthen 4167: If not specified, 2048 is used.
1.1 jsing 4168: It is used if the
4169: .Fl new
4170: option is used.
4171: It can be overridden by using the
4172: .Fl newkey
4173: option.
4174: .It Ar default_keyfile
4175: This is the default file to write a private key to.
4176: If not specified, the key is written to standard output.
4177: This can be overridden by the
4178: .Fl keyout
4179: option.
4180: .It Ar default_md
4181: This option specifies the digest algorithm to use.
4182: Possible values include
1.4 sthen 4183: .Ar md5 ,
4184: .Ar sha1
1.1 jsing 4185: and
1.4 sthen 4186: .Ar sha256 .
4187: If not present, SHA256 is used.
1.1 jsing 4188: This option can be overridden on the command line.
4189: .It Ar distinguished_name
4190: This specifies the section containing the distinguished name fields to
4191: prompt for when generating a certificate or certificate request.
4192: The format is described in the next section.
4193: .It Ar encrypt_key
4194: If this is set to
4195: .Em no
4196: and a private key is generated, it is
4197: .Em not
4198: encrypted.
4199: This is equivalent to the
4200: .Fl nodes
4201: command line option.
4202: For compatibility,
4203: .Ar encrypt_rsa_key
4204: is an equivalent option.
4205: .It Ar input_password | output_password
4206: The passwords for the input private key file
4207: .Pq if present
4208: and the output private key file
4209: .Pq if one will be created .
4210: The command line options
4211: .Fl passin
4212: and
4213: .Fl passout
4214: override the configuration file values.
4215: .It Ar oid_file
4216: This specifies a file containing additional OBJECT IDENTIFIERS.
4217: Each line of the file should consist of the numerical form of the
4218: object identifier, followed by whitespace, then the short name followed
4219: by whitespace and finally the long name.
4220: .It Ar oid_section
4221: This specifies a section in the configuration file containing extra
4222: object identifiers.
4223: Each line should consist of the short name of the
4224: object identifier followed by
4225: .Sq =
4226: and the numerical form.
4227: The short and long names are the same when this option is used.
4228: .It Ar prompt
4229: If set to the value
4230: .Em no ,
4231: this disables prompting of certificate fields
4232: and just takes values from the config file directly.
4233: It also changes the expected format of the
4234: .Em distinguished_name
4235: and
4236: .Em attributes
4237: sections.
4238: .It Ar req_extensions
4239: This specifies the configuration file section containing a list of
4240: extensions to add to the certificate request.
4241: It can be overridden by the
4242: .Fl reqexts
4243: command line switch.
4244: .It Ar string_mask
4245: This option limits the string types for encoding certain
4246: fields.
4247: The following values may be used, limiting strings to the indicated types:
4248: .Bl -tag -width "MASK:number"
4249: .It Ar utf8only
4250: .Em UTF8String.
4251: This is the default, as recommended by PKIX in RFC 2459.
4252: .It Ar default
4253: .Em PrintableString , IA5String , T61String , BMPString , UTF8String .
4254: .It Ar pkix
4255: .Em PrintableString , IA5String , BMPString , UTF8String .
4256: This was inspired by the PKIX recommendation in RFC 2459 for certificates
4257: generated before 2004, but differs by also permitting
4258: .Em IA5String .
4259: .It Ar nombstr
4260: .Em PrintableString , IA5String , T61String , UniversalString .
4261: This was a workaround for some ancient software that had problems
4262: with the variable-sized
4263: .Em BMPString
4264: and
4265: .Em UTF8String
4266: types.
4267: .It Cm MASK : Ns Ar number
4268: This is an explicit bitmask of permitted types, where
4269: .Ar number
4270: is a C-style hex, decimal, or octal number that's a bit-wise OR of
4271: .Dv B_ASN1_*
4272: values from
4273: .In openssl/asn1.h .
4274: .El
4275: .It Ar utf8
4276: If set to the value
4277: .Em yes ,
4278: then field values are interpreted as UTF8 strings;
4279: by default they are interpreted as ASCII.
4280: This means that the field values, whether prompted from a terminal or
4281: obtained from a configuration file, must be valid UTF8 strings.
4282: .It Ar x509_extensions
4283: This specifies the configuration file section containing a list of
4284: extensions to add to a certificate generated when the
4285: .Fl x509
4286: switch is used.
4287: It can be overridden by the
4288: .Fl extensions
4289: command line switch.
4290: .El
4291: .Sh REQ DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
4292: There are two separate formats for the distinguished name and attribute
4293: sections.
4294: If the
4295: .Fl prompt
4296: option is set to
4297: .Em no ,
4298: then these sections just consist of field names and values: for example,
4299: .Bd -unfilled -offset indent
4300: CN=My Name
4301: OU=My Organization
4302: emailAddress=someone@somewhere.org
4303: .Ed
4304: .Pp
4305: This allows external programs
4306: .Pq e.g. GUI based
4307: to generate a template file with all the field names and values
4308: and just pass it to
4309: .Nm req .
4310: An example of this kind of configuration file is contained in the
4311: .Sx REQ EXAMPLES
4312: section.
4313: .Pp
4314: Alternatively if the
4315: .Fl prompt
4316: option is absent or not set to
4317: .Em no ,
4318: then the file contains field prompting information.
4319: It consists of lines of the form:
4320: .Bd -unfilled -offset indent
4321: fieldName="prompt"
4322: fieldName_default="default field value"
4323: fieldName_min= 2
4324: fieldName_max= 4
4325: .Ed
4326: .Pp
4327: .Qq fieldName
4328: is the field name being used, for example
4329: .Em commonName
4330: .Pq or CN .
4331: The
4332: .Qq prompt
4333: string is used to ask the user to enter the relevant details.
4334: If the user enters nothing, the default value is used;
4335: if no default value is present, the field is omitted.
4336: A field can still be omitted if a default value is present,
4337: if the user just enters the
4338: .Sq \&.
4339: character.
4340: .Pp
4341: The number of characters entered must be between the
4342: .Em fieldName_min
4343: and
4344: .Em fieldName_max
4345: limits:
4346: there may be additional restrictions based on the field being used
4347: (for example
4348: .Em countryName
4349: can only ever be two characters long and must fit in a
4350: .Em PrintableString ) .
4351: .Pp
4352: Some fields (such as
4353: .Em organizationName )
4354: can be used more than once in a DN.
4355: This presents a problem because configuration files will
4356: not recognize the same name occurring twice.
4357: To avoid this problem, if the
4358: .Em fieldName
4359: contains some characters followed by a full stop, they will be ignored.
4360: So, for example, a second
4361: .Em organizationName
4362: can be input by calling it
4363: .Qq 1.organizationName .
4364: .Pp
4365: The actual permitted field names are any object identifier short or
4366: long names.
4367: These are compiled into
4368: .Nm OpenSSL
4369: and include the usual values such as
4370: .Em commonName , countryName , localityName , organizationName ,
4371: .Em organizationUnitName , stateOrProvinceName .
4372: Additionally,
4373: .Em emailAddress
4374: is included as well as
4375: .Em name , surname , givenName initials
4376: and
4377: .Em dnQualifier .
4378: .Pp
4379: Additional object identifiers can be defined with the
4380: .Ar oid_file
4381: or
4382: .Ar oid_section
4383: options in the configuration file.
4384: Any additional fields will be treated as though they were a
4385: .Em DirectoryString .
4386: .Sh REQ EXAMPLES
4387: Examine and verify a certificate request:
4388: .Pp
4389: .Dl $ openssl req -in req.pem -text -verify -noout
4390: .Pp
4391: Create a private key and then generate a certificate request from it:
4392: .Bd -literal -offset indent
4393: $ openssl genrsa -out key.pem 2048
4394: $ openssl req -new -key key.pem -out req.pem
4395: .Ed
4396: .Pp
4397: The same but just using req:
4398: .Pp
4399: .Dl $ openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
4400: .Pp
4401: Generate a self-signed root certificate:
4402: .Pp
4403: .Dl "$ openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem"
4404: .Pp
4405: Example of a file pointed to by the
4406: .Ar oid_file
4407: option:
4408: .Bd -unfilled -offset indent
4409: 1.2.3.4 shortName A longer Name
4410: 1.2.3.6 otherName Other longer Name
4411: .Ed
4412: .Pp
4413: Example of a section pointed to by
4414: .Ar oid_section
4415: making use of variable expansion:
4416: .Bd -unfilled -offset indent
4417: testoid1=1.2.3.5
4418: testoid2=${testoid1}.6
4419: .Ed
4420: .Pp
4421: Sample configuration file prompting for field values:
4422: .Bd -literal
4423: \& [ req ]
4424: \& default_bits = 1024
4425: \& default_keyfile = privkey.pem
4426: \& distinguished_name = req_distinguished_name
4427: \& attributes = req_attributes
4428: \& x509_extensions = v3_ca
4429:
4430: \& dirstring_type = nobmp
4431:
4432: \& [ req_distinguished_name ]
4433: \& countryName = Country Name (2 letter code)
4434: \& countryName_default = AU
4435: \& countryName_min = 2
4436: \& countryName_max = 2
4437:
4438: \& localityName = Locality Name (eg, city)
4439:
4440: \& organizationalUnitName = Organizational Unit Name (eg, section)
4441:
4442: \& commonName = Common Name (eg, YOUR name)
4443: \& commonName_max = 64
4444:
4445: \& emailAddress = Email Address
4446: \& emailAddress_max = 40
4447:
4448: \& [ req_attributes ]
4449: \& challengePassword = A challenge password
4450: \& challengePassword_min = 4
4451: \& challengePassword_max = 20
4452:
4453: \& [ v3_ca ]
4454:
4455: \& subjectKeyIdentifier=hash
4456: \& authorityKeyIdentifier=keyid:always,issuer:always
4457: \& basicConstraints = CA:true
4458: .Ed
4459: .Pp
4460: Sample configuration containing all field values:
4461: .Bd -literal
4462:
4463: \& [ req ]
4464: \& default_bits = 1024
4465: \& default_keyfile = keyfile.pem
4466: \& distinguished_name = req_distinguished_name
4467: \& attributes = req_attributes
4468: \& prompt = no
4469: \& output_password = mypass
4470:
4471: \& [ req_distinguished_name ]
4472: \& C = GB
4473: \& ST = Test State or Province
4474: \& L = Test Locality
4475: \& O = Organization Name
4476: \& OU = Organizational Unit Name
4477: \& CN = Common Name
4478: \& emailAddress = test@email.address
4479:
4480: \& [ req_attributes ]
4481: \& challengePassword = A challenge password
4482: .Ed
4483: .Sh REQ NOTES
4484: The header and footer lines in the PEM format are normally:
4485: .Bd -unfilled -offset indent
4486: -----BEGIN CERTIFICATE REQUEST-----
4487: -----END CERTIFICATE REQUEST-----
4488: .Ed
4489: .Pp
4490: Some software
4491: .Pq some versions of Netscape certificate server
4492: instead needs:
4493: .Bd -unfilled -offset indent
4494: -----BEGIN NEW CERTIFICATE REQUEST-----
4495: -----END NEW CERTIFICATE REQUEST-----
4496: .Ed
4497: .Pp
4498: which is produced with the
4499: .Fl newhdr
4500: option but is otherwise compatible.
4501: Either form is accepted transparently on input.
4502: .Pp
4503: The certificate requests generated by Xenroll with MSIE have extensions added.
4504: It includes the
4505: .Em keyUsage
4506: extension which determines the type of key
4507: .Pq signature only or general purpose
4508: and any additional OIDs entered by the script in an
4509: .Em extendedKeyUsage
4510: extension.
4511: .Sh REQ DIAGNOSTICS
4512: The following messages are frequently asked about:
4513: .Bd -unfilled -offset indent
4514: Using configuration from /some/path/openssl.cnf
4515: Unable to load config info
4516: .Ed
4517: .Pp
4518: This is followed some time later by...
4519: .Bd -unfilled -offset indent
4520: unable to find 'distinguished_name' in config
4521: problems making Certificate Request
4522: .Ed
4523: .Pp
4524: The first error message is the clue: it can't find the configuration
4525: file!
4526: Certain operations
4527: .Pq like examining a certificate request
4528: don't need a configuration file so its use isn't enforced.
4529: Generation of certificates or requests, however, do need a configuration file.
4530: This could be regarded as a bug.
4531: .Pp
4532: Another puzzling message is this:
4533: .Bd -unfilled -offset indent
4534: Attributes:
4535: a0:00
4536: .Ed
4537: .Pp
4538: This is displayed when no attributes are present and the request includes
4539: the correct empty SET OF structure
4540: .Pq the DER encoding of which is 0xa0 0x00 .
4541: If you just see:
4542: .Pp
4543: .D1 Attributes:
4544: .Pp
4545: then the SET OF is missing and the encoding is technically invalid
4546: .Pq but it is tolerated .
4547: See the description of the command line option
4548: .Fl asn1-kludge
4549: for more information.
4550: .Sh REQ ENVIRONMENT VARIABLES
4551: The variable
4552: .Ev OPENSSL_CONF ,
4553: if defined, allows an alternative configuration
4554: file location to be specified; it will be overridden by the
4555: .Fl config
4556: command line switch if it is present.
4557: .Sh REQ BUGS
4558: .Nm OpenSSL Ns Li 's
4559: handling of T61Strings
4560: .Pq aka TeletexStrings
4561: is broken: it effectively treats them as ISO 8859-1
4562: .Pq Latin 1 ;
4563: Netscape and MSIE have similar behaviour.
4564: This can cause problems if you need characters that aren't available in
4565: .Em PrintableStrings
4566: and you don't want to or can't use
4567: .Em BMPStrings .
4568: .Pp
4569: As a consequence of the T61String handling, the only correct way to represent
4570: accented characters in
4571: .Nm OpenSSL
4572: is to use a
4573: .Em BMPString :
4574: unfortunately Netscape currently chokes on these.
4575: If you have to use accented characters with Netscape
4576: and MSIE then you currently need to use the invalid T61String form.
4577: .Pp
4578: The current prompting is not very friendly.
4579: It doesn't allow you to confirm what you've just entered.
4580: Other things, like extensions in certificate requests, are
4581: statically defined in the configuration file.
4582: Some of these, like an email address in
4583: .Em subjectAltName ,
4584: should be input by the user.
4585: .\"
4586: .\" RSA
4587: .\"
4588: .Sh RSA
4589: .nr nS 1
4590: .Nm "openssl rsa"
4591: .Bk -words
4592: .Oo
4593: .Fl aes128 | aes192 | aes256 |
4594: .Fl des | des3
4595: .Oc
4596: .Op Fl check
4597: .Op Fl in Ar file
4598: .Op Fl inform Ar DER | NET | PEM
4599: .Op Fl modulus
4600: .Op Fl noout
4601: .Op Fl out Ar file
4602: .Op Fl outform Ar DER | NET | PEM
4603: .Op Fl passin Ar arg
4604: .Op Fl passout Ar arg
4605: .Op Fl pubin
4606: .Op Fl pubout
4607: .Op Fl sgckey
4608: .Op Fl text
4609: .nr nS 0
4610: .Ek
4611: .Pp
4612: The
4613: .Nm rsa
4614: command processes RSA keys.
4615: They can be converted between various forms and their components printed out.
4616: .Pp
4617: .Sy Note :
4618: this command uses the traditional
4619: .Nm SSLeay
4620: compatible format for private key encryption:
4621: newer applications should use the more secure PKCS#8 format using the
4622: .Nm pkcs8
4623: utility.
4624: .Pp
4625: The options are as follows:
4626: .Bl -tag -width Ds
4627: .It Xo
4628: .Fl aes128 | aes192 | aes256 |
4629: .Fl des | des3
4630: .Xc
4631: These options encrypt the private key with the AES, DES,
4632: or the triple DES ciphers, respectively, before outputting it.
4633: A pass phrase is prompted for.
4634: If none of these options are specified, the key is written in plain text.
4635: This means that using the
4636: .Nm rsa
4637: utility to read in an encrypted key with no encryption option can be used
4638: to remove the pass phrase from a key, or by setting the encryption options
4639: it can be used to add or change the pass phrase.
4640: These options can only be used with PEM format output files.
4641: .It Fl check
4642: This option checks the consistency of an RSA private key.
4643: .It Fl in Ar file
4644: This specifies the input
4645: .Ar file
4646: to read a key from, or standard input if this
4647: option is not specified.
4648: If the key is encrypted, a pass phrase will be prompted for.
4649: .It Fl inform Ar DER | NET | PEM
4650: This specifies the input format.
4651: The
4652: .Ar DER
4653: argument
4654: uses an ASN1 DER-encoded form compatible with the PKCS#1
4655: RSAPrivateKey or SubjectPublicKeyInfo format.
4656: The
4657: .Ar PEM
4658: form is the default format: it consists of the DER format base64-encoded with
4659: additional header and footer lines.
4660: On input PKCS#8 format private keys are also accepted.
4661: The
4662: .Ar NET
4663: form is a format described in the
4664: .Sx RSA NOTES
4665: section.
4666: .It Fl noout
4667: This option prevents output of the encoded version of the key.
4668: .It Fl modulus
4669: This option prints out the value of the modulus of the key.
4670: .It Fl out Ar file
4671: This specifies the output
4672: .Ar file
4673: to write a key to, or standard output if this option is not specified.
4674: If any encryption options are set, a pass phrase will be prompted for.
4675: The output filename should
4676: .Em not
4677: be the same as the input filename.
4678: .It Fl outform Ar DER | NET | PEM
4679: This specifies the output format; the options have the same meaning as the
4680: .Fl inform
4681: option.
4682: .It Fl passin Ar arg
4683: The key password source.
4684: .It Fl passout Ar arg
4685: The output file password source.
4686: .It Fl pubin
4687: By default, a private key is read from the input file; with this
4688: option a public key is read instead.
4689: .It Fl pubout
4690: By default, a private key is output;
4691: with this option a public key will be output instead.
4692: This option is automatically set if the input is a public key.
4693: .It Fl sgckey
4694: Use the modified
4695: .Em NET
4696: algorithm used with some versions of Microsoft IIS and SGC keys.
4697: .It Fl text
4698: Prints out the various public or private key components in
4699: plain text, in addition to the encoded version.
4700: .El
4701: .Sh RSA NOTES
4702: The PEM private key format uses the header and footer lines:
4703: .Bd -unfilled -offset indent
4704: -----BEGIN RSA PRIVATE KEY-----
4705: -----END RSA PRIVATE KEY-----
4706: .Ed
4707: .Pp
4708: The PEM public key format uses the header and footer lines:
4709: .Bd -unfilled -offset indent
4710: -----BEGIN PUBLIC KEY-----
4711: -----END PUBLIC KEY-----
4712: .Ed
4713: .Pp
4714: The
4715: .Em NET
4716: form is a format compatible with older Netscape servers
4717: and Microsoft IIS .key files; this uses unsalted RC4 for its encryption.
4718: It is not very secure and so should only be used when necessary.
4719: .Pp
4720: Some newer version of IIS have additional data in the exported .key files.
4721: To use these with the
4722: .Nm rsa
4723: utility, view the file with a binary editor
4724: and look for the string
4725: .Qq private-key ,
4726: then trace back to the byte sequence 0x30, 0x82
4727: .Pq this is an ASN1 SEQUENCE .
4728: Copy all the data from this point onwards to another file and use that as
4729: the input to the
4730: .Nm rsa
4731: utility with the
4732: .Fl inform Ar NET
4733: option.
4734: If there is an error after entering the password, try the
4735: .Fl sgckey
4736: option.
4737: .Sh RSA EXAMPLES
4738: To remove the pass phrase on an RSA private key:
4739: .Pp
4740: .Dl $ openssl rsa -in key.pem -out keyout.pem
4741: .Pp
4742: To encrypt a private key using triple DES:
4743: .Pp
4744: .Dl $ openssl rsa -in key.pem -des3 -out keyout.pem
4745: .Pp
4746: To convert a private key from PEM to DER format:
4747: .Pp
4748: .Dl $ openssl rsa -in key.pem -outform DER -out keyout.der
4749: .Pp
4750: To print out the components of a private key to standard output:
4751: .Pp
4752: .Dl $ openssl rsa -in key.pem -text -noout
4753: .Pp
4754: To just output the public part of a private key:
4755: .Pp
4756: .Dl $ openssl rsa -in key.pem -pubout -out pubkey.pem
4757: .Sh RSA BUGS
4758: The command line password arguments don't currently work with
4759: .Em NET
4760: format.
4761: .Pp
4762: There should be an option that automatically handles .key files,
4763: without having to manually edit them.
4764: .\"
4765: .\" RSAUTL
4766: .\"
4767: .Sh RSAUTL
4768: .nr nS 1
4769: .Nm "openssl rsautl"
4770: .Bk -words
4771: .Op Fl asn1parse
4772: .Op Fl certin
4773: .Op Fl decrypt
4774: .Op Fl encrypt
4775: .Op Fl hexdump
4776: .Op Fl in Ar file
4777: .Op Fl inkey Ar file
4778: .Op Fl keyform Ar DER | PEM
4779: .Op Fl oaep | pkcs | raw | ssl
4780: .Op Fl out Ar file
4781: .Op Fl pubin
4782: .Op Fl sign
4783: .Op Fl verify
4784: .Ek
4785: .nr nS 0
4786: .Pp
4787: The
4788: .Nm rsautl
4789: command can be used to sign, verify, encrypt and decrypt
4790: data using the RSA algorithm.
4791: .Pp
4792: The options are as follows:
4793: .Bl -tag -width Ds
4794: .It Fl asn1parse
4795: Asn1parse the output data; this is useful when combined with the
4796: .Fl verify
4797: option.
4798: .It Fl certin
4799: The input is a certificate containing an RSA public key.
4800: .It Fl decrypt
4801: Decrypt the input data using an RSA private key.
4802: .It Fl encrypt
4803: Encrypt the input data using an RSA public key.
4804: .It Fl hexdump
4805: Hex dump the output data.
4806: .It Fl in Ar file
4807: This specifies the input
4808: .Ar file
4809: to read data from, or standard input
4810: if this option is not specified.
4811: .It Fl inkey Ar file
4812: The input key file, by default it should be an RSA private key.
4813: .It Fl keyform Ar DER | PEM
4814: Private ket format.
4815: Default is
4816: .Ar PEM .
4817: .It Fl oaep | pkcs | raw | ssl
4818: The padding to use:
4819: PKCS#1 OAEP, PKCS#1 v1.5
4820: .Pq the default ,
4821: or no padding, respectively.
4822: For signatures, only
4823: .Fl pkcs
4824: and
4825: .Fl raw
4826: can be used.
4827: .It Fl out Ar file
4828: Specifies the output
4829: .Ar file
4830: to write to, or standard output by
4831: default.
4832: .It Fl pubin
4833: The input file is an RSA public key.
4834: .It Fl sign
4835: Sign the input data and output the signed result.
4836: This requires an RSA private key.
4837: .It Fl verify
4838: Verify the input data and output the recovered data.
4839: .El
4840: .Sh RSAUTL NOTES
4841: .Nm rsautl ,
4842: because it uses the RSA algorithm directly, can only be
4843: used to sign or verify small pieces of data.
4844: .Sh RSAUTL EXAMPLES
4845: Sign some data using a private key:
4846: .Pp
4847: .Dl "$ openssl rsautl -sign -in file -inkey key.pem -out sig"
4848: .Pp
4849: Recover the signed data:
4850: .Pp
4851: .Dl $ openssl rsautl -verify -in sig -inkey key.pem
4852: .Pp
4853: Examine the raw signed data:
4854: .Pp
4855: .Li "\ \&$ openssl rsautl -verify -in file -inkey key.pem -raw -hexdump"
4856: .Bd -unfilled
4857: \& 0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
4858: \& 0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
4859: \& 0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
4860: \& 0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
4861: \& 0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
4862: \& 0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
4863: \& 0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................
4864: \& 0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64 .....hello world
4865: .Ed
4866: .Pp
4867: The PKCS#1 block formatting is evident from this.
4868: If this was done using encrypt and decrypt, the block would have been of type 2
4869: .Pq the second byte
4870: and random padding data visible instead of the 0xff bytes.
4871: .Pp
4872: It is possible to analyse the signature of certificates using this
4873: utility in conjunction with
4874: .Nm asn1parse .
4875: Consider the self-signed example in
4876: .Pa certs/pca-cert.pem :
4877: running
4878: .Nm asn1parse
4879: as follows yields:
4880: .Pp
4881: .Li "\ \&$ openssl asn1parse -in pca-cert.pem"
4882: .Bd -unfilled
4883: \& 0:d=0 hl=4 l= 742 cons: SEQUENCE
4884: \& 4:d=1 hl=4 l= 591 cons: SEQUENCE
4885: \& 8:d=2 hl=2 l= 3 cons: cont [ 0 ]
4886: \& 10:d=3 hl=2 l= 1 prim: INTEGER :02
4887: \& 13:d=2 hl=2 l= 1 prim: INTEGER :00
4888: \& 16:d=2 hl=2 l= 13 cons: SEQUENCE
4889: \& 18:d=3 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
4890: \& 29:d=3 hl=2 l= 0 prim: NULL
4891: \& 31:d=2 hl=2 l= 92 cons: SEQUENCE
4892: \& 33:d=3 hl=2 l= 11 cons: SET
4893: \& 35:d=4 hl=2 l= 9 cons: SEQUENCE
4894: \& 37:d=5 hl=2 l= 3 prim: OBJECT :countryName
4895: \& 42:d=5 hl=2 l= 2 prim: PRINTABLESTRING :AU
4896: \& ....
4897: \& 599:d=1 hl=2 l= 13 cons: SEQUENCE
4898: \& 601:d=2 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
4899: \& 612:d=2 hl=2 l= 0 prim: NULL
4900: \& 614:d=1 hl=3 l= 129 prim: BIT STRING
4901: .Ed
4902: .Pp
4903: The final BIT STRING contains the actual signature.
4904: It can be extracted with:
4905: .Pp
4906: .Dl "$ openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614"
4907: .Pp
4908: The certificate public key can be extracted with:
4909: .Pp
4910: .Dl $ openssl x509 -in test/testx509.pem -pubkey -noout \*(Gtpubkey.pem
4911: .Pp
4912: The signature can be analysed with:
4913: .Pp
4914: .Li "\ \&$ openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin"
4915: .Bd -unfilled
4916: \& 0:d=0 hl=2 l= 32 cons: SEQUENCE
4917: \& 2:d=1 hl=2 l= 12 cons: SEQUENCE
4918: \& 4:d=2 hl=2 l= 8 prim: OBJECT :md5
4919: \& 14:d=2 hl=2 l= 0 prim: NULL
4920: \& 16:d=1 hl=2 l= 16 prim: OCTET STRING
4921: \& 0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5 .F...Js.7...H%..
4922: .Ed
4923: .Pp
4924: This is the parsed version of an ASN1
4925: .Em DigestInfo
4926: structure.
4927: It can be seen that the digest used was MD5.
4928: The actual part of the certificate that was signed can be extracted with:
4929: .Pp
4930: .Dl "$ openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4"
4931: .Pp
4932: and its digest computed with:
4933: .Pp
4934: .Dl $ openssl md5 -c tbs
4935: .D1 MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5
4936: .Pp
4937: which it can be seen agrees with the recovered value above.
4938: .\"
4939: .\" S_CLIENT
4940: .\"
4941: .Sh S_CLIENT
4942: .nr nS 1
4943: .Nm "openssl s_client"
4944: .Bk -words
4945: .Op Fl 4 | 6
4946: .Op Fl bugs
4947: .Op Fl CAfile Ar file
4948: .Op Fl CApath Ar directory
4949: .Op Fl cert Ar file
4950: .Op Fl check_ss_sig
4951: .Op Fl cipher Ar cipherlist
4952: .Oo
4953: .Fl connect Ar host : Ns Ar port |
4954: .Ar host Ns / Ns Ar port
4955: .Oc
4956: .Op Fl crl_check
4957: .Op Fl crl_check_all
4958: .Op Fl crlf
4959: .Op Fl debug
4960: .Op Fl extended_crl
4961: .Op Fl ign_eof
4962: .Op Fl ignore_critical
4963: .Op Fl issuer_checks
4964: .Op Fl key Ar keyfile
4965: .Op Fl msg
4966: .Op Fl nbio
4967: .Op Fl nbio_test
4968: .Op Fl no_ticket
4969: .Op Fl no_tls1
1.6 guenther 4970: .Op Fl no_tls1_1
4971: .Op Fl no_tls1_2
1.1 jsing 4972: .Op Fl pause
4973: .Op Fl policy_check
4974: .Op Fl prexit
1.11 bluhm 4975: .Op Fl proxy Ar host : Ns Ar port
1.1 jsing 4976: .Op Fl psk Ar key
4977: .Op Fl psk_identity Ar identity
4978: .Op Fl quiet
4979: .Op Fl reconnect
1.5 jsing 4980: .Op Fl servername Ar name
1.1 jsing 4981: .Op Fl showcerts
4982: .Op Fl starttls Ar protocol
4983: .Op Fl state
4984: .Op Fl tls1
1.31 jmc 4985: .Op Fl tls1_1
4986: .Op Fl tls1_2
1.1 jsing 4987: .Op Fl tlsextdebug
4988: .Op Fl verify Ar depth
4989: .Op Fl x509_strict
1.19 landry 4990: .Op Fl xmpphost Ar host
1.1 jsing 4991: .Ek
4992: .nr nS 0
4993: .Pp
4994: The
4995: .Nm s_client
4996: command implements a generic SSL/TLS client which connects
4997: to a remote host using SSL/TLS.
4998: It is a
4999: .Em very
5000: useful diagnostic tool for SSL servers.
5001: .Pp
5002: The options are as follows:
5003: .Bl -tag -width Ds
5004: .It Fl 4
5005: Specify that
5006: .Nm s_client
5007: should attempt connections using IPv4 only.
5008: .It Fl 6
5009: Specify that
5010: .Nm s_client
5011: should attempt connections using IPv6 only.
5012: .It Fl bugs
5013: There are several known bugs in SSL and TLS implementations.
5014: Adding this option enables various workarounds.
5015: .It Fl CAfile Ar file
5016: A
5017: .Ar file
5018: containing trusted certificates to use during server authentication
5019: and to use when attempting to build the client certificate chain.
5020: .It Fl CApath Ar directory
5021: The
5022: .Ar directory
5023: to use for server certificate verification.
5024: This directory must be in
5025: .Qq hash format ;
5026: see
5027: .Fl verify
5028: for more information.
5029: These are also used when building the client certificate chain.
5030: .It Fl cert Ar file
5031: The certificate to use, if one is requested by the server.
5032: The default is not to use a certificate.
5033: .It Xo
5034: .Fl check_ss_sig ,
5035: .Fl crl_check ,
5036: .Fl crl_check_all ,
5037: .Fl extended_crl ,
5038: .Fl ignore_critical ,
5039: .Fl issuer_checks ,
5040: .Fl policy_check ,
5041: .Fl x509_strict
5042: .Xc
5043: Set various certificate chain validation options.
5044: See the
5045: .Nm VERIFY
5046: command for details.
5047: .It Fl cipher Ar cipherlist
5048: This allows the cipher list sent by the client to be modified.
5049: Although the server determines which cipher suite is used, it should take
5050: the first supported cipher in the list sent by the client.
5051: See the
5052: .Sx CIPHERS
5053: section above for more information.
5054: .It Xo
5055: .Fl connect Ar host : Ns Ar port |
5056: .Ar host Ns / Ns Ar port
5057: .Xc
5058: This specifies the
5059: .Ar host
5060: and optional
5061: .Ar port
5062: to connect to.
5063: If not specified, an attempt is made to connect to the local host
5064: on port 4433.
5065: Alternatively, the host and port pair may be separated using a forward-slash
5066: character.
5067: This form is useful for numeric IPv6 addresses.
5068: .It Fl crlf
5069: This option translates a line feed from the terminal into CR+LF as required
5070: by some servers.
5071: .It Fl debug
5072: Print extensive debugging information including a hex dump of all traffic.
5073: .It Fl ign_eof
5074: Inhibit shutting down the connection when end of file is reached in the
5075: input.
5076: .It Fl key Ar keyfile
5077: The private key to use.
5078: If not specified, the certificate file will be used.
5079: .It Fl msg
5080: Show all protocol messages with hex dump.
5081: .It Fl nbio
5082: Turns on non-blocking I/O.
5083: .It Fl nbio_test
5084: Tests non-blocking I/O.
1.31 jmc 5085: .It Fl no_tls1 | no_tls1_1 | no_tls1_2
1.1 jsing 5086: By default, the initial handshake uses a method which should be compatible
1.31 jmc 5087: with servers supporting any version of TLS.
5088: These options disable the use of TLS1.0, 1.1, and 1.2, respectively.
1.1 jsing 5089: .Pp
5090: Unfortunately there are a lot of ancient and broken servers in use which
5091: cannot handle this technique and will fail to connect.
5092: .It Fl no_ticket
5093: Disable RFC 4507 session ticket support.
5094: .It Fl pause
5095: Pauses 1 second between each read and write call.
5096: .It Fl prexit
5097: Print session information when the program exits.
5098: This will always attempt
5099: to print out information even if the connection fails.
5100: Normally, information will only be printed out once if the connection succeeds.
5101: This option is useful because the cipher in use may be renegotiated
5102: or the connection may fail because a client certificate is required or is
5103: requested only after an attempt is made to access a certain URL.
5104: .Sy Note :
5105: the output produced by this option is not always accurate because a
5106: connection might never have been established.
1.11 bluhm 5107: .It Fl proxy Ar host : Ns Ar port
5108: Use the HTTP proxy at
5109: .Ar host
5110: and
5111: .Ar port .
5112: The connection to the proxy is done in cleartext and the
5113: .Fl connect
5114: argument is given to the proxy.
5115: If not specified, localhost is used as final destination.
5116: After that, switch the connection through the proxy to the destination
5117: to TLS.
1.1 jsing 5118: .It Fl psk Ar key
5119: Use the PSK key
5120: .Ar key
5121: when using a PSK cipher suite.
5122: The key is given as a hexadecimal number without the leading 0x,
5123: for example -psk 1a2b3c4d.
5124: .It Fl psk_identity Ar identity
5125: Use the PSK identity
5126: .Ar identity
5127: when using a PSK cipher suite.
5128: .It Fl quiet
5129: Inhibit printing of session and certificate information.
5130: This implicitly turns on
5131: .Fl ign_eof
5132: as well.
5133: .It Fl reconnect
5134: Reconnects to the same server 5 times using the same session ID; this can
5135: be used as a test that session caching is working.
1.5 jsing 5136: .It Fl servername Ar name
5137: Include the TLS Server Name Indication (SNI) extension in the ClientHello
5138: message, using the specified server
5139: .Ar name .
1.1 jsing 5140: .It Fl showcerts
5141: Display the whole server certificate chain: normally only the server
5142: certificate itself is displayed.
5143: .It Fl starttls Ar protocol
5144: Send the protocol-specific message(s) to switch to TLS for communication.
5145: .Ar protocol
5146: is a keyword for the intended protocol.
5147: Currently, the supported keywords are
5148: .Qq ftp ,
5149: .Qq imap ,
5150: .Qq smtp ,
5151: .Qq pop3 ,
5152: and
5153: .Qq xmpp .
5154: .It Fl state
5155: Prints out the SSL session states.
1.31 jmc 5156: .It Fl tls1 | tls1_1 | tls1_2
5157: Permit only TLS1.0, 1.1, or 1.2, respectively.
1.1 jsing 5158: .It Fl tlsextdebug
5159: Print out a hex dump of any TLS extensions received from the server.
5160: .It Fl verify Ar depth
5161: The verify
5162: .Ar depth
5163: to use.
5164: This specifies the maximum length of the
5165: server certificate chain and turns on server certificate verification.
5166: Currently the verify operation continues after errors so all the problems
5167: with a certificate chain can be seen.
5168: As a side effect the connection will never fail due to a server
5169: certificate verify failure.
1.19 landry 5170: .It Fl xmpphost Ar hostname
5171: This option, when used with
5172: .Fl starttls Ar xmpp ,
5173: specifies the host for the "to" attribute of the stream element.
5174: If this option is not specified then the host specified with
5175: .Fl connect
5176: will be used.
1.1 jsing 5177: .El
5178: .Sh S_CLIENT CONNECTED COMMANDS
5179: If a connection is established with an SSL server, any data received
5180: from the server is displayed and any key presses will be sent to the
5181: server.
5182: When used interactively (which means neither
5183: .Fl quiet
5184: nor
5185: .Fl ign_eof
5186: have been given), the session will be renegotiated if the line begins with an
5187: .Em R ;
5188: if the line begins with a
5189: .Em Q
5190: or if end of file is reached, the connection will be closed down.
5191: .Sh S_CLIENT NOTES
5192: .Nm s_client
5193: can be used to debug SSL servers.
5194: To connect to an SSL HTTP server the command:
5195: .Pp
5196: .Dl $ openssl s_client -connect servername:443
5197: .Pp
5198: would typically be used
5199: .Pq HTTPS uses port 443 .
5200: If the connection succeeds, an HTTP command can be given such as
5201: .Qq GET
5202: to retrieve a web page.
5203: .Pp
5204: If the handshake fails, there are several possible causes; if it is
5205: nothing obvious like no client certificate, then the
1.31 jmc 5206: .Fl bugs , tls1 , tls1_1, tls1_2 , no_tls1 , no_tls1_1 ,
1.1 jsing 5207: and
1.6 guenther 5208: .Fl no_tls1_2
1.1 jsing 5209: options can be tried in case it is a buggy server.
5210: .Pp
5211: A frequent problem when attempting to get client certificates working
5212: is that a web client complains it has no certificates or gives an empty
5213: list to choose from.
5214: This is normally because the server is not sending the client's certificate
5215: authority in its
5216: .Qq acceptable CA list
5217: when it requests a certificate.
5218: By using
5219: .Nm s_client
5220: the CA list can be viewed and checked.
5221: However some servers only request client authentication
5222: after a specific URL is requested.
5223: To obtain the list in this case it is necessary to use the
5224: .Fl prexit
5225: option and send an HTTP request for an appropriate page.
5226: .Pp
5227: If a certificate is specified on the command line using the
5228: .Fl cert
5229: option, it will not be used unless the server specifically requests
5230: a client certificate.
5231: Therefore merely including a client certificate
5232: on the command line is no guarantee that the certificate works.
5233: .Pp
5234: If there are problems verifying a server certificate, the
5235: .Fl showcerts
5236: option can be used to show the whole chain.
5237: .Pp
5238: Compression methods are only supported for
5239: .Fl tls1 .
5240: .Sh S_CLIENT BUGS
5241: Because this program has a lot of options and also because some of
5242: the techniques used are rather old, the C source of
5243: .Nm s_client
5244: is rather hard to read and not a model of how things should be done.
5245: A typical SSL client program would be much simpler.
5246: .Pp
5247: The
5248: .Fl verify
5249: option should really exit if the server verification fails.
5250: .Pp
5251: The
5252: .Fl prexit
5253: option is a bit of a hack.
5254: We should really report information whenever a session is renegotiated.
5255: .\"
5256: .\" S_SERVER
5257: .\"
5258: .Sh S_SERVER
5259: .nr nS 1
5260: .Nm "openssl s_server"
5261: .Bk -words
5262: .Op Fl accept Ar port
5263: .Op Fl bugs
5264: .Op Fl CAfile Ar file
5265: .Op Fl CApath Ar directory
5266: .Op Fl cert Ar file
5267: .Op Fl cipher Ar cipherlist
5268: .Op Fl context Ar id
5269: .Op Fl crl_check
5270: .Op Fl crl_check_all
5271: .Op Fl crlf
5272: .Op Fl dcert Ar file
5273: .Op Fl debug
5274: .Op Fl dhparam Ar file
5275: .Op Fl dkey Ar file
5276: .Op Fl hack
5277: .Op Fl HTTP
5278: .Op Fl id_prefix Ar arg
5279: .Op Fl key Ar keyfile
5280: .Op Fl msg
5281: .Op Fl nbio
5282: .Op Fl nbio_test
5283: .Op Fl no_dhe
5284: .Op Fl no_tls1
1.6 guenther 5285: .Op Fl no_tls1_1
5286: .Op Fl no_tls1_2
1.1 jsing 5287: .Op Fl no_tmp_rsa
5288: .Op Fl nocert
5289: .Op Fl psk Ar key
5290: .Op Fl psk_hint Ar hint
5291: .Op Fl quiet
5292: .Op Fl serverpref
5293: .Op Fl state
5294: .Op Fl tls1
1.31 jmc 5295: .Op Fl tls1_1
5296: .Op Fl tls1_2
1.1 jsing 5297: .Op Fl Verify Ar depth
5298: .Op Fl verify Ar depth
5299: .Op Fl WWW
5300: .Op Fl www
5301: .Ek
5302: .nr nS 0
5303: .Pp
5304: The
5305: .Nm s_server
5306: command implements a generic SSL/TLS server which listens
5307: for connections on a given port using SSL/TLS.
5308: .Pp
5309: The options are as follows:
5310: .Bl -tag -width Ds
5311: .It Fl accept Ar port
5312: The TCP
5313: .Ar port
5314: to listen on for connections.
5315: If not specified, 4433 is used.
5316: .It Fl bugs
5317: There are several known bugs in SSL and TLS implementations.
5318: Adding this option enables various workarounds.
5319: .It Fl CAfile Ar file
5320: A file containing trusted certificates to use during client authentication
5321: and to use when attempting to build the server certificate chain.
5322: The list is also used in the list of acceptable client CAs passed to the
5323: client when a certificate is requested.
5324: .It Fl CApath Ar directory
5325: The
5326: .Ar directory
5327: to use for client certificate verification.
5328: This directory must be in
5329: .Qq hash format ;
5330: see
5331: .Fl verify
5332: for more information.
5333: These are also used when building the server certificate chain.
5334: .It Fl cert Ar file
5335: The certificate to use; most server's cipher suites require the use of a
5336: certificate and some require a certificate with a certain public key type:
5337: for example the DSS cipher suites require a certificate containing a DSS
5338: .Pq DSA
5339: key.
5340: If not specified, the file
5341: .Pa server.pem
5342: will be used.
5343: .It Fl cipher Ar cipherlist
5344: This allows the cipher list used by the server to be modified.
5345: When the client sends a list of supported ciphers, the first client cipher
5346: also included in the server list is used.
5347: Because the client specifies the preference order, the order of the server
5348: cipherlist is irrelevant.
5349: See the
5350: .Sx CIPHERS
5351: section for more information.
5352: .It Fl context Ar id
5353: Sets the SSL context ID.
5354: It can be given any string value.
5355: If this option is not present, a default value will be used.
5356: .It Fl crl_check , crl_check_all
5357: Check the peer certificate has not been revoked by its CA.
5358: The CRLs are appended to the certificate file.
5359: With the
5360: .Fl crl_check_all
5361: option, all CRLs of all CAs in the chain are checked.
5362: .It Fl crlf
5363: This option translates a line feed from the terminal into CR+LF.
5364: .It Fl dcert Ar file , Fl dkey Ar file
5365: Specify an additional certificate and private key; these behave in the
5366: same manner as the
5367: .Fl cert
5368: and
5369: .Fl key
5370: options except there is no default if they are not specified
5371: .Pq no additional certificate or key is used .
5372: As noted above some cipher suites require a certificate containing a key of
5373: a certain type.
5374: Some cipher suites need a certificate carrying an RSA key
5375: and some a DSS
5376: .Pq DSA
5377: key.
5378: By using RSA and DSS certificates and keys,
5379: a server can support clients which only support RSA or DSS cipher suites
5380: by using an appropriate certificate.
5381: .It Fl debug
5382: Print extensive debugging information including a hex dump of all traffic.
5383: .It Fl dhparam Ar file
5384: The DH parameter file to use.
5385: The ephemeral DH cipher suites generate keys
5386: using a set of DH parameters.
5387: If not specified, an attempt is made to
5388: load the parameters from the server certificate file.
5389: If this fails, a static set of parameters hard coded into the
5390: .Nm s_server
5391: program will be used.
5392: .It Fl hack
5393: This option enables a further workaround for some early Netscape
5394: SSL code
5395: .Pq \&? .
5396: .It Fl HTTP
5397: Emulates a simple web server.
5398: Pages will be resolved relative to the current directory;
5399: for example if the URL
5400: .Pa https://myhost/page.html
5401: is requested, the file
5402: .Pa ./page.html
5403: will be loaded.
5404: The files loaded are assumed to contain a complete and correct HTTP
5405: response (lines that are part of the HTTP response line and headers
5406: must end with CRLF).
5407: .It Fl id_prefix Ar arg
5408: Generate SSL/TLS session IDs prefixed by
5409: .Ar arg .
5410: This is mostly useful for testing any SSL/TLS code
5411: .Pq e.g. proxies
5412: that wish to deal with multiple servers, when each of which might be
5413: generating a unique range of session IDs
5414: .Pq e.g. with a certain prefix .
5415: .It Fl key Ar keyfile
5416: The private key to use.
5417: If not specified, the certificate file will be used.
5418: .It Fl msg
5419: Show all protocol messages with hex dump.
5420: .It Fl nbio
5421: Turns on non-blocking I/O.
5422: .It Fl nbio_test
5423: Tests non-blocking I/O.
5424: .It Fl no_dhe
5425: If this option is set, no DH parameters will be loaded, effectively
5426: disabling the ephemeral DH cipher suites.
1.31 jmc 5427: .It Fl no_tls1 | no_tls1_1 | no_tls1_2
1.1 jsing 5428: By default, the initial handshake uses a method which should be compatible
1.32 jmc 5429: with clients supporting any version of TLS.
1.31 jmc 5430: These options disable the use of TLS1.0, 1.1, and 1.2, respectively.
1.1 jsing 5431: .It Fl no_tmp_rsa
5432: Certain export cipher suites sometimes use a temporary RSA key; this option
5433: disables temporary RSA key generation.
5434: .It Fl nocert
5435: If this option is set, no certificate is used.
5436: This restricts the cipher suites available to the anonymous ones
5437: .Pq currently just anonymous DH .
5438: .It Fl psk Ar key
5439: Use the PSK key
5440: .Ar key
5441: when using a PSK cipher suite.
5442: The key is given as a hexadecimal number without the leading 0x,
5443: for example -psk 1a2b3c4d.
5444: .It Fl psk_hint Ar hint
5445: Use the PSK identity hint
5446: .Ar hint
5447: when using a PSK cipher suite.
5448: .It Fl quiet
5449: Inhibit printing of session and certificate information.
5450: .It Fl serverpref
5451: Use server's cipher preferences.
5452: .It Fl state
5453: Prints out the SSL session states.
1.31 jmc 5454: .It Fl tls1 | tls1_1 | tls1_2
5455: Permit only TLS1.0, 1.1, or 1.2, respectively.
1.1 jsing 5456: .It Fl WWW
5457: Emulates a simple web server.
5458: Pages will be resolved relative to the current directory;
5459: for example if the URL
5460: .Pa https://myhost/page.html
5461: is requested, the file
5462: .Pa ./page.html
5463: will be loaded.
5464: .It Fl www
5465: Sends a status message back to the client when it connects.
5466: This includes lots of information about the ciphers used and various
5467: session parameters.
5468: The output is in HTML format so this option will normally be used with a
5469: web browser.
5470: .It Fl Verify Ar depth , Fl verify Ar depth
5471: The verify
5472: .Ar depth
5473: to use.
5474: This specifies the maximum length of the client certificate chain
5475: and makes the server request a certificate from the client.
5476: With the
5477: .Fl Verify
5478: option, the client must supply a certificate or an error occurs.
5479: With the
5480: .Fl verify
5481: option, a certificate is requested but the client does not have to send one.
5482: .El
5483: .Sh S_SERVER CONNECTED COMMANDS
5484: If a connection request is established with an SSL client and neither the
5485: .Fl www
5486: nor the
5487: .Fl WWW
5488: option has been used, then normally any data received
5489: from the client is displayed and any key presses will be sent to the client.
5490: .Pp
5491: Certain single letter commands are also recognized which perform special
5492: operations: these are listed below.
5493: .Bl -tag -width "XXXX"
5494: .It Ar P
5495: Send some plain text down the underlying TCP connection: this should
5496: cause the client to disconnect due to a protocol violation.
5497: .It Ar Q
5498: End the current SSL connection and exit.
5499: .It Ar q
5500: End the current SSL connection, but still accept new connections.
5501: .It Ar R
5502: Renegotiate the SSL session and request a client certificate.
5503: .It Ar r
5504: Renegotiate the SSL session.
5505: .It Ar S
5506: Print out some session cache status information.
5507: .El
5508: .Sh S_SERVER NOTES
5509: .Nm s_server
5510: can be used to debug SSL clients.
5511: To accept connections from a web browser the command:
5512: .Pp
5513: .Dl $ openssl s_server -accept 443 -www
5514: .Pp
5515: can be used, for example.
5516: .Pp
5517: Most web browsers
5518: .Pq in particular Netscape and MSIE
5519: only support RSA cipher suites, so they cannot connect to servers
5520: which don't use a certificate carrying an RSA key or a version of
5521: .Nm OpenSSL
5522: with RSA disabled.
5523: .Pp
5524: Although specifying an empty list of CAs when requesting a client certificate
5525: is strictly speaking a protocol violation, some SSL
5526: clients interpret this to mean any CA is acceptable.
5527: This is useful for debugging purposes.
5528: .Pp
5529: The session parameters can printed out using the
5530: .Nm sess_id
5531: program.
5532: .Sh S_SERVER BUGS
5533: Because this program has a lot of options and also because some of
5534: the techniques used are rather old, the C source of
5535: .Nm s_server
5536: is rather hard to read and not a model of how things should be done.
5537: A typical SSL server program would be much simpler.
5538: .Pp
5539: The output of common ciphers is wrong: it just gives the list of ciphers that
5540: .Nm OpenSSL
5541: recognizes and the client supports.
5542: .Pp
5543: There should be a way for the
5544: .Nm s_server
5545: program to print out details of any
5546: unknown cipher suites a client says it supports.
5547: .\"
5548: .\" S_TIME
5549: .\"
5550: .Sh S_TIME
5551: .nr nS 1
5552: .Nm "openssl s_time"
5553: .Bk -words
5554: .Op Fl bugs
5555: .Op Fl CAfile Ar file
5556: .Op Fl CApath Ar directory
5557: .Op Fl cert Ar file
5558: .Op Fl cipher Ar cipherlist
5559: .Op Fl connect Ar host : Ns Ar port
5560: .Op Fl key Ar keyfile
5561: .Op Fl nbio
5562: .Op Fl new
1.20 lteo 5563: .Op Fl no_shutdown
1.1 jsing 5564: .Op Fl reuse
5565: .Op Fl time Ar seconds
5566: .Op Fl verify Ar depth
5567: .Op Fl www Ar page
5568: .Ek
5569: .nr nS 0
5570: .Pp
5571: The
5572: .Nm s_client
5573: command implements a generic SSL/TLS client which connects to a
5574: remote host using SSL/TLS.
5575: It can request a page from the server and includes
5576: the time to transfer the payload data in its timing measurements.
5577: It measures the number of connections within a given timeframe,
5578: the amount of data transferred
5579: .Pq if any ,
5580: and calculates the average time spent for one connection.
5581: .Pp
5582: The options are as follows:
5583: .Bl -tag -width Ds
5584: .It Fl bugs
5585: There are several known bugs in SSL and TLS implementations.
5586: Adding this option enables various workarounds.
5587: .It Fl CAfile Ar file
5588: A file containing trusted certificates to use during server authentication
5589: and to use when attempting to build the client certificate chain.
5590: .It Fl CApath Ar directory
5591: The directory to use for server certificate verification.
5592: This directory must be in
5593: .Qq hash format ;
5594: see
5595: .Nm verify
5596: for more information.
5597: These are also used when building the client certificate chain.
5598: .It Fl cert Ar file
5599: The certificate to use, if one is requested by the server.
5600: The default is not to use a certificate.
5601: The file is in PEM format.
5602: .It Fl cipher Ar cipherlist
5603: This allows the cipher list sent by the client to be modified.
5604: Although the server determines which cipher suite is used,
5605: it should take the first supported cipher in the list sent by the client.
5606: See the
5607: .Nm ciphers
5608: command for more information.
5609: .It Fl connect Ar host : Ns Ar port
5610: This specifies the host and optional port to connect to.
5611: .It Fl key Ar keyfile
5612: The private key to use.
5613: If not specified, the certificate file will be used.
5614: The file is in PEM format.
5615: .It Fl nbio
5616: Turns on non-blocking I/O.
5617: .It Fl new
5618: Performs the timing test using a new session ID for each connection.
5619: If neither
5620: .Fl new
5621: nor
5622: .Fl reuse
5623: are specified,
5624: they are both on by default and executed in sequence.
1.20 lteo 5625: .It Fl no_shutdown
1.21 jmc 5626: Shut down the connection without sending a
1.20 lteo 5627: .Dq close notify
5628: shutdown alert to the server.
1.1 jsing 5629: .It Fl reuse
5630: Performs the timing test using the same session ID;
5631: this can be used as a test that session caching is working.
5632: If neither
5633: .Fl new
5634: nor
5635: .Fl reuse
5636: are specified,
5637: they are both on by default and executed in sequence.
5638: .It Fl time Ar seconds
5639: Specifies how long
5640: .Pq in seconds
5641: .Nm s_time
5642: should establish connections and
5643: optionally transfer payload data from a server.
5644: The default is 30 seconds.
5645: Server and client performance and the link speed
5646: determine how many connections
5647: .Nm s_time
5648: can establish.
5649: .It Fl verify Ar depth
5650: The verify depth to use.
5651: This specifies the maximum length of the server certificate chain
5652: and turns on server certificate verification.
5653: Currently the verify operation continues after errors, so all the problems
5654: with a certificate chain can be seen.
5655: As a side effect,
5656: the connection will never fail due to a server certificate verify failure.
5657: .It Fl www Ar page
5658: This specifies the page to GET from the server.
5659: A value of
5660: .Sq /
5661: gets the index.htm[l] page.
5662: If this parameter is not specified,
5663: .Nm s_time
5664: will only perform the handshake to establish SSL connections
5665: but not transfer any payload data.
5666: .El
5667: .Sh S_TIME NOTES
5668: .Nm s_client
5669: can be used to measure the performance of an SSL connection.
5670: To connect to an SSL HTTP server and get the default page the command
5671: .Bd -literal -offset indent
5672: $ openssl s_time -connect servername:443 -www / -CApath yourdir \e
1.18 jmc 5673: -CAfile yourfile.pem -cipher commoncipher
1.1 jsing 5674: .Ed
5675: .Pp
5676: would typically be used
5677: .Pq HTTPS uses port 443 .
5678: .Dq commoncipher
5679: is a cipher to which both client and server can agree;
5680: see the
5681: .Nm ciphers
5682: command for details.
5683: .Pp
5684: If the handshake fails, there are several possible causes:
5685: if it is nothing obvious like no client certificate, the
5686: .Fl bugs
1.18 jmc 5687: option can be tried in case it is a buggy server.
1.1 jsing 5688: .Pp
5689: A frequent problem when attempting to get client certificates working
5690: is that a web client complains it has no certificates or gives an empty
5691: list to choose from.
5692: This is normally because the server is not sending
5693: the clients certificate authority in its
5694: .Qq acceptable CA list
5695: when it requests a certificate.
5696: By using
5697: .Nm s_client ,
5698: the CA list can be viewed and checked.
5699: However some servers only request client authentication
5700: after a specific URL is requested.
5701: To obtain the list in this case, it is necessary to use the
5702: .Fl prexit
5703: option of
5704: .Nm s_client
5705: and send an HTTP request for an appropriate page.
5706: .Pp
5707: If a certificate is specified on the command line using the
5708: .Fl cert
5709: option,
5710: it will not be used unless the server specifically requests
5711: a client certificate.
5712: Therefore merely including a client certificate
5713: on the command line is no guarantee that the certificate works.
5714: .Sh S_TIME BUGS
5715: Because this program does not have all the options of the
5716: .Nm s_client
5717: program to turn protocols on and off,
5718: you may not be able to measure the performance
5719: of all protocols with all servers.
5720: .Pp
5721: The
5722: .Fl verify
5723: option should really exit if the server verification fails.
5724: .\"
5725: .\" SESS_ID
5726: .\"
5727: .Sh SESS_ID
5728: .nr nS 1
5729: .Nm "openssl sess_id"
5730: .Bk -words
5731: .Op Fl cert
5732: .Op Fl context Ar ID
5733: .Op Fl in Ar file
5734: .Op Fl inform Ar DER | PEM
5735: .Op Fl noout
5736: .Op Fl out Ar file
5737: .Op Fl outform Ar DER | PEM
5738: .Op Fl text
5739: .Ek
5740: .nr nS 0
5741: .Pp
5742: The
5743: .Nm sess_id
5744: program processes the encoded version of the SSL session structure and
5745: optionally prints out SSL session details
5746: .Pq for example the SSL session master key
5747: in human readable format.
5748: Since this is a diagnostic tool that needs some knowledge of the SSL
5749: protocol to use properly, most users will not need to use it.
5750: .Pp
5751: The options are as follows:
5752: .Bl -tag -width Ds
5753: .It Fl cert
5754: If a certificate is present in the session,
5755: it will be output using this option;
5756: if the
5757: .Fl text
5758: option is also present, then it will be printed out in text form.
5759: .It Fl context Ar ID
5760: This option can set the session ID so the output session information uses the
5761: supplied
5762: .Ar ID .
5763: The
5764: .Ar ID
5765: can be any string of characters.
5766: This option won't normally be used.
5767: .It Fl in Ar file
5768: This specifies the input
5769: .Ar file
5770: to read session information from, or standard input by default.
5771: .It Fl inform Ar DER | PEM
5772: This specifies the input format.
5773: The
5774: .Ar DER
5775: argument uses an ASN1 DER-encoded
5776: format containing session details.
5777: The precise format can vary from one version to the next.
5778: The
5779: .Ar PEM
5780: form is the default format: it consists of the DER
5781: format base64-encoded with additional header and footer lines.
5782: .It Fl noout
5783: This option prevents output of the encoded version of the session.
5784: .It Fl out Ar file
5785: This specifies the output
5786: .Ar file
5787: to write session information to, or standard
5788: output if this option is not specified.
5789: .It Fl outform Ar DER | PEM
5790: This specifies the output format; the options have the same meaning as the
5791: .Fl inform
5792: option.
5793: .It Fl text
5794: Prints out the various public or private key components in
5795: plain text in addition to the encoded version.
5796: .El
5797: .Sh SESS_ID OUTPUT
5798: Typical output:
5799: .Bd -literal
5800: SSL-Session:
5801: Protocol : TLSv1
5802: Cipher : 0016
5803: Session-ID: 871E62626C554CE95488823752CBD5F3673A3EF3DCE9C67BD916C809914B40ED
5804: Session-ID-ctx: 01000000
5805: Master-Key: A7CEFC571974BE02CAC305269DC59F76EA9F0B180CB6642697A68251F2D2BB57E51DBBB4C7885573192AE9AEE220FACD
5806: Key-Arg : None
5807: Start Time: 948459261
5808: Timeout : 300 (sec)
5809: Verify return code 0 (ok)
5810: .Ed
5811: .Pp
5812: These are described below in more detail.
5813: .Pp
5814: .Bl -tag -width "Verify return code " -compact
5815: .It Ar Protocol
1.18 jmc 5816: This is the protocol in use.
1.1 jsing 5817: .It Ar Cipher
5818: The cipher used is the actual raw SSL or TLS cipher code;
5819: see the SSL or TLS specifications for more information.
5820: .It Ar Session-ID
5821: The SSL session ID in hex format.
5822: .It Ar Session-ID-ctx
5823: The session ID context in hex format.
5824: .It Ar Master-Key
5825: This is the SSL session master key.
5826: .It Ar Key-Arg
5827: The key argument; this is only used in SSL v2.
5828: .It Ar Start Time
5829: This is the session start time, represented as an integer in standard
5830: .Ux
5831: format.
5832: .It Ar Timeout
5833: The timeout in seconds.
5834: .It Ar Verify return code
5835: This is the return code when an SSL client certificate is verified.
5836: .El
5837: .Sh SESS_ID NOTES
5838: The PEM-encoded session format uses the header and footer lines:
5839: .Bd -unfilled -offset indent
5840: -----BEGIN SSL SESSION PARAMETERS-----
5841: -----END SSL SESSION PARAMETERS-----
5842: .Ed
5843: .Pp
5844: Since the SSL session output contains the master key, it is possible to read
5845: the contents of an encrypted session using this information.
5846: Therefore appropriate security precautions
5847: should be taken if the information is being output by a
5848: .Qq real
5849: application.
5850: This is, however, strongly discouraged and should only be used for
5851: debugging purposes.
5852: .Sh SESS_ID BUGS
5853: The cipher and start time should be printed out in human readable form.
5854: .\"
5855: .\" SMIME
5856: .\"
5857: .Sh SMIME
5858: .nr nS 1
5859: .Nm "openssl smime"
5860: .Bk -words
5861: .Oo
5862: .Fl aes128 | aes192 | aes256 | des |
5863: .Fl des3 | rc2-40 | rc2-64 | rc2-128
5864: .Oc
5865: .Op Fl binary
5866: .Op Fl CAfile Ar file
5867: .Op Fl CApath Ar directory
5868: .Op Fl certfile Ar file
5869: .Op Fl check_ss_sig
5870: .Op Fl content Ar file
5871: .Op Fl crl_check
5872: .Op Fl crl_check_all
5873: .Op Fl decrypt
5874: .Op Fl encrypt
5875: .Op Fl extended_crl
5876: .Op Fl from Ar addr
5877: .Op Fl ignore_critical
5878: .Op Fl in Ar file
5879: .Op Fl indef
5880: .Op Fl inform Ar DER | PEM | SMIME
5881: .Op Fl inkey Ar file
5882: .Op Fl issuer_checks
1.22 bcook 5883: .Op Fl keyform Ar PEM
1.1 jsing 5884: .Op Fl md Ar digest
5885: .Op Fl noattr
5886: .Op Fl nocerts
5887: .Op Fl nochain
5888: .Op Fl nodetach
5889: .Op Fl noindef
5890: .Op Fl nointern
5891: .Op Fl nosigs
5892: .Op Fl noverify
5893: .Op Fl out Ar file
5894: .Op Fl outform Ar DER | PEM | SMIME
5895: .Op Fl passin Ar arg
5896: .Op Fl pk7out
5897: .Op Fl policy_check
5898: .Op Fl recip Ar file
5899: .Op Fl resign
5900: .Op Fl sign
5901: .Op Fl signer Ar file
5902: .Op Fl stream
5903: .Op Fl subject Ar s
5904: .Op Fl text
5905: .Op Fl to Ar addr
5906: .Op Fl verify
5907: .Op Fl x509_strict
5908: .Op Ar cert.pem ...
5909: .Ek
5910: .nr nS 0
5911: .Pp
5912: The
5913: .Nm smime
5914: command handles
5915: .Em S/MIME
5916: mail.
5917: It can encrypt, decrypt, sign, and verify
5918: .Em S/MIME
5919: messages.
5920: .Pp
5921: There are six operation options that set the type of operation to be performed.
5922: The meaning of the other options varies according to the operation type.
5923: .Pp
5924: The six operation options are as follows:
5925: .Bl -tag -width "XXXX"
5926: .It Fl decrypt
5927: Decrypt mail using the supplied certificate and private key.
5928: Expects an encrypted mail message in
5929: .Em MIME
5930: format for the input file.
5931: The decrypted mail is written to the output file.
5932: .It Fl encrypt
5933: Encrypt mail for the given recipient certificates.
5934: Input file is the message to be encrypted.
5935: The output file is the encrypted mail in
5936: .Em MIME
5937: format.
5938: .It Fl pk7out
5939: Takes an input message and writes out a PEM-encoded PKCS#7 structure.
5940: .It Fl resign
5941: Resign a message: take an existing message and one or more new signers.
5942: .It Fl sign
5943: Sign mail using the supplied certificate and private key.
5944: Input file is the message to be signed.
5945: The signed message in
5946: .Em MIME
5947: format is written to the output file.
5948: .It Fl verify
5949: Verify signed mail.
5950: Expects a signed mail message on input and outputs the signed data.
5951: Both clear text and opaque signing is supported.
5952: .El
5953: .Pp
1.14 jmc 5954: The remaining options are as follows:
1.1 jsing 5955: .Bl -tag -width "XXXX"
5956: .It Xo
5957: .Fl aes128 | aes192 | aes256 | des |
5958: .Fl des3 | rc2-40 | rc2-64 | rc2-128
5959: .Xc
5960: The encryption algorithm to use.
5961: 128-, 192-, or 256-bit AES,
5962: DES
5963: .Pq 56 bits ,
5964: triple DES
5965: .Pq 168 bits ,
5966: or 40-, 64-, or 128-bit RC2, respectively;
5967: if not specified, 40-bit RC2 is
5968: used.
5969: Only used with
5970: .Fl encrypt .
5971: .It Fl binary
5972: Normally, the input message is converted to
5973: .Qq canonical
5974: format which is effectively using CR and LF as end of line \-
5975: as required by the
5976: .Em S/MIME
5977: specification.
5978: When this option is present no translation occurs.
5979: This is useful when handling binary data which may not be in
5980: .Em MIME
5981: format.
5982: .It Fl CAfile Ar file
5983: A
5984: .Ar file
5985: containing trusted CA certificates; only used with
5986: .Fl verify .
5987: .It Fl CApath Ar directory
5988: A
5989: .Ar directory
5990: containing trusted CA certificates; only used with
5991: .Fl verify .
5992: This directory must be a standard certificate directory:
5993: that is, a hash of each subject name (using
5994: .Nm x509 -hash )
5995: should be linked to each certificate.
5996: .It Ar cert.pem ...
5997: One or more certificates of message recipients: used when encrypting
5998: a message.
5999: .It Fl certfile Ar file
6000: Allows additional certificates to be specified.
6001: When signing, these will be included with the message.
6002: When verifying, these will be searched for the signers' certificates.
6003: The certificates should be in PEM format.
6004: .It Xo
6005: .Fl check_ss_sig ,
6006: .Fl crl_check ,
6007: .Fl crl_check_all ,
6008: .Fl extended_crl ,
6009: .Fl ignore_critical ,
6010: .Fl issuer_checks ,
6011: .Fl policy_check ,
6012: .Fl x509_strict
6013: .Xc
6014: Set various certificate chain validation options.
6015: See the
6016: .Nm VERIFY
6017: command for details.
6018: .It Fl content Ar file
6019: This specifies a file containing the detached content.
6020: This is only useful with the
6021: .Fl verify
6022: command.
6023: This is only usable if the PKCS#7 structure is using the detached
6024: signature form where the content is not included.
6025: This option will override any content if the input format is
6026: .Em S/MIME
6027: and it uses the multipart/signed
6028: .Em MIME
6029: content type.
6030: .It Xo
6031: .Fl from Ar addr ,
6032: .Fl subject Ar s ,
6033: .Fl to Ar addr
6034: .Xc
6035: The relevant mail headers.
6036: These are included outside the signed
6037: portion of a message so they may be included manually.
6038: When signing, many
6039: .Em S/MIME
6040: mail clients check that the signer's certificate email
6041: address matches the From: address.
6042: .It Fl in Ar file
6043: The input message to be encrypted or signed or the
6044: .Em MIME
6045: message to
6046: be decrypted or verified.
6047: .It Fl indef
6048: Enable streaming I/O for encoding operations.
6049: This permits single pass processing of data without
6050: the need to hold the entire contents in memory,
6051: potentially supporting very large files.
6052: Streaming is automatically set for S/MIME signing with detached
6053: data if the output format is SMIME;
6054: it is currently off by default for all other operations.
6055: .It Fl inform Ar DER | PEM | SMIME
6056: This specifies the input format for the PKCS#7 structure.
6057: The default is
6058: .Em SMIME ,
6059: which reads an
6060: .Em S/MIME
6061: format message.
6062: .Ar PEM
6063: and
6064: .Ar DER
6065: format change this to expect PEM and DER format PKCS#7 structures
6066: instead.
6067: This currently only affects the input format of the PKCS#7
6068: structure; if no PKCS#7 structure is being input (for example with
6069: .Fl encrypt
6070: or
6071: .Fl sign ) ,
6072: this option has no effect.
6073: .It Fl inkey Ar file
6074: The private key to use when signing or decrypting.
6075: This must match the corresponding certificate.
6076: If this option is not specified, the private key must be included
6077: in the certificate file specified with
6078: the
6079: .Fl recip
6080: or
6081: .Fl signer
6082: file.
6083: When signing,
6084: this option can be used multiple times to specify successive keys.
1.22 bcook 6085: .It Fl keyform Ar PEM
1.1 jsing 6086: Input private key format.
6087: .It Fl md Ar digest
6088: The digest algorithm to use when signing or resigning.
6089: If not present then the default digest algorithm for the signing key is used
6090: (usually SHA1).
6091: .It Fl noattr
6092: Normally, when a message is signed a set of attributes are included which
6093: include the signing time and supported symmetric algorithms.
6094: With this option they are not included.
6095: .It Fl nocerts
6096: When signing a message, the signer's certificate is normally included;
6097: with this option it is excluded.
6098: This will reduce the size of the signed message but the verifier must
6099: have a copy of the signer's certificate available locally (passed using the
6100: .Fl certfile
6101: option, for example).
6102: .It Fl nochain
6103: Do not do chain verification of signers' certificates: that is,
6104: don't use the certificates in the signed message as untrusted CAs.
6105: .It Fl nodetach
6106: When signing a message use opaque signing: this form is more resistant
6107: to translation by mail relays but it cannot be read by mail agents that
6108: do not support
6109: .Em S/MIME .
6110: Without this option cleartext signing with the
6111: .Em MIME
6112: type multipart/signed is used.
6113: .It Fl noindef
6114: Disable streaming I/O where it would produce an encoding of indefinite length.
6115: This option currently has no effect.
6116: In future streaming will be enabled by default on all relevant operations
6117: and this option will disable it.
6118: .It Fl nointern
6119: When verifying a message, normally certificates
6120: .Pq if any
6121: included in the message are searched for the signing certificate.
6122: With this option, only the certificates specified in the
6123: .Fl certfile
6124: option are used.
6125: The supplied certificates can still be used as untrusted CAs however.
6126: .It Fl nosigs
6127: Don't try to verify the signatures on the message.
6128: .It Fl noverify
6129: Do not verify the signer's certificate of a signed message.
6130: .It Fl out Ar file
6131: The message text that has been decrypted or verified, or the output
6132: .Em MIME
6133: format message that has been signed or verified.
6134: .It Fl outform Ar DER | PEM | SMIME
6135: This specifies the output format for the PKCS#7 structure.
6136: The default is
6137: .Em SMIME ,
6138: which writes an
6139: .Em S/MIME
6140: format message.
6141: .Ar PEM
6142: and
6143: .Ar DER
6144: format change this to write PEM and DER format PKCS#7 structures
6145: instead.
6146: This currently only affects the output format of the PKCS#7
6147: structure; if no PKCS#7 structure is being output (for example with
6148: .Fl verify
6149: or
6150: .Fl decrypt )
6151: this option has no effect.
6152: .It Fl passin Ar arg
6153: The key password source.
6154: .It Fl recip Ar file
6155: The recipients certificate when decrypting a message.
6156: This certificate
6157: must match one of the recipients of the message or an error occurs.
6158: .It Fl signer Ar file
6159: A signing certificate when signing or resigning a message;
6160: this option can be used multiple times if more than one signer is required.
6161: If a message is being verified, the signer's certificates will be
6162: written to this file if the verification was successful.
6163: .It Fl stream
6164: The same as
6165: .Fl indef .
6166: .It Fl text
6167: This option adds plain text
6168: .Pq text/plain
6169: .Em MIME
6170: headers to the supplied message if encrypting or signing.
6171: If decrypting or verifying, it strips off text headers:
6172: if the decrypted or verified message is not of
6173: .Em MIME
6174: type text/plain then an error occurs.
6175: .El
6176: .Sh SMIME NOTES
6177: The
6178: .Em MIME
6179: message must be sent without any blank lines between the
6180: headers and the output.
6181: Some mail programs will automatically add a blank line.
1.3 jmc 6182: Piping the mail directly to an MTA is one way to
1.1 jsing 6183: achieve the correct format.
6184: .Pp
6185: The supplied message to be signed or encrypted must include the
6186: necessary
6187: .Em MIME
6188: headers or many
6189: .Em S/MIME
6190: clients won't display it properly
6191: .Pq if at all .
6192: You can use the
6193: .Fl text
6194: option to automatically add plain text headers.
6195: .Pp
6196: A
6197: .Qq signed and encrypted
6198: message is one where a signed message is then encrypted.
6199: This can be produced by encrypting an already signed message:
6200: see the
6201: .Sx SMIME EXAMPLES
6202: section.
6203: .Pp
6204: This version of the program only allows one signer per message, but it
6205: will verify multiple signers on received messages.
6206: Some
6207: .Em S/MIME
6208: clients choke if a message contains multiple signers.
6209: It is possible to sign messages
6210: .Qq in parallel
6211: by signing an already signed message.
6212: .Pp
6213: The options
6214: .Fl encrypt
6215: and
6216: .Fl decrypt
6217: reflect common usage in
6218: .Em S/MIME
6219: clients.
6220: Strictly speaking these process PKCS#7 enveloped data: PKCS#7
6221: encrypted data is used for other purposes.
6222: .Pp
6223: The
6224: .Fl resign
6225: option uses an existing message digest when adding a new signer.
6226: This means that attributes must be present in at least one existing
6227: signer using the same message digest or this operation will fail.
6228: .Pp
6229: The
6230: .Fl stream
6231: and
6232: .Fl indef
6233: options enable experimental streaming I/O support.
6234: As a result the encoding is BER using indefinite length constructed encoding
6235: and no longer DER.
6236: Streaming is supported for the
6237: .Fl encrypt
6238: and
6239: .Fl sign
6240: operations if the content is not detached.
6241: .Pp
6242: Streaming is always used for the
6243: .Fl sign
6244: operation with detached data
6245: but since the content is no longer part of the PKCS#7 structure
6246: the encoding remains DER.
6247: .Sh SMIME EXIT CODES
6248: .Bl -tag -width "XXXX"
6249: .It Ar 0
6250: The operation was completely successful.
6251: .It Ar 1
6252: An error occurred parsing the command options.
6253: .It Ar 2
6254: One of the input files could not be read.
6255: .It Ar 3
6256: An error occurred creating the PKCS#7 file or when reading the
6257: .Em MIME
6258: message.
6259: .It Ar 4
6260: An error occurred decrypting or verifying the message.
6261: .It Ar 5
6262: The message was verified correctly, but an error occurred writing out
6263: the signer's certificates.
6264: .El
6265: .Sh SMIME EXAMPLES
6266: Create a cleartext signed message:
6267: .Bd -literal -offset indent
6268: $ openssl smime -sign -in message.txt -text -out mail.msg \e
6269: -signer mycert.pem
6270: .Ed
6271: .Pp
6272: Create an opaque signed message:
6273: .Bd -literal -offset indent
6274: $ openssl smime -sign -in message.txt -text -out mail.msg \e
6275: -nodetach -signer mycert.pem
6276: .Ed
6277: .Pp
6278: Create a signed message, include some additional certificates and
6279: read the private key from another file:
6280: .Bd -literal -offset indent
6281: $ openssl smime -sign -in in.txt -text -out mail.msg \e
6282: -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
6283: .Ed
6284: .Pp
6285: Create a signed message with two signers:
6286: .Bd -literal -offset indent
6287: openssl smime -sign -in message.txt -text -out mail.msg \e
6288: -signer mycert.pem -signer othercert.pem
6289: .Ed
6290: .Pp
6291: Send a signed message under
6292: .Ux
6293: directly to
6294: .Xr sendmail 8 ,
6295: including headers:
6296: .Bd -literal -offset indent
6297: $ openssl smime -sign -in in.txt -text -signer mycert.pem \e
6298: -from steve@openssl.org -to someone@somewhere \e
6299: -subject "Signed message" | sendmail someone@somewhere
6300: .Ed
6301: .Pp
6302: Verify a message and extract the signer's certificate if successful:
6303: .Bd -literal -offset indent
6304: $ openssl smime -verify -in mail.msg -signer user.pem \e
6305: -out signedtext.txt
6306: .Ed
6307: .Pp
6308: Send encrypted mail using triple DES:
6309: .Bd -literal -offset indent
6310: $ openssl smime -encrypt -in in.txt -from steve@openssl.org \e
6311: -to someone@somewhere -subject "Encrypted message" \e
6312: -des3 -out mail.msg user.pem
6313: .Ed
6314: .Pp
6315: Sign and encrypt mail:
6316: .Bd -literal -offset indent
6317: $ openssl smime -sign -in ml.txt -signer my.pem -text | \e
6318: openssl smime -encrypt -out mail.msg \e
6319: -from steve@openssl.org -to someone@somewhere \e
6320: -subject "Signed and Encrypted message" -des3 user.pem
6321: .Ed
6322: .Pp
6323: .Sy Note :
6324: The encryption command does not include the
6325: .Fl text
6326: option because the message being encrypted already has
6327: .Em MIME
6328: headers.
6329: .Pp
6330: Decrypt mail:
6331: .Bd -literal -offset indent
6332: $ openssl smime -decrypt -in mail.msg -recip mycert.pem \e
6333: -inkey key.pem"
6334: .Ed
6335: .Pp
6336: The output from Netscape form signing is a PKCS#7 structure with the
6337: detached signature format.
6338: You can use this program to verify the signature by line wrapping the
6339: base64-encoded structure and surrounding it with:
6340: .Bd -unfilled -offset indent
6341: -----BEGIN PKCS7-----
6342: -----END PKCS7-----
6343: .Ed
6344: .Pp
6345: and using the command:
6346: .Bd -literal -offset indent
6347: $ openssl smime -verify -inform PEM -in signature.pem \e
6348: -content content.txt
6349: .Ed
6350: .Pp
6351: Alternatively, you can base64 decode the signature and use:
6352: .Bd -literal -offset indent
6353: $ openssl smime -verify -inform DER -in signature.der \e
6354: -content content.txt
6355: .Ed
6356: .Pp
6357: Create an encrypted message using 128-bit AES:
6358: .Bd -literal -offset indent
6359: openssl smime -encrypt -in plain.txt -aes128 \e
6360: -out mail.msg cert.pem
6361: .Ed
6362: .Pp
6363: Add a signer to an existing message:
6364: .Bd -literal -offset indent
6365: openssl smime -resign -in mail.msg -signer newsign.pem \e
6366: -out mail2.msg
6367: .Ed
6368: .Sh SMIME BUGS
6369: The
6370: .Em MIME
6371: parser isn't very clever: it seems to handle most messages that I've thrown
6372: at it, but it may choke on others.
6373: .Pp
6374: The code currently will only write out the signer's certificate to a file:
6375: if the signer has a separate encryption certificate this must be manually
6376: extracted.
6377: There should be some heuristic that determines the correct encryption
6378: certificate.
6379: .Pp
6380: Ideally, a database should be maintained of a certificate for each email
6381: address.
6382: .Pp
6383: The code doesn't currently take note of the permitted symmetric encryption
6384: algorithms as supplied in the
6385: .Em SMIMECapabilities
6386: signed attribute.
6387: This means the user has to manually include the correct encryption algorithm.
6388: It should store the list of permitted ciphers in a database and only use those.
6389: .Pp
6390: No revocation checking is done on the signer's certificate.
6391: .Pp
6392: The current code can only handle
6393: .Em S/MIME
6394: v2 messages; the more complex
6395: .Em S/MIME
6396: v3 structures may cause parsing errors.
6397: .Sh SMIME HISTORY
6398: The use of multiple
6399: .Fl signer
6400: options and the
6401: .Fl resign
6402: command were first added in
6403: .Nm OpenSSL
6404: 1.0.0.
6405: .\"
6406: .\" SPEED
6407: .\"
6408: .Sh SPEED
6409: .nr nS 1
6410: .Nm "openssl speed"
6411: .Bk -words
6412: .Op Cm aes
6413: .Op Cm aes-128-cbc
6414: .Op Cm aes-192-cbc
6415: .Op Cm aes-256-cbc
1.25 bcook 6416: .Op Cm aes-128-gcm
6417: .Op Cm aes-256-gcm
1.1 jsing 6418: .Op Cm blowfish
6419: .Op Cm bf-cbc
6420: .Op Cm cast
6421: .Op Cm cast-cbc
1.25 bcook 6422: .Op Cm chacha20-poly1305
1.1 jsing 6423: .Op Cm des
6424: .Op Cm des-cbc
6425: .Op Cm des-ede3
6426: .Op Cm dsa
6427: .Op Cm dsa512
6428: .Op Cm dsa1024
6429: .Op Cm dsa2048
6430: .Op Cm hmac
1.28 doug 6431: .Op Cm md4
1.1 jsing 6432: .Op Cm md5
6433: .Op Cm rc2
6434: .Op Cm rc2-cbc
6435: .Op Cm rc4
6436: .Op Cm rmd160
6437: .Op Cm rsa
6438: .Op Cm rsa512
6439: .Op Cm rsa1024
6440: .Op Cm rsa2048
6441: .Op Cm rsa4096
6442: .Op Cm sha1
6443: .Op Fl decrypt
6444: .Op Fl elapsed
6445: .Op Fl evp Ar e
6446: .Op Fl mr
6447: .Op Fl multi Ar number
6448: .Ek
6449: .nr nS 0
6450: .Pp
6451: The
6452: .Nm speed
6453: command is used to test the performance of cryptographic algorithms.
6454: .Bl -tag -width "XXXX"
6455: .It Bq Cm zero or more test algorithms
6456: If any options are given,
6457: .Nm speed
6458: tests those algorithms, otherwise all of the above are tested.
6459: .It Fl decrypt
6460: Time decryption instead of encryption
6461: .Pq only EVP .
6462: .It Fl elapsed
6463: Measure time in real time instead of CPU user time.
6464: .It Fl evp Ar e
6465: Use EVP
6466: .Ar e .
6467: .It Fl mr
6468: Produce machine readable output.
6469: .It Fl multi Ar number
6470: Run
6471: .Ar number
6472: benchmarks in parallel.
6473: .El
6474: .\"
6475: .\" TS
6476: .\"
6477: .Sh TS
6478: .nr nS 1
6479: .Nm "openssl ts"
6480: .Bk -words
6481: .Fl query
1.29 bcook 6482: .Op Fl md4 | md5 | ripemd160 | sha1
1.1 jsing 6483: .Op Fl cert
6484: .Op Fl config Ar configfile
6485: .Op Fl data Ar file_to_hash
6486: .Op Fl digest Ar digest_bytes
6487: .Op Fl in Ar request.tsq
6488: .Op Fl no_nonce
6489: .Op Fl out Ar request.tsq
6490: .Op Fl policy Ar object_id
6491: .Op Fl text
6492: .Ek
6493: .nr nS 0
6494: .Pp
6495: .nr nS 1
6496: .Nm "openssl ts"
6497: .Bk -words
6498: .Fl reply
6499: .Op Fl chain Ar certs_file.pem
6500: .Op Fl config Ar configfile
6501: .Op Fl in Ar response.tsr
6502: .Op Fl inkey Ar private.pem
6503: .Op Fl out Ar response.tsr
6504: .Op Fl passin Ar arg
6505: .Op Fl policy Ar object_id
6506: .Op Fl queryfile Ar request.tsq
6507: .Op Fl section Ar tsa_section
6508: .Op Fl signer Ar tsa_cert.pem
6509: .Op Fl text
6510: .Op Fl token_in
6511: .Op Fl token_out
6512: .Ek
6513: .nr nS 0
6514: .Pp
6515: .nr nS 1
6516: .Nm "openssl ts"
6517: .Bk -words
6518: .Fl verify
6519: .Op Fl CAfile Ar trusted_certs.pem
6520: .Op Fl CApath Ar trusted_cert_path
6521: .Op Fl data Ar file_to_hash
6522: .Op Fl digest Ar digest_bytes
6523: .Op Fl in Ar response.tsr
6524: .Op Fl queryfile Ar request.tsq
6525: .Op Fl token_in
6526: .Op Fl untrusted Ar cert_file.pem
6527: .Ek
6528: .nr nS 0
6529: .Pp
6530: The
6531: .Nm ts
6532: command is a basic Time Stamping Authority (TSA) client and server
6533: application as specified in RFC 3161 (Time-Stamp Protocol, TSP).
6534: A TSA can be part of a PKI deployment and its role is to provide long
6535: term proof of the existence of a certain datum before a particular time.
6536: Here is a brief description of the protocol:
6537: .Bl -enum
6538: .It
6539: The TSA client computes a one-way hash value for a data file and sends
6540: the hash to the TSA.
6541: .It
6542: The TSA attaches the current date and time to the received hash value,
6543: signs them and sends the time stamp token back to the client.
6544: By creating this token the TSA certifies the existence of the original
6545: data file at the time of response generation.
6546: .It
6547: The TSA client receives the time stamp token and verifies the
6548: signature on it.
6549: It also checks if the token contains the same hash
6550: value that it had sent to the TSA.
6551: .El
6552: .Pp
6553: There is one DER-encoded protocol data unit defined for transporting a time
6554: stamp request to the TSA and one for sending the time stamp response
6555: back to the client.
6556: The
6557: .Nm ts
6558: command has three main functions:
6559: creating a time stamp request based on a data file;
6560: creating a time stamp response based on a request;
6561: and verifying if a response corresponds
6562: to a particular request or a data file.
6563: .Pp
6564: There is no support for sending the requests/responses automatically
6565: over HTTP or TCP yet as suggested in RFC 3161.
6566: Users must send the requests either by FTP or email.
6567: .Pp
6568: The
6569: .Fl query
6570: switch can be used for creating and printing a time stamp
6571: request with the following options:
6572: .Bl -tag -width Ds
6573: .It Fl cert
6574: The TSA is expected to include its signing certificate in the
6575: response.
6576: .It Fl config Ar configfile
6577: The configuration file to use.
6578: This option overrides the
6579: .Ev OPENSSL_CONF
6580: environment variable.
6581: Only the OID section of the config file is used with the
6582: .Fl query
6583: command.
6584: .It Fl data Ar file_to_hash
6585: The data file for which the time stamp request needs to be created.
6586: stdin is the default if neither the
6587: .Fl data
6588: nor the
6589: .Fl digest
6590: option is specified.
6591: .It Fl digest Ar digest_bytes
6592: It is possible to specify the message imprint explicitly without the data
6593: file.
6594: The imprint must be specified in a hexadecimal format,
6595: two characters per byte,
6596: the bytes optionally separated by colons (e.g. 1A:F6:01:... or 1AF601...).
6597: The number of bytes must match the message digest algorithm in use.
6598: .It Fl in Ar request.tsq
6599: This option specifies a previously created time stamp request in DER
6600: format that will be printed into the output file.
6601: Useful when you need to examine the content of a request in human-readable
6602: format.
1.28 doug 6603: .It Fl md4|md5|ripemd160|sha|sha1
1.1 jsing 6604: The message digest to apply to the data file.
6605: It supports all the message digest algorithms that are supported by the
6606: .Nm dgst
6607: command.
6608: The default is SHA-1.
6609: .It Fl no_nonce
6610: No nonce is specified in the request if this option is given.
6611: Otherwise a 64-bit long pseudo-random none is
6612: included in the request.
6613: It is recommended to use nonce to protect against replay-attacks.
6614: .It Fl out Ar request.tsq
6615: Name of the output file to which the request will be written.
6616: The default is stdout.
6617: .It Fl policy Ar object_id
6618: The policy that the client expects the TSA to use for creating the
6619: time stamp token.
6620: Either the dotted OID notation or OID names defined
6621: in the config file can be used.
6622: If no policy is requested the TSA will
6623: use its own default policy.
6624: .It Fl text
6625: If this option is specified the output is in human-readable text format
6626: instead of DER.
6627: .El
6628: .Pp
6629: A time stamp response (TimeStampResp) consists of a response status
6630: and the time stamp token itself (ContentInfo),
6631: if the token generation was successful.
6632: The
6633: .Fl reply
6634: command is for creating a time stamp
6635: response or time stamp token based on a request and printing the
6636: response/token in human-readable format.
6637: If
6638: .Fl token_out
6639: is not specified the output is always a time stamp response (TimeStampResp),
6640: otherwise it is a time stamp token (ContentInfo).
6641: .Bl -tag -width Ds
6642: .It Fl chain Ar certs_file.pem
6643: The collection of certificates, in PEM format,
6644: that will be included in the response
6645: in addition to the signer certificate if the
6646: .Fl cert
6647: option was used for the request.
6648: This file is supposed to contain the certificate chain
6649: for the signer certificate from its issuer upwards.
6650: The
6651: .Fl reply
6652: command does not build a certificate chain automatically.
6653: .It Fl config Ar configfile
6654: The configuration file to use.
6655: This option overrides the
6656: .Ev OPENSSL_CONF
6657: environment variable.
6658: See
6659: .Sx TS CONFIGURATION FILE OPTIONS
6660: for configurable variables.
6661: .It Fl in Ar response.tsr
6662: Specifies a previously created time stamp response or time stamp token, if
6663: .Fl token_in
6664: is also specified,
6665: in DER format that will be written to the output file.
6666: This option does not require a request;
6667: it is useful, for example,
6668: when you need to examine the content of a response or token
6669: or you want to extract the time stamp token from a response.
6670: If the input is a token and the output is a time stamp response a default
6671: .Dq granted
6672: status info is added to the token.
6673: .It Fl inkey Ar private.pem
6674: The signer private key of the TSA in PEM format.
6675: Overrides the
6676: .Cm signer_key
6677: config file option.
6678: .It Fl out Ar response.tsr
6679: The response is written to this file.
6680: The format and content of the file depends on other options (see
6681: .Fl text
6682: and
6683: .Fl token_out ) .
6684: The default is stdout.
6685: .It Fl passin Ar arg
6686: The key password source.
6687: .It Fl policy Ar object_id
6688: The default policy to use for the response unless the client
6689: explicitly requires a particular TSA policy.
6690: The OID can be specified either in dotted notation or with its name.
6691: Overrides the
6692: .Cm default_policy
6693: config file option.
6694: .It Fl queryfile Ar request.tsq
6695: The name of the file containing a DER-encoded time stamp request.
6696: .It Fl section Ar tsa_section
6697: The name of the config file section containing the settings for the
6698: response generation.
6699: If not specified the default TSA section is used; see
6700: .Sx TS CONFIGURATION FILE OPTIONS
6701: for details.
6702: .It Fl signer Ar tsa_cert.pem
6703: The signer certificate of the TSA in PEM format.
6704: The TSA signing certificate must have exactly one extended key usage
6705: assigned to it: timeStamping.
6706: The extended key usage must also be critical,
6707: otherwise the certificate is going to be refused.
6708: Overrides the
6709: .Cm signer_cert
6710: variable of the config file.
6711: .It Fl text
6712: If this option is specified the output is human-readable text format
6713: instead of DER.
6714: .It Fl token_in
6715: This flag can be used together with the
6716: .Fl in
6717: option and indicates that the input is a DER-encoded time stamp token
6718: (ContentInfo) instead of a time stamp response (TimeStampResp).
6719: .It Fl token_out
6720: The output is a time stamp token (ContentInfo) instead of time stamp
6721: response (TimeStampResp).
6722: .El
6723: .Pp
6724: The
6725: .Fl verify
6726: command is for verifying if a time stamp response or time stamp token
6727: is valid and matches a particular time stamp request or data file.
6728: The
6729: .Fl verify
6730: command does not use the configuration file.
6731: .Bl -tag -width Ds
6732: .It Fl CAfile Ar trusted_certs.pem
6733: The name of the file containing a set of trusted self-signed CA
6734: certificates in PEM format.
6735: See the similar option of
6736: .Nm verify
6737: for additional details.
6738: Either this option or
6739: .Fl CApath
6740: must be specified.
6741: .It Fl CApath Ar trusted_cert_path
6742: The name of the directory containing the trused CA certificates of the
6743: client.
6744: See the similar option of
6745: .Nm verify
6746: for additional details.
6747: Either this option or
6748: .Fl CAfile
6749: must be specified.
6750: .It Fl data Ar file_to_hash
6751: The response or token must be verified against
6752: .Ar file_to_hash .
6753: The file is hashed with the message digest algorithm specified in the token.
6754: The
6755: .Fl digest
6756: and
6757: .Fl queryfile
6758: options must not be specified with this one.
6759: .It Fl digest Ar digest_bytes
6760: The response or token must be verified against the message digest specified
6761: with this option.
6762: The number of bytes must match the message digest algorithm
6763: specified in the token.
6764: The
6765: .Fl data
6766: and
6767: .Fl queryfile
6768: options must not be specified with this one.
6769: .It Fl in Ar response.tsr
6770: The time stamp response that needs to be verified, in DER format.
6771: This option in mandatory.
6772: .It Fl queryfile Ar request.tsq
6773: The original time stamp request, in DER format.
6774: The
6775: .Fl data
6776: and
6777: .Fl digest
6778: options must not be specified with this one.
6779: .It Fl token_in
6780: This flag can be used together with the
6781: .Fl in
6782: option and indicates that the input is a DER-encoded time stamp token
6783: (ContentInfo) instead of a time stamp response (TimeStampResp).
6784: .It Fl untrusted Ar cert_file.pem
6785: Set of additional untrusted certificates in PEM format which may be
6786: needed when building the certificate chain for the TSA's signing
6787: certificate.
6788: This file must contain the TSA signing certificate and
6789: all intermediate CA certificates unless the response includes them.
6790: .El
6791: .Sh TS CONFIGURATION FILE OPTIONS
6792: The
6793: .Fl query
6794: and
6795: .Fl reply
6796: options make use of a configuration file defined by the
6797: .Ev OPENSSL_CONF
6798: environment variable.
6799: The
6800: .Fl query
6801: option uses only the symbolic OID names section
6802: and it can work without it.
6803: However, the
6804: .Fl reply
6805: option needs the config file for its operation.
6806: .Pp
6807: When there is a command line switch equivalent of a variable the
6808: switch always overrides the settings in the config file.
6809: .Bl -tag -width Ds
6810: .It Cm tsa Ar section , Cm default_tsa
6811: This is the main section and it specifies the name of another section
6812: that contains all the options for the
6813: .Fl reply
6814: option.
6815: This default section can be overridden with the
6816: .Fl section
6817: command line switch.
6818: .It Cm oid_file
6819: See
6820: .Nm ca
6821: for a description.
6822: .It Cm oid_section
6823: See
6824: .Nm ca
6825: for a description.
6826: .It Cm serial
6827: The name of the file containing the hexadecimal serial number of the
6828: last time stamp response created.
6829: This number is incremented by 1 for each response.
6830: If the file does not exist at the time of response
6831: generation a new file is created with serial number 1.
6832: This parameter is mandatory.
6833: .It Cm signer_cert
6834: TSA signing certificate, in PEM format.
6835: The same as the
6836: .Fl signer
6837: command line option.
6838: .It Cm certs
6839: A file containing a set of PEM-encoded certificates that need to be
6840: included in the response.
6841: The same as the
6842: .Fl chain
6843: command line option.
6844: .It Cm signer_key
6845: The private key of the TSA, in PEM format.
6846: The same as the
6847: .Fl inkey
6848: command line option.
6849: .It Cm default_policy
6850: The default policy to use when the request does not mandate any policy.
6851: The same as the
6852: .Fl policy
6853: command line option.
6854: .It Cm other_policies
6855: Comma separated list of policies that are also acceptable by the TSA
6856: and used only if the request explicitly specifies one of them.
6857: .It Cm digests
6858: The list of message digest algorithms that the TSA accepts.
6859: At least one algorithm must be specified.
6860: This parameter is mandatory.
6861: .It Cm accuracy
6862: The accuracy of the time source of the TSA in seconds, milliseconds
6863: and microseconds.
6864: For example, secs:1, millisecs:500, microsecs:100.
6865: If any of the components is missing,
6866: zero is assumed for that field.
6867: .It Cm clock_precision_digits
6868: Specifies the maximum number of digits, which represent the fraction of
6869: seconds, that need to be included in the time field.
6870: The trailing zeroes must be removed from the time,
6871: so there might actually be fewer digits,
6872: or no fraction of seconds at all.
6873: The maximum value is 6;
6874: the default is 0.
6875: .It Cm ordering
6876: If this option is yes,
6877: the responses generated by this TSA can always be ordered,
6878: even if the time difference between two responses is less
6879: than the sum of their accuracies.
6880: The default is no.
6881: .It Cm tsa_name
6882: Set this option to yes if the subject name of the TSA must be included in
6883: the TSA name field of the response.
6884: The default is no.
6885: .It Cm ess_cert_id_chain
6886: The SignedData objects created by the TSA always contain the
6887: certificate identifier of the signing certificate in a signed
6888: attribute (see RFC 2634, Enhanced Security Services).
6889: If this option is set to yes and either the
6890: .Cm certs
6891: variable or the
6892: .Fl chain
6893: option is specified then the certificate identifiers of the chain will also
6894: be included in the SigningCertificate signed attribute.
6895: If this variable is set to no,
6896: only the signing certificate identifier is included.
6897: The default is no.
6898: .El
6899: .Sh TS ENVIRONMENT VARIABLES
6900: .Ev OPENSSL_CONF
6901: contains the path of the configuration file and can be
6902: overridden by the
6903: .Fl config
6904: command line option.
6905: .Sh TS EXAMPLES
6906: All the examples below presume that
6907: .Ev OPENSSL_CONF
6908: is set to a proper configuration file,
6909: e.g. the example configuration file
6910: .Pa openssl/apps/openssl.cnf
6911: will do.
6912: .Pp
6913: To create a time stamp request for design1.txt with SHA-1
6914: without nonce and policy and no certificate is required in the response:
6915: .Bd -literal -offset indent
6916: $ openssl ts -query -data design1.txt -no_nonce \e
6917: -out design1.tsq
6918: .Ed
6919: .Pp
6920: To create a similar time stamp request but specifying the message imprint
6921: explicitly:
6922: .Bd -literal -offset indent
6923: $ openssl ts -query \e
6924: -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e
6925: -no_nonce -out design1.tsq
6926: .Ed
6927: .Pp
6928: To print the content of the previous request in human readable format:
6929: .Bd -literal -offset indent
6930: $ openssl ts -query -in design1.tsq -text
6931: .Ed
6932: .Pp
6933: To create a time stamp request which includes the MD5 digest
6934: of design2.txt, requests the signer certificate and nonce,
6935: specifies a policy ID
6936: (assuming the tsa_policy1 name is defined in the
6937: OID section of the config file):
6938: .Bd -literal -offset indent
6939: $ openssl ts -query -data design2.txt -md5 \e
6940: -policy tsa_policy1 -cert -out design2.tsq
6941: .Ed
6942: .Pp
6943: Before generating a response,
6944: a signing certificate must be created for the TSA that contains the
6945: .Cm timeStamping
6946: critical extended key usage extension
6947: without any other key usage extensions.
6948: You can add the
6949: .Dq extendedKeyUsage = critical,timeStamping
6950: line to the user certificate section
6951: of the config file to generate a proper certificate.
6952: See the
6953: .Nm req ,
6954: .Nm ca ,
6955: and
6956: .Nm x509
6957: commands for instructions.
6958: The examples below assume that cacert.pem contains the certificate of the CA,
6959: tsacert.pem is the signing certificate issued by cacert.pem and
6960: tsakey.pem is the private key of the TSA.
6961: .Pp
6962: To create a time stamp response for a request:
6963: .Bd -literal -offset indent
6964: $ openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \e
6965: -signer tsacert.pem -out design1.tsr
6966: .Ed
6967: .Pp
6968: If you want to use the settings in the config file you could just write:
6969: .Bd -literal -offset indent
6970: $ openssl ts -reply -queryfile design1.tsq -out design1.tsr
6971: .Ed
6972: .Pp
6973: To print a time stamp reply to stdout in human readable format:
6974: .Bd -literal -offset indent
6975: $ openssl ts -reply -in design1.tsr -text
6976: .Ed
6977: .Pp
6978: To create a time stamp token instead of time stamp response:
6979: .Bd -literal -offset indent
6980: $ openssl ts -reply -queryfile design1.tsq \e
6981: -out design1_token.der -token_out
6982: .Ed
6983: .Pp
6984: To print a time stamp token to stdout in human readable format:
6985: .Bd -literal -offset indent
6986: $ openssl ts -reply -in design1_token.der -token_in \e
6987: -text -token_out
6988: .Ed
6989: .Pp
6990: To extract the time stamp token from a response:
6991: .Bd -literal -offset indent
6992: $ openssl ts -reply -in design1.tsr -out design1_token.der \e
6993: -token_out
6994: .Ed
6995: .Pp
6996: To add
6997: .Dq granted
6998: status info to a time stamp token thereby creating a valid response:
6999: .Bd -literal -offset indent
7000: $ openssl ts -reply -in design1_token.der \e
7001: -token_in -out design1.tsr
7002: .Ed
7003: .Pp
7004: To verify a time stamp reply against a request:
7005: .Bd -literal -offset indent
7006: $ openssl ts -verify -queryfile design1.tsq -in design1.tsr \e
7007: -CAfile cacert.pem -untrusted tsacert.pem
7008: .Ed
7009: .Pp
7010: To verify a time stamp reply that includes the certificate chain:
7011: .Bd -literal -offset indent
7012: $ openssl ts -verify -queryfile design2.tsq -in design2.tsr \e
7013: -CAfile cacert.pem
7014: .Ed
7015: .Pp
7016: To verify a time stamp token against the original data file:
7017: .Bd -literal -offset indent
7018: $ openssl ts -verify -data design2.txt -in design2.tsr \e
7019: -CAfile cacert.pem
7020: .Ed
7021: .Pp
7022: To verify a time stamp token against a message imprint:
7023: .Bd -literal -offset indent
7024: $ openssl ts -verify \e
7025: -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e
7026: -in design2.tsr -CAfile cacert.pem
7027: .Ed
7028: .Sh TS BUGS
7029: No support for time stamps over SMTP, though it is quite easy
7030: to implement an automatic email-based TSA with
7031: .Xr procmail
7032: and
7033: .Xr perl 1 .
7034: Pure TCP/IP is not supported.
7035: .Pp
7036: The file containing the last serial number of the TSA is not
7037: locked when being read or written.
7038: This is a problem if more than one instance of
7039: .Nm OpenSSL
7040: is trying to create a time stamp
7041: response at the same time.
7042: .Pp
7043: Look for the FIXME word in the source files.
7044: .Pp
7045: The source code should really be reviewed by somebody else, too.
7046: .Pp
7047: More testing is needed.
7048: .Sh TS AUTHORS
7049: .An Zoltan Glozik Aq Mt zglozik@opentsa.org ,
7050: OpenTSA project
7051: .Pq Lk http://www.opentsa.org .
7052: .\"
7053: .\" SPKAC
7054: .\"
7055: .Sh SPKAC
7056: .nr nS 1
7057: .Nm "openssl spkac"
7058: .Bk -words
7059: .Op Fl challenge Ar string
7060: .Op Fl in Ar file
7061: .Op Fl key Ar keyfile
7062: .Op Fl noout
7063: .Op Fl out Ar file
7064: .Op Fl passin Ar arg
7065: .Op Fl pubkey
7066: .Op Fl spkac Ar spkacname
7067: .Op Fl spksect Ar section
7068: .Op Fl verify
7069: .Ek
7070: .nr nS 0
7071: .Pp
7072: The
7073: .Nm spkac
7074: command processes Netscape signed public key and challenge
7075: .Pq SPKAC
7076: files.
7077: It can print out their contents, verify the signature,
7078: and produce its own SPKACs from a supplied private key.
7079: .Pp
7080: The options are as follows:
7081: .Bl -tag -width Ds
7082: .It Fl challenge Ar string
7083: Specifies the challenge string if an SPKAC is being created.
7084: .It Fl in Ar file
7085: This specifies the input
7086: .Ar file
7087: to read from, or standard input if this option is not specified.
7088: Ignored if the
7089: .Fl key
7090: option is used.
7091: .It Fl key Ar keyfile
7092: Create an SPKAC file using the private key in
7093: .Ar keyfile .
7094: The
7095: .Fl in , noout , spksect ,
7096: and
7097: .Fl verify
7098: options are ignored if present.
7099: .It Fl noout
7100: Don't output the text version of the SPKAC
7101: .Pq not used if an SPKAC is being created .
7102: .It Fl out Ar file
7103: Specifies the output
7104: .Ar file
7105: to write to, or standard output by default.
7106: .It Fl passin Ar arg
7107: The key password source.
7108: .It Fl pubkey
7109: Output the public key of an SPKAC
7110: .Pq not used if an SPKAC is being created .
7111: .It Fl spkac Ar spkacname
7112: Allows an alternative name for the variable containing the SPKAC.
7113: The default is "SPKAC".
7114: This option affects both generated and input SPKAC files.
7115: .It Fl spksect Ar section
7116: Allows an alternative name for the
7117: .Ar section
7118: containing the SPKAC.
7119: The default is the default section.
7120: .It Fl verify
7121: Verifies the digital signature on the supplied SPKAC.
7122: .El
7123: .Sh SPKAC EXAMPLES
7124: Print out the contents of an SPKAC:
7125: .Pp
7126: .Dl $ openssl spkac -in spkac.cnf
7127: .Pp
7128: Verify the signature of an SPKAC:
7129: .Pp
7130: .Dl $ openssl spkac -in spkac.cnf -noout -verify
7131: .Pp
7132: Create an SPKAC using the challenge string
7133: .Qq hello :
7134: .Pp
7135: .Dl $ openssl spkac -key key.pem -challenge hello -out spkac.cnf
7136: .Pp
7137: Example of an SPKAC,
7138: .Pq long lines split up for clarity :
7139: .Bd -unfilled -offset indent
7140: SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA1cCoq2Wa3Ixs47uI7F\e
7141: PVwHVIPDx5yso105Y6zpozam135a8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03u\e
7142: PFoQIDAQABFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJh1bEIYuc\e
7143: 2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnDdq+NQ3F+X4deMx9AaEglZtULwV\e
7144: 4=
7145: .Ed
7146: .Sh SPKAC NOTES
7147: A created SPKAC with suitable DN components appended can be fed into
7148: the
7149: .Nm ca
7150: utility.
7151: .Pp
7152: SPKACs are typically generated by Netscape when a form is submitted
7153: containing the
7154: .Em KEYGEN
7155: tag as part of the certificate enrollment process.
7156: .Pp
7157: The challenge string permits a primitive form of proof of possession
7158: of private key.
7159: By checking the SPKAC signature and a random challenge
7160: string, some guarantee is given that the user knows the private key
7161: corresponding to the public key being certified.
7162: This is important in some applications.
7163: Without this it is possible for a previous SPKAC
7164: to be used in a
7165: .Qq replay attack .
7166: .\"
7167: .\" VERIFY
7168: .\"
7169: .Sh VERIFY
7170: .nr nS 1
7171: .Nm "openssl verify"
7172: .Bk -words
7173: .Op Fl CAfile Ar file
7174: .Op Fl CApath Ar directory
7175: .Op Fl check_ss_sig
7176: .Op Fl crl_check
7177: .Op Fl crl_check_all
7178: .Op Fl explicit_policy
7179: .Op Fl extended_crl
7180: .Op Fl help
7181: .Op Fl ignore_critical
7182: .Op Fl inhibit_any
7183: .Op Fl inhibit_map
7184: .Op Fl issuer_checks
7185: .Op Fl policy_check
7186: .Op Fl purpose Ar purpose
7187: .Op Fl untrusted Ar file
7188: .Op Fl verbose
7189: .Op Fl x509_strict
7190: .Op Fl
7191: .Op Ar certificates
7192: .Ek
7193: .nr nS 0
7194: .Pp
7195: The
7196: .Nm verify
7197: command verifies certificate chains.
7198: .Pp
7199: The options are as follows:
7200: .Bl -tag -width Ds
7201: .It Fl check_ss_sig
7202: Verify the signature on the self-signed root CA.
7203: This is disabled by default
7204: because it doesn't add any security.
7205: .It Fl CAfile Ar file
7206: A
7207: .Ar file
7208: of trusted certificates.
7209: The
7210: .Ar file
7211: should contain multiple certificates in PEM format, concatenated together.
7212: .It Fl CApath Ar directory
7213: A
7214: .Ar directory
7215: of trusted certificates.
7216: The certificates should have names of the form
7217: .Em hash.0 ,
7218: or have symbolic links to them of this form
7219: ("hash" is the hashed certificate subject name: see the
7220: .Fl hash
7221: option of the
7222: .Nm x509
7223: utility).
7224: The
7225: .Nm c_rehash
7226: script distributed with OpenSSL
7227: will automatically create symbolic links to a directory of certificates.
7228: .It Fl crl_check
7229: Checks end entity certificate validity by attempting to look up a valid CRL.
7230: If a valid CRL cannot be found an error occurs.
7231: .It Fl crl_check_all
7232: Checks the validity of all certificates in the chain by attempting
7233: to look up valid CRLs.
7234: .It Fl explicit_policy
7235: Set policy variable require-explicit-policy (see RFC 3280 et al).
7236: .It Fl extended_crl
7237: Enable extended CRL features such as indirect CRLs and alternate CRL
7238: signing keys.
7239: .It Fl help
7240: Prints out a usage message.
7241: .It Fl ignore_critical
7242: Normally if an unhandled critical extension is present which is not
7243: supported by
7244: .Nm OpenSSL ,
7245: the certificate is rejected (as required by RFC 3280 et al).
7246: If this option is set, critical extensions are ignored.
7247: .It Fl inhibit_any
7248: Set policy variable inhibit-any-policy (see RFC 3280 et al).
7249: .It Fl inhibit_map
7250: Set policy variable inhibit-policy-mapping (see RFC 3280 et al).
7251: .It Fl issuer_checks
7252: Print out diagnostics relating to searches for the issuer certificate
7253: of the current certificate.
7254: This shows why each candidate issuer certificate was rejected.
7255: However the presence of rejection messages
7256: does not itself imply that anything is wrong: during the normal
7257: verify process several rejections may take place.
7258: .It Fl policy_check
7259: Enables certificate policy processing.
7260: .It Fl purpose Ar purpose
7261: The intended use for the certificate.
7262: Without this option no chain verification will be done.
7263: Currently accepted uses are
7264: .Ar sslclient , sslserver ,
7265: .Ar nssslserver , smimesign ,
7266: .Ar smimeencrypt , crlsign ,
7267: .Ar any ,
7268: and
7269: .Ar ocsphelper .
7270: See the
7271: .Sx VERIFY OPERATION
7272: section for more information.
7273: .It Fl untrusted Ar file
7274: A
7275: .Ar file
7276: of untrusted certificates.
7277: The
7278: .Ar file
7279: should contain multiple certificates.
7280: .It Fl verbose
7281: Print extra information about the operations being performed.
7282: .It Fl x509_strict
7283: Disable workarounds for broken certificates which have to be disabled
7284: for strict X.509 compliance.
7285: .It Fl
7286: Marks the last option.
7287: All arguments following this are assumed to be certificate files.
7288: This is useful if the first certificate filename begins with a
7289: .Sq - .
7290: .It Ar certificates
7291: One or more
7292: .Ar certificates
7293: to verify.
7294: If no certificate files are included, an attempt is made to read
7295: a certificate from standard input.
7296: They should all be in PEM format.
7297: .El
7298: .Sh VERIFY OPERATION
7299: The
7300: .Nm verify
7301: program uses the same functions as the internal SSL and S/MIME verification,
7302: therefore this description applies to these verify operations too.
7303: .Pp
7304: There is one crucial difference between the verify operations performed
7305: by the
7306: .Nm verify
7307: program: wherever possible an attempt is made to continue
7308: after an error, whereas normally the verify operation would halt on the
7309: first error.
7310: This allows all the problems with a certificate chain to be determined.
7311: .Pp
7312: The verify operation consists of a number of separate steps:
7313: .Pp
7314: Firstly a certificate chain is built up starting from the supplied certificate
7315: and ending in the root CA.
7316: It is an error if the whole chain cannot be built up.
7317: The chain is built up by looking up the issuer's certificate of the current
7318: certificate.
7319: If a certificate is found which is its own issuer, it is assumed
7320: to be the root CA.
7321: .Pp
7322: The process of
7323: .Qq looking up the issuer's certificate
7324: itself involves a number of steps.
7325: In versions of
7326: .Nm OpenSSL
7327: before 0.9.5a the first certificate whose subject name matched the issuer
7328: of the current certificate was assumed to be the issuer's certificate.
7329: In
7330: .Nm OpenSSL
7331: 0.9.6 and later all certificates whose subject name matches the issuer name
7332: of the current certificate are subject to further tests.
7333: The relevant authority key identifier components of the current certificate
7334: .Pq if present
7335: must match the subject key identifier
7336: .Pq if present
7337: and issuer and serial number of the candidate issuer; in addition the
7338: .Em keyUsage
7339: extension of the candidate issuer
7340: .Pq if present
7341: must permit certificate signing.
7342: .Pp
7343: The lookup first looks in the list of untrusted certificates and if no match
7344: is found the remaining lookups are from the trusted certificates.
7345: The root CA is always looked up in the trusted certificate list: if the
7346: certificate to verify is a root certificate, then an exact match must be
7347: found in the trusted list.
7348: .Pp
7349: The second operation is to check every untrusted certificate's extensions for
7350: consistency with the supplied purpose.
7351: If the
7352: .Fl purpose
7353: option is not included, then no checks are done.
7354: The supplied or
7355: .Qq leaf
7356: certificate must have extensions compatible with the supplied purpose
7357: and all other certificates must also be valid CA certificates.
7358: The precise extensions required are described in more detail in
7359: the
7360: .Sx X.509 CERTIFICATE EXTENSIONS
7361: section below.
7362: .Pp
7363: The third operation is to check the trust settings on the root CA.
7364: The root CA should be trusted for the supplied purpose.
7365: For compatibility with previous versions of
7366: .Nm SSLeay
7367: and
7368: .Nm OpenSSL ,
7369: a certificate with no trust settings is considered to be valid for
7370: all purposes.
7371: .Pp
7372: The final operation is to check the validity of the certificate chain.
7373: The validity period is checked against the current system time and the
7374: .Em notBefore
7375: and
7376: .Em notAfter
7377: dates in the certificate.
7378: The certificate signatures are also checked at this point.
7379: .Pp
7380: If all operations complete successfully, the certificate is considered
7381: valid.
7382: If any operation fails then the certificate is not valid.
7383: .Sh VERIFY DIAGNOSTICS
7384: When a verify operation fails, the output messages can be somewhat cryptic.
7385: The general form of the error message is:
7386: .Bd -unfilled
7387: \& server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024-bit)
7388: \& error 24 at 1 depth lookup:invalid CA certificate
7389: .Ed
7390: .Pp
7391: The first line contains the name of the certificate being verified, followed by
7392: the subject name of the certificate.
7393: The second line contains the error number and the depth.
7394: The depth is the number of the certificate being verified when a
7395: problem was detected starting with zero for the certificate being verified
7396: itself, then 1 for the CA that signed the certificate and so on.
7397: Finally a text version of the error number is presented.
7398: .Pp
7399: An exhaustive list of the error codes and messages is shown below; this also
7400: includes the name of the error code as defined in the header file
1.12 bentley 7401: .In openssl/x509_vfy.h .
1.1 jsing 7402: Some of the error codes are defined but never returned: these are described
7403: as
7404: .Qq unused .
7405: .Bl -tag -width "XXXX"
7406: .It Ar "0 X509_V_OK: ok"
7407: The operation was successful.
7408: .It Ar 2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate
7409: The issuer certificate could not be found: this occurs if the issuer certificate
7410: of an untrusted certificate cannot be found.
7411: .It Ar 3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL
7412: The CRL of a certificate could not be found.
7413: .It Ar 4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature
7414: The certificate signature could not be decrypted.
7415: This means that the actual signature value could not be determined rather
7416: than it not matching the expected value.
7417: This is only meaningful for RSA keys.
7418: .It Ar 5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature
7419: The CRL signature could not be decrypted: this means that the actual
7420: signature value could not be determined rather than it not matching the
7421: expected value.
7422: Unused.
7423: .It Ar 6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key
7424: The public key in the certificate
7425: .Em SubjectPublicKeyInfo
7426: could not be read.
7427: .It Ar 7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure
7428: The signature of the certificate is invalid.
7429: .It Ar 8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure
7430: The signature of the certificate is invalid.
7431: .It Ar 9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid
7432: The certificate is not yet valid: the
7433: .Em notBefore
7434: date is after the current time.
7435: .It Ar 10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired
7436: The certificate has expired; that is, the
7437: .Em notAfter
7438: date is before the current time.
7439: .It Ar 11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid
7440: The CRL is not yet valid.
7441: .It Ar 12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired
7442: The CRL has expired.
7443: .It Ar 13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field
7444: The certificate
7445: .Em notBefore
7446: field contains an invalid time.
7447: .It Ar 14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field
7448: The certificate
7449: .Em notAfter
7450: field contains an invalid time.
7451: .It Ar 15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field
7452: The CRL
7453: .Em lastUpdate
7454: field contains an invalid time.
7455: .It Ar 16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field
7456: The CRL
7457: .Em nextUpdate
7458: field contains an invalid time.
7459: .It Ar 17 X509_V_ERR_OUT_OF_MEM: out of memory
7460: An error occurred trying to allocate memory.
7461: This should never happen.
7462: .It Ar 18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate
7463: The passed certificate is self-signed and the same certificate cannot be
7464: found in the list of trusted certificates.
7465: .It Ar 19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain
7466: The certificate chain could be built up using the untrusted certificates but
7467: the root could not be found locally.
7468: .It Ar 20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate
7469: The issuer certificate of a locally looked up certificate could not be found.
7470: This normally means the list of trusted certificates is not complete.
7471: .It Ar 21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate
7472: No signatures could be verified because the chain contains only one
7473: certificate and it is not self-signed.
7474: .It Ar 22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long
7475: The certificate chain length is greater than the supplied maximum depth.
7476: Unused.
7477: .It Ar 23 X509_V_ERR_CERT_REVOKED: certificate revoked
7478: The certificate has been revoked.
7479: .It Ar 24 X509_V_ERR_INVALID_CA: invalid CA certificate
7480: A CA certificate is invalid.
7481: Either it is not a CA or its extensions are not consistent
7482: with the supplied purpose.
7483: .It Ar 25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded
7484: The
7485: .Em basicConstraints
7486: pathlength parameter has been exceeded.
7487: .It Ar 26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose
7488: The supplied certificate cannot be used for the specified purpose.
7489: .It Ar 27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted
7490: The root CA is not marked as trusted for the specified purpose.
7491: .It Ar 28 X509_V_ERR_CERT_REJECTED: certificate rejected
7492: The root CA is marked to reject the specified purpose.
7493: .It Ar 29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch
7494: The current candidate issuer certificate was rejected because its subject name
7495: did not match the issuer name of the current certificate.
7496: Only displayed when the
7497: .Fl issuer_checks
7498: option is set.
7499: .It Ar 30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch
7500: The current candidate issuer certificate was rejected because its subject key
7501: identifier was present and did not match the authority key identifier current
7502: certificate.
7503: Only displayed when the
7504: .Fl issuer_checks
7505: option is set.
7506: .It Ar 31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch
7507: The current candidate issuer certificate was rejected because its issuer name
7508: and serial number were present and did not match the authority key identifier
7509: of the current certificate.
7510: Only displayed when the
7511: .Fl issuer_checks
7512: option is set.
7513: .It Ar 32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing
7514: The current candidate issuer certificate was rejected because its
7515: .Em keyUsage
7516: extension does not permit certificate signing.
7517: .It Ar 50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure
7518: An application specific error.
7519: Unused.
7520: .El
7521: .Sh VERIFY BUGS
7522: Although the issuer checks are a considerable improvement over the old
7523: technique, they still suffer from limitations in the underlying
7524: X509_LOOKUP API.
7525: One consequence of this is that trusted certificates with matching subject
7526: name must either appear in a file (as specified by the
7527: .Fl CAfile
7528: option) or a directory (as specified by
7529: .Fl CApath ) .
7530: If they occur in both, only the certificates in the file will
7531: be recognised.
7532: .Pp
7533: Previous versions of
7534: .Nm OpenSSL
7535: assumed certificates with matching subject name were identical and
7536: mishandled them.
7537: .\"
7538: .\" VERSION
7539: .\"
7540: .Sh VERSION
7541: .Nm openssl version
7542: .Op Fl abdfopv
7543: .Pp
7544: The
7545: .Nm version
7546: command is used to print out version information about
7547: .Nm OpenSSL .
7548: .Pp
7549: The options are as follows:
7550: .Bl -tag -width Ds
7551: .It Fl a
7552: All information: this is the same as setting all the other flags.
7553: .It Fl b
7554: The date the current version of
7555: .Nm OpenSSL
7556: was built.
7557: .It Fl d
7558: .Ev OPENSSLDIR
7559: setting.
7560: .It Fl f
7561: Compilation flags.
7562: .It Fl o
7563: Option information: various options set when the library was built.
7564: .It Fl p
7565: Platform setting.
7566: .It Fl v
7567: The current
7568: .Nm OpenSSL
7569: version.
7570: .El
7571: .Sh VERSION NOTES
7572: The output of
7573: .Nm openssl version -a
7574: would typically be used when sending in a bug report.
7575: .Sh VERSION HISTORY
7576: The
7577: .Fl d
7578: option was added in
7579: .Nm OpenSSL
7580: 0.9.7.
7581: .\"
7582: .\" X509
7583: .\"
7584: .Sh X509
7585: .nr nS 1
7586: .Nm "openssl x509"
7587: .Bk -words
7588: .Op Fl C
7589: .Op Fl addreject Ar arg
7590: .Op Fl addtrust Ar arg
7591: .Op Fl alias
7592: .Op Fl CA Ar file
7593: .Op Fl CAcreateserial
7594: .Op Fl CAform Ar DER | PEM
7595: .Op Fl CAkey Ar file
7596: .Op Fl CAkeyform Ar DER | PEM
7597: .Op Fl CAserial Ar file
7598: .Op Fl certopt Ar option
7599: .Op Fl checkend Ar arg
7600: .Op Fl clrext
7601: .Op Fl clrreject
7602: .Op Fl clrtrust
7603: .Op Fl dates
7604: .Op Fl days Ar arg
7605: .Op Fl email
7606: .Op Fl enddate
7607: .Op Fl extensions Ar section
7608: .Op Fl extfile Ar file
7609: .Op Fl fingerprint
7610: .Op Fl hash
7611: .Op Fl in Ar file
7612: .Op Fl inform Ar DER | NET | PEM
7613: .Op Fl issuer
7614: .Op Fl issuer_hash
7615: .Op Fl issuer_hash_old
7616: .Op Fl keyform Ar DER | PEM
1.29 bcook 7617: .Op Fl md5 | sha1
1.1 jsing 7618: .Op Fl modulus
7619: .Op Fl nameopt Ar option
7620: .Op Fl noout
7621: .Op Fl ocsp_uri
7622: .Op Fl ocspid
7623: .Op Fl out Ar file
7624: .Op Fl outform Ar DER | NET | PEM
7625: .Op Fl passin Ar arg
7626: .Op Fl pubkey
7627: .Op Fl purpose
7628: .Op Fl req
7629: .Op Fl serial
7630: .Op Fl set_serial Ar n
7631: .Op Fl setalias Ar arg
7632: .Op Fl signkey Ar file
7633: .Op Fl startdate
7634: .Op Fl subject
7635: .Op Fl subject_hash
7636: .Op Fl subject_hash_old
7637: .Op Fl text
7638: .Op Fl trustout
7639: .Op Fl x509toreq
7640: .Ek
7641: .nr nS 0
7642: .Pp
7643: The
7644: .Nm x509
7645: command is a multi-purpose certificate utility.
7646: It can be used to display certificate information, convert certificates to
7647: various forms, sign certificate requests like a
7648: .Qq mini CA ,
7649: or edit certificate trust settings.
7650: .Pp
7651: Since there are a large number of options, they are split up into
7652: various sections.
7653: .Sh X509 INPUT, OUTPUT, AND GENERAL PURPOSE OPTIONS
7654: .Bl -tag -width "XXXX"
7655: .It Fl in Ar file
7656: This specifies the input
7657: .Ar file
7658: to read a certificate from, or standard input if this option is not specified.
7659: .It Fl inform Ar DER | NET | PEM
7660: This specifies the input format.
7661: Normally, the command will expect an X.509 certificate,
7662: but this can change if other options such as
7663: .Fl req
7664: are present.
7665: The
7666: .Ar DER
7667: format is the DER encoding of the certificate and
7668: .Ar PEM
7669: is the base64 encoding of the DER encoding with header and footer lines added.
7670: The
7671: .Ar NET
7672: option is an obscure Netscape server format that is now
7673: obsolete.
1.29 bcook 7674: .It Fl md5 | sha1
1.1 jsing 7675: The digest to use.
7676: This affects any signing or display option that uses a message digest,
7677: such as the
7678: .Fl fingerprint , signkey ,
7679: and
7680: .Fl CA
7681: options.
7682: If not specified, MD5 is used.
7683: If the key being used to sign with is a DSA key,
7684: this option has no effect: SHA1 is always used with DSA keys.
7685: .It Fl out Ar file
7686: This specifies the output
7687: .Ar file
7688: to write to, or standard output by default.
7689: .It Fl outform Ar DER | NET | PEM
7690: This specifies the output format; the options have the same meaning as the
7691: .Fl inform
7692: option.
7693: .It Fl passin Ar arg
7694: The key password source.
7695: .El
7696: .Sh X509 DISPLAY OPTIONS
7697: .Sy Note :
7698: The
7699: .Fl alias
7700: and
7701: .Fl purpose
7702: options are also display options but are described in the
7703: .Sx X509 TRUST SETTINGS
7704: section.
7705: .Bl -tag -width "XXXX"
7706: .It Fl C
7707: This outputs the certificate in the form of a C source file.
7708: .It Fl certopt Ar option
7709: Customise the output format used with
7710: .Fl text .
7711: The
7712: .Ar option
7713: argument can be a single option or multiple options separated by commas.
7714: The
7715: .Fl certopt
7716: switch may also be used more than once to set multiple options.
7717: See the
7718: .Sx X509 TEXT OPTIONS
7719: section for more information.
7720: .It Fl dates
7721: Prints out the start and expiry dates of a certificate.
7722: .It Fl email
7723: Outputs the email address(es), if any.
7724: .It Fl enddate
7725: Prints out the expiry date of the certificate; that is, the
7726: .Em notAfter
7727: date.
7728: .It Fl fingerprint
7729: Prints out the digest of the DER-encoded version of the whole certificate
7730: (see
7731: .Sx DIGEST OPTIONS ) .
7732: .It Fl hash
7733: A synonym for
7734: .Fl subject_hash ,
7735: for backwards compatibility.
7736: .It Fl issuer
7737: Outputs the issuer name.
7738: .It Fl issuer_hash
7739: Outputs the
7740: .Qq hash
7741: of the certificate issuer name.
7742: .It Fl issuer_hash_old
7743: Outputs the
7744: .Qq hash
7745: of the certificate issuer name using the older algorithm
7746: as used by
7747: .Nm OpenSSL
7748: versions before 1.0.0.
7749: .It Fl modulus
7750: This option prints out the value of the modulus of the public key
7751: contained in the certificate.
7752: .It Fl nameopt Ar option
7753: Option which determines how the subject or issuer names are displayed.
7754: The
7755: .Ar option
7756: argument can be a single option or multiple options separated by commas.
7757: Alternatively, the
7758: .Fl nameopt
7759: switch may be used more than once to set multiple options.
7760: See the
7761: .Sx X509 NAME OPTIONS
7762: section for more information.
7763: .It Fl noout
7764: This option prevents output of the encoded version of the request.
7765: .It Fl ocsp_uri
7766: Outputs the OCSP responder addresses, if any.
7767: .It Fl ocspid
7768: Print OCSP hash values for the subject name and public key.
7769: .It Fl pubkey
7770: Output the public key.
7771: .It Fl serial
7772: Outputs the certificate serial number.
7773: .It Fl startdate
7774: Prints out the start date of the certificate; that is, the
7775: .Em notBefore
7776: date.
7777: .It Fl subject
7778: Outputs the subject name.
7779: .It Fl subject_hash
7780: Outputs the
7781: .Qq hash
7782: of the certificate subject name.
7783: This is used in
7784: .Nm OpenSSL
7785: to form an index to allow certificates in a directory to be looked up
7786: by subject name.
7787: .It Fl subject_hash_old
7788: Outputs the
7789: .Qq hash
7790: of the certificate subject name using the older algorithm
7791: as used by
7792: .Nm OpenSSL
7793: versions before 1.0.0.
7794: .It Fl text
7795: Prints out the certificate in text form.
7796: Full details are output including the public key, signature algorithms,
7797: issuer and subject names, serial number, any extensions present,
7798: and any trust settings.
7799: .El
7800: .Sh X509 TRUST SETTINGS
7801: Please note these options are currently experimental and may well change.
7802: .Pp
7803: A
7804: .Em trusted certificate
7805: is an ordinary certificate which has several
7806: additional pieces of information attached to it such as the permitted
7807: and prohibited uses of the certificate and an
7808: .Qq alias .
7809: .Pp
7810: Normally, when a certificate is being verified at least one certificate
7811: must be
7812: .Qq trusted .
7813: By default, a trusted certificate must be stored
7814: locally and must be a root CA: any certificate chain ending in this CA
7815: is then usable for any purpose.
7816: .Pp
7817: Trust settings currently are only used with a root CA.
7818: They allow a finer control over the purposes the root CA can be used for.
7819: For example, a CA may be trusted for an SSL client but not for
7820: SSL server use.
7821: .Pp
7822: See the description of the
7823: .Nm verify
7824: utility for more information on the meaning of trust settings.
7825: .Pp
7826: Future versions of
7827: .Nm OpenSSL
7828: will recognize trust settings on any certificate: not just root CAs.
7829: .Bl -tag -width "XXXX"
7830: .It Fl addreject Ar arg
7831: Adds a prohibited use.
7832: It accepts the same values as the
7833: .Fl addtrust
7834: option.
7835: .It Fl addtrust Ar arg
7836: Adds a trusted certificate use.
7837: Any object name can be used here, but currently only
7838: .Ar clientAuth
7839: .Pq SSL client use ,
7840: .Ar serverAuth
7841: .Pq SSL server use ,
7842: and
7843: .Ar emailProtection
7844: .Pq S/MIME email
7845: are used.
7846: Other
7847: .Nm OpenSSL
7848: applications may define additional uses.
7849: .It Fl alias
7850: Outputs the certificate alias, if any.
7851: .It Fl clrreject
7852: Clears all the prohibited or rejected uses of the certificate.
7853: .It Fl clrtrust
7854: Clears all the permitted or trusted uses of the certificate.
7855: .It Fl purpose
7856: This option performs tests on the certificate extensions and outputs
7857: the results.
7858: For a more complete description, see the
7859: .Sx X.509 CERTIFICATE EXTENSIONS
7860: section.
7861: .It Fl setalias Ar arg
7862: Sets the alias of the certificate.
7863: This will allow the certificate to be referred to using a nickname,
7864: for example
7865: .Qq Steve's Certificate .
7866: .It Fl trustout
7867: This causes
7868: .Nm x509
7869: to output a
7870: .Em trusted certificate .
7871: An ordinary or trusted certificate can be input, but by default an ordinary
7872: certificate is output and any trust settings are discarded.
7873: With the
7874: .Fl trustout
7875: option a trusted certificate is output.
7876: A trusted certificate is automatically output if any trust settings
7877: are modified.
7878: .El
7879: .Sh X509 SIGNING OPTIONS
7880: The
7881: .Nm x509
7882: utility can be used to sign certificates and requests: it
7883: can thus behave like a
7884: .Qq mini CA .
7885: .Bl -tag -width "XXXX"
7886: .It Fl CA Ar file
7887: Specifies the CA certificate to be used for signing.
7888: When this option is present,
7889: .Nm x509
7890: behaves like a
7891: .Qq mini CA .
7892: The input file is signed by the CA using this option;
7893: that is, its issuer name is set to the subject name of the CA and it is
7894: digitally signed using the CA's private key.
7895: .Pp
7896: This option is normally combined with the
7897: .Fl req
7898: option.
7899: Without the
7900: .Fl req
7901: option, the input is a certificate which must be self-signed.
7902: .It Fl CAcreateserial
7903: With this option the CA serial number file is created if it does not exist:
7904: it will contain the serial number
7905: .Sq 02
7906: and the certificate being signed will have
7907: .Sq 1
7908: as its serial number.
7909: Normally, if the
7910: .Fl CA
7911: option is specified and the serial number file does not exist, it is an error.
7912: .It Fl CAform Ar DER | PEM
7913: The format of the CA certificate file.
7914: The default is
7915: .Ar PEM .
7916: .It Fl CAkey Ar file
7917: Sets the CA private key to sign a certificate with.
7918: If this option is not specified, it is assumed that the CA private key
7919: is present in the CA certificate file.
7920: .It Fl CAkeyform Ar DER | PEM
7921: The format of the CA private key.
7922: The default is
7923: .Ar PEM .
7924: .It Fl CAserial Ar file
7925: Sets the CA serial number file to use.
7926: .Pp
7927: When the
7928: .Fl CA
7929: option is used to sign a certificate,
7930: it uses a serial number specified in a file.
7931: This file consists of one line containing an even number of hex digits
7932: with the serial number to use.
7933: After each use the serial number is incremented and written out
7934: to the file again.
7935: .Pp
7936: The default filename consists of the CA certificate file base name with
7937: .Pa .srl
7938: appended.
7939: For example, if the CA certificate file is called
7940: .Pa mycacert.pem ,
7941: it expects to find a serial number file called
7942: .Pa mycacert.srl .
7943: .It Fl checkend Ar arg
7944: Check whether the certificate expires in the next
7945: .Ar arg
7946: seconds.
7947: If so, exit with return value 1;
7948: otherwise exit with return value 0.
7949: .It Fl clrext
7950: Delete any extensions from a certificate.
7951: This option is used when a certificate is being created from another
7952: certificate (for example with the
7953: .Fl signkey
7954: or the
7955: .Fl CA
7956: options).
7957: Normally, all extensions are retained.
7958: .It Fl days Ar arg
7959: Specifies the number of days to make a certificate valid for.
7960: The default is 30 days.
7961: .It Fl extensions Ar section
7962: The section to add certificate extensions from.
7963: If this option is not specified, the extensions should either be
7964: contained in the unnamed
7965: .Pq default
7966: section or the default section should contain a variable called
7967: .Qq extensions
7968: which contains the section to use.
7969: .It Fl extfile Ar file
7970: File containing certificate extensions to use.
7971: If not specified, no extensions are added to the certificate.
7972: .It Fl keyform Ar DER | PEM
7973: Specifies the format
7974: .Pq DER or PEM
7975: of the private key file used in the
7976: .Fl signkey
7977: option.
7978: .It Fl req
7979: By default, a certificate is expected on input.
7980: With this option a certificate request is expected instead.
7981: .It Fl set_serial Ar n
7982: Specifies the serial number to use.
7983: This option can be used with either the
7984: .Fl signkey
7985: or
7986: .Fl CA
7987: options.
7988: If used in conjunction with the
7989: .Fl CA
7990: option, the serial number file (as specified by the
7991: .Fl CAserial
7992: or
7993: .Fl CAcreateserial
7994: options) is not used.
7995: .Pp
7996: The serial number can be decimal or hex (if preceded by
7997: .Sq 0x ) .
7998: Negative serial numbers can also be specified but their use is not recommended.
7999: .It Fl signkey Ar file
8000: This option causes the input file to be self-signed using the supplied
8001: private key.
8002: .Pp
8003: If the input file is a certificate, it sets the issuer name to the
8004: subject name
8005: .Pq i.e. makes it self-signed ,
8006: changes the public key to the supplied value,
8007: and changes the start and end dates.
8008: The start date is set to the current time and the end date is set to
8009: a value determined by the
8010: .Fl days
8011: option.
8012: Any certificate extensions are retained unless the
8013: .Fl clrext
8014: option is supplied.
8015: .Pp
8016: If the input is a certificate request, a self-signed certificate
8017: is created using the supplied private key using the subject name in
8018: the request.
8019: .It Fl x509toreq
8020: Converts a certificate into a certificate request.
8021: The
8022: .Fl signkey
8023: option is used to pass the required private key.
8024: .El
8025: .Sh X509 NAME OPTIONS
8026: The
8027: .Fl nameopt
8028: command line switch determines how the subject and issuer
8029: names are displayed.
8030: If no
8031: .Fl nameopt
8032: switch is present, the default
8033: .Qq oneline
8034: format is used which is compatible with previous versions of
8035: .Nm OpenSSL .
8036: Each option is described in detail below; all options can be preceded by a
8037: .Sq -
8038: to turn the option off.
8039: Only
8040: .Ar compat ,
8041: .Ar RFC2253 ,
8042: .Ar oneline ,
8043: and
8044: .Ar multiline
8045: will normally be used.
8046: .Bl -tag -width "XXXX"
8047: .It Ar align
8048: Align field values for a more readable output.
8049: Only usable with
8050: .Ar sep_multiline .
8051: .It Ar compat
8052: Use the old format.
8053: This is equivalent to specifying no name options at all.
8054: .It Ar dn_rev
8055: Reverse the fields of the DN.
8056: This is required by RFC 2253.
8057: As a side effect, this also reverses the order of multiple AVAs but this is
8058: permissible.
8059: .It Ar dump_all
8060: Dump all fields.
8061: This option, when used with
8062: .Ar dump_der ,
8063: allows the DER encoding of the structure to be unambiguously determined.
8064: .It Ar dump_der
8065: When this option is set, any fields that need to be hexdumped will
8066: be dumped using the DER encoding of the field.
8067: Otherwise just the content octets will be displayed.
8068: Both options use the RFC 2253 #XXXX... format.
8069: .It Ar dump_nostr
8070: Dump non-character string types
8071: .Pq for example OCTET STRING ;
8072: if this option is not set, non-character string types will be displayed
8073: as though each content octet represents a single character.
8074: .It Ar dump_unknown
8075: Dump any field whose OID is not recognised by
8076: .Nm OpenSSL .
8077: .It Ar esc_2253
8078: Escape the
8079: .Qq special
8080: characters required by RFC 2253 in a field that is
8081: .Dq \& ,+"\*(Lt\*(Gt; .
8082: Additionally,
8083: .Sq #
8084: is escaped at the beginning of a string
8085: and a space character at the beginning or end of a string.
8086: .It Ar esc_ctrl
8087: Escape control characters.
8088: That is, those with ASCII values less than 0x20
8089: .Pq space
8090: and the delete
8091: .Pq 0x7f
8092: character.
8093: They are escaped using the RFC 2253 \eXX notation (where XX are two hex
8094: digits representing the character value).
8095: .It Ar esc_msb
8096: Escape characters with the MSB set; that is, with ASCII values larger than
8097: 127.
8098: .It Ar multiline
8099: A multiline format.
8100: It is equivalent to
8101: .Ar esc_ctrl , esc_msb , sep_multiline ,
8102: .Ar space_eq , lname ,
8103: and
8104: .Ar align .
8105: .It Ar no_type
8106: This option does not attempt to interpret multibyte characters in any
8107: way.
8108: That is, their content octets are merely dumped as though one octet
8109: represents each character.
8110: This is useful for diagnostic purposes but will result in rather odd
8111: looking output.
8112: .It Ar nofname , sname , lname , oid
8113: These options alter how the field name is displayed.
8114: .Ar nofname
8115: does not display the field at all.
8116: .Ar sname
8117: uses the
8118: .Qq short name
8119: form (CN for
8120: .Ar commonName ,
8121: for example).
8122: .Ar lname
8123: uses the long form.
8124: .Ar oid
8125: represents the OID in numerical form and is useful for diagnostic purpose.
8126: .It Ar oneline
8127: A oneline format which is more readable than
8128: .Ar RFC2253 .
8129: It is equivalent to specifying the
8130: .Ar esc_2253 , esc_ctrl , esc_msb , utf8 ,
8131: .Ar dump_nostr , dump_der , use_quote , sep_comma_plus_spc ,
8132: .Ar space_eq ,
8133: and
8134: .Ar sname
8135: options.
8136: .It Ar RFC2253
8137: Displays names compatible with RFC 2253; equivalent to
8138: .Ar esc_2253 , esc_ctrl ,
8139: .Ar esc_msb , utf8 , dump_nostr , dump_unknown ,
8140: .Ar dump_der , sep_comma_plus , dn_rev ,
8141: and
8142: .Ar sname .
8143: .It Ar sep_comma_plus , sep_comma_plus_space , sep_semi_plus_space , sep_multiline
8144: These options determine the field separators.
8145: The first character is between RDNs and the second between multiple AVAs
8146: (multiple AVAs are very rare and their use is discouraged).
8147: The options ending in
8148: .Qq space
8149: additionally place a space after the separator to make it more readable.
8150: The
8151: .Ar sep_multiline
8152: uses a linefeed character for the RDN separator and a spaced
8153: .Sq +
8154: for the AVA separator.
8155: It also indents the fields by four characters.
8156: .It Ar show_type
8157: Show the type of the ASN1 character string.
8158: The type precedes the field contents.
8159: For example
8160: .Qq BMPSTRING: Hello World .
8161: .It Ar space_eq
8162: Places spaces round the
8163: .Sq =
8164: character which follows the field name.
8165: .It Ar use_quote
8166: Escapes some characters by surrounding the whole string with
8167: .Sq \&"
8168: characters.
8169: Without the option, all escaping is done with the
8170: .Sq \e
8171: character.
8172: .It Ar utf8
8173: Convert all strings to UTF8 format first.
8174: This is required by RFC 2253.
8175: If you are lucky enough to have a UTF8 compatible terminal,
8176: the use of this option (and
8177: .Em not
8178: setting
8179: .Ar esc_msb )
8180: may result in the correct display of multibyte
8181: .Pq international
8182: characters.
8183: If this option is not present, multibyte characters larger than 0xff
8184: will be represented using the format \eUXXXX for 16 bits and \eWXXXXXXXX
8185: for 32 bits.
8186: Also, if this option is off, any UTF8Strings will be converted to their
8187: character form first.
8188: .El
8189: .Sh X509 TEXT OPTIONS
8190: As well as customising the name output format, it is also possible to
8191: customise the actual fields printed using the
8192: .Fl certopt
8193: options when the
8194: .Fl text
8195: option is present.
8196: The default behaviour is to print all fields.
8197: .Bl -tag -width "XXXX"
8198: .It Ar ca_default
8199: The value used by the
8200: .Nm ca
8201: utility; equivalent to
8202: .Ar no_issuer , no_pubkey , no_header ,
8203: .Ar no_version , no_sigdump ,
8204: and
8205: .Ar no_signame .
8206: .It Ar compatible
8207: Use the old format.
8208: This is equivalent to specifying no output options at all.
8209: .It Ar ext_default
8210: Retain default extension behaviour: attempt to print out unsupported
8211: certificate extensions.
8212: .It Ar ext_dump
8213: Hex dump unsupported extensions.
8214: .It Ar ext_error
8215: Print an error message for unsupported certificate extensions.
8216: .It Ar ext_parse
8217: ASN1 parse unsupported extensions.
8218: .It Ar no_aux
8219: Don't print out certificate trust information.
8220: .It Ar no_extensions
8221: Don't print out any X509V3 extensions.
8222: .It Ar no_header
8223: Don't print header information: that is, the lines saying
8224: .Qq Certificate
8225: and
8226: .Qq Data .
8227: .It Ar no_issuer
8228: Don't print out the issuer name.
8229: .It Ar no_pubkey
8230: Don't print out the public key.
8231: .It Ar no_serial
8232: Don't print out the serial number.
8233: .It Ar no_sigdump
8234: Don't give a hexadecimal dump of the certificate signature.
8235: .It Ar no_signame
8236: Don't print out the signature algorithm used.
8237: .It Ar no_subject
8238: Don't print out the subject name.
8239: .It Ar no_validity
8240: Don't print the validity; that is, the
8241: .Em notBefore
8242: and
8243: .Em notAfter
8244: fields.
8245: .It Ar no_version
8246: Don't print out the version number.
8247: .El
8248: .Sh X509 EXAMPLES
8249: Display the contents of a certificate:
8250: .Pp
8251: .Dl $ openssl x509 -in cert.pem -noout -text
8252: .Pp
8253: Display the certificate serial number:
8254: .Pp
8255: .Dl $ openssl x509 -in cert.pem -noout -serial
8256: .Pp
8257: Display the certificate subject name:
8258: .Pp
8259: .Dl $ openssl x509 -in cert.pem -noout -subject
8260: .Pp
8261: Display the certificate subject name in RFC 2253 form:
8262: .Pp
8263: .Dl $ openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
8264: .Pp
8265: Display the certificate subject name in oneline form on a terminal
8266: supporting UTF8:
8267: .Bd -literal -offset indent
8268: $ openssl x509 -in cert.pem -noout -subject \e
8269: -nameopt oneline,-esc_msb
8270: .Ed
8271: .Pp
8272: Display the certificate MD5 fingerprint:
8273: .Pp
8274: .Dl $ openssl x509 -in cert.pem -noout -fingerprint
8275: .Pp
8276: Display the certificate SHA1 fingerprint:
8277: .Pp
8278: .Dl $ openssl x509 -sha1 -in cert.pem -noout -fingerprint
8279: .Pp
8280: Convert a certificate from PEM to DER format:
8281: .Pp
8282: .Dl "$ openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER"
8283: .Pp
8284: Convert a certificate to a certificate request:
8285: .Bd -literal -offset indent
8286: $ openssl x509 -x509toreq -in cert.pem -out req.pem \e
8287: -signkey key.pem
8288: .Ed
8289: .Pp
8290: Convert a certificate request into a self-signed certificate using
8291: extensions for a CA:
8292: .Bd -literal -offset indent
8293: $ openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions \e
8294: v3_ca -signkey key.pem -out cacert.pem
8295: .Ed
8296: .Pp
8297: Sign a certificate request using the CA certificate above and add user
8298: certificate extensions:
8299: .Bd -literal -offset indent
8300: $ openssl x509 -req -in req.pem -extfile openssl.cnf -extensions \e
8301: v3_usr -CA cacert.pem -CAkey key.pem -CAcreateserial
8302: .Ed
8303: .Pp
8304: Set a certificate to be trusted for SSL
8305: client use and set its alias to
8306: .Qq Steve's Class 1 CA :
8307: .Bd -literal -offset indent
8308: $ openssl x509 -in cert.pem -addtrust clientAuth \e
8309: -setalias "Steve's Class 1 CA" -out trust.pem
8310: .Ed
8311: .Sh X509 NOTES
8312: The PEM format uses the header and footer lines:
8313: .Bd -unfilled -offset indent
8314: -----BEGIN CERTIFICATE-----
8315: -----END CERTIFICATE-----
8316: .Ed
8317: .Pp
8318: It will also handle files containing:
8319: .Bd -unfilled -offset indent
8320: -----BEGIN X509 CERTIFICATE-----
8321: -----END X509 CERTIFICATE-----
8322: .Ed
8323: .Pp
8324: Trusted certificates have the lines:
8325: .Bd -unfilled -offset indent
8326: -----BEGIN TRUSTED CERTIFICATE-----
8327: -----END TRUSTED CERTIFICATE-----
8328: .Ed
8329: .Pp
8330: The conversion to UTF8 format used with the name options assumes that
8331: T61Strings use the ISO 8859-1 character set.
8332: This is wrong, but Netscape and MSIE do this, as do many certificates.
8333: So although this is incorrect
8334: it is more likely to display the majority of certificates correctly.
8335: .Pp
8336: The
8337: .Fl fingerprint
8338: option takes the digest of the DER-encoded certificate.
8339: This is commonly called a
8340: .Qq fingerprint .
8341: Because of the nature of message digests, the fingerprint of a certificate
8342: is unique to that certificate and two certificates with the same fingerprint
8343: can be considered to be the same.
8344: .Pp
8345: The Netscape fingerprint uses MD5, whereas MSIE uses SHA1.
8346: .Pp
8347: The
8348: .Fl email
8349: option searches the subject name and the subject alternative
8350: name extension.
8351: Only unique email addresses will be printed out: it will
8352: not print the same address more than once.
8353: .Sh X.509 CERTIFICATE EXTENSIONS
8354: The
8355: .Fl purpose
8356: option checks the certificate extensions and determines
8357: what the certificate can be used for.
8358: The actual checks done are rather
8359: complex and include various hacks and workarounds to handle broken
8360: certificates and software.
8361: .Pp
8362: The same code is used when verifying untrusted certificates in chains,
8363: so this section is useful if a chain is rejected by the verify code.
8364: .Pp
8365: The
8366: .Em basicConstraints
8367: extension CA flag is used to determine whether the
8368: certificate can be used as a CA.
8369: If the CA flag is true, it is a CA;
8370: if the CA flag is false, it is not a CA.
8371: .Em All
8372: CAs should have the CA flag set to true.
8373: .Pp
8374: If the
8375: .Em basicConstraints
8376: extension is absent, then the certificate is
8377: considered to be a
8378: .Qq possible CA ;
8379: other extensions are checked according to the intended use of the certificate.
8380: A warning is given in this case because the certificate should really not
8381: be regarded as a CA: however,
8382: it is allowed to be a CA to work around some broken software.
8383: .Pp
8384: If the certificate is a V1 certificate
8385: .Pq and thus has no extensions
8386: and it is self-signed, it is also assumed to be a CA but a warning is again
8387: given: this is to work around the problem of Verisign roots which are V1
8388: self-signed certificates.
8389: .Pp
8390: If the
8391: .Em keyUsage
8392: extension is present, then additional restraints are
8393: made on the uses of the certificate.
8394: A CA certificate
8395: .Em must
8396: have the
8397: .Em keyCertSign
8398: bit set if the
8399: .Em keyUsage
8400: extension is present.
8401: .Pp
8402: The extended key usage extension places additional restrictions on the
8403: certificate uses.
8404: If this extension is present
8405: .Pq whether critical or not ,
8406: the key can only be used for the purposes specified.
8407: .Pp
8408: A complete description of each test is given below.
8409: The comments about
8410: .Em basicConstraints
8411: and
8412: .Em keyUsage
8413: and V1 certificates above apply to
8414: .Em all
8415: CA certificates.
8416: .Bl -tag -width "XXXX"
8417: .It Ar SSL Client
8418: The extended key usage extension must be absent or include the
8419: .Qq web client authentication
8420: OID.
8421: .Ar keyUsage
8422: must be absent or it must have the
8423: .Em digitalSignature
8424: bit set.
8425: Netscape certificate type must be absent or it must have the SSL
8426: client bit set.
8427: .It Ar SSL Client CA
8428: The extended key usage extension must be absent or include the
8429: .Qq web client authentication
8430: OID.
8431: Netscape certificate type must be absent or it must have the SSL CA
8432: bit set: this is used as a work around if the
8433: .Em basicConstraints
8434: extension is absent.
8435: .It Ar SSL Server
8436: The extended key usage extension must be absent or include the
8437: .Qq web server authentication
8438: and/or one of the SGC OIDs.
8439: .Em keyUsage
8440: must be absent or it must have the
8441: .Em digitalSignature
8442: set, the
8443: .Em keyEncipherment
8444: set, or both bits set.
8445: Netscape certificate type must be absent or have the SSL server bit set.
8446: .It Ar SSL Server CA
8447: The extended key usage extension must be absent or include the
8448: .Qq web server authentication
8449: and/or one of the SGC OIDs.
8450: Netscape certificate type must be absent or the SSL CA
8451: bit must be set: this is used as a work around if the
8452: .Em basicConstraints
8453: extension is absent.
8454: .It Ar Netscape SSL Server
8455: For Netscape SSL clients to connect to an SSL server; it must have the
8456: .Em keyEncipherment
8457: bit set if the
8458: .Em keyUsage
8459: extension is present.
8460: This isn't always valid because some cipher suites use the key for
8461: digital signing.
8462: Otherwise it is the same as a normal SSL server.
8463: .It Ar Common S/MIME Client Tests
8464: The extended key usage extension must be absent or include the
8465: .Qq email protection
8466: OID.
8467: Netscape certificate type must be absent or should have the
8468: .Em S/MIME
8469: bit set.
8470: If the
8471: .Em S/MIME
8472: bit is not set in Netscape certificate type, then the SSL
8473: client bit is tolerated as an alternative but a warning is shown:
8474: this is because some Verisign certificates don't set the
8475: .Em S/MIME
8476: bit.
8477: .It Ar S/MIME Signing
8478: In addition to the common
8479: .Em S/MIME
8480: client tests, the
8481: .Em digitalSignature
8482: bit must be set if the
8483: .Em keyUsage
8484: extension is present.
8485: .It Ar S/MIME Encryption
8486: In addition to the common
8487: .Em S/MIME
8488: tests, the
8489: .Em keyEncipherment
8490: bit must be set if the
8491: .Em keyUsage
8492: extension is present.
8493: .It Ar S/MIME CA
8494: The extended key usage extension must be absent or include the
8495: .Qq email protection
8496: OID.
8497: Netscape certificate type must be absent or must have the
8498: .Em S/MIME CA
8499: bit set: this is used as a work around if the
8500: .Em basicConstraints
8501: extension is absent.
8502: .It Ar CRL Signing
8503: The
8504: .Em keyUsage
8505: extension must be absent or it must have the
8506: .Em CRL
8507: signing bit set.
8508: .It Ar CRL Signing CA
8509: The normal CA tests apply.
8510: Except in this case the
8511: .Em basicConstraints
8512: extension must be present.
8513: .El
8514: .Sh X509 BUGS
8515: Extensions in certificates are not transferred to certificate requests and
8516: vice versa.
8517: .Pp
8518: It is possible to produce invalid certificates or requests by specifying the
8519: wrong private key or using inconsistent options in some cases: these should
8520: be checked.
8521: .Pp
8522: There should be options to explicitly set such things as start and end dates,
8523: rather than an offset from the current time.
8524: .Pp
8525: The code to implement the verify behaviour described in the
8526: .Sx X509 TRUST SETTINGS
8527: is currently being developed.
8528: It thus describes the intended behaviour rather than the current behaviour.
8529: It is hoped that it will represent reality in
8530: .Nm OpenSSL
8531: 0.9.5 and later.
8532: .Sh X509 HISTORY
8533: Before
8534: .Nm OpenSSL
8535: 0.9.8,
8536: the default digest for RSA keys was MD5.
8537: .Pp
8538: The hash algorithm used in the
8539: .Fl subject_hash
8540: and
8541: .Fl issuer_hash
8542: options before
8543: .Nm OpenSSL
8544: 1.0.0 was based on the deprecated MD5 algorithm and the encoding
8545: of the distinguished name.
8546: In
8547: .Nm OpenSSL
8548: 1.0.0 and later it is based on a canonical version of the DN using SHA1.
8549: This means that any directories using the old form
8550: must have their links rebuilt using
8551: .Ar c_rehash
8552: or similar.
1.38 jmc 8553: .Sh COMMON NOTATION
8554: Several commands share a common syntax,
8555: as detailed below.
8556: .Pp
8557: Password arguments, typically specified using
1.33 jmc 8558: .Fl passin
8559: and
8560: .Fl passout
1.38 jmc 8561: for input and output passwords,
8562: allow passwords to be obtained from a variety of sources.
8563: Both of these options take a single argument, described below.
1.33 jmc 8564: If no password argument is given and a password is required,
8565: then the user is prompted to enter one:
8566: this will typically be read from the current terminal with echoing turned off.
1.38 jmc 8567: .Bl -tag -width "pass:password" -offset indent
8568: .It Cm pass : Ns Ar password
1.33 jmc 8569: The actual password is
8570: .Ar password .
1.38 jmc 8571: Since the password is visible to utilities,
1.33 jmc 8572: this form should only be used where security is not important.
1.38 jmc 8573: .It Cm env : Ns Ar var
1.33 jmc 8574: Obtain the password from the environment variable
8575: .Ar var .
1.38 jmc 8576: Since the environment of other processes is visible,
8577: this option should be used with caution.
8578: .It Cm file : Ns Ar path
1.33 jmc 8579: The first line of
8580: .Ar path
8581: is the password.
8582: If the same
8583: .Ar path
8584: argument is supplied to
8585: .Fl passin
8586: and
8587: .Fl passout ,
8588: then the first line will be used for the input password and the next line
8589: for the output password.
8590: .Ar path
8591: need not refer to a regular file:
8592: it could, for example, refer to a device or named pipe.
1.38 jmc 8593: .It Cm fd : Ns Ar number
1.33 jmc 8594: Read the password from the file descriptor
8595: .Ar number .
1.38 jmc 8596: This can be used to send the data via a pipe, for example.
8597: .It Cm stdin
1.33 jmc 8598: Read the password from standard input.
1.35 jmc 8599: .El
1.38 jmc 8600: .Pp
8601: File formats,
8602: typically specified using
8603: .Fl inform
8604: and
8605: .Fl outform ,
8606: indicate the type of file being read from
8607: or the file format to write.
8608: The argument is case insensitive.
8609: .Pp
8610: .Bl -tag -width Ds -offset indent -compact
8611: .It Cm der
8612: Distinguished Encoding Rules (DER)
8613: is a binary format.
8614: .It Cm pem
8615: Privacy Enhanced Mail (PEM)
8616: is base64-encoded.
8617: .It Cm txt
8618: Plain ASCII text.
8619: .El
1.35 jmc 8620: .Sh ENVIRONMENT
8621: The following environment variables affect the execution of
8622: .Nm openssl :
1.38 jmc 8623: .Bl -tag -width "/etc/ssl/openssl.cnf"
1.35 jmc 8624: .It Ev OPENSSL_CONF
8625: The location of the master configuration file.
1.33 jmc 8626: .El
1.1 jsing 8627: .\"
8628: .\" FILES
8629: .\"
8630: .Sh FILES
8631: .Bl -tag -width "/etc/ssl/openssl.cnf" -compact
1.17 sobrado 8632: .It Pa /etc/ssl/
1.1 jsing 8633: Default config directory for
8634: .Nm openssl .
1.17 sobrado 8635: .It Pa /etc/ssl/lib/
1.1 jsing 8636: Unused.
1.17 sobrado 8637: .It Pa /etc/ssl/private/
1.1 jsing 8638: Default private key directory.
1.17 sobrado 8639: .It Pa /etc/ssl/openssl.cnf
1.1 jsing 8640: Default configuration file for
8641: .Nm openssl .
1.17 sobrado 8642: .It Pa /etc/ssl/x509v3.cnf
1.1 jsing 8643: Default configuration file for
8644: .Nm x509
8645: certificates.
8646: .El
8647: .\"
8648: .\" SEE ALSO
8649: .\"
8650: .Sh SEE ALSO
1.26 jmc 8651: .Xr nc 1 ,
1.1 jsing 8652: .Xr ssl 8 ,
8653: .Xr starttls 8
8654: .Sh STANDARDS
8655: .Rs
8656: .%D February 1995
8657: .%Q Netscape Communications Corp.
8658: .%T The SSL Protocol
8659: .Re
8660: .Pp
8661: .Rs
8662: .%D November 1996
8663: .%Q Netscape Communications Corp.
8664: .%T The SSL 3.0 Protocol
8665: .Re
8666: .Pp
8667: .Rs
8668: .%A T. Dierks
8669: .%A C. Allen
8670: .%D January 1999
8671: .%R RFC 2246
8672: .%T The TLS Protocol Version 1.0
8673: .Re
8674: .Pp
8675: .Rs
8676: .%A M. Wahl
8677: .%A S. Killie
8678: .%A T. Howes
8679: .%D December 1997
8680: .%R RFC 2253
8681: .%T Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names
8682: .Re
8683: .Pp
8684: .Rs
8685: .%A B. Kaliski
8686: .%D March 1998
8687: .%R RFC 2315
8688: .%T PKCS #7: Cryptographic Message Syntax Version 1.5
8689: .Re
8690: .Pp
8691: .Rs
8692: .%A R. Housley
8693: .%A W. Ford
8694: .%A W. Polk
8695: .%A D. Solo
8696: .%D January 1999
8697: .%R RFC 2459
8698: .%T Internet X.509 Public Key Infrastructure Certificate and CRL Profile
8699: .Re
8700: .Pp
8701: .Rs
8702: .%A M. Myers
8703: .%A R. Ankney
8704: .%A A. Malpani
8705: .%A S. Galperin
8706: .%A C. Adams
8707: .%D June 1999
8708: .%R RFC 2560
8709: .%T X.509 Internet Public Key Infrastructure Online Certificate Status Protocol \(en OCSP
8710: .Re
8711: .Pp
8712: .Rs
8713: .%A R. Housley
8714: .%D June 1999
8715: .%R RFC 2630
8716: .%T Cryptographic Message Syntax
8717: .Re
8718: .Pp
8719: .Rs
8720: .%A P. Chown
8721: .%D June 2002
8722: .%R RFC 3268
1.24 jmc 8723: .%T Advanced Encryption Standard (AES) Ciphersuites for Transport Layer Security (TLS)
1.1 jsing 8724: .Re