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