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