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