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