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