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