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