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