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