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