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