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