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