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