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