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