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