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