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