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