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