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