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