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