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