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