diff options
| -rw-r--r-- | lib/libssl/man/Makefile | 3 | ||||
| -rw-r--r-- | usr.sbin/openssl/Makefile | 2 | ||||
| -rw-r--r-- | usr.sbin/openssl/openssl.1 | 7616 |
3 files changed, 7618 insertions, 3 deletions
diff --git a/lib/libssl/man/Makefile b/lib/libssl/man/Makefile index 0ab8c2e360f..930c5f56af2 100644 --- a/lib/libssl/man/Makefile +++ b/lib/libssl/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.3 2002/10/09 08:22:49 fgsch Exp $ +# $OpenBSD: Makefile,v 1.4 2003/03/05 20:59:15 deraadt Exp $ .include <bsd.own.mk> # for NOMAN @@ -173,7 +173,6 @@ MANALL= \ dsa.cat3 \ lh_stats.cat3 \ lhash.cat3 \ - openssl.cat1 \ rsa.cat3 \ ssl.cat3 diff --git a/usr.sbin/openssl/Makefile b/usr.sbin/openssl/Makefile index ee8f5b8c5cf..c1563892b31 100644 --- a/usr.sbin/openssl/Makefile +++ b/usr.sbin/openssl/Makefile @@ -6,7 +6,7 @@ BINGRP= bin BINMODE= 555 BINDIR= /usr/sbin LDADD= -lssl -lcrypto -NOMAN= not yet kiddies +MAN1= openssl.1 SSLEAYDIST= lib/libssl/src diff --git a/usr.sbin/openssl/openssl.1 b/usr.sbin/openssl/openssl.1 new file mode 100644 index 00000000000..1d826d8b0f5 --- /dev/null +++ b/usr.sbin/openssl/openssl.1 @@ -0,0 +1,7616 @@ +.\" ==================================================================== +.\" Copyright (c) 1998-2002 The OpenSSL Project. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" 3. All advertising materials mentioning features or use of this +.\" software must display the following acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" +.\" +.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to +.\" endorse or promote products derived from this software without +.\" prior written permission. For written permission, please contact +.\" openssl-core@openssl.org. +.\" +.\" 5. Products derived from this software may not be called "OpenSSL" +.\" nor may "OpenSSL" appear in their names without prior written +.\" permission of the OpenSSL Project. +.\" +.\" 6. Redistributions of any form whatsoever must retain the following +.\" acknowledgment: +.\" "This product includes software developed by the OpenSSL Project +.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY +.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR +.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED +.\" OF THE POSSIBILITY OF SUCH DAMAGE. +.\" ==================================================================== +.\" +.\" This product includes cryptographic software written by Eric Young +.\" (eay@cryptsoft.com). This product includes software written by Tim +.\" Hudson (tjh@cryptsoft.com). +.\" +.\" +.\" Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com) +.\" All rights reserved. +.\" +.\" This package is an SSL implementation written +.\" by Eric Young (eay@cryptsoft.com). +.\" The implementation was written so as to conform with Netscapes SSL. +.\" +.\" This library is free for commercial and non-commercial use as long as +.\" the following conditions are aheared to. The following conditions +.\" apply to all code found in this distribution, be it the RC4, RSA, +.\" lhash, DES, etc., code; not just the SSL code. The SSL documentation +.\" included with this distribution is covered by the same copyright terms +.\" except that the holder is Tim Hudson (tjh@cryptsoft.com). +.\" +.\" Copyright remains Eric Young's, and as such any Copyright notices in +.\" the code are not to be removed. +.\" If this package is used in a product, Eric Young should be given attribution +.\" as the author of the parts of the library used. +.\" This can be in the form of a textual message at program startup or +.\" in documentation (online or textual) provided with the package. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" "This product includes cryptographic software written by +.\" Eric Young (eay@cryptsoft.com)" +.\" The word 'cryptographic' can be left out if the rouines from the library +.\" being used are not cryptographic related :-). +.\" 4. If you include any Windows specific code (or a derivative thereof) from +.\" the apps directory (application code) you must include an +.\" acknowledgement: +.\" "This product includes software written by Tim Hudson +.\" (tjh@cryptsoft.com)" +.\" +.\" THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" The licence and distribution terms for any publically available version or +.\" derivative of this code cannot be changed. i.e. this code cannot simply be +.\" copied and put under another distribution licence +.\" [including the GNU Public Licence.] +.\" +.\" ssl(1) +.\" +.Dd February, 28 2003 +.Dt OPENSSL 1 +.Os +.Sh NAME +.Nm openssl +.Nd OpenSSL command line tool +.Sh SYNOPSIS +.Nm +.Cm command +.Op Ar command_opts +.Op Ar command_args +.Pp +.Nm +.Bk -words +.Oo Cm list-standard-commands Li |\ \& +.Cm list-message-digest-commands | +.Cm \ \ \ \ list-cipher-commands +.Oc +.Ek +.Pp +.Nm +.Cm no- Ns Ar XXX +.Op Ar arbitrary options +.Pp +.Sh DESCRIPTION +.Nm OpenSSL +is a cryptography toolkit implementing the Secure Sockets Layer +(SSL v2/v3) and Transport Layer Security (TLS v1) network protocols and +related cryptography standards required by them. +.Pp +The +.Nm +program is a command line tool for using the various +cryptography functions of +.Nm OpenSSL Ns Li 's +.Em crypto +library from the shell. +It can be used for +.Pp +.Bl -bullet -compact +.It +Creation of RSA, DH and DSA key parameters +.It +Creation of X.509 certificates, CSRs and CRLs +.It +Calculation of Message Digests +.It +Encryption and Decryption with Ciphers +.It +SSL/TLS Client and Server Tests +.It +Handling of S/MIME signed or encrypted mail +.El +.Sh COMMAND SUMMARY +The +.Nm +program provides a rich variety of commands +.Po Cm command\ \& +in the +.Sx SYNOPSIS +above +.Pc , +each of which often has a wealth of options and arguments +.Po Ar command_opts\ \& +and +.Ar command_args +in the +.Sx SYNOPSIS +.Pc . +.Pp +The pseudo-commands +.Cm list-standard-commands , list-message-digest-commands , +and +.Cm list-cipher-commands +output a list (one entry per line) of the names +of all standard commands, message digest commands, or cipher commands, +respectively, that are available in the present +.Nm +utility. +.Pp +The pseudo-command +.Cm no- Ns Ar XXX +tests whether a command of the +specified name is available. +If no command named +.Ar XXX +exists, +it returns 0 (success) and prints +.Cm no- Ns Ar XXX ; +otherwise it returns 1 and prints +.Ar XXX . +In both cases, the output goes to +.Em stdout +and nothing is printed to +.Em stderr . +Additional command line arguments are always ignored. +Since for each cipher there is a command of the same name, +this provides an easy way for shell scripts to test for the +availability of ciphers in the +.Nm +program. +.Pp +.Sy Note: +.Cm no- Ns Ar XXX +is not able to detect pseudo-commands such as +.Cm quit , +.Cm list- Ns Ar ... Ns Cm -commands , +or +.Cm no- Ns Ar XXX +itself. +.Sh STANDARD COMMANDS +.Bl -tag -width "asn1parse" +.It Cm asn1parse +Parse an ASN.1 sequence. +.It Cm ca +Certificate Authority (CA) Management. +.It Cm ciphers +Cipher Suite Description Determination. +.It Cm crl +Certificate Revocation List (CRL) Management. +.It Cm crl2pkcs7 +CRL to PKCS#7 Conversion. +.It Cm dgst +Message Digest Calculation. +.It Cm dh +Diffie-Hellman Parameter Management. +Obsoleted by +.Cm dhparam . +.It Cm dhparam +Generation and Management of Diffie-Hellman Parameters. +.It Cm dsa +DSA Data Management. +.It Cm dsaparam +DSA Parameter Generation. +.It Cm enc +Encoding with Ciphers. +.It Cm errstr +Error Number to Error String Conversion. +.It Cm gendh +Generation of Diffie-Hellman Parameters. +Obsoleted by +.Cm dhparam . +.It Cm gendsa +Generation of DSA Parameters. +.It Cm genrsa +Generation of RSA Parameters. +.It Cm nseq +Create or examine a netscape certificate sequence. +.It Cm ocsp +Online Certificate Status Protocol utility. +.It Cm passwd +Generation of hashed passwords. +.It Cm pkcs7 +PKCS#7 Data Management. +.It Cm pkcs8 +PKCS#8 Data Management. +.It Cm pkcs12 +PKCS#12 Data Management. +.It Cm rand +Generate pseudo-random bytes. +.It Cm req +X.509 Certificate Signing Request (CSR) Management. +.It Cm rsa +RSA Data Management. +.It Cm rsautl +RSA utility for signing, verification, encryption, and decryption. +.It Cm s_client +This implements a generic SSL/TLS client which can establish a transparent +connection to a remote server speaking SSL/TLS. +It's intended for testing purposes only and provides only rudimentary +interface functionality but internally uses mostly all functionality of the +.Nm OpenSSL +.Em ssl +library. +.It Cm s_server +This implements a generic SSL/TLS server which accepts connections from remote +clients speaking SSL/TLS. +It's intended for testing purposes only and provides only rudimentary +interface functionality but internally uses mostly all functionality of the +.Nm OpenSSL +.Em ssl +library. +It provides both an own command line oriented protocol for testing +SSL functions and a simple HTTP response +facility to emulate an SSL/TLS-aware webserver. +.It Cm s_time +SSL Connection Timer. +.It Cm sess_id +SSL Session Data Management. +.It Cm smime +S/MIME mail processing. +.It Cm speed +Algorithm Speed Measurement. +.It Cm spkac +SPKAC printing and generating utility. +.It Cm verify +X.509 Certificate Verification. +.It Cm version +.Nm OpenSSL +Version Information. +.It Cm x509 +X.509 Certificate Data Management. +.El +.Sh MESSAGE DIGEST COMMANDS +.Bl -tag -width "asn1parse" +.It Cm md2 +MD2 Digest. +.It Cm md5 +MD5 Digest. +.It Cm mdc2 +MDC2 Digest. +.It Cm rmd160 +RMD-160 Digest. +.It Cm sha +SHA Digest. +.It Cm sha1 +SHA-1 Digest. +.El +.Sh ENCODING AND CIPHER COMMANDS +.Bl -tag -width "asn1parse" +.It Cm base64 +Base64 Encoding. +.It Cm bf bf-cbc bf-cfb bf-ecb bf-ofb +Blowfish Cipher. +.It Cm cast cast-cbc +CAST Cipher. +.It Cm cast5-cbc cast5-cfb cast5-ecb cast5-ofb +CAST5 Cipher. +.It Cm des des-cbc des-cfb des-ecb des-ede des-ede-cbc +.It Cm des-ede-cfb des-ede-ofb des-ofb +DES Cipher. +.It Cm des3 desx des-ede3 des-ede3-cbc des-ede3-cfb des-ede3-ofb +Triple-DES Cipher. +.It Cm idea idea-cbc idea-cfb idea-ecb idea-ofb +IDEA Cipher. +.It Cm rc2 rc2-cbc rc2-cfb rc2-ecb rc2-ofb +RC2 Cipher. +.It Cm rc4 +RC4 Cipher. +.It Cm rc5 rc5-cbc rc5-cfb rc5-ecb rc5-ofb +RC5 Cipher. +.El +.Sh PASS PHRASE ARGUMENTS +Several commands accept password arguments, typically using +.Fl passin +and +.Fl passout +for input and output passwords, respectively. +These allow the password to be obtained from a variety of sources. +Both of these options take a single argument whose format is described below. +If no password argument is given and a password is required then the user is +prompted to enter one: this will typically be read from the current +terminal with echoing turned off. +.Bl -tag -width "fd:number" +.It Ar pass:password +The actual password is +.Ar password . +Since the password is visible to utilities +(like +.Xr ps 1 +under Unix) this form should only be used where security is not important. +.It Ar env:var +Obtain the password from the environment variable +.Ar var . +Since the environment of other processes is visible on certain platforms +(e.g. +.Xr ps 1 +under certain Unix OSes) this option should be used with caution. +.It Ar file:pathname +The first line of +.Ar pathname +is the password. +If the same +.Ar pathname +argument is supplied to +.Fl passin +and +.Fl passout +then the first line will be used for the input password and the next line +for the output password. +.Ar pathname +need not refer to a regular file: +it could, for example, refer to a device or named pipe. +.It Ar fd:number +Read the password from the file descriptor +.Ar number . +This can be used to send the data via a pipe for example. +.It Ar stdin +Read the password from standard input. +.\" +.\" ASN1PARSE +.\" +.Sh ASN1PARSE +.Pp +.Nm "openssl asn1parse" +.Op Fl inform Ar PEM|DER +.Op Fl in Ar filename +.Op Fl out Ar filename +.Op Fl noout +.Op Fl offset Ar number +.Op Fl length Ar number +.Op Fl i +.Op Fl oid Ar filename +.Op Fl strparse Ar offset +.Pp +The +.Nm asn1parse +command is a diagnostic utility that can parse ASN.1 structures. +It can also be used to extract data from ASN.1 formatted data. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl inform Ar DER|PEM +The input format. +.Ar DER +is binary format and +.Ar PEM +(the default) is base64 encoded. +.It Fl in Ar filename +The input file; default is standard input. +.It Fl out Ar filename +Output file to place the +.Em DER +encoded data into. +If this option is not present then no data will be output. +This is most useful when combined with the +.Fl strparse +option. +.It Fl noout +Don't output the parsed version of the input file. +.It Fl offset Ar number +Starting offset to begin parsing; default is start of file. +.It Fl length Ar number +Number of bytes to parse; default is until end of file. +.It Fl i +Indents the output according to the "depth" of the structures. +.It Fl oid Ar filename +A file containing additional OBJECT IDENTIFIERs (OIDs). +The format of this file is described in the +.Sx ASN1PARSE NOTES +section below. +.It Fl strparse Ar offset +Parse the contents octets of the ASN.1 object starting at +.Ar offset . +This option can be used multiple times to "drill down" into a nested structure. +.Sh ASN1PARSE OUTPUT +The output will typically contain lines like this: +.Pp +.Bd -literal + 0:d=0 hl=4 l= 681 cons: SEQUENCE +.Pp +\&..... +.Pp + 229:d=3 hl=3 l= 141 prim: BIT STRING + 373:d=2 hl=3 l= 162 cons: cont [ 3 ] + 376:d=3 hl=3 l= 159 cons: SEQUENCE + 379:d=4 hl=2 l= 29 cons: SEQUENCE + 381:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Subject Key Identifier + 386:d=5 hl=2 l= 22 prim: OCTET STRING + 410:d=4 hl=2 l= 112 cons: SEQUENCE + 412:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Authority Key Identifier + 417:d=5 hl=2 l= 105 prim: OCTET STRING + 524:d=4 hl=2 l= 12 cons: SEQUENCE +.Pp +\&..... +.Ed +.Pp +This example is part of a self-signed certificate. +Each line starts with the offset in decimal. +.Cm d=XX +specifies the current depth. +The depth is increased within the scope of any SET or SEQUENCE. +.Cm hl=XX +gives the header length (tag and length octets) of the current type. +.Cm l=XX +gives the length of the contents octets. +.Pp +The +.Fl i +option can be used to make the output more readable. +.Pp +Some knowledge of the ASN.1 structure is needed to interpret the output. +.Pp +In this example the BIT STRING at offset 229 is the certificate public key. +The contents octets of this will contain the public key information. +This can be examined using the option +.Fl strparse Cm 229 +to yield: +.Pp +.Bd -literal +\& 0:d=0 hl=3 l= 137 cons: SEQUENCE +\& 3:d=1 hl=3 l= 129 prim: INTEGER :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897 +\& 135:d=1 hl=2 l= 3 prim: INTEGER :010001 +.Sh ASN1PARSE NOTES +If an OID is not part of +.Nm OpenSSL Ns Li 's +internal table it will be represented in +numerical form (for example 1.2.3.4). +The file passed to the +.Fl oid +option allows additional OIDs to be included. +Each line consists of three columns, +the first column is the OID in numerical format and should be followed by +whitespace. +The second column is the "short name" which is a single word followed +by whitespace. +The final column is the rest of the line and is the "long name". +.Nm asn1parse +displays the long name. +Example: +.Pp +"1.2.3.4 shortName A long name" +.Sh ASN1PARSE BUGS +There should be options to change the format of input lines. +The output of some ASN.1 types is not well handled (if at all). +.\" +.\" ca +.\" +.Sh CA +.Nm openssl ca +.Bk -words +.Op Fl verbose +.Op Fl config Ar filename +.Op Fl name Ar section +.Op Fl gencrl +.Op Fl revoke Ar file +.Op Fl subj Ar arg +.Op Fl crldays Ar days +.Op Fl crlhours Ar hours +.Op Fl crlexts Ar section +.Op Fl startdate Ar date +.Op Fl enddate Ar date +.Op Fl days Ar arg +.Op Fl md Ar arg +.Op Fl policy Ar arg +.Op Fl keyfile Ar arg +.Op Fl key Ar arg +.Op Fl passin Ar arg +.Op Fl cert Ar file +.Op Fl in Ar file +.Op Fl out Ar file +.Op Fl notext +.Op Fl outdir Ar dir +.Op Fl infiles +.Op Fl spkac Ar file +.Op Fl ss_cert Ar file +.Op Fl preserveDN +.Op Fl noemailDN +.Op Fl batch +.Op Fl msie_hack +.Op Fl extensions Ar section +.Op Fl extfile Ar section +.Ek +.Pp +The +.Nm ca +command is a minimal CA application. +It can be used to sign certificate requests in a variety of forms +and generate CRLs. +It also maintains a text database of issued certificates and their status. +.Pp +The options descriptions will be divided into each purpose. +.Sh CA OPTIONS +.Bl -tag -width Ds +.It Fl config Ar filename +Specifies the configuration file to use. +.It Fl name Ar section +Specifies the configuration file +.Ar section +to use (overrides +.Cm default_ca +in the +.Cm ca +section). +.It Fl in Ar filename +An input +.Ar filename +containing a single certificate request to be signed by the CA. +.It Fl ss_cert Ar filename +A single self-signed certificate to be signed by the CA. +.It Fl spkac Ar filename +A file containing a single Netscape signed public key and challenge, +and additional field values to be signed by the CA. +See the +.Sx CA NOTES +section for information on the required format. +.It Fl infiles +If present, this should be the last option; all subsequent arguments +are assumed to be the names of files containing certificate requests. +.It Fl out Ar filename +The output file to output certificates to. +The default is standard output. +The certificate details will also be printed out to this file. +.It Fl outdir Ar directory +The +.Ar directory +to output certificates to. +The certificate will be written to a filename consisting of the +serial number in hex with ".pem" appended. +.It Fl cert +The CA certificate file. +.It Fl keyfile Ar filename +The private key to sign requests with. +.It Fl key Ar password +The password used to encrypt the private key. +Since on some systems the command line arguments are visible +(e.g. Unix with the +.Xr ps 1 +utility) this option should be used with caution. +.It Fl passin Ar arg +The key password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl verbose +This prints extra details about the operations being performed. +.It Fl notext +Don't output the text form of a certificate to the output file. +.It Fl startdate Ar date +This allows the start date to be explicitly set. +The format of the date is YYMMDDHHMMSSZ +(the same as an ASN1 UTCTime structure). +.It Fl enddate Ar date +This allows the expiry date to be explicitly set. +The format of the date is YYMMDDHHMMSSZ +(the same as an ASN1 UTCTime structure). +.It Fl days Ar arg +The number of days to certify the certificate for. +.It Fl md Ar alg +The message digest to use. +Possible values include +.Ar md5 , sha1 +and +.Ar mdc2 . +This option also applies to CRLs. +.It Fl policy Ar arg +This option defines the CA "policy" to use. +This is a section in the configuration file which decides which fields +should be mandatory or match the CA certificate. +Check out the +.Sx CA POLICY FORMAT +section for more information. +.It Fl msie_hack +This is a legacy option to make +.Nm ca +work with very old versions of the IE certificate enrollment control +"certenr3". +It used UniversalStrings for almost everything. +Since the old control has various security bugs, +its use is strongly discouraged. +The newer control "Xenroll" does not need this option. +.It Fl preserveDN +Normally the DN order of a certificate is the same as the order of the +fields in the relevant policy section. +When this option is set, the order is the same as the request. +This is largely for compatibility with the older IE enrollment control +which would only accept certificates if their DNs matched the order of the +request. +This is not needed for Xenroll. +.It Fl noemailDN +The DN of a certificate can contain the EMAIL field if present in the +request DN, however it is good policy just having the e-mail set into +the +.Em altName +extension of the certificate. +When this option is set the EMAIL field is removed from the certificate's +subject and set only in the, eventually present, extensions. +The +.Ar email_in_dn +keyword can be used in the configuration file to enable this behaviour. +.It Fl batch +This sets the batch mode. +In this mode no questions will be asked +and all certificates will be certified automatically. +.It Fl extensions Ar section +The section of the configuration file containing certificate extensions +to be added when a certificate is issued (defaults to +.Em x509_extensions +unless the +.Fl extfile +option is used). +If no extension section is present, then a V1 certificate is created. +If the extension section is present (even if it is empty), +then a V3 certificate is created. +.It Fl extfile Ar file +An additional configuration +.Ar file +to read certificate extensions from +(using the default section unless the +.Fl extensions +option is also used). +.El +.Sh CRL OPTIONS +.Bl -tag -width Ds +.It Fl gencrl +This option generates a CRL based on information in the index file. +.It Fl crldays Ar num +The number of days before the next CRL is due. +This is the days from now to place in the CRL +.Em nextUpdate +field. +.It Fl crlhours Ar num +The number of hours before the next CRL is due. +.It Fl revoke Ar filename +A +.Ar filename +containing a certificate to revoke. +.It Fl subj Ar arg +Supersedes the subject name given in the request. +The +.Ar arg +must be formatted as +.Ar /type0=value0/type1=value1/type2=... ; +characters may be escaped by \e (backslash), no spaces are skipped. +.It Fl crlexts Ar section +The +.Ar section +of the configuration file containing CRL extensions to include. +If no CRL extension section is present then a V1 CRL is created; +if the CRL extension section is present (even if it is empty) +then a V2 CRL is created. +The CRL extensions specified are CRL extensions and +.Em not +CRL entry extensions. +It should be noted that some software (for example Netscape) +can't handle V2 CRLs. +.El +.Sh CA CONFIGURATION FILE OPTIONS +The section of the configuration file containing options for +.Nm ca +is found as follows: +If the +.Fl name +command line option is used, then it names the section to be used. +Otherwise the section to be used must be named in the +.Em default_ca +option of the +.Em ca +section of the configuration file (or in the default section of the +configuration file). +Besides +.Em default_ca , +the following options are read directly from the +.Em ca +section: +.Pp + RANDFILE + preserve + msie_hack +.Pp +With the exception of RANDFILE, this is probably a bug and may +change in future releases. +.Pp +Many of the configuration file options are identical to command line +options. +Where the option is present in the configuration file and the command line, +the command line value is used. +Where an option is described as mandatory, then it must be present in +the configuration file or the command line equivalent (if any) used. +.Pp +.Bl -tag -width Ds +.It Ar oid_file +This specifies a file containing additional OBJECT IDENTIFIERS. +Each line of the file should consist of the numerical form of the +object identifier followed by whitespace, then the short name followed +by whitespace and finally the long name. +.It Ar oid_section +This specifies a section in the configuration file containing extra +object identifiers. +Each line should consist of the short name of the object identifier +followed by +.Cm = +and the numerical form. +The short and long names are the same when this option is used. +.It Ar new_certs_dir +The same as the +.Fl outdir +command line option. +It specifies the directory where new certificates will be placed. +Mandatory. +.It Ar certificate +The same as +.Fl cert. +It gives the file containing the CA certificate. +Mandatory. +.It Ar private_key +Same as the +.Fl keyfile +option. +The file containing the CA private key. +Mandatory. +.It Ar RANDFILE +A file used to read and write random number seed information, +or an EGD socket (see +.Xr RAND_egd 3 ) . +.It Ar default_days +The same as the +.Fl days +option. +The number of days to certify a certificate for. +.It Ar default_startdate +The same as the +.Fl startdate +option. +The start date to certify a certificate for. +If not set, the current time is used. +.It Ar default_enddate +The same as the +.Fl enddate +option. +Either this option or +.Ar default_days +(or the command line equivalents) must be present. +.It Ar default_crl_hours default_crl_days +The same as the +.Fl crlhours +and the +.Fl crldays +options. +These will only be used if neither command line option is present. +At least one of these must be present to generate a CRL. +.It Ar default_md +The same as the +.Fl md +option. +The message digest to use. +Mandatory. +.It Ar database +The text database file to use. +Mandatory. +This file must be present, though initially it will be empty. +.It Ar serialfile +A text file containing the next serial number to use in hex. +Mandatory. +This file must be present and contain a valid serial number. +.It Ar x509_extensions +The same as +.Fl extensions . +.It Ar crl_extensions +the same as +.Fl crlexts . +.It Ar preserve +The same as +.Fl preserveDN . +.It Ar email_in_dn +The same as +.Fl noemailDN . +If the EMAIL field is to be removed from the DN of the certificate, +simply set this to 'no'. +If not present the default is to allow for the EMAIL field in the +certificate's DN. +.It Ar msie_hack +The same as +.Fl msie_hack . +.It Ar policy +The same as +.Fl policy . +Mandatory. +See the +.Sx CA POLICY FORMAT +section for more information. +.It Ar nameopt , certopt +These options allow the format used to display the certificate details +when asking the user to confirm signing. +All the options supported by the +.Nm x509 +utilities' +.Fl nameopt +and +.Fl certopt +switches can be used here, except that +.Ar no_signame +and +.Ar no_sigdump +are permanently set and cannot be disabled +(this is because the certificate signature cannot be displayed because +the certificate has not been signed at this point). +.Pp +For convenience the values +.Em default_ca +are accepted by both to produce a reasonable output. +.Pp +If neither option is present the format used in earlier versions of +.Nm OpenSSL +is used. +Use of the old format is +.Em strongly +discouraged because it only displays fields mentioned in the +.Ar policy +section, +mishandles multicharacter string types and does not display extensions. +.It Ar copy_extensions +Determines how extensions in certificate requests should be handled. +If set to +.Ar none +or this option is not present, then extensions are +ignored and not copied to the certificate. +If set to +.Ar copy +then any extensions present in the request that are not already present +are copied to the certificate. +If set to +.Ar copyall +then all extensions in the request are copied to the certificate: +if the extension is already present in the certificate it is deleted first. +See the +.Sx CA WARNINGS +section before using this option. +.Pp +The main use of this option is to allow a certificate request to supply +values for certain extensions such as +.Em subjectAltName . +.El +.Sh CA POLICY FORMAT +The policy section consists of a set of variables corresponding to +certificate DN fields. +If the value is "match" then the field value +must match the same field in the CA certificate. +If the value is "supplied" then it must be present. +If the value is "optional" then it may be present. +Any fields not mentioned in the policy section +are silently deleted, unless the +.Fl preserveDN +option is set, +but this can be regarded more of a quirk than intended behaviour. +.Sh SPKAC FORMAT +The input to the +.Fl spkac +command line option is a Netscape signed public key and challenge. +This will usually come from the +.Em KEYGEN +tag in an HTML form to create a new private key. +It is, however, possible to create SPKACs using the +.Nm spkac +utility. +.Pp +The file should contain the variable SPKAC set to the value of +the SPKAC and also the required DN components as name value pairs. +If it's necessary to include the same component twice then it can be +preceded by a number and a '.'. +.Sh CA EXAMPLES +.Sy Note: +these examples assume that the +.Nm ca +directory structure is already set up and the relevant files already exist. +This usually involves creating a CA certificate and private key with +.Cm req , +a serial number file and an empty index file and placing them in +the relevant directories. +.Pp +To use the sample configuration file below, the directories +.Pa demoCA , +.Pa demoCA/private +and +.Pa demoCA/newcerts +would be created. +The CA certificate would be copied to +.Pa demoCA/cacert.pem +and its private key to +.Pa demoCA/private/cakey.pem . +A file +.Pa demoCA/serial +would be created containing, for example, "01" and the empty index file +.Pa demoCA/index.txt . +.Pp +Sign a certificate request: +.Pp +\& $ openssl ca -in req.pem -out newcert.pem +.Pp +Sign a certificate request, using CA extensions: +.Pp +\& $ openssl ca -in req.pem -extensions v3_ca -out newcert.pem +.Pp +Generate a CRL: +.Pp +\& $ openssl ca -gencrl -out crl.pem +.Pp +Sign several requests: +.Pp +\& $ openssl ca -infiles req1.pem req2.pem req3.pem +.Pp +Certify a Netscape SPKAC: +.Pp +\& $ openssl ca -spkac spkac.txt +.Pp +A sample SPKAC file (the SPKAC line has been truncated for clarity): +.Pp +.Bd -literal +\& SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5 +\& CN=Steve Test +\& emailAddress=steve@openssl.org +\& 0.OU=OpenSSL Group +\& 1.OU=Another Group +.Ed +.Pp +A sample configuration file with the relevant sections for +.Nm ca : +.Pp +.Bd -literal +\& [ ca ] +\& default_ca = CA_default # The default ca section +.Pp +\& [ CA_default ] +.Pp +\& dir = ./demoCA # top dir +\& database = $dir/index.txt # index file +\& new_certs_dir = $dir/newcerts # new certs dir +.Pp +\& certificate = $dir/cacert.pem # The CA cert +\& serial = $dir/serial # serial no file +\& private_key = $dir/private/cakey.pem# CA private key +\& RANDFILE = $dir/private/.rand # random number file +.Pp +\& default_days = 365 # how long to certify for +\& default_crl_days= 30 # how long before next CRL +\& default_md = md5 # md to use +.Pp +\& policy = policy_any # default policy +\& email_in_dn = no # Don't add the email into cert DN +.Pp +\& nameopt = default_ca # Subject name display option +\& certopt = default_ca # Certificate display option +\& copy_extensions = none # Don't copy extensions from request +.Pp +\& [ policy_any ] +\& countryName = supplied +\& stateOrProvinceName = optional +\& organizationName = optional +\& organizationalUnitName = optional +\& commonName = supplied +\& emailAddress = optional +.Ed +.Sh CA WARNINGS +The +.Nm ca +command is quirky and at times downright unfriendly. +.Pp +The +.Nm ca +utility was originally meant as an example of how to do things in a CA. +It was not supposed to be used as a full blown CA itself; +nevertheless some people are using it for this purpose. +.Pp +The +.Nm ca +command is effectively a single user command: no locking is +done on the various files and attempts to run more than one +.Nm ca +command on the same database can have unpredictable results. +.Sh CA FILES +.Sy Note: +the location of all files can change either by compile time options, +configuration file entries, environment variables or command line options. +The values below reflect the default values. +.Pp +.Bd -literal +/usr/local/ssl/lib/openssl.cnf - master configuration file +\&./demoCA - main CA directory +\&./demoCA/cacert.pem - CA certificate +\&./demoCA/private/cakey.pem - CA private key +\&./demoCA/serial - CA serial number file +\&./demoCA/serial.old - CA serial number backup file +\&./demoCA/index.txt - CA text database file +\&./demoCA/index.txt.old - CA text database backup file +\&./demoCA/certs - certificate output file +\&./demoCA/.rnd - CA random seed information +.Ed +.Sh CA ENVIRONMENT VARIABLES +.Em OPENSSL_CONF +reflects the location of the master configuration file; +it can be overridden by the +.Fl config +command line option. +.Sh CA RESTRICTIONS +The text database index file is a critical part of the process, +and if corrupted it can be difficult to fix. +It is theoretically possible to rebuild the index file from all the +issued certificates and a current CRL; however there is no option to do this. +.Pp +CRL entry extensions cannot currently be created; only CRL extensions +can be added. +.Pp +V2 CRL features like delta CRL support and CRL numbers are not currently +supported. +.Pp +Although several requests can be input and handled at once, it is only +possible to include one SPKAC or self-signed certificate. +.Sh CA BUGS +The use of an in-memory text database can cause problems when large +numbers of certificates are present because, as the name implies, +the database has to be kept in memory. +.Pp +It is not possible to certify two certificates with the same DN; this +is a side effect of how the text database is indexed and it cannot easily +be fixed without introducing other problems. +Some S/MIME clients can use two certificates with the same DN for separate +signing and encryption keys. +.Pp +The +.Nm ca +command really needs rewriting or the required functionality +exposed at either a command or interface level so a more friendly utility +(perl script or GUI) can handle things properly. +The scripts +.Nm CA.sh +and +.Nm CA.pl +help a little but not very much. +.Pp +Any fields in a request that are not present in a policy are silently +deleted. +This does not happen if the +.Fl preserveDN +option is used. +To enforce the absence of the EMAIL field within the DN, as suggested +by RFCs, regardless of the contents of the request's subject the +.Fl noemailDN +option can be used. +The behaviour should be more friendly and configurable. +.Pp +Cancelling some commands by refusing to certify a certificate can +create an empty file. +.Sh CA WARNINGS +The +.Ar copy_extensions +option should be used with caution. +If care is not taken then it can be a security risk. +For example, if a certificate request contains a +.Em basicConstraints +extension with CA:TRUE and the +.Ar copy_extensions +value is set to +.Ar copyall +and the user does not spot +this when the certificate is displayed, then this will hand the requestor +a valid CA certificate. +.Pp +This situation can be avoided by setting +.Ar copy_extensions +to +.Ar copy +and including +.Em basicConstraints +with CA:FALSE in the configuration file. +Then if the request contains a +.Em basicConstraints +extension, it will be ignored. +.Pp +It is advisable to also include values for other extensions such +as +.Ar keyUsage +to prevent a request supplying its own values. +.Pp +Additional restrictions can be placed on the CA certificate itself. +For example if the CA certificate has: +.Pp +\& basicConstraints = CA:TRUE, pathlen:0 +.Pp +then even if a certificate is issued with CA:TRUE it will not be valid. +.\" +.\" CIPHERS +.\" +.Sh CIPHERS +.Nm openssl ciphers +.Op Fl v +.Op Fl ssl2 +.Op Fl ssl3 +.Op Fl tls1 +.Op Cm cipherlist +.Pp +The +.Nm cipherlist +command converts +.Nm OpenSSL +cipher lists into ordered SSL cipher preference lists. +It can be used as a test tool to determine the appropriate cipherlist. +.Pp +The options are as follows: +.Bl -tag -width -Ds +.It Fl v +Verbose option. +List ciphers with a complete description of protocol version +(SSLv2 or SSLv3; the latter includes TLS), key exchange, +authentication, encryption and mac algorithms used along with any key size +restrictions and whether the algorithm is classed as an +.Em export +cipher. +Note that without the +.Fl v +option, ciphers may seem to appear twice in a cipher list; +this is when similar ciphers are available for +SSL v2 and for SSL v3/TLS v1. +.It Fl ssl3 +Only include SSL v3 ciphers. +.It Fl ssl2 +Only include SSL v2 ciphers. +.It Fl tls1 +Only include TLS v1 ciphers. +.It Fl h , ? +Print a brief usage message. +.It Fl cipherlist +A cipher list to convert to a cipher preference list. +If it is not included, then the default cipher list will be used. +The format is described below. +.El +.Sh CIPHERS LIST FORMAT +The cipher list consists of one or more +.Em cipher strings +separated by colons. +Commas or spaces are also acceptable separators, but colons are normally used. +.Pp +The actual +.Em cipher string +can take several different forms: +.Pp +It can consist of a single cipher suite such as +.Em RC4-SHA . +.Pp +It can represent a list of cipher suites containing a certain algorithm, +or cipher suites of a certain type. +For example +.Em SHA1 +represents all cipher suites using the digest algorithm SHA1, and +.Em SSLv3 +represents all SSL v3 algorithms. +.Pp +Lists of cipher suites can be combined in a single +.Em cipher string +using the +.Cm + +character. +This is used as a logical +.Em and +operation. +For example, +.Em SHA1+DES +represents all cipher suites containing the SHA1 and the DES algorithms. +.Pp +Each cipher string can be optionally preceded by the characters +.Cm ! , - +or +.Cm + . +.Pp +If +.Cm ! +is used, then the ciphers are permanently deleted from the list. +The ciphers deleted can never reappear in the list even if they are +explicitly stated. +.Pp +If +.Cm - +is used, then the ciphers are deleted from the list, but some or +all of the ciphers can be added again by later options. +.br +.Pp +If +.Cm + +is used, then the ciphers are moved to the end of the list. +This option doesn't add any new ciphers, it just moves matching existing ones. +.Pp +If none of these characters is present, then the string is just interpreted +as a list of ciphers to be appended to the current preference list. +If the list includes any ciphers already present they will be ignored; +that is, they will not be moved to the end of the list. +.Pp +Additionally the cipher string +.Em @STRENGTH +can be used at any point to sort the current cipher list in order of +encryption algorithm key length. +.Sh CIPHERS STRINGS +The following is a list of all permitted cipher strings and their meanings. +.Bl -tag -width Ds +.It Ar DEFAULT +The default cipher list. +This is determined at compile time and is normally +.Ar ALL:!ADH:RC4+RSA:+SSLv2:@STRENGTH . +This must be the first +.Ar cipher string +specified. +.It Ar COMPLEMENTOFDEFAULT +The ciphers included in +.Ar ALL , +but not enabled by default. +Currently this is +.Ar ADH . +Note that this rule does not cover +.Ar eNULL , +which is not included by +.Ar ALL +(use +.Ar COMPLEMENTOFALL +if necessary). +.It Ar ALL +All ciphers suites except the +.Ar eNULL +ciphers which must be explicitly enabled. +.It Ar COMPLEMENTOFALL +The cipher suites not enabled by +.Ar ALL , +currently being +.Ar eNULL . +.It Ar HIGH +"High" encryption cipher suites. +This currently means those with key lengths larger than 128 bits. +.It Ar MEDIUM +"Medium" encryption cipher suites, currently those using 128 bit encryption. +.It Ar LOW +"Low" encryption cipher suites, currently those using 64 or 56 bit encryption +algorithms, but excluding export cipher suites. +.It Ar EXP , EXPORT +Export encryption algorithms. +Including 40 and 56 bits algorithms. +.It Ar EXPORT40 +40 bit export encryption algorithms +.It Ar EXPORT56 +56 bit export encryption algorithms. +.It Ar eNULL, NULL +The "NULL" ciphers; that is those offering no encryption. +Because these offer no encryption at all and are a security risk +they are disabled unless explicitly included. +.It Ar aNULL +The cipher suites offering no authentication. +This is currently the anonymous DH algorithms. +These cipher suites are vulnerable to a "man in the middle" +attack and so their use is normally discouraged. +.It Ar kRSA , RSA +Cipher suites using RSA key exchange. +.It Ar kEDH +Cipher suites using ephemeral DH key agreement. +.It Ar kDHr , kDHd +Cipher suites using DH key agreement and DH certificates signed by +CAs with RSA and DSS keys respectively. +Not implemented. +.It Ar aRSA +Cipher suites using RSA authentication, i.e. the certificates carry RSA keys. +.It Ar aDSS , DSS +Cipher suites using DSS authentication, i.e. the certificates carry DSS keys. +.It Ar aDH +Cipher suites effectively using DH authentication, i.e. the certificates carry +DH keys. +Not implemented. +.It Ar kFZA , aFZA , eFZA , FZA +Ciphers suites using FORTEZZA key exchange, authentication, encryption +or all FORTEZZA algorithms. +Not implemented. +.It Ar TLSv1 , SSLv3 , SSLv2 +TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites, respectively. +.It Ar DH +Cipher suites using DH, including anonymous DH. +.It Ar ADH +Anonymous DH cipher suites. +.It Ar 3DES +Cipher suites using triple DES. +.It Ar DES +Cipher suites using DES (not triple DES). +.It Ar RC4 +Cipher suites using RC4. +.It Ar RC2 +Cipher suites using RC2. +.It Ar IDEA +Cipher suites using IDEA. +.It Ar MD5 +Cipher suites using MD5. +.It Ar SHA1 , SHA +Cipher suites using SHA1. +.El +.Sh CIPHERS SUITE NAMES +The following lists give the SSL or TLS cipher suites names from the +relevant specification and their +.Nm OpenSSL +equivalents. +.Pp +.Cm SSL v3.0 cipher suites +.Pp +.Bd -literal +\& SSL_RSA_WITH_NULL_MD5 NULL-MD5 +\& SSL_RSA_WITH_NULL_SHA NULL-SHA +\& SSL_RSA_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5 +\& SSL_RSA_WITH_RC4_128_MD5 RC4-MD5 +\& SSL_RSA_WITH_RC4_128_SHA RC4-SHA +\& SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5 +\& SSL_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA +\& SSL_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA +\& SSL_RSA_WITH_DES_CBC_SHA DES-CBC-SHA +\& SSL_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA +.Ed +.Pp +.Bd -literal +\& SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA Not implemented. +\& SSL_DH_DSS_WITH_DES_CBC_SHA Not implemented. +\& SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA Not implemented. +\& SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA Not implemented. +\& SSL_DH_RSA_WITH_DES_CBC_SHA Not implemented. +\& SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA Not implemented. +\& SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA +\& SSL_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA +\& SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA +\& SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-RSA-DES-CBC-SHA +\& SSL_DHE_RSA_WITH_DES_CBC_SHA EDH-RSA-DES-CBC-SHA +\& SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA +.Ed +.Pp +.Bd -literal +\& SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 EXP-ADH-RC4-MD5 +\& SSL_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5 +\& SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA EXP-ADH-DES-CBC-SHA +\& SSL_DH_anon_WITH_DES_CBC_SHA ADH-DES-CBC-SHA +\& SSL_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA +.Ed +.Pp +.Bd -literal +\& SSL_FORTEZZA_KEA_WITH_NULL_SHA Not implemented. +\& SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA Not implemented. +\& SSL_FORTEZZA_KEA_WITH_RC4_128_SHA Not implemented. +.Ed +.Pp +.Cm TLS v1.0 cipher suites +.Pp +.Bd -literal +\& TLS_RSA_WITH_NULL_MD5 NULL-MD5 +\& TLS_RSA_WITH_NULL_SHA NULL-SHA +\& TLS_RSA_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5 +\& TLS_RSA_WITH_RC4_128_MD5 RC4-MD5 +\& TLS_RSA_WITH_RC4_128_SHA RC4-SHA +\& TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5 +\& TLS_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA +\& TLS_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA +\& TLS_RSA_WITH_DES_CBC_SHA DES-CBC-SHA +\& TLS_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA +.Ed +.Pp +.Bd -literal +\& TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA Not implemented. +\& TLS_DH_DSS_WITH_DES_CBC_SHA Not implemented. +\& TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA Not implemented. +\& TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA Not implemented. +\& TLS_DH_RSA_WITH_DES_CBC_SHA Not implemented. +\& TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA Not implemented. +\& TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA +\& TLS_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA +\& TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA +\& TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-RSA-DES-CBC-SHA +\& TLS_DHE_RSA_WITH_DES_CBC_SHA EDH-RSA-DES-CBC-SHA +\& TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA +.Ed +.Pp +.Bd -literal +\& TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 EXP-ADH-RC4-MD5 +\& TLS_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5 +\& TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA EXP-ADH-DES-CBC-SHA +\& TLS_DH_anon_WITH_DES_CBC_SHA ADH-DES-CBC-SHA +\& TLS_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA +.Ed +.Pp +.Cm Additional Export 1024 and other cipher suites +.Pp +.Sy Note: +These ciphers can also be used in SSL v3. +.Pp +.Bd -literal +\& TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DES-CBC-SHA +\& TLS_RSA_EXPORT1024_WITH_RC4_56_SHA EXP1024-RC4-SHA +\& TLS_DHE_DSS_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DHE-DSS-DES-CBC-SHA +\& TLS_DHE_DSS_EXPORT1024_WITH_RC4_56_SHA EXP1024-DHE-DSS-RC4-SHA +\& TLS_DHE_DSS_WITH_RC4_128_SHA DHE-DSS-RC4-SHA +.Ed +.Pp +.Cm SSL v2.0 cipher suites +.Bd -literal +.Pp +\& SSL_CK_RC4_128_WITH_MD5 RC4-MD5 +\& SSL_CK_RC4_128_EXPORT40_WITH_MD5 EXP-RC4-MD5 +\& SSL_CK_RC2_128_CBC_WITH_MD5 RC2-MD5 +\& SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5 EXP-RC2-MD5 +\& SSL_CK_IDEA_128_CBC_WITH_MD5 IDEA-CBC-MD5 +\& SSL_CK_DES_64_CBC_WITH_MD5 DES-CBC-MD5 +\& SSL_CK_DES_192_EDE3_CBC_WITH_MD5 DES-CBC3-MD5 +.Ed +.Pp +.Sh CIPHERS NOTES +The non-ephemeral DH modes are currently unimplemented in +.Nm OpenSSL +because there is no support for DH certificates. +.Pp +Some compiled versions of +.Nm OpenSSL +may not include all the ciphers +listed here because some ciphers were excluded at compile time. +.Sh CIPHERS EXAMPLES +Verbose listing of all +.Nm OpenSSL +ciphers including NULL ciphers: +.Pp +\& $ openssl ciphers -v 'ALL:eNULL' +.Pp +Include all ciphers except NULL and anonymous DH then sort by +strength: +.Pp +\& $ openssl ciphers -v 'ALL:!ADH:@STRENGTH' +.Pp +Include only 3DES ciphers and then place RSA ciphers last: +.Pp +\& $ openssl ciphers -v '3DES:+RSA' +.Pp +Include all RC4 ciphers but leave out those without authentication: +.Pp +\& $ openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT' +.Pp +Include all ciphers with RSA authentication but leave out ciphers without +encryption: +.Pp +\& $ openssl ciphers -v 'RSA:!COMPLEMENTOFALL' +.Sh CIPHERS HISTORY +The +.Ar COMPLENTOFALL +and +.Ar COMPLEMENTOFDEFAULT +selection options were added in version 0.9.7. +.\" +.\" crl +.\" +.Sh CRL +.Nm openssl crl +.Op Fl inform Ar PEM|DER +.Op Fl outform Ar PEM|DER +.Op Fl text +.Op Fl in Ar filename +.Op Fl out Ar filename +.Op Fl noout +.Op Fl hash +.Op Fl issuer +.Op Fl lastupdate +.Op Fl nextupdate +.Op Cm CAfile Ar file +.Op Cm CApath Ar dir +.Pp +The +.Nm crl +command processes CRL files in +.Ar DER +or +.Ar PEM +format. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl inform Ar DER|PEM +This specifies the input format. +.Ar DER +format is DER encoded CRL structure. +.Ar PEM +(the default) is a base64 encoded version of the DER form with header +and footer lines. +.It Fl outform Ar DER|PEM +This specifies the output format; the options have the same meaning as the +.Fl inform +option. +.It Fl in Ar filename +This specifies the input filename to read from or standard input if this +option is not specified. +.It Fl out Ar filename +Specifies the output filename to write to, or standard output by +default. +.It Fl text +Print out the CRL in text form. +.It Fl noout +Don't output the encoded version of the CRL. +.It Fl hash +Output a hash of the issuer name. +This can be used to lookup CRLs in a directory by issuer name. +.It Fl issuer +Output the issuer name. +.It Fl lastupdate +Output the +.Ar lastUpdate +field. +.It Fl nextupdate +Output the +.Ar nextUpdate +field. +.It Fl CAfile Ar file +Verify the signature on a CRL by looking up the issuing certificate in +.Ar file . +.It Fl CApath Ar dir +Verify the signature on a CRL by looking up the issuing certificate in +.Ar dir . +This directory must be a standard certificate directory, +i.e. a hash of each subject name (using +.Cm x509 Fl hash ) +should be linked to each certificate. +.El +.Sh CRL NOTES +The PEM CRL format uses the header and footer lines: +.Pp +.Bd -literal +\& -----BEGIN X509 CRL----- +\& -----END X509 CRL----- +.Ed +.Sh CRL EXAMPLES +Convert a CRL file from +.Ar PEM +to +.Ar DER : +.Pp +\& $ openssl crl -in crl.pem -outform DER -out crl.der +.Pp +Output the text form of a +.Ar DER +encoded certificate: +.Pp +\& $ openssl crl -in crl.der -text -noout +.Sh CRL BUGS +Ideally it should be possible to create a CRL using appropriate options +and files too. +.\" +.\" CRL2PKCS7 +.\" +.Sh CRL2PKCS7 +.Nm openssl crl2pkcs7 +.Op Fl inform Ar PEM|DER +.Op Fl outform Ar PEM|DER +.Op Fl in Ar filename +.Op Fl out Ar filename +.Op Fl certfile Ar filename +.Op Fl nocrl +.Pp +The +.Nm crl2pkcs7 +command takes an optional CRL and one or more +certificates and converts them into a PKCS#7 degenerate +"certificates only" structure. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl inform Ar DER|PEM +This specifies the CRL input format. +.Ar DER +format is DER encoded CRL structure. +.Ar PEM +(the default) is a base64 encoded version of the DER form with header +and footer lines. +.It Fl outform Ar DER|PEM +This specifies the PKCS#7 structure output format. +.Ar DER +format is DER encoded PKCS#7 structure. +.Ar PEM +(the default) is a base64 encoded version of the DER form with header +and footer lines. +.It Fl in Ar filename +This specifies the input +.Ar filename +to read a CRL from or standard input if this option is not specified. +.It Fl out Ar filename +Specifies the output +.Ar filename +to write the PKCS#7 structure to or standard output by default. +.It Fl certfile Ar filename +Specifies a +.Ar filename +containing one or more certificates in +.Ar PEM +format. +All certificates in the file will be added to the PKCS#7 structure. +This option can be used more than once to read certificates form multiple +files. +.It Fl nocrl +Normally a CRL is included in the output file. +With this option, no CRL is +included in the output file and a CRL is not read from the input file. +.El +.Sh CRL2PKCS7 EXAMPLES +Create a PKCS#7 structure from a certificate and CRL: +.Pp +\& $ openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem +.Pp +Creates a PKCS#7 structure in +.Ar DER +format with no CRL from several +different certificates: +.Pp +.Bd -literal +\& $ openssl crl2pkcs7 -nocrl -certfile newcert.pem +\& -certfile demoCA/cacert.pem -outform DER -out p7.der +.Ed +.Sh CRL2PKCS7 NOTES +The output file is a PKCS#7 signed data structure containing no signers and +just certificates and an optional CRL. +.Pp +This utility can be used to send certificates and CAs to Netscape as part of +the certificate enrollment process. +This involves sending the DER encoded output +as MIME type +.Em application/x-x509-user-cert . +.Pp +The +.Ar PEM +encoded form with the header and footer lines removed can be used to +install user certificates and CAs in MSIE using the Xenroll control. +.\" +.\" DGST +.\" +.Sh DGST +.Nm openssl dgst +.Op Cm -md5|-md4|-md2|-sha1|-sha|-mdc2|-ripemd160|-dss1 +.Op Fl c +.Op Fl d +.Op Fl hex +.Op Fl binary +.Op Fl out Ar filename +.Op Fl sign Ar filename +.Op Fl verify Ar filename +.Op Fl prverify Ar filename +.Op Fl rand Ar file ... +.Op Fl signature Ar filename +.Op Ar file ... +.Pp +.Cm md5|md4|md2|sha1|sha|mdc2|ripemd160 +.Op Fl c +.Op Fl d +.Op Ar file ... +.Pp +The digest functions output the message digest of a supplied +.Ar file +or +.Ar files +in hexadecimal form. +They can also be used for digital signing and verification. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl c +Print out the digest in two digit groups separated by colons, only relevant if +.Em hex +format output is used. +.It Fl d +Print out BIO debugging information. +.It Fl hex +Digest is to be output as a hex dump. +This is the default case for a "normal" +digest as opposed to a digital signature. +.It Fl binary +Output the digest or signature in binary form. +.It Fl out Ar filename +Filename to output to, or standard output by default. +.It Fl sign Ar filename +Digitally sign the digest using the private key in +.Ar filename . +.It Fl verify Ar filename +Verify the signature using the the public key in +.Ar filename. +The output is either "Verification OK" or "Verification Failure". +.It Fl prverify Ar filename +Verify the signature using the private key in +.Ar filename . +.It Fl rand Ar file ... +A +.Ar file +or +.Ar file Ns Li s +containing random data used to seed the random number +generator, or an EGD socket (see +.Xr RAND_egd 3 ) . +Multiple files can be specified separated by an OS-dependent character. +The separator is +.Cm \&; +for MS-Windows, +.Cm \&, +for OpenVMS, and +.Cm \&: +for all others. +.It Fl signature Ar filename +The actual signature to verify. +.It Ar file ... +File or files to digest. +If no files are specified then standard input is used. +.El +.Sh DGST NOTES +The digest of choice for all new applications is SHA1. +Other digests are, however, still widely used. +.Pp +If you wish to sign or verify data using the DSA algorithm then the dss1 +digest must be used. +.Pp +A source of random numbers is required for certain signing algorithms, in +particular DSA. +.Pp +The signing and verify options should only be used if a single file is +being signed or verified. +.\" +.\" DH +.\" +.Sh DH +Diffie-Hellman Parameter Management. The +.Nm dh +command has been replaced by +.Nm dhparam. +See +.Sx DHPARAM +below. +.\" +.\" DHPARAM +.\" +.Sh DHPARAM +.Nm openssl dhparam +.Bk -words +.Op Fl inform Ar DER|PEM +.Op Fl outform Ar DER|PEM +.Op Fl in Ar filename +.Op Fl out Ar filename +.Op Fl dsaparam +.Op Fl noout +.Op Fl text +.Op Fl C +.Op Fl 2 +.Op Fl 5 +.Op Fl rand Ar file ... +.Op Ar numbits +.Ek +.Pp +The +.Nm dhparam +command is used to manipulate DH parameter files. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl inform Ar DER|PEM +This specifies the input format. +The argument +.Ar DER +uses an ASN1 DER encoded form compatible with the PKCS#3 DHparameter +structure. +The +.Ar PEM +form is the default format: +it consists of the DER format base64 encoded with +additional header and footer lines. +.It Fl outform Ar DER|PEM +This specifies the output format, the options have the same meaning as the +.Fl inform +option. +.It Fl in Ar filename +This specifies the input +.Ar filename +to read parameters from or standard input if this option is not specified. +.It Fl out Ar filename +This specifies the output +.Ar filename +to write parameters to. +Standard output is used if this option is not present. +The output filename should +.Em not +be the same as the input filename. +.It Fl dsaparam +If this option is used, DSA rather than DH parameters are read or created; +they are converted to DH format. +Otherwise, "strong" primes (such that (p-1)/2 is also prime) +will be used for DH parameter generation. +.Pp +DH parameter generation with the +.Fl dsaparam +option is much faster, +and the recommended exponent length is shorter, +which makes DH key exchange more efficient. +Beware that with such DSA-style DH parameters, +a fresh DH key should be created for each use to +avoid small-subgroup attacks that may be possible otherwise. +.It Fl 2 , 5 +The generator to use, either 2 or 5. +2 is the default. +If present then the input file is ignored and parameters are generated instead. +.It Fl rand Ar file ... +A +.Ar file +or +.Ar file Ns Li s +containing random data used to seed the random number generator, +or an EGD socket (see +.Xr RAND_egd 3 ) . +Multiple files can be specified, separated by an OS-dependent character. +The separator is +.Cm \&; +for MS-Windows, +.Cm \&, +for OpenVMS, and +.Cm \&: +for all others. +.It Ar numbits +This argument specifies that a parameter set should be generated of size +.Ar numbits . +It must be the last option. +If not present, then a value of 512 is used. +If this value is present then the input file is ignored and +parameters are generated instead. +.It Fl noout +This option inhibits the output of the encoded version of the parameters. +.It Fl text +This option prints out the DH parameters in human readable form. +.It Fl C +This option converts the parameters into C code. +The parameters can then be loaded by calling the +.Cm get_dh Ns Ar numbits Ns Li () +function. +.Sh DHPARAM WARNINGS +The program +.Nm dhparam +combines the functionality of the programs +.Nm dh +and +.Nm gendh +in previous versions of +.Nm OpenSSL +and +.Nm SSLeay . +The +.Nm dh +and +.Nm gendh +programs are retained for now, but may have different purposes in future +versions of +.Nm OpenSSL . +.Sh DHPARAM NOTES +.Ar PEM +format DH parameters use the header and footer lines: +.Pp +.Bd -literal +\& -----BEGIN DH PARAMETERS----- +\& -----END DH PARAMETERS----- +.Ed +.Pp +.Nm OpenSSL +currently only supports the older PKCS#3 DH, +not the newer X9.42 DH. +.Pp +This program manipulates DH parameters not keys. +.Sh DHPARAM BUGS +There should be a way to generate and manipulate DH keys. +.Sh DHPARAM HISTORY +The +.Nm dhparam +command was added in +.Nm OpenSSL +0.9.5. +The +.Fl dsaparam +option was added in +.Nm OpenSSL +0.9.6. +.\" +.\" DSA +.\" +.Sh DSA +.Nm openssl dsa +.Bk -words +.Op Fl inform Ar PEM|DER +.Op Fl outform Ar PEM|DER +.Op Fl in Ar filename +.Op Fl passin Ar arg +.Op Fl out Ar filename +.Op Fl passout Ar arg +.Op Fl des +.Op Fl des3 +.Op Fl idea +.Op Fl text +.Op Fl noout +.Op Fl modulus +.Op Fl pubin +.Op Fl pubout +.Ek +.Pp +The +.Nm dsa +command processes DSA keys. +They can be converted between various forms and their components printed out. +.Pp +.Sy Note: +This command uses the traditional +.Nm SSLeay +compatible format for private key encryption: +newer applications should use the more secure PKCS#8 format using the +.Nm pkcs8 +command. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl inform Ar DER|PEM +This specifies the input format. +The +.Ar DER +argument with a private key uses an ASN1 DER encoded form of an ASN.1 +SEQUENCE consisting of the values of version (currently zero), p, q, g, +the public and private key components respectively as ASN.1 INTEGERs. +When used with a public key it uses a +.Em SubjectPublicKeyInfo +structure: +It is an error if the key is not DSA. +.Pp +The +.Ar PEM +form is the default format: +It consists of the DER format base64 +encoded with additional header and footer lines. +In the case of a private key, PKCS#8 format is also accepted. +.It Fl outform Ar DER|PEM +This specifies the output format, the options have the same meaning as the +.Fl inform +option. +.It Fl in Ar filename +This specifies the input +.Ar filename +to read a key from or standard input if this option is not specified. +If the key is encrypted a pass phrase will be prompted for. +.It Fl passin Ar arg +The input file password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl out Ar filename +This specifies the output +.Ar filename +to write a key to, or standard output if not specified. +If any encryption options are set then a pass phrase will be +prompted for. +The output filename should +.Em not +be the same as the input filename. +.It Fl passout Ar arg +The output file password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Cm -des|-des3|-idea +These options encrypt the private key with the DES, triple DES, or the +IDEA ciphers, respectively, before outputting it. +A pass phrase is prompted for. +If none of these options is specified, the key is written in plain text. +This means that using the +.Nm dsa +utility to read in an encrypted key with no encryption option can be used to +remove the pass phrase from a key, +or by setting the encryption options it can be use to add or change +the pass phrase. +These options can only be used with +.Ar PEM +format output files. +.It Fl text +Prints out the public, private key components and parameters. +.It Fl noout +This option prevents output of the encoded version of the key. +.It Fl modulus +This option prints out the value of the public key component of the key. +.It Fl pubin +By default a private key is read from the input file. +With this option a public key is read instead. +.It Fl pubout +By default a private key is output. +With this option a public key will be output instead. +This option is automatically set if the input is a public key. +.Sh DSA NOTES +The +.Ar PEM +private key format uses the header and footer lines: +.Pp +.Bd -literal +\& -----BEGIN DSA PRIVATE KEY----- +\& -----END DSA PRIVATE KEY----- +.Ed +.Pp +The +.Ar PEM +public key format uses the header and footer lines: +.Pp +.Bd -literal +\& -----BEGIN PUBLIC KEY----- +\& -----END PUBLIC KEY----- +.Ed +.Sh DSA EXAMPLES +To remove the pass phrase on a DSA private key: +.Pp +\& $ openssl dsa -in key.pem -out keyout.pem +.Pp +To encrypt a private key using triple DES: +.Pp +\& $ openssl dsa -in key.pem -des3 -out keyout.pem +.Pp +To convert a private key from PEM to DER format: +.Pp +\& $ openssl dsa -in key.pem -outform DER -out keyout.der +.Pp +To print out the components of a private key to standard output: +.Pp +\& $ openssl dsa -in key.pem -text -noout +.Pp +To just output the public part of a private key: +.Pp +\& $ openssl dsa -in key.pem -pubout -out pubkey.pem +.\" +.\" DSAPARAM +.\" +.Sh DSAPARAM +.Nm openssl dsaparam +.Op Fl inform Ar DER|PEM +.Op Fl outform Ar DER|PEM +.Op Fl in Ar filename +.Op Fl out Ar filename +.Op Fl noout +.Op Fl text +.Op Fl C +.Op Fl rand Ar file ... +.Op Fl genkey +.Op Ar numbits +.Pp +The +.Nm dsaparam +command is used to manipulate or generate \s-1DSA\s0 parameter files. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl inform Ar DER|PEM +This specifies the input format. +The +.Ar DER +argument uses an ASN1 DER encoded form compatible with RFC2459 (PKIX) +DSS-Parms that is a SEQUENCE consisting of p, q and g, respectively. +The +.Ar PEM +form is the default format: +it consists of the DER format base64 encoded with additional header +and footer lines. +.It Fl outform Ar DER|PEM +This specifies the output format; the options have the same meaning as the +.Fl inform +option. +.It Fl in Ar filename +This specifies the input +.Ar filename +to read parameters from, or standard input if this option is not specified. +If the +.Ar numbits +parameter is included then this option will be ignored. +.It Fl out Ar filename +This specifies the output +.Ar filename +to write parameters to. +Standard output is used if this option is not present. +The output filename should +.Em not +be the same as the input filename. +.It Fl noout +This option inhibits the output of the encoded version of the parameters. +.It Fl text +This option prints out the DSA parameters in human readable form. +.It Fl C +This option converts the parameters into C code. +The parameters can then be loaded by calling the +.Cm get_dsa Ns Ar XXX Ns Li () +function. +.It Fl genkey +This option will generate a DSA either using the specified or generated +parameters. +.It Fl rand Ar file ... +A +.Ar file +or +.Ar file Ns Li s +containing random data used to seed the random number +generator, or an EGD socket (see +.Xr RAND_egd 3 ) . +Multiple files can be specified, separated by an OS-dependent character. +The separator is +.Cm \&; +for MS-Windows, +.Cm \&, +for OpenVMS, and +.Cm \&: +for all others. +.It Ar numbits +This option specifies that a parameter set should be generated of size +.Ar numbits . +It must be the last option. +If this option is included, then the input file (if any) is ignored. +.El +.Sh DSAPARAM NOTES +.Ar PEM +format DSA parameters use the header and footer lines: +.Pp +.Bd -literal +\& -----BEGIN DSA PARAMETERS----- +\& -----END DSA PARAMETERS----- +.Ed +.Pp +DSA parameter generation is a slow process and as a result the same set of +DSA parameters is often used to generate several distinct keys. +.\" +.\" ENC +.\" +.Sh ENC +.Nm openssl enc +.Fl ciphername +.Op Fl in Ar filename +.Op Fl out Ar filename +.Op Fl pass Ar arg +.Op Fl e +.Op Fl d +.Op Fl a +.Op Fl A +.Op Fl k Ar password +.Op Fl kfile Ar filename +.Op Fl K Ar key +.Op Fl iv Ar IV +.Op Fl p +.Op Fl P +.Op Fl bufsize Ar number +.Op Fl nopad +.Op Fl debug +.Pp +The symmetric cipher commands allow data to be encrypted or decrypted +using various block and stream ciphers using keys based on passwords +or explicitly provided. Base64 encoding or decoding can also be performed +either by itself or in addition to the encryption or decryption. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl in Ar filename +The input +.Ar filename , +standard input by default. +.It Fl out Ar filename +The output +.Ar filename , +standard output by default. +.It Fl pass Ar arg +The password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl salt +Use a +.Ar salt +in the key derivation routines. +This option should +.Em ALWAYS +be used unless compatibility with previous versions of +.Nm OpenSSL +or +.Nm SSLeay +is required. +This option is only present on +.Nm OpenSSL +versions 0.9.5 or above. +.It Fl nosalt +Don't use a +.Ar salt +in the key derivation routines. +This is the default for compatibility with previous versions of +.Nm OpenSSL +and +.Nm SSLeay . +.It Fl e +Encrypt the input data: this is the default. +.It Fl d +Decrypt the input data. +.It Fl a +Base64 process the data. +This means that if encryption is taking place, the data is base64 encoded +after encryption. +If decryption is set, then the input data is base64 decoded before +being decrypted. +.It Fl A +If the +.Fl a +option is set, then base64 process the data on one line. +.It Fl k Ar password +The +.Ar password +to derive the key from. +This is for compatibility with previous versions of +.Nm OpenSSL . +Superseded by the +.Fl pass +option. +.It Fl kfile Ar filename +Read the password to derive the key from the first line of +.Ar filename . +This is for compatibility with previous versions of +.Nm OpenSSL . +Superseded by the +.Fl pass +option. +.It Fl S Ar salt +The actual +.Ar salt +to use: +this must be represented as a string comprised only of hex digits. +.It Fl K Ar key +The actual +.Ar key +to use: +this must be represented as a string comprised only of hex digits. +If only the key is specified, the +.Ar IV +must additionally specified using the +.Fl iv +option. +When both a +.Ar key +and a +.Ar password +are specified, the +.Ar key +given with the +.Fl K +option will be used and the +.Ar IV +generated from the password will be taken. +It probably does not make much sense to specify both +.Ar key +and +.Ar password . +.It Fl iv Ar IV +The actual +.Ar IV +to use: +this must be represented as a string comprised only of hex digits. +When only the +.Ar key +is specified using the +.Fl K +option, the +.Ar IV +must explicitly be defined. +When a password is being specified using one of the other options, +the +.Ar IV +is generated from this password. +.It Fl p +Print out the key and +.Ar IV +used. +.It Fl P +Print out the +.Ar key +and +.Ar IV +used then immediately exit: +don't do any encryption or decryption. +.It Fl bufsize Ar number +Set the buffer size for I/O. +.It Fl nopad +Disable standard block padding. +.It Fl debug +Debug the BIOs used for I/O. +.El +.Sh ENC NOTES +The program can be called either as +.Nm openssl ciphername +or +.Nm openssl enc -ciphername . +.Pp +A password will be prompted for to derive the +.Ar key +and +.Ar IV +if necessary. +.Pp +The +.Fl salt +option should +.Em ALWAYS +be used if the key is being derived from a password unless compatibility +with previous versions of +.Nm OpenSSL +and +.Nm SSLeay +is necessary. +.Pp +Without the +.Fl salt +option it is possible to perform efficient dictionary +attacks on the password and to attack stream cipher encrypted data. +The reason for this is that without the +.Ar salt +the same password always generates the same encryption key. +When the +.Ar salt +is being used the first eight bytes of the encrypted data are reserved +for the +.Ar salt : +it is generated at random when encrypting a file and read from the +encrypted file when it is decrypted. +.Pp +Some of the ciphers do not have large keys and others have security +implications if not used correctly. +A beginner is advised to just use a strong block cipher in CBC mode +such as bf or des3. +.Pp +All the block ciphers normally use PKCS#5 padding also known as standard block +padding: +this allows a rudimentary integrity or password check to be performed. +However, since the chance of random data passing the test is +better than 1 in 256, it isn't a very good test. +.Pp +If padding is disabled then the input data must be a multiple of the cipher +block length. +.Pp +All RC2 ciphers have the same key and effective key length. +.Pp +Blowfish and RC5 algorithms use a 128 bit key. +.Sh ENC SUPPORTED CIPHERS +.Bd -literal +\& base64 Base 64 +.Ed +.Pp +.Bd -literal +\& bf-cbc Blowfish in CBC mode +\& bf Alias for bf-cbc +\& bf-cfb Blowfish in CFB mode +\& bf-ecb Blowfish in ECB mode +\& bf-ofb Blowfish in OFB mode +.Ed +.Pp +.Bd -literal +\& cast-cbc CAST in CBC mode +\& cast Alias for cast-cbc +\& cast5-cbc CAST5 in CBC mode +\& cast5-cfb CAST5 in CFB mode +\& cast5-ecb CAST5 in ECB mode +\& cast5-ofb CAST5 in OFB mode +.Ed +.Pp +.Bd -literal +\& des-cbc DES in CBC mode +\& des Alias for des-cbc +\& des-cfb DES in CBC mode +\& des-ofb DES in OFB mode +\& des-ecb DES in ECB mode +.Ed +.Pp +.Bd -literal +\& des-ede-cbc Two key triple DES EDE in CBC mode +\& des-ede Alias for des-ede +\& des-ede-cfb Two key triple DES EDE in CFB mode +\& des-ede-ofb Two key triple DES EDE in OFB mode +.Ed +.Pp +.Bd -literal +\& des-ede3-cbc Three key triple DES EDE in CBC mode +\& des-ede3 Alias for des-ede3-cbc +\& des3 Alias for des-ede3-cbc +\& des-ede3-cfb Three key triple DES EDE CFB mode +\& des-ede3-ofb Three key triple DES EDE in OFB mode +.Ed +.Pp +.Bd -literal +\& desx DESX algorithm. +.Ed +.Pp +.Bd -literal +\& idea-cbc IDEA algorithm in CBC mode +\& idea same as idea-cbc +\& idea-cfb IDEA in CFB mode +\& idea-ecb IDEA in ECB mode +\& idea-ofb IDEA in OFB mode +.Ed +.Pp +.Bd -literal +\& rc2-cbc 128 bit RC2 in CBC mode +\& rc2 Alias for rc2-cbc +\& rc2-cfb 128 bit RC2 in CBC mode +\& rc2-ecb 128 bit RC2 in CBC mode +\& rc2-ofb 128 bit RC2 in CBC mode +\& rc2-64-cbc 64 bit RC2 in CBC mode +\& rc2-40-cbc 40 bit RC2 in CBC mode +.Ed +.Pp +.Bd -literal +\& rc4 128 bit RC4 +\& rc4-64 64 bit RC4 +\& rc4-40 40 bit RC4 +.Ed +.Pp +.Bd -literal +\& rc5-cbc RC5 cipher in CBC mode +\& rc5 Alias for rc5-cbc +\& rc5-cfb RC5 cipher in CBC mode +\& rc5-ecb RC5 cipher in CBC mode +\& rc5-ofb RC5 cipher in CBC mode +.Ed +.Sh ENC EXAMPLES +Just base64 encode a binary file: +.Pp +\& $ openssl base64 -in file.bin -out file.b64 +.Pp +Decode the same file: +.Pp +\& $ openssl base64 -d -in file.b64 -out file.bin +.Pp +Encrypt a file using triple DES in CBC mode using a prompted password: +.Pp +\& $ openssl des3 -salt -in file.txt -out file.des3 +.Pp +Decrypt a file using a supplied password: +.Pp +\& $ openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword +.Pp +Encrypt a file then base64 encode it (so it can be sent via mail for example) +using Blowfish in CBC mode: +.Pp +\& $ openssl bf -a -salt -in file.txt -out file.bf +.Pp +Base64 decode a file then decrypt it: +.Pp +\& $ openssl bf -d -salt -a -in file.bf -out file.txt +.Pp +Decrypt some data using a supplied 40 bit RC4 key: +.Pp +\& $ openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405 +.Sh ENC BUGS +The +.Fl A +option when used with large files doesn't work properly. +.Pp +There should be an option to allow an iteration count to be included. +.Pp +The +.Nm enc +program only supports a fixed number of algorithms with certain parameters. +Therefore it is not possible to use RC2 with a 76-bit key +or RC4 with an 84-bit key with this program. +.\" +.\" ERRSTR +.\" +.Sh ERRSTR +The +.Nm errstr +utility is undocumented. +.\" +.\" GENDH +.\" +.Sh GENDH +Generation of Diffie-Hellman Parameters. Replaced by +.Nm dhparam. +See +.Sx DHPARAM +above. +.\" +.\" GENDSA +.\" +.Sh GENDSA +.Nm openssl gendsa +.Op Fl out Ar filename +.Op Fl des +.Op Fl des3 +.Op Fl idea +.Op Fl rand Ar file ... +.Op Ar paramfile +.Pp +The +.Nm gendsa +command generates a DSA private key from a DSA parameter file +(which will be typically generated by the +.Nm openssl dsaparam +command). +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Cm -des|-des3|-idea +These options encrypt the private key with the DES, triple DES, +or the IDEA ciphers, respectively, before outputting it. +A pass phrase is prompted for. +If none of these options is specified, no encryption is used. +.It Fl rand Ar file ... +A +.Ar file +or +.Ar file Ns Li s +containing random data used to seed the random number +generator, or an EGD socket (see +.Xr RAND_egd 3 ) . +Multiple files can be specified separated by an OS-dependent character. +The separator is +.Cm \&; +for MS-Windows, +.Cm \&, +for OpenVMS, and +.Cm \&: +for all others. +.It Ar paramfile +This option specifies the DSA parameter file to use. +The parameters in this file determine the size of the private key. +DSA parameters can be generated and examined using the +.Nm openssl dsaparam +command. +.Sh GENDSA NOTES +DSA key generation is little more than random number generation so it is +much quicker that RSA key generation for example. +.\" +.\" GENRSA +.\" +.Sh GENRSA +.Nm openssl genrsa +.Op Fl out Ar filename +.Op Fl passout Ar arg +.Op Fl des +.Op Fl des3 +.Op Fl idea +.Op Fl f4 +.Op Fl 3 +.Op Fl rand Ar file ... +.Op Ar numbits +.Pp +The +.Nm genrsa +command generates an RSA private key. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl out Ar filename +The output +.Ar filename . +If this argument is not specified then standard output is used. +.It Fl passout Ar arg +The output file password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Cm -des|-des3|-idea +These options encrypt the private key with the DES, triple DES, or the +IDEA ciphers, respectively, before outputting it. +If none of these options is specified, no encryption is used. +If encryption is used a pass phrase is prompted for, +if it is not supplied via the +.Fl passout +option. +.It Cm -F4|-3 +The public exponent to use, either 65537 or 3. +The default is 65537. +.It Fl rand Ar file ... +A +.Ar file +or +.Ar file Ns Li s +containing random data used to seed the random number +generator, or an EGD socket (see +.Xr RAND_egd 3 ) . +Multiple files can be specified separated by an OS-dependent character. +The separator is +.Cm \&; +for MS-Windows, +.Cm \&, +for OpenVMS, and +.Cm \&: +for all others. +.It Ar numbits +The size of the private key to generate in bits. +This must be the last option specified. +The default is 512. +.Sh GENRSA NOTES +RSA private key generation essentially involves the generation of two prime +numbers. +When generating a private key, various symbols will be output to +indicate the progress of the generation. +A +.Em \&. +represents each number which has passed an initial sieve test, +.Em \&+ +means a number has passed a single round of the Miller-Rabin primality test. +A newline means that the number has passed all the prime tests +(the actual number depends on the key size). +.Pp +Because key generation is a random process the time taken to generate a key +may vary somewhat. +.Sh GENRSA BUGS +A quirk of the prime generation algorithm is that it cannot generate small +primes. +Therefore the number of bits should not be less that 64. +For typical private keys this will not matter because for security reasons +they will be much larger (typically 1024 bits). +.\" +.\" NSEQ +.\" +.Sh NSEQ +.Nm openssl nseq +.Op Fl in Ar filename +.Op Fl out Ar filename +.Op Fl toseq +.Pp +The +.Nm nseq +command takes a file containing a Netscape certificate +sequence and prints out the certificates contained in it or takes a +file of certificates and converts it into a Netscape certificate +sequence. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl in Ar filename +This specifies the input +.Ar filename +to read or standard input if this option is not specified. +.It Fl out Ar filename +Specifies the output +.Ar filename +or standard output by default. +.It Fl toseq +Normally a Netscape certificate sequence will be input and the output +is the certificates contained in it. +With the +.Fl toseq +option the situation is reversed: +a Netscape certificate sequence is created from a file of certificates. +.El +.Sh NSEQ EXAMPLES +Output the certificates in a Netscape certificate sequence: +.Bd -literal +\& $ openssl nseq -in nseq.pem -out certs.pem +.Ed +.Pp +Create a Netscape certificate sequence: +.Pp +.Bd -literal +\& $ openssl nseq -in certs.pem -toseq -out nseq.pem +.Ed +.Sh NSEQ NOTES +The +.Em PEM +encoded form uses the same headers and footers as a certificate: +.Pp +.Bd -literal +\& -----BEGIN CERTIFICATE----- +\& -----END CERTIFICATE----- +.Ed +.Pp +A Netscape certificate sequence is a Netscape specific form that can be sent +to browsers as an alternative to the standard PKCS#7 format when several +certificates are sent to the browser: +for example during certificate enrollment. +It is used by Netscape certificate server for example. +.Sh NSEQ BUGS +This program needs a few more options: +like allowing +.Em DER +or +.Em PEM +input and output files and allowing multiple certificate files to be used. +.\" +.\" OCSP +.\" +.Sh OCSP +.Nm openssl ocsp +.Bk -words +.Op Fl out Ar file +.Op Fl issuer Ar file +.Op Fl cert Ar file +.Op Fl serial Ar n +.Op Fl req_text +.Op Fl resp_text +.Op Fl text +.Op Fl reqout Ar file +.Op Fl respout Ar file +.Op Fl reqin Ar file +.Op Fl respin Ar file +.Op Fl nonce +.Op Fl no_nonce +.Op Fl url Ar responder_url +.Op Fl host Ar host:n +.Op Fl path +.Op Fl CApath Ar file +.Op Fl CAfile Ar file +.Op Fl VAfile Ar file +.Op Fl verify_certs Ar file +.Op Fl noverify +.Op Fl trust_other +.Op Fl no_intern +.Op Fl no_sig_verify +.Op Fl no_cert_verify +.Op Fl no_chain +.Op Fl no_cert_checks +.Op Fl validity_period Ar nsec +.Op Fl status_age Ar nsec +.Ek +.br +.Pp +.Sy WARNING: +this documentation is preliminary and subject to change. +.Pp +The Online Certificate Status Protocol (OCSP) enables applications to +determine the (revocation) state of an identified certificate (RFC 2560). +.Pp +The +.Nm ocsp +command performs many common OCSP tasks. +It can be used to print out requests and responses, +create requests and send queries to an OCSP responder and behave like +a mini OCSP server itself. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl out Ar filename +Specify output +.Ar filename , +default is standard output. +.It Fl issuer Ar filename +This specifies the current issuer certificate. +This option can be used multiple times. +The certificate specified in +.Ar filename +must be in +.Ar PEM +format. +.It Fl cert Ar filename +Add the certificate +.Ar filename +to the request. +The issuer certificate is taken from the previous +.Fl issuer +option, or an error occurs if no issuer certificate is specified. +.It Fl serial Ar num +Same as the +.Fl cert +option except the certificate with serial number +.Ar num +is added to the request. +The serial number is interpreted as a decimal integer unless preceded by +.Em 0x . +Negative integers can also be specified by preceding the value by a `-' sign. +.It Fl signer Ar filename , Fl signkey Ar filename +Sign the OCSP request using the certificate specified in the +.Fl signer +option and the private key specified by the +.Fl signkey +option. +If the +.Fl signkey +option is not present then the private key is read from the same file +as the certificate. +If neither option is specified then the OCSP request is not signed. +.It Fl nonce , no_nonce +Add an OCSP +.Em nonce +extension to a request or disable an OCSP +.Em nonce +addition. +Normally, if an OCSP request is input using the +.Fl respin +option no +.Em nonce +is added: +using the +.Fl nonce +option will force addition of a +.Em nonce . +If an OCSP request is being created (using the +.Fl cert +and +.Fl serial +options) +a +.Em nonce +is automatically added; specifying +.Fl no_nonce +overrides this. +.It Fl req_text , resp_text , text +Print out the text form of the OCSP request, response or both, respectively. +.It Fl reqout Ar file , Fl respout Ar file +Write out the DER encoded certificate request or response to +.Ar file . +.It Fl reqin Ar file , Fl respin Ar file +Read an OCSP request or response file from +.Ar file . +These option are ignored +if an OCSP request or response creation is implied by other options +(for example with the +.Fl serial , cert +and +.Fl host +options). +.It Fl url Ar responder_url +Specify the responder URL. +Both HTTP and HTTPS (SSL/TLS) URLs can be specified. +.It Fl host Ar hostname:port , Fl path Ar pathname +If the +.Fl host +option is present, then the OCSP request is sent to the host +.Ar hostname +on port +.Ar port . +.Fl path +specifies the HTTP path name to use, or "/" by default. +.It Fl CAfile Ar file , Fl CApath Ar pathname +.Ar file +or +.Ar pathname +containing trusted CA certificates. +These are used to verify the signature on the OCSP response. +.It Fl verify_certs Ar file +.Ar file +containing additional certificates to search when attempting to locate +the OCSP response signing certificate. +Some responders omit the actual signer's certificate from the response: +this option can be used to supply the necessary certificate in such cases. +.It Fl trust_other +The certificates specified by the +.Fl verify_certs +option should be explicitly trusted and no additional checks will be +performed on them. +This is useful when the complete responder certificate chain is not available +or trusting a root CA is not appropriate. +.It Fl VAfile Ar file +.Ar file +containing explicitly trusted responder certificates. +Equivalent to the +.Fl verify_certs +and +.Fl trust_other +options. +.It Fl noverify +Don't attempt to verify the OCSP response signature or the +.Em nonce +values. +This option will normally only be used for debugging +since it disables all verification of the responders certificate. +.It Fl no_intern +Ignore certificates contained in the OCSP response +when searching for the signer's certificate. +With this option the signer's certificate must be specified with either the +.Fl verify_certs +or +.Fl VAfile +options. +.It Fl no_sig_verify +Don't check the signature on the OCSP response. +Since this option tolerates invalid signatures on OCSP responses, +it will normally only be used for testing purposes. +.It Fl no_cert_verify +Don't verify the OCSP response signers certificate at all. +Since this option allows the OCSP response to be signed by any certificate, +it should only be used for testing purposes. +.It Fl no_chain +Do not use certificates in the response as additional untrusted CA +certificates. +.It Fl no_cert_checks +Don't perform any additional checks on the OCSP response signers certificate. +That is, do not make any checks to see if the signers certificate is authorised +to provide the necessary status information: +as a result this option should only be used for testing purposes. +.It Fl validity_period Ar nsec , Fl status_age Ar age +These options specify the range of times, in seconds, which will be tolerated +in an OCSP response. +Each certificate status response includes a +.Em notBefore +time and an optional +.Em notAfter +time. +The current time should fall between these two values, +but the interval between the two times may be only a few seconds. +In practice the OCSP responder and clients' clocks may not be precisely +synchronised and so such a check may fail. +To avoid this the +.Fl validity_period +option can be used to specify an acceptable error range in seconds, +the default value is 5 minutes. +.Pp +If the +.Em notAfter +time is omitted from a response then this means that new status +information is immediately available. +In this case the age of the +.Em notBefore +field is checked to see it is not older than +.Ar age +seconds old. +By default this additional check is not performed. +.El +.Sh OCSP SERVER OPTIONS +.Pp +.Bl -tag -with DS +.It Fl index Ar indexfile +.Ar indexfile +is a text index file in +.Nm ca +format containing certificate revocation information. +.Pp +If the +.Fl index +option is specified, the +.Nm ocsp +utility is in +.Em responder +mode, otherwise it is in +.Em client +mode. +The request(s) the responder processes can be either specified on +the command line (using the +.Fl issuer +and +.Fl serial +options), supplied in a file (using the +.Fl respin +option) or via external OCSP clients (if +.Ar port +or +.Ar url +is specified). +.Pp +If the +.Fl index +option is present, then the +.Fl CA +and +.Fl rsigner +options must also be present. +.It Fl CA Ar file +CA certificate corresponding to the revocation information in +.Ar indexfile . +.It Fl rsigner Ar file +The certificate to sign OCSP responses with. +.It Fl rother Ar file +Additional certificates to include in the OCSP response. +.It Fl resp_no_certs +Don't include any certificates in the OCSP response. +.It Fl resp_key_id +Identify the signer certificate using the key ID, +default is to use the subject name. +.It Fl rkey Ar file +The private key to sign OCSP responses with; +if not present the file specified in the +.Fl rsigner +option is used. +.It Fl port Ar portnum +Port to listen for OCSP requests on. +The port may also be specified using the +.Fl url +option. +.It Fl nrequest Ar number +The OCSP server will exit after receiving +.Ar number +requests, default unlimited. +.It Fl nmin Ar minutes , Fl ndays Ar days +Number of +.Ar minutes +or +.Ar days +when fresh revocation information is available: used in the +.Ar nextUpdate +field. +If neither option is present then the +.Em nextUpdate +field is omitted meaning fresh revocation information is immediately available. +.El +.Sh OCSP RESPONSE VERIFICATION +OCSP Response follows the rules specified in RFC2560. +.Pp +Initially the OCSP responder certificate is located and the signature on +the OCSP request checked using the responder certificate's public key. +.Pp +Then a normal certificate verify is performed on the OCSP responder certificate +building up a certificate chain in the process. +The locations of the trusted certificates used to build the chain can be +specified by the +.Fl CAfile +and +.Fl CApath +options or they will be looked for in the standard +.Nm OpenSSL +certificates +directory. +.Pp +If the initial verify fails then the OCSP verify process halts with an +error. +.Pp +Otherwise the issuing CA certificate in the request is compared to the OCSP +responder certificate: if there is a match then the OCSP verify succeeds. +.Pp +Otherwise the OCSP responder certificate's CA is checked against the issuing +CA certificate in the request. +If there is a match and the OCSPSigning extended key usage is present +in the OCSP responder certificate, then the OCSP verify succeeds. +.Pp +Otherwise the root CA of the OCSP responders CA is checked to see if it +is trusted for OCSP signing. +If it is, the OCSP verify succeeds. +.Pp +If none of these checks is successful then the OCSP verify fails. +.Pp +What this effectively means is that if the OCSP responder certificate is +authorised directly by the CA it is issuing revocation information about +(and it is correctly configured) then verification will succeed. +.Pp +If the OCSP responder is a +.Em global responder +which can give details about multiple CAs and has its own separate +certificate chain, then its root CA can be trusted for OCSP signing. +For example: +.Pp +.Bd -literal +\& $ openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem +.Ed +.Pp +Alternatively the responder certificate itself can be explicitly trusted +with the +.Fl VAfile +option. +.Sh OCSP NOTES +As noted, most of the verify options are for testing or debugging purposes. +Normally only the +.Fl CApath , CAfile +and (if the responder is a 'global VA') +.Fl VAfile +options need to be used. +.Pp +The OCSP server is only useful for test and demonstration purposes: +it is not really usable as a full OCSP responder. +It contains only a very simple HTTP request handling and can only handle +the POST form of OCSP queries. +It also handles requests serially, meaning it cannot respond to +new requests until it has processed the current one. +The text index file format of revocation is also inefficient for large +quantities of revocation data. +.Pp +It is possible to run the +.Nm ocsp +application in +.Em responder +mode via a CGI script using the +.Fl respin +and +.Fl respout +options. +.Sh OCSP EXAMPLES +Create an OCSP request and write it to a file: +.Pp +.Bd -literal +\& $ openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout \e + req.der +.Ed +.Pp +Send a query to an OCSP responder with URL +.Pa http://ocsp.myhost.com/ , +save the response to a file and print it out in text form: +.Pp +.Bd -literal +\& $ openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \e +\& -url http://ocsp.myhost.com/ -resp_text -respout resp.der +.Ed +.Pp +Read in an OCSP response and print out text form: +.Pp +.Bd -literal +\& $ openssl ocsp -respin resp.der -text +.Ed +.Pp +OCSP server on port 8888 using a standard +.Nm ca +configuration, and a separate responder certificate. +All requests and responses are printed to a file: +.Pp +.Bd -literal +\& $ openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem \e + -CA demoCA/cacert.pem -text -out log.txt +.Ed +.Pp +As above, but exit after processing one request: +.Pp +.Bd -literal +\& $ openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem \e + -CA demoCA/cacert.pem -nrequest 1 +.Ed +.Pp +Query status information using internally generated request: +.Pp +.Bd -literal +\& $ openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA \e + demoCA/cacert.pem -issuer demoCA/cacert.pem -serial 1 +.Ed +.Pp +Query status information using request read from a file, write response to a +second file: +.Pp +.Bd -literal +\& $ openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA \e + demoCA/cacert.pem -reqin req.der -respout resp.der +.Ed +.\" +.\" PASSWD +.\" +.Sh PASSWD +.Nm openssl passwd +.Op Fl crypt +.Op Fl 1 +.Op Fl apr1 +.Op Fl salt Ar string +.Op Fl in Ar file +.Op Fl stdin +.Op Fl noverify +.Op Fl quiet +.Op Fl table +.Op Ar password +.Pp +The +.Nm passwd +command computes the hash of a password typed at run-time +or the hash of each password in a list. +The password list is taken from the named +.Ar file +for option +.Fl in , +from stdin for option +.Fl stdin, +or from the command line, or from the terminal otherwise. +The Unix standard algorithm +.Em crypt +and the MD5-based BSD password algorithm +.Em 1 +and its Apache variant +.Em apr1 +are available. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl crypt +Use the +.Em crypt +algorithm (default). +.It Fl 1 +Use the MD5 based BSD password algorithm +.Em 1 . +.It Fl apr1 +Use the +.Em apr1 +algorithm (Apache variant of the BSD algorithm). +.It Fl salt Ar string +Use the specified +.Ar salt . +When reading a password from the terminal, this implies +.Fl noverify . +.It Fl in Ar file +Read passwords from +.Ar file . +.It Fl stdin +Read passwords from +.Em stdin . +.It Fl noverify +Don't verify when reading a password from the terminal. +.It Fl quiet +Don't output warnings when passwords given at the command line are truncated. +.It Fl table +In the output list, prepend the cleartext password and a TAB character +to each password hash. +.El +.Sh PASSWD EXAMPLES +.Pp +.Bl -tag -width Ds +.It $ openssl passwd -crypt -salt xx password +prints +.Em xxj31ZMTZzkVA . +.It $ openssl passwd -1 -salt xxxxxxxx password +prints +.Em $1$xxxxxxxx$8XJIcl6ZXqBMCK0qFevqT1 . +.It $ openssl passwd -apr1 -salt xxxxxxxx password +prints +.Em $apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0 . +.\" +.\" PKCS7 +.\" +.Sh PKCS7 +.Nm openssl pkcs7 +.Bk -words +.Op Fl inform Ar PEM|DER +.Op Fl outform Ar PEM|DER +.Op Fl in Ar filename +.Op Fl out Ar filename +.Op Fl print_certs +.Op Fl text +.Op Fl noout +.Ek +.br +.Pp +The +.Nm pkcs7 +command processes PKCS#7 files in +.Em DER +or +.Em PEM +format. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl inform Ar DER|PEM +This specifies the input format. +.Ar DER +format is DER encoded PKCS#7 v1.5 structure. +.Ar PEM +(the default) is a base64 encoded version of the DER form with header +and footer lines. +.It Fl outform Ar DER|PEM +This specifies the output format, the options have the same meaning as the +.Fl inform +option. +.It Fl in Ar filename +This specifies the input +.Ar filename +to read from or standard input if this option is not specified. +.It Fl out Ar filename +Specifies the output +.Ar filename +to write to or standard output by default. +.It Fl print_certs +Prints out any certificates or CRLs contained in the file. +They are preceded by their subject and issuer names in one line format. +.It Fl text +Prints out certificate details in full rather than just subject and +issuer names. +.It Fl noout +Don't output the encoded version of the PKCS#7 structure +(or certificates if +.Fl print_certs +is set). +.Sh PKCS7 EXAMPLES +Convert a PKCS#7 file from +.Em PEM +to +.Em DER : +.Pp +\& $ openssl pkcs7 -in file.pem -outform DER -out file.der +.Pp +Output all certificates in a file: +.Pp +\& $ openssl pkcs7 -in file.pem -print_certs -out certs.pem +.Sh PKCS7 NOTES +The +.Em PEM +PKCS#7 format uses the header and footer lines: +.Pp +.Bd -literal +\& -----BEGIN PKCS7----- +\& -----END PKCS7----- +.Ed +.Pp +For compatibility with some CAs it will also accept: +.Pp +.Bd -literal +\& -----BEGIN CERTIFICATE----- +\& -----END CERTIFICATE----- +.Ed +.Sh PKCS7 RESTRICTIONS +There is no option to print out all the fields of a PKCS#7 file. +.Pp +The PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315. +They cannot currently parse, for example, the new CMS as described in RFC2630. +.\" +.\" PKCS8 +.\" +.Sh PKCS8 +.Nm openssl pkcs8 +.Bk -words +.Op Fl topk8 +.Op Fl inform Ar PEM|DER +.Op Fl outform Ar PEM|DER +.Op Fl in Ar filename +.Op Fl passin Ar arg +.Op Fl out Ar filename +.Op Fl passout Ar arg +.Op Fl noiter +.Op Fl nocrypt +.Op Fl nooct +.Op Fl embed +.Op Fl nsdb +.Op Fl v2 Ar alg +.Op Fl v1 Ar alg +.Ek +.Pp +The +.Nm pkcs8 +command processes private keys in PKCS#8 format. +It can handle both unencrypted PKCS#8 PrivateKeyInfo format +and EncryptedPrivateKeyInfo format with a variety of PKCS#5 +(v1.5 and v2.0) and PKCS#12 algorithms. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl topk8 +Normally a PKCS#8 private key is expected on input and a traditional format +private key will be written. +With the +.Fl topk8 +option the situation is reversed: +it reads a traditional format private key and writes a PKCS#8 format key. +.It Fl inform Ar DER|PEM +This specifies the input format. +If a PKCS#8 format key is expected on input, +then either a +.Em DER +or +.Em PEM +encoded version of a PKCS#8 key will be expected. +Otherwise the +.Em DER +or +.Em PEM +format of the traditional format private key is used. +.It Fl outform Ar DER|PEM +This specifies the output format, the options have the same meaning as the +.Fl inform +option. +.It Fl in Ar filename +This specifies the input +.Ar filename +to read a key from or standard input if this option is not specified. +If the key is encrypted a pass phrase will be prompted for. +.It Fl passin Ar arg +The input file password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl out Ar filename +This specifies the output +.Ar filename +to write a key to or standard output by default. +If any encryption options are set then a pass phrase will be prompted for. +The output filename should +.Em not +be the same as the input filename. +.It Fl passout Ar arg +The output file password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl nocrypt +PKCS#8 keys generated or input are normally PKCS#8 +.Em EncryptedPrivateKeyInfo +structures using an appropriate password based encryption algorithm. +With this option an unencrypted +.Em PrivateKeyInfo +structure is expected or output. +This option does not encrypt private keys at all and should only be used +when absolutely necessary. +Certain software such as some versions of Java code signing software used +unencrypted private keys. +.It Fl nooct +This option generates RSA private keys in a broken format that some software +uses. +Specifically the private key should be enclosed in a OCTET STRING, +but some software just includes the structure itself without the +surrounding OCTET STRING. +.It Fl embed +This option generates DSA keys in a broken format. +The DSA parameters are embedded inside the +.Em PrivateKey +structure. +In this form the OCTET STRING contains an ASN1 SEQUENCE consisting of +two structures: +a SEQUENCE containing the parameters and an ASN1 INTEGER containing +the private key. +.It Fl nsdb +This option generates DSA keys in a broken format compatible with Netscape +private key databases. +The +.Em PrivateKey +contains a SEQUENCE consisting of the public and private keys, respectively. +.It Fl v2 Ar alg +This option enables the use of PKCS#5 v2.0 algorithms. +Normally PKCS#8 private keys are encrypted with the password based +encryption algorithm called +.Em pbeWithMD5AndDES-CBC ; +this uses 56 bit DES encryption but it was the strongest encryption +algorithm supported in PKCS#5 v1.5. +Using the +.Fl v2 +option PKCS#5 v2.0 algorithms are used which can use any +encryption algorithm such as 168 bit triple DES or 128 bit RC2, however +not many implementations support PKCS#5 v2.0 yet. +If using private keys with +.Nm OpenSSL +then this doesn't matter. +.Pp +The +.Ar alg +argument is the encryption algorithm to use, valid values include +.Ar des , des3 +and +.Ar rc2 . +It is recommended that +.Ar des3 +is used. +.It Fl v1 Ar alg +This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. +A complete list of possible algorithms is included below. +.Sh PKCS8 NOTES +The encrypted form of a +.Em PEM +encoded PKCS#8 file uses the following +headers and footers: +.Pp +.Bd -literal +\& -----BEGIN ENCRYPTED PRIVATE KEY----- +\& -----END ENCRYPTED PRIVATE KEY----- +.Ed +.Pp +The unencrypted form uses: +.Pp +.Bd -literal +\& -----BEGIN PRIVATE KEY----- +\& -----END PRIVATE KEY----- +.Ed +.Pp +Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration +counts are more secure that those encrypted using the traditional +.Nm SSLeay +compatible formats. +So if additional security is considered, important the keys should be converted. +.Pp +The default encryption is only 56 bits because this is the encryption +that most current implementations of PKCS#8 will support. +.Pp +Some software may use PKCS#12 password based encryption algorithms +with PKCS#8 format private keys: these are handled automatically +but there is no option to produce them. +.Pp +It is possible to write out +.Em DER +encoded encrypted private keys in PKCS#8 format because the encryption +details are included at an ASN1 +level whereas the traditional format includes them at a +.Em PEM +level. +.Sh PKCS#5 V1.5 AND PKCS#12 ALGORITHMS +Various algorithms can be used with the +.Fl v1 +command line option, including PKCS#5 v1.5 and PKCS#12. +These are described in more detail below. +.Pp +.Bd -literal -offset indent +.It Ar \ \ PBE-MD2-DES PBE-MD5-DES +.br +These algorithms were included in the original PKCS#5 v1.5 specification. +They only offer 56 bits of protection since they both use DES. +.It Ar \ \ PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES +.br +These algorithms are not mentioned in the original PKCS#5 v1.5 specification +but they use the same key derivation algorithm and are supported by some +software. +They are mentioned in PKCS#5 v2.0. +They use either 64 bit RC2 or 56 bit DES. +.It Ar \ \ PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40 +.br +These algorithms use the PKCS#12 password based encryption algorithm and +allow strong encryption algorithms like triple DES or 128 bit RC2 to be used. +.Ed +.Sh PKCS8 EXAMPLES +Convert a private from traditional to PKCS#5 v2.0 format using triple DES: +.Pp +\& $ openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem +.Pp +Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm (DES): +.Pp +\& $ openssl pkcs8 -in key.pem -topk8 -out enckey.pem +.Pp +Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm (3DES): +.Pp +\& $ openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES +.Pp +Read a DER unencrypted PKCS#8 format private key: +.Pp +\& $ openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem +.Pp +Convert a private key from any PKCS#8 format to traditional format: +.Pp +\& $ openssl pkcs8 -in pk8.pem -out key.pem +.Sh PKCS8 STANDARDS +Test vectors from this PKCS#5 v2.0 implementation were posted to the +pkcs-tng mailing list using triple DES, DES and RC2 with high iteration +counts, several people confirmed that they could decrypt the private +keys produced and therefore it can be assumed that the PKCS#5 v2.0 +implementation is reasonably accurate at least as far as these +algorithms are concerned. +.Pp +The format of PKCS#8 DSA (and other) private keys is not well documented: +it is hidden away in PKCS#11 v2.01, section 11.9.; +.Nm OpenSSL Ns Li 's +default DSA PKCS#8 private key format complies with this standard. +.Sh PKCS8 BUGS +There should be an option that prints out the encryption algorithm +in use and other details such as the iteration count. +.Pp +PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private +key format; for +.Nm OpenSSL +compatibility, several of the utilities use the old format at present. +.\" +.\" PKCS12 +.\" +.Sh PKCS12 +.Nm "openssl pkcs12" +.Op Fl export +.Op Fl chain +.Op Fl inkey Ar filename +.Op Fl certfile Ar filename +.Op Fl name Ar name +.Op Fl caname Ar name +.Op Fl in Ar filename +.Op Fl out Ar filename +.Op Fl noout +.Op Fl nomacver +.Op Fl nocerts +.Op Fl clcerts +.Op Fl cacerts +.Op Fl nokeys +.Op Fl info +.Op Fl des +.Op Fl des3 +.Op Fl idea +.Op Fl nodes +.Op Fl noiter +.Op Fl maciter +.Op Fl twopass +.Op Fl descert +.Op Fl certpbe +.Op Fl keypbe +.Op Fl keyex +.Op Fl keysig +.Op Fl password Ar arg +.Op Fl passin Ar arg +.Op Fl passout Ar arg +.Op Fl rand Ar file ... +.Pp +The +.Nm pkcs12 +command allows PKCS#12 files (sometimes referred to as PFX files) +to be created and parsed. +PKCS#12 files are used by several programs including Netscape, MSIE +and MS Outlook. +.Pp +There are a lot of options; the meaning of some depends on whether a +PKCS#12 file is being created or parsed. +By default a PKCS#12 file is parsed; +a PKCS#12 file can be created by using the +.Fl export +option (see below). +.Sh PKCS12 PARSING OPTIONS +.Bd -ragged -offset indent +.It Fl in Ar filename +This specifies the +.Ar filename +of the PKCS#12 file to be parsed. +Standard input is used by default. +.It Fl out Ar filename +The +.Ar filename +to write certificates and private keys to, standard output by default. +They are all written in +.Em PEM +format. +.It Fl pass Ar arg , Fl passin Ar arg +The PKCS#12 file (i.e. input file) password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl passout Ar arg +Pass phrase source to encrypt any outputed private keys with. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl noout +This option inhibits output of the keys and certificates to the output file +version of the PKCS#12 file. +.It Fl clcerts +Only output client certificates (not CA certificates). +.It Fl cacerts +Only output CA certificates (not client certificates). +.It Fl nocerts +No certificates at all will be output. +.It Fl nokeys +No private keys will be output. +.It Fl info +Output additional information about the PKCS#12 file structure, +algorithms used and iteration counts. +.It Fl des +Use DES to encrypt private keys before outputting. +.It Fl des3 +Use triple DES to encrypt private keys before outputting, this is the default. +.It Fl idea +Use IDEA to encrypt private keys before outputting. +.It Fl nodes +Don't encrypt the private keys at all. +.It Fl nomacver +Don't attempt to verify the integrity MAC before reading the file. +.It Fl twopass +Prompt for separate integrity and encryption passwords: most software +always assumes these are the same so this option will render such +PKCS#12 files unreadable. +.Ed +.Sh PKCS12 FILE CREATION OPTIONS +.Bd -ragged -offset indent +.It Fl export +This option specifies that a PKCS#12 file will be created rather than +parsed. +.It Fl out Ar filename +This specifies +.Ar filename +to write the PKCS#12 file to. +Standard output is used by default. +.It Fl in Ar filename +The +.Ar filename +to read certificates and private keys from, standard input by default. +They must all be in +.Em PEM +format. +The order doesn't matter but one private key and its corresponding +certificate should be present. +If additional certificates are present, they will also be included +in the PKCS#12 file. +.It Fl inkey Ar filename +File to read private key from. +If not present then a private key must be present in the input file. +.It Fl name Ar friendlyname +This specifies the "friendly name" for the certificate and private key. +This name is typically displayed in list boxes by software importing the file. +.It Fl certfile Ar filename +A filename to read additional certificates from. +.It Fl caname Ar friendlyname +This specifies the "friendly name" for other certificates. +This option may be used multiple times to specify names for all certificates +in the order they appear. +Netscape ignores friendly names on other certificates, +whereas MSIE displays them. +.It Fl pass Ar arg , Fl passout Ar arg +The PKCS#12 file (i.e. output file) password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl passin Ar password +Pass phrase source to decrypt any input private keys with. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl chain +If this option is present then an attempt is made to include the entire +certificate chain of the user certificate. +The standard CA store is used for this search. +If the search fails it is considered a fatal error. +.It Fl descert +Encrypt the certificate using triple DES; this may render the PKCS#12 +file unreadable by some "export grade" software. +By default the private key is encrypted using triple DES and the +certificate using 40 bit RC2. +.It Fl keypbe Ar alg , Fl certpbe Ar alg +These options allow the algorithm used to encrypt the private key and +certificates to be selected. +Although any PKCS#5 v1.5 or PKCS#12 algorithms can be selected, +it is advisable only to use PKCS#12 algorithms. +See the list in the +.Sx PKCS12 NOTES +section for more information. +.It Fl keyex | keysig +Specifies that the private key is to be used for key exchange or just signing. +This option is only interpreted by MSIE and similar MS software. +Normally "export grade" software will only allow 512 bit RSA keys to be +used for encryption purposes, but arbitrary length keys for signing. +The +.Fl keysig +option marks the key for signing only. +Signing only keys can be used for S/MIME signing, +authenticode (ActiveX control signing) and SSL client authentication; +however, due to a bug only MSIE 5.0 and later support +the use of signing only keys for SSL client authentication. +.It Fl nomaciter , noiter +These options affect the iteration counts on the MAC and key algorithms. +Unless you wish to produce files compatible with MSIE 4.0 you should leave +these options alone. +.Pp +To discourage attacks by using large dictionaries of common passwords the +algorithm that derives keys from passwords can have an iteration count applied +to it: this causes a certain part of the algorithm to be repeated and slows it +down. +The MAC is used to check the file integrity but since it will normally +have the same password as the keys and certificates it could also be attacked. +By default both MAC and encryption iteration counts are set to 2048; +using these options the MAC and encryption iteration counts can be set to 1. +Since this reduces the file security you should not use these options +unless you really have to. +Most software supports both MAC and key iteration counts. +MSIE 4.0 doesn't support MAC iteration counts, so it needs the +.Fl nomaciter +option. +.It Fl maciter +This option is included for compatibility with previous versions, it used +to be needed to use MAC iterations counts but they are now used by default. +.It Fl rand Ar file ... +A +.Ar file +or +.Ar file Ns Li s +containing random data used to seed the random number generator, +or an EGD socket (see +.Xr RAND_egd 3 ) . +Multiple files can be specified separated by an OS-dependent character. +The separator is +.Cm \&; +for MS-Windows, +.Cm \&, +for OpenVMS, and +.Cm \&: +for all others. +.Ed +.Sh PKCS12 NOTES +Although there are a large number of options, +most of them are very rarely used. +For PKCS#12 file parsing only +.Fl in +and +.Fl out +need to be used for PKCS#12 file creation. +.Fl export +and +.Fl name +are also used. +.Pp +If none of the +.Fl clcerts , cacerts +or +.Fl nocerts +options are present then all certificates will be output in the order +they appear in the input PKCS#12 files. +There is no guarantee that the first certificate present is +the one corresponding to the private key. +Certain software which requires a private key and certificate and assumes +the first certificate in the file is the one corresponding to the private key: +this may not always be the case. +Using the +.Fl clcerts +option will solve this problem by only outputting the certificate +corresponding to the private key. +If the CA certificates are required then they can be output to a separate +file using the +.Fl nokeys +and +.Fl cacerts +options to just output CA certificates. +.Pp +The +.Fl keypbe +and +.Fl certpbe +algorithms allow the precise encryption algorithms for private keys +and certificates to be specified. +Normally the defaults are fine but occasionally software can't handle +triple DES encrypted private keys; +then the option +.Fl keypbe Ar PBE-SHA1-RC2-40 +can be used to reduce the private key encryption to 40 bit RC2. +A complete description of all algorithms is contained in the +.Sx PKCS8 +section above. +.Sh PKCS12 EXAMPLES +Parse a PKCS#12 file and output it to a file: +.Pp +\& $ openssl pkcs12 -in file.p12 -out file.pem +.Pp +Output only client certificates to a file: +.Pp +\& $ openssl pkcs12 -in file.p12 -clcerts -out file.pem +.Pp +Don't encrypt the private key: +.Pp +\& $ openssl pkcs12 -in file.p12 -out file.pem -nodes +.br +.Pp +Print some info about a PKCS#12 file: +.Pp +\& $ openssl pkcs12 -in file.p12 -info -noout +.Pp +Create a PKCS#12 file: +.Pp +.Bd -literal +\& $ openssl pkcs12 -export -in file.pem -out file.p12 \e + -name "My Certificate" +.Ed +.Pp +Include some extra certificates: +.Pp +.Bd -literal +\& $ openssl pkcs12 -export -in file.pem -out file.p12 \e + -name "My Certificate" -certfile othercerts.pem +.Ed +.Sh PKCS12 BUGS +Some would argue that the PKCS#12 standard is one big bug :\-) +.Pp +Versions of +.Nm OpenSSL +before 0.9.6a had a bug in the PKCS#12 key generation routines. +Under rare circumstances this could produce a PKCS#12 file encrypted +with an invalid key. +As a result some PKCS#12 files which triggered this bug +from other implementations (MSIE or Netscape) could not be decrypted +by +.Nm OpenSSL +and similarly +.Nm OpenSSL +could produce PKCS#12 files which could not be decrypted by other +implementations. +The chances of producing such a file are relatively small: less than 1 in 256. +.Pp +A side effect of fixing this bug is that any old invalidly encrypted PKCS#12 +files can no longer be parsed by the fixed version. +Under such circumstances the +.Nm pkcs12 +utility will report that the MAC is OK but fail with a decryption +error when extracting private keys. +.Pp +This problem can be resolved by extracting the private keys and certificates +from the PKCS#12 file using an older version of +.Nm OpenSSL +and recreating +the PKCS#12 file from the keys and certificates using a newer version of +.Nm OpenSSL . +For example: +.Pp +.Bd -literal +\& $ old-openssl -in bad.p12 -out keycerts.pem +\& $ openssl -in keycerts.pem -export -name "My PKCS#12 file" -out fixed.p12 +.Ed +.\" +.\" RAND +.\" +.Sh RAND +.Cm openssl rand +.Op Fl out Ar file +.Op Fl rand Ar file +.Op Fl base64 +.Ar num +.Pp +The +.Nm rand +command outputs +.Ar num +pseudo-random bytes after seeding +the random number generator once. +As in other +.Nm openssl +command line tools, PRNG seeding uses the file +.Pa $HOME/.rnd +or +.Pa .rnd +in addition to the files given in the +.Fl rand +option. +A new +.Pa $HOME/.rnd +or +.Pa .rnd +file will be written back if enough +seeding was obtained from these sources. +.Pp +The options are as follows: +.Bd -ragged -offset indent +.It Fl out Ar file +Write to +.Ar file +instead of standard output. +.It Fl rand Ar file ... +Use specified +.Ar file +or +.Ar file Ns Li s +or EGD socket (see +.Xr RAND_egd 3 ) +for seeding the random number generator. +Multiple files can be specified separated by an OS-dependent character. +The separator is +.Cm \&; +for MS-Windows, +.Cm \&, +for OpenVMS, and +.Cm \&: +for all others. +.It Fl base64 +Perform +.Em base64 +encoding on the output. +.El +.\" +.\" REQ +.\" +.Sh REQ +.Nm openssl req +.Bk -words +.Op Fl inform Ar PEM|DER +.Op Fl outform Ar PEM|DER +.Op Fl in Ar filename +.Op Fl passin Ar arg +.Op Fl out Ar filename +.Op Fl passout Ar arg +.Op Fl text +.Op Fl pubkey +.Op Fl noout +.Op Fl verify +.Op Fl modulus +.Op Fl new +.Op Fl rand Ar file ... +.Op Fl newkey Ar rsa:bits +.Op Fl newkey Ar dsa:file +.Op Fl nodes +.Op Fl key Ar filename +.Op Fl keyform Ar PEM|DER +.Op Fl keyout Ar filename +.Op Fl Op Cm md5|sha1|md2|mdc2 +.Op Fl config Ar filename +.Op Fl subj Ar arg +.Op Fl x509 +.Op Fl days Ar n +.Op Fl set_serial Ar n +.Op Fl asn1-kludge +.Op Fl newhdr +.Op Fl extensions Ar section +.Op Fl reqexts Ar section +.Op Fl utf8 +.Op Fl nameopt +.Op Fl batch +.Op Fl verbose +.Ek +.Pp +The +.Nm req +command primarily creates and processes certificate requests +in PKCS#10 format. +It can additionally create self-signed certificates, +for use as root CAs, for example. +.Pp +The options are as follows: +.Bd -ragged -offset indent +.It Fl inform Ar DER|PEM +This specifies the input format. +The +.Ar DER +argument uses an ASN1 DER encoded +form compatible with the PKCS#10. +The +.Ar PEM +form is the default format: +it consists of the DER format base64 encoded with additional header and +footer lines. +.It Fl outform Ar DER|PEM +This specifies the output format, the options have the same meaning as the +.Fl inform +option. +.It Fl in Ar filename +This specifies the input +.Ar filename +to read a request from, or standard input +if this option is not specified. +A request is only read if the creation options +.Fl new +and +.Fl newkey +are not specified. +.It Fl passin Ar arg +The input file password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl out Ar filename +This specifies the output +.Ar filename +to write to, or standard output by default. +.It Fl passout Ar arg +The output file password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl text +Prints out the certificate request in text form. +.It Fl pubkey +Outputs the public key. +.It Fl noout +This option prevents output of the encoded version of the request. +.It Fl modulus +This option prints out the value of the modulus of the public key +contained in the request. +.It Fl verify +Verifies the signature on the request. +.It Fl new +This option generates a new certificate request. +It will prompt the user for the relevant field values. +The actual fields prompted for and their maximum and minimum sizes +are specified in the configuration file and any requested extensions. +.Pp +If the +.Fl key +option is not used it will generate a new RSA private +key using information specified in the configuration file. +.It Fl rand Ar file ... +A +.Ar file +or +.Ar file Ns Li s +containing random data used to seed the random number generator, +or an EGD socket (see +.Xr RAND_egd 3 ) . +Multiple files can be specified separated by an OS-dependent character. +The separator is +.Cm \&; +for MS-Windows, +.Cm \&, +for OpenVMS, and +.Cm \&: +for all others. +.It Fl newkey Ar arg +This option creates a new certificate request and a new private key. +The argument takes one of two forms: +.Ar rsa:nbits , +where +.Ar nbits +is the number of bits, generates an RSA key +.Ar nbits +in size. +.Ar dsa:filename +generates a DSA key using the parameters in the file +.Ar filename. +.It Fl key Ar filename +This specifies the file to read the private key from. +It also accepts PKCS#8 format private keys for +.Em PEM +format files. +.It Fl keyform Ar PEM|DER +The format of the private key file specified in the +.Fl key +argument. +.AR PEM +is the default. +.It Fl keyout Ar filename +This gives the +.Ar filename +to write the newly created private key to. +If this option is not specified, then the filename present in the +configuration file is used. +.It Fl nodes +If this option is specified then if a private key is created it +will not be encrypted. +.It Fl md5|sha1|md2|mdc2 +This specifies the message digest to sign the request with. +This overrides the digest algorithm specified in the configuration file. +This option is ignored for DSA requests: they always use SHA1. +.It Fl config Ar filename +This allows an alternative configuration file to be specified; +this overrides the compile time filename or any specified in +the +.Em OPENSSL_CONF +environment variable. +.It Fl subj Ar arg +Sets subject name for new request or supersedes the subject name +when processing a request. +The arg must be formatted as +.Em /type0=value0/type1=value1/type2=... , +characters may be escaped by \e (backslash), no spaces are skipped. +.It Fl x509 +This option outputs a self-signed certificate instead of a certificate +request. +This is typically used to generate a test certificate or +a self-signed root CA. +The extensions added to the certificate +(if any) are specified in the configuration file. +Unless specified using the +.Fl set_serial +option, 0 will be used for the serial number. +.It Fl days Ar n +When the +.Fl x509 +option is being used this specifies the number of +days to certify the certificate for. +The default is 30 days. +.It Fl set_serial Ar n +Serial number to use when outputting a self-signed certificate. +This may be specified as a decimal value or a hex value if preceded by +.Em 0x . +It is possible to use negative serial numbers but this is not recommended. +.It Fl extensions Ar section , Fl reqexts Ar section +These options specify alternative sections to include certificate +extensions (if the +.Fl x509 +option is present) or certificate request extensions. +This allows several different sections to +be used in the same configuration file to specify requests for +a variety of purposes. +.It Fl utf8 +This option causes field values to be interpreted as UTF8 strings, by +default they are interpreted as ASCII. +This means that the field values, whether prompted from a terminal or +obtained from a configuration file, must be valid UTF8 strings. +.It Fl nameopt Ar option +Option which determines how the subject or issuer names are displayed. +The +.Ar option +argument can be a single option or multiple options separated by commas. +Alternatively, the +.Fl nameopt +switch may be used more than once to set multiple options. +See the +.Sx X509 +section below for details. +.It Fl asn1-kludge +By default the +.Nm req +command outputs certificate requests containing +no attributes in the correct PKCS#10 format. +However certain CAs will only +accept requests containing no attributes in an invalid form: this +option produces this invalid format. +.Pp +More precisely the +.Em Attributes +in a PKCS#10 certificate request are defined as a SET OF Attribute. +They are +.Em not +optional, so if no attributes are present then they should be encoded as an +empty SET OF. +The invalid form does not include the empty +SET OF, whereas the correct form does. +.Pp +It should be noted that very few CAs still require the use of this option. +.It Fl newhdr +Adds the word NEW to the +.Em PEM +file header and footer lines on the outputed request. +Some software (Netscape certificate server) and some CAs need this. +.It Fl batch +Non-interactive mode. +.It Fl verbose +Print extra details about the operations being performed. +.Ed +.Sh REQ CONFIGURATION FILE FORMAT +The configuration options are specified in the +.Em req +section of the configuration file. +As with all configuration files, if no value is specified in the specific +section (i.e. +.Em req ) +then the initial unnamed or +.Em default +section is searched too. +.Pp +The options available are described in detail below. +.Bd -ragged -offset indent +.It Ar input_password output_password +The passwords for the input private key file (if present) and +the output private key file (if one will be created). +The command line options +.Fl passin +and +.Fl passout +override the configuration file values. +.It Ar default_bits +This specifies the default key size in bits. +If not specified, then 512 is used. +It is used if the +.Fl new +option is used. +It can be overridden by using the +.Fl newkey +option. +.It Ar default_keyfile +This is the default filename to write a private key to. +If not specified, the key is written to standard output. +This can be overridden by the +.Fl keyout +option. +.It Ar oid_file +This specifies a file containing additional OBJECT IDENTIFIERS. +Each line of the file should consist of the numerical form of the +object identifier, followed by whitespace, then the short name followed +by whitespace and finally the long name. +.It Ar oid_section +This specifies a section in the configuration file containing extra +object identifiers. +Each line should consist of the short name of the +object identifier followed by +.Cm = +and the numerical form. +The short and long names are the same when this option is used. +.It Ar RANDFILE +This specifies a filename in which random number seed information is +placed and read from, or an EGD socket (see +.Xr RAND_egd 3 ) . +It is used for private key generation. +.It Ar encrypt_key +If this is set to +.Em no +then if a private key is generated it is +.Em not +encrypted. +This is equivalent to the +.Fl nodes +command line option. +For compatibility, +.Ar encrypt_rsa_key +is an equivalent option. +.It Ar default_md +This option specifies the digest algorithm to use. +Possible values include +.Ar md5, sha1 +and +.Ar mdc2 . +If not present then MD5 is used. +This option can be overridden on the command line. +.It Ar string_mask +This option masks out the use of certain string types in certain +fields. +Most users will not need to change this option. +.Pp +It can be set to several values: +.Ar default , +which is also the default option, uses +.Em PrintableStrings , T61Strings +and +.Em BMPStrings ; +if the +.Ar pkix +value is used then only +.Em PrintableStrings +and +.Em BMPStrings +will be used. +This follows the PKIX recommendation in RFC2459. +If the +.Fl utf8only +option is used then only +.Em UTF8Strings +will be used: this is the PKIX recommendation in RFC2459 after 2003. +Finally, the +.Ar nombstr +option just uses +.Em PrintableStrings +and +.Em T61Strings : +certain software has problems with +.Em BMPStrings +and +.Em UTF8Strings : +in particular Netscape. +.It Ar req_extensions +This specifies the configuration file section containing a list of +extensions to add to the certificate request. +It can be overridden by the +.Fl reqexts +command line switch. +.It Ar x509_extensions +This specifies the configuration file section containing a list of +extensions to add to a certificate generated when the +.Fl x509 +switch is used. +It can be overridden by the +.Fl extensions +command line switch. +.It Ar prompt +If set to the value +.Em no , +this disables prompting of certificate fields +and just takes values from the config file directly. +It also changes the expected format of the +.Em distinguished_name +and +.Em attributes +sections. +.It Ar utf8 +If set to the value +.Em yes , +then field values are interpreted as UTF8 strings; +by default they are interpreted as ASCII. +This means that the field values, whether prompted from a terminal or +obtained from a configuration file, must be valid UTF8 strings. +.It Ar attributes +This specifies the section containing any request attributes: its format +is the same as +.Ar distinguished_name . +Typically these may contain the +.Em challengePassword +or +.Em unstructuredName +types. +They are currently ignored by +.Nm OpenSSL Ns Li 's +request signing utilities, but some CAs might want them. +.It Ar distinguished_name +This specifies the section containing the distinguished name fields to +prompt for when generating a certificate or certificate request. +The format is described in the next section. +.Ed +.Sh REQ DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT +There are two separate formats for the distinguished name and attribute +sections. +If the +.Fl prompt +option is set to +.Em no +then these sections just consist of field names and values: for example, +.Pp +.Bd -literal +\& CN=My Name +\& OU=My Organization +\& emailAddress=someone@somewhere.org +.Ed +.Pp +This allows external programs (e.g. GUI based) to generate a template file +with all the field names and values and just pass it to +.Nm req . +An example of this kind of configuration file is contained in the +.Sx REQ EXAMPLES +section. +.Pp +Alternatively if the +.Fl prompt +option is absent or not set to +.Em no , +then the file contains field prompting information. +It consists of lines of the form: +.Pp +.Bd -literal +\& fieldName="prompt" +\& fieldName_default="default field value" +\& fieldName_min= 2 +\& fieldName_max= 4 +.Ed +.Pp +"fieldName" is the field name being used, for example +.Em commonName +(or CN). +The "prompt" string is used to ask the user to enter the relevant details. +If the user enters nothing, then the default value is used; +if no default value is present then the field is omitted. +A field can still be omitted if a default value is present, +if the user just enters the '.' character. +.Pp +The number of characters entered must be between the +.Em fieldName_min +and +.Em fieldName_max +limits: +there may be additional restrictions based on the field being used +(for example +.Em countryName +can only ever be two characters long and must fit in a +.Em PrintableString ) . +.Pp +Some fields (such as +.Em organizationName ) +can be used more than once in a DN. +This presents a problem because configuration files will +not recognize the same name occurring twice. +To avoid this problem if the +.Em fieldName +contains some characters followed by a full stop they will be ignored. +So, for example, a second +.Em organizationName +can be input by calling it "1.organizationName". +.Pp +The actual permitted field names are any object identifier short or +long names. +These are compiled into +.Nm OpenSSL +and include the usual values such as +.Em commonName , countryName , localityName , organizationName , +.Em organizationUnitName , stateOrPrivinceName . +Additionally +.Em emailAddress +is included as well as +.Em name , surname , givenName initials +and +.Em dnQualifier . +.Pp +Additional object identifiers can be defined with the +.Ar oid_file +or +.Ar oid_section +options in the configuration file. +Any additional fields will be treated as though they were a +.Em DirectoryString . +.Sh REQ EXAMPLES +Examine and verify certificate request: +.Pp +\& $ openssl req -in req.pem -text -verify -noout +.Pp +Create a private key and then generate a certificate request from it: +.Pp +.Bd -literal +\& $ openssl genrsa -out key.pem 1024 +\& $ openssl req -new -key key.pem -out req.pem +.Ed +.Pp +The same but just using req: +.Pp +\& $ openssl req -newkey rsa:1024 -keyout key.pem -out req.pem +.Pp +Generate a self-signed root certificate: +.Pp +\& $ openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem +.br +.Pp +Example of a file pointed to by the +.Ar oid_file +option: +.Pp +.Bd -literal +\& 1.2.3.4 shortName A longer Name +\& 1.2.3.6 otherName Other longer Name +.Ed +.Pp +Example of a section pointed to by +.Ar oid_section +making use of variable expansion: +.Pp +.Bd -literal +\& testoid1=1.2.3.5 +\& testoid2=${testoid1}.6 +.Ed +.Pp +Sample configuration file prompting for field values: +.Pp +.Bd -literal +\& [ req ] +\& default_bits = 1024 +\& default_keyfile = privkey.pem +\& distinguished_name = req_distinguished_name +\& attributes = req_attributes +\& x509_extensions = v3_ca +.Pp +\& dirstring_type = nobmp +.Pp +\& [ req_distinguished_name ] +\& countryName = Country Name (2 letter code) +\& countryName_default = AU +\& countryName_min = 2 +\& countryName_max = 2 +.Pp +\& localityName = Locality Name (eg, city) +.Pp +\& organizationalUnitName = Organizational Unit Name (eg, section) +.Pp +\& commonName = Common Name (eg, YOUR name) +\& commonName_max = 64 +.Pp +\& emailAddress = Email Address +\& emailAddress_max = 40 +.Pp +\& [ req_attributes ] +\& challengePassword = A challenge password +\& challengePassword_min = 4 +\& challengePassword_max = 20 +.Pp +\& [ v3_ca ] +.Pp +\& subjectKeyIdentifier=hash +\& authorityKeyIdentifier=keyid:always,issuer:always +\& basicConstraints = CA:true +.Ed +.Pp +Sample configuration containing all field values: +.Pp +.Bd -literal +\& RANDFILE = $ENV::HOME/.rnd +.Pp +\& [ req ] +\& default_bits = 1024 +\& default_keyfile = keyfile.pem +\& distinguished_name = req_distinguished_name +\& attributes = req_attributes +\& prompt = no +\& output_password = mypass +.Pp +\& [ req_distinguished_name ] +\& C = GB +\& ST = Test State or Province +\& L = Test Locality +\& O = Organization Name +\& OU = Organizational Unit Name +\& CN = Common Name +\& emailAddress = test@email.address +.Pp +\& [ req_attributes ] +\& challengePassword = A challenge password +.Ed +.Sh REQ NOTES +The header and footer lines in the +.Ar PEM +format are normally: +.Pp +.Bd -literal +\& -----BEGIN CERTIFICATE REQUEST---- +\& -----END CERTIFICATE REQUEST---- +.Ed +.Pp +Some software (some versions of Netscape certificate server) instead needs: +.Pp +.Bd -literal +\& -----BEGIN NEW CERTIFICATE REQUEST---- +\& -----END NEW CERTIFICATE REQUEST---- +.Ed +.Pp +which is produced with the +.Fl newhdr +option but is otherwise compatible. +Either form is accepted transparently on input. +.Pp +The certificate requests generated by Xenroll with MSIE have extensions added. +It includes the +.Em keyUsage +extension which determines the type of +key (signature only or general purpose) and any additional OIDs entered +by the script in an +.Em extendedKeyUsage +extension. +.Sh REQ DIAGNOSTICS +The following messages are frequently asked about: +.Pp +.Bd -literal +\& Using configuration from /some/path/openssl.cnf +\& Unable to load config info +.Ed +.Pp +This is followed some time later by... +.Pp +.Bd -literal +\& unable to find 'distinguished_name' in config +\& problems making Certificate Request +.Ed +.Pp +The first error message is the clue: it can't find the configuration +file! +Certain operations (like examining a certificate request) don't +need a configuration file so its use isn't enforced. +Generation of certificates or requests, however, do need a configuration file. +This could be regarded as a bug. +.Pp +Another puzzling message is this: +.Pp +.Bd -literal +\& Attributes: +\& a0:00 +.Ed +.Pp +This is displayed when no attributes are present and the request includes +the correct empty SET OF structure (the DER encoding of which is 0xa0 0x00). +If you just see: +.Pp +\& Attributes: +.Pp +then the SET OF is missing and the encoding is technically invalid (but +it is tolerated). +See the description of the command line option +.Fl asn1-kludge +for more information. +.Sh REQ ENVIRONMENT VARIABLES +The variable +.Em OPENSSL_CONF , +if defined, allows an alternative configuration +file location to be specified; it will be overridden by the +.Fl config +command line switch if it is present. +For compatibility reasons the +.Em SSLEAY_CONF +environment variable serves the same purpose but its use is discouraged. +.Sh REQ BUGS +.Nm OpenSSL Ns Li 's +handling of T61Strings (aka TeletexStrings) is broken: it effectively +treats them as ISO-8859-1 (Latin 1); +Netscape and MSIE have similar behaviour. +This can cause problems if you need characters that aren't available in +.Em PrintableStrings +and you don't want to or can't use +.Em BMPStrings . +.Pp +As a consequence of the T61String handling the only correct way to represent +accented characters in +.Nm OpenSSL +is to use a +.Em BMPString : +unfortunately Netscape currently chokes on these. +If you have to use accented characters with Netscape +and MSIE then you currently need to use the invalid T61String form. +.Pp +The current prompting is not very friendly. +It doesn't allow you to confirm what you've just entered. +Other things like extensions in certificate requests are +statically defined in the configuration file. +Some of these, like an email address in +.Em subjectAltName +should be input by the user. +.\" +.\" RSA +.\" +.Sh RSA +.Cm openssl rsa +.Op Fl inform Ar PEM|NET|DER +.Op Fl outform Ar PEM|NET|DER +.Op Fl in Ar filename +.Op Fl passin Ar arg +.Op Fl out Ar filename +.Op Fl passout Ar arg +.Op Fl sgckey +.Op Fl des +.Op Fl des3 +.Op Fl idea +.Op Fl text +.Op Fl noout +.Op Fl modulus +.Op Fl check +.Op Fl pubin +.Op Fl pubout +.Pp +The +.Nm rsa +command processes RSA keys. +They can be converted between various forms and their components printed out. +.Pp +.Sy Note : +this command uses the traditional +.Nm SSLeay +compatible format for private key encryption: +newer applications should use the more secure PKCS#8 format using the +.Nm pkcs8 +utility. +.Pp +The options are as follows: +.Bd -ragged -offset indent +.It Fl inform Ar DER|NET|PEM +This specifies the input format. +The +.Ar DER +argument +uses an ASN1 DER encoded form compatible with the PKCS#1 +RSAPrivateKey or SubjectPublicKeyInfo format. +The +.Ar PEM +form is the default format: it consists of the DER format base64 +encoded with additional header and footer lines. +On input PKCS#8 format private keys are also accepted. +The +.Ar NET +form is a format described in the +.Sx RSA NOTES +section. +.It Fl outform Ar DER|NET|PEM +This specifies the output format, the options have the same meaning as the +.Fl inform +option. +.It Fl in Ar filename +This specifies the input +.Ar filename +to read a key from or standard input if this +option is not specified. +If the key is encrypted, a pass phrase will be prompted for. +.It Fl passin Ar arg +The input file password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl out Ar filename +This specifies the output +.Ar filename +to write a key to, or standard output if this option is not specified. +If any encryption options are set then a pass phrase will be prompted for. +The output filename should +.Em not +be the same as the input filename. +.It Fl passout Ar password +The output file password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl sgckey +Use the modified +.Em NET +algorithm used with some versions of Microsoft IIS and SGC keys. +.It Cm -des|-des3|-idea +These options encrypt the private key with the DES, triple DES, or the +IDEA ciphers, respectively, before outputting it. +A pass phrase is prompted for. +If none of these options is specified the key is written in plain text. +This means that using the +.Nm rsa +utility to read in an encrypted key with no encryption option can be used +to remove the pass phrase from a key, or by setting the encryption options +it can be used to add or change the pass phrase. +These options can only be used with +.Ar PEM +format output files. +.It Fl text +Prints out the various public or private key components in +plain text, in addition to the encoded version. +.It Fl noout +This option prevents output of the encoded version of the key. +.It Fl modulus +This option prints out the value of the modulus of the key. +.It Fl check +This option checks the consistency of an RSA private key. +.It Fl pubin +By default a private key is read from the input file: with this +option a public key is read instead. +.It Fl pubout +By default a private key is output: +with this option a public key will be output instead. +This option is automatically set if the input is a public key. +.Ed +.Sh RSA NOTES +The +.Em PEM +private key format uses the header and footer lines: +.Pp +.Bd -literal +\& -----BEGIN RSA PRIVATE KEY----- +\& -----END RSA PRIVATE KEY----- +.Ed +.Pp +The +.Em PEM +public key format uses the header and footer lines: +.Pp +.Bd -literal +\& -----BEGIN PUBLIC KEY----- +\& -----END PUBLIC KEY----- +.Ed +.Pp +The +.Em NET +form is a format compatible with older Netscape servers +and Microsoft IIS .key files; this uses unsalted RC4 for its encryption. +It is not very secure and so should only be used when necessary. +.Pp +Some newer version of IIS have additional data in the exported .key files. +To use these with the +.Nm rsa +utility, view the file with a binary editor +and look for the string "private-key", then trace back to the byte +sequence 0x30, 0x82 (this is an ASN1 SEQUENCE). +Copy all the data from this point onwards to another file and use that as +the input to the +.Nm rsa +utility with the +.Fl inform Ar NET +option. +If there is an error after entering the password, try the +.Fl sgckey +option. +.Sh RSA EXAMPLES +To remove the pass phrase on an RSA private key: +.Pp +\& $ openssl rsa -in key.pem -out keyout.pem +.Pp +To encrypt a private key using triple DES: +.Pp +\& $ openssl rsa -in key.pem -des3 -out keyout.pem +.Pp +To convert a private key from +.Em PEM +to +.Em DER +format: +.Pp +\& $ openssl rsa -in key.pem -outform DER -out keyout.der +.br +.Pp +To print out the components of a private key to standard output: +.Pp +\& $ openssl rsa -in key.pem -text -noout +.Pp +To just output the public part of a private key: +.Pp +\& $ openssl rsa -in key.pem -pubout -out pubkey.pem +.Sh RSA BUGS +The command line password arguments don't currently work with +.Em NET +format. +.Pp +There should be an option that automatically handles .key files, +without having to manually edit them. +.\" +.\" RSAUTL +.\" +.Sh RSAUTL +.Nm openssl rsautl +.Op Fl in Ar file +.Op Fl out Ar file +.Op Fl inkey Ar file +.Op Fl pubin +.Op Fl certin +.Op Fl sign +.Op Fl verify +.Op Fl encrypt +.Op Fl decrypt +.Op Fl pkcs +.Op Fl ssl +.Op Fl raw +.Op Fl hexdump +.Op Fl asn1parse +.Pp +The +.Nm rsautl +command can be used to sign, verify, encrypt and decrypt +data using the RSA algorithm. +.Pp +The options are as follows: +.Bd -ragged -offset indent +.It Fl in Ar filename +This specifies the input +.Ar filename +to read data from or standard input +if this option is not specified. +.It Fl out Ar filename +Specifies the output +.Ar filename +to write to or standard output by +default. +.It Fl inkey Ar file +The input key file, by default it should be an RSA private key. +.It Fl pubin +The input file is an RSA public key. +.It Fl certin +The input is a certificate containing an RSA public key. +.It Fl sign +Sign the input data and output the signed result. +This requires an RSA private key. +.It Fl verify +Verify the input data and output the recovered data. +.It Fl encrypt +Encrypt the input data using an RSA public key. +.It Fl decrypt +Decrypt the input data using an RSA private key. +.It Fl pkcs , oaep , ssl , raw +The padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP, +special padding used in SSL v2 backwards compatible handshakes, +or no padding, respectively. +For signatures, only +.Fl pkcs +and +.Fl raw +can be used. +.It Fl hexdump +Hex dump the output data. +.It Fl asn1parse +Asn1parse the output data, this is useful when combined with the +.Fl verify +option. +.El +.Sh RSAUTL NOTES +.Nm rsautl , +because it uses the RSA algorithm directly, can only be +used to sign or verify small pieces of data. +.Sh RSAUTL EXAMPLES +Sign some data using a private key: +.Pp +\& $ openssl rsautl -sign -in file -inkey key.pem -out sig +.Pp +Recover the signed data: +.Pp +\& $ openssl rsautl -verify -in sig -inkey key.pem +.Pp +Examine the raw signed data: +.Pp +\& $ openssl rsautl -verify -in file -inkey key.pem -raw -hexdump +.Pp +.Bd -literal +\& 0000 - 00 01 ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ +\& 0010 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ +\& 0020 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ +\& 0030 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ +\& 0040 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ +\& 0050 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ +\& 0060 - ff ff ff ff ff ff ff ff-ff ff ff ff ff ff ff ff ................ +\& 0070 - ff ff ff ff 00 68 65 6c-6c 6f 20 77 6f 72 6c 64 .....hello world +.Ed +.Pp +The PKCS#1 block formatting is evident from this. If this was done using +encrypt and decrypt the block would have been of type 2 (the second byte) +and random padding data visible instead of the 0xff bytes. +.Pp +It is possible to analyse the signature of certificates using this +utility in conjunction with +.Nm asn1parse . +Consider the self-signed example in +.Pa certs/pca-cert.pem : +Running +.Nm asn1parse +as follows yields: +.Pp +\& $ openssl asn1parse -in pca-cert.pem +.Pp +.Bd -literal +\& 0:d=0 hl=4 l= 742 cons: SEQUENCE +\& 4:d=1 hl=4 l= 591 cons: SEQUENCE +\& 8:d=2 hl=2 l= 3 cons: cont [ 0 ] +\& 10:d=3 hl=2 l= 1 prim: INTEGER :02 +\& 13:d=2 hl=2 l= 1 prim: INTEGER :00 +\& 16:d=2 hl=2 l= 13 cons: SEQUENCE +\& 18:d=3 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption +\& 29:d=3 hl=2 l= 0 prim: NULL +\& 31:d=2 hl=2 l= 92 cons: SEQUENCE +\& 33:d=3 hl=2 l= 11 cons: SET +\& 35:d=4 hl=2 l= 9 cons: SEQUENCE +\& 37:d=5 hl=2 l= 3 prim: OBJECT :countryName +\& 42:d=5 hl=2 l= 2 prim: PRINTABLESTRING :AU +\& .... +\& 599:d=1 hl=2 l= 13 cons: SEQUENCE +\& 601:d=2 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption +\& 612:d=2 hl=2 l= 0 prim: NULL +\& 614:d=1 hl=3 l= 129 prim: BIT STRING +.Ed +.Pp +The final BIT STRING contains the actual signature. +It can be extracted with: +.Pp +\& $ openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614 +.Pp +The certificate public key can be extracted with: +.Pp +\& $ openssl x509 -in test/testx509.pem -pubout -noout >pubkey.pem +.Pp +The signature can be analysed with: +.Pp +\& $ openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin +.Pp +.Bd -literal +\& 0:d=0 hl=2 l= 32 cons: SEQUENCE +\& 2:d=1 hl=2 l= 12 cons: SEQUENCE +\& 4:d=2 hl=2 l= 8 prim: OBJECT :md5 +\& 14:d=2 hl=2 l= 0 prim: NULL +\& 16:d=1 hl=2 l= 16 prim: OCTET STRING +\& 0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5 .F...Js.7...H%.. +.Ed +.Pp +This is the parsed version of an ASN1 +.Em DigestInfo +structure. +It can be seen that the digest used was md5. +The actual part of the certificate that was signed can be extracted with: +.Pp +\& $ openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4 +.Pp +and its digest computed with: +.Pp +.Bd -literal +\& $ openssl md5 -c tbs +\& MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5 +.Ed +.Pp +which it can be seen agrees with the recovered value above. +.\" +.\" S_CLIENT +.\" +.Sh S_CLIENT +.Nm openssl s_client +.Op Fl connect Ar host:port> +.Op Fl verify Ar depth +.Op Fl cert Ar filename +.Op Fl key Ar filename +.Op Fl CApath Ar directory +.Op Fl CAfile Ar filename +.Op Fl reconnect +.Op Fl pause +.Op Fl showcerts +.Op Fl debug +.Op Fl msg +.Op Fl nbio_test +.Op Fl state +.Op Fl nbio +.Op Fl crlf +.Op Fl ign_eof +.Op Fl quiet +.Op Fl ssl2 +.Op Fl ssl3 +.Op Fl tls1 +.Op Fl no_ssl2 +.Op Fl no_ssl3 +.Op Fl no_tls1 +.Op Fl bugs +.Op Fl cipher Ar cipherlist +.Op Fl engine Ar id +.Op Fl rand Ar file ... +.Pp +The +.Nm s_client +command implements a generic SSL/TLS client which connects +to a remote host using SSL/TLS. +It is a +.Em very +useful diagnostic tool for SSL servers. +.Pp +The options are as follows: +.Bd -ragged -offset indent +.It Fl connect Ar host:port +This specifies the +.Ar host +and optional +.Ar port +to connect to. +If not specified then an attempt is made to connect to the local host +on port 4433. +.It Fl cert Ar certname +The certificate to use, if one is requested by the server. +The default is not to use a certificate. +.It Fl key Ar keyfile +The private key to use. +If not specified then the certificate file will be used. +.It Fl verify Ar depth +The verify +.Ar depth +to use. +This specifies the maximum length of the +server certificate chain and turns on server certificate verification. +Currently the verify operation continues after errors so all the problems +with a certificate chain can be seen. +As a side effect the connection will never fail due to a server +certificate verify failure. +.It Fl CApath Ar directory +The +.Ar directory +to use for server certificate verification. +This directory must be in "hash format", see +.Fl verify +for more information. +These are also used when building the client certificate chain. +.It Fl CAfile Ar file +A +.Ar file +containing trusted certificates to use during server authentication +and to use when attempting to build the client certificate chain. +.It Fl reconnect +Reconnects to the same server 5 times using the same session ID; this can +be used as a test that session caching is working. +.It Fl pause +Pauses 1 second between each read and write call. +.It Fl showcerts +Display the whole server certificate chain: normally only the server +certificate itself is displayed. +.It Fl prexit +Print session information when the program exits. +This will always attempt +to print out information even if the connection fails. +Normally information will only be printed out once if the connection succeeds. +This option is useful because the cipher in use may be renegotiated +or the connection may fail because a client certificate is required or is +requested only after an attempt is made to access a certain URL. +.Sy Note : +the output produced by this option is not always accurate because a +connection might never have been established. +.It Fl state +Prints out the SSL session states. +.It Fl debug +Print extensive debugging information including a hex dump of all traffic. +.It Fl msg +Show all protocol messages with hex dump. +.It Fl nbio_test +Tests non-blocking I/O. +.It Fl nbio +Turns on non-blocking I/O. +.It Fl crlf +This option translates a line feed from the terminal into CR+LF as required +by some servers. +.It Fl ign_eof +Inhibit shutting down the connection when end of file is reached in the +input. +.It Fl quiet +Inhibit printing of session and certificate information. +This implicitly turns on +.Fl ign_eof +as well. +.It Fl ssl2 , ssl3 , tls1 , no_ssl2 , +.It Fl no_ssl3 , no_tls1 +These options disable the use of certain SSL or TLS protocols. +By default the initial handshake uses a method which should be compatible +with all servers and permit them to use SSL v3, SSL v2 or TLS as appropriate. +.Pp +Unfortunately there are a lot of ancient and broken servers in use which +cannot handle this technique and will fail to connect. +Some servers only work if TLS is turned off with the +.Fl no_tls +option, others will only support SSL v2 and may need the +.Fl ssl2 +option. +.It Fl bugs +There are several known bugs in SSL and TLS implementations. +Adding this option enables various workarounds. +.It Fl cipher Ar cipherlist +This allows the cipher list sent by the client to be modified. +Although the server determines which cipher suite is used it should take +the first supported cipher in the list sent by the client. +See the +.Sx CIPHERS +section above for more information. +.It Fl engine Ar id +Specifying an engine (by it's unique +.Ar id +string) will cause +.Nm s_client +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. +The engine will then be set as the default for all available algorithms. +.It Fl rand Ar file ... +A +.Ar file +or +.Ar file Ns Li s +containing random data used to seed the random number generator, +or an EGD socket (see +.Xr RAND_egd 3 ) . +Multiple files can be specified separated by an OS-dependent character. +The separator is +.Cm \&; +for MS-Windows, +.Cm \&, +for OpenVMS, and +.Cm \&: +for +all others. +.Ed +.Sh S_CLIENT CONNECTED COMMANDS +If a connection is established with an SSL server then any data received +from the server is displayed and any key presses will be sent to the +server. +When used interactively (which means neither +.Fl quiet +nor +.Fl ign_eof +have been given), the session will be renegotiated if the line begins with an +.Em R , +and if the line begins with a +.Em Q +or if end of file is reached, the connection will be closed down. +.Sh S_CLIENT NOTES +.Nm s_client +can be used to debug SSL servers. +To connect to an SSL HTTP server the command: +.Pp +\& $ openssl s_client -connect servername:443 +.Pp +would typically be used (https uses port 443). +If the connection succeeds then an HTTP command can be given such as +"GET" to retrieve a web page. +.Pp +If the handshake fails then there are several possible causes; if it is +nothing obvious like no client certificate then the +.Fl bugs , ssl2 , ssl3 , tls1 , +.Fl no_ssl2 , no_ssl3 +and +.Fl no_tls1 +options can be tried in case it is a buggy server. +In particular these options should be tried +.Em before +submitting a bug report to an +.Nm OpenSSL +mailing list. +.Pp +A frequent problem when attempting to get client certificates working +is that a web client complains it has no certificates or gives an empty +list to choose from. +This is normally because the server is not sending the clients certificate +authority in its "acceptable CA list" when it +requests a certificate. +By using +.Nm s_client +the CA list can be viewed and checked. +However some servers only request client authentication +after a specific URL is requested. +To obtain the list in this case it is necessary to use the +.Fl prexit +command and send an HTTP request for an appropriate page. +.Pp +If a certificate is specified on the command line using the +.Fl cert +option it will not be used unless the server specifically requests +a client certificate. +Therefore merely including a client certificate +on the command line is no guarantee that the certificate works. +.Pp +If there are problems verifying a server certificate then the +.Fl showcerts +option can be used to show the whole chain. +.Sh S_CLIENT BUGS +Because this program has a lot of options and also because some of +the techniques used are rather old, the C source of +.Nm s_client +is rather hard to read and not a model of how things should be done. +A typical SSL client program would be much simpler. +.Pp +The +.Fl verify +option should really exit if the server verification fails. +.Pp +The +.Fl prexit +option is a bit of a hack. +We should really report information whenever a session is renegotiated. +.\" +.\" S_SERVER +.\" +.Sh S_SERVER +.Nm openssl s_server +.Bk -words +.Op Fl accept Ar port +.Op Fl context Ar id +.Op Fl verify Ar depth +.Op Fl Verify Ar depth +.Op Fl cert Ar filename +.Op Fl key Ar keyfile +.Op Fl dcert Ar filename +.Op Fl dkey Ar keyfile +.Op Fl dhparam Ar filename +.Op Fl nbio +.Op Fl nbio_test +.Op Fl crlf +.Op Fl debug +.Op Fl msg +.Op Fl state +.Op Fl CApath Ar directory +.Op Fl CAfile Ar filename +.Op Fl nocert +.Op Fl cipher Ar cipherlist +.Op Fl quiet +.Op Fl no_tmp_rsa +.Op Fl ssl2 +.Op Fl ssl3 +.Op Fl tls1 +.Op Fl no_ssl2 +.Op Fl no_ssl3 +.Op Fl no_tls1 +.Op Fl no_dhe +.Op Fl bugs +.Op Fl hack +.Op Fl www +.Op Fl WWW +.Op Fl HTTP +.Op Fl engine Ar id +.Op Fl rand Ar file ... +.Ek +.Pp +The +.Nm s_server +command implements a generic SSL/TLS server which listens +for connections on a given port using SSL/TLS. +.Pp +The options are as follows: +.Bd -ragged -offset indent +.It Fl accept Ar port +The TCP +.Ar port +to listen on for connections. +If not specified, 4433 is used. +.It Fl context Ar id +Sets the SSL context id. +It can be given any string value. +If this option is not present, a default value will be used. +.It Fl cert Ar certname +The certificate to use; most servers cipher suites require the use of a +certificate and some require a certificate with a certain public key type: +for example the DSS cipher suites require a certificate containing a DSS +(DSA) key. +If not specified then the filename +.Pa server.pem +will be used. +.It Fl key Ar keyfile +The private key to use. +If not specified then the certificate file will be used. +.It Fl dcert Ar filename , Fl dkey Ar keyname +Specify an additional certificate and private key; these behave in the +same manner as the +.Fl cert +and +.Fl key +options except there is no default if they are not specified +(no additional certificate and key is used). +As noted above some cipher suites require a certificate containing a key of +a certain type. +Some cipher suites need a certificate carrying an RSA key +and some a DSS (DSA) key. +By using RSA and DSS certificates and keys +a server can support clients which only support RSA or DSS cipher suites +by using an appropriate certificate. +.It Fl nocert +If this option is set then no certificate is used. +This restricts the cipher suites available to the anonymous ones +(currently just anonymous DH). +.It Fl dhparam Ar filename +The DH parameter file to use. +The ephemeral DH cipher suites generate keys +using a set of DH parameters. +If not specified, then an attempt is made to +load the parameters from the server certificate file. +If this fails then a static set of parameters hard coded into the +.Nm s_server +program will be used. +.It Fl no_dhe +If this option is set, then no DH parameters will be loaded, effectively +disabling the ephemeral DH cipher suites. +.It Fl no_tmp_rsa +Certain export cipher suites sometimes use a temporary RSA key; this option +disables temporary RSA key generation. +.It Fl verify Ar depth , Fl Verify Ar depth +The verify +.Ar depth +to use. +This specifies the maximum length of the client certificate chain +and makes the server request a certificate from the client. +With the +.Fl verify +option a certificate is requested but the client does not have to send one. +With the +.Fl Verify +option the client must supply a certificate or an error occurs. +.It Fl CApath Ar directory +The +.Ar directory +to use for client certificate verification. +This directory must be in "hash format", see +.Fl verify +for more information. +These are also used when building the server certificate chain. +.It Fl CAfile Ar file +A file containing trusted certificates to use during client authentication +and to use when attempting to build the server certificate chain. +The list is also used in the list of acceptable client CAs passed to the +client when a certificate is requested. +.It Fl state +Prints out the SSL session states. +.It Fl debug +Print extensive debugging information including a hex dump of all traffic. +.It Fl msg +Show all protocol messages with hex dump. +.It Fl nbio_test +Tests non blocking I/O. +.It Fl nbio +Turns on non blocking I/O. +.It Fl crlf +This option translates a line feed from the terminal into CR+LF. +.It Fl quiet +Inhibit printing of session and certificate information. +.It Fl ssl2 , ssl3 , tls1 , no_ssl2 , +.It Fl no_ssl3 , no_tls1 +These options disable the use of certain SSL or TLS protocols. +By default, the initial handshake uses a method which should be compatible +with all servers and permit them to use SSL v3, SSL v2 or TLS as appropriate. +.It Fl bugs +There are several known bugs in SSL and TLS implementations. +Adding this option enables various workarounds. +.It Fl hack +This option enables a further workaround for some some early Netscape +SSL code (?). +.It Fl cipher Ar cipherlist +This allows the cipher list used by the server to be modified. +When the client sends a list of supported ciphers, the first client cipher +also included in the server list is used. +Because the client specifies the preference order, the order of the server +cipherlist irrelevant. +See the +.Sx CIPHERS +section for more information. +.It Fl www +Sends a status message back to the client when it connects. +This includes lots of information about the ciphers used and various +session parameters. +The output is in HTML format so this option will normally be used with a +web browser. +.It Fl WWW +Emulates a simple web server. +Pages will be resolved relative to the current directory; +for example if the URL +.Pa https://myhost/page.html +is requested, the file +.Pa ./page.html +will be loaded. +.It Fl HTTP +Emulates a simple web server. +Pages will be resolved relative to the current directory; +for example if the URL +.Pa https://myhost/page.html +is requested the file +.Pa ./page.html +will be loaded. +The files loaded are assumed to contain a complete and correct HTTP +response (lines that are part of the HTTP response line and headers +must end with CRLF). +.It Fl engine Ar id +Specifying an engine (by it's unique +.Ar id +string) will cause +.Nm s_server +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. +The engine will then be set as the default for all available algorithms. +.It Fl rand Ar file ... +A +.Ar file +or +.Ar file Ns Li s +containing random data used to seed the random number generator, +or an EGD socket (see +.Xr RAND_egd 3 ) . +Multiple files can be specified separated by an OS-dependent character. +The separator is +.Cm \&; +for MS-Windows, +.Cm \&, +for OpenVMS, and +.Cm \&: +for all others. +.Ed +.Sh S_SERVER CONNECTED COMMANDS +If a connection request is established with an SSL client and neither the +.Fl www +nor the +.Fl WWW +option has been used, then normally any data received +from the client is displayed and any key presses will be sent to the client. +.Pp +Certain single letter commands are also recognized which perform special +operations: these are listed below. +.Pp +.Bd -ragged -offset indent +.It Ar q +End the current SSL connection, but still accept new connections. +.It Ar Q +End the current SSL connection and exit. +.It Ar r +Renegotiate the SSL session. +.It Ar R +Renegotiate the SSL session and request a client certificate. +.It Ar P +Send some plain text down the underlying TCP connection: this should +cause the client to disconnect due to a protocol violation. +.It Ar S +Print out some session cache status information. +.Ed +.Sh S_SERVER NOTES +.Nm s_server +can be used to debug SSL clients. +To accept connections from a web browser the command: +.Pp +\& $ openssl s_server -accept 443 -www +.Pp +can be used for example. +.Pp +Most web browsers (in particular Netscape and MSIE) only support RSA cipher +suites, so they cannot connect to servers which don't use a certificate +carrying an RSA key or a version of +.Nm OpenSSL +with RSA disabled. +.Pp +Although specifying an empty list of CAs when requesting a client certificate +is strictly speaking a protocol violation, some SSL +clients interpret this to mean any CA is acceptable. +This is useful for debugging purposes. +.Pp +The session parameters can printed out using the +.Nm sess_id +program. +.Sh S_SERVER BUGS +Because this program has a lot of options and also because some of +the techniques used are rather old, the C source of +.Nm s_server +is rather hard to read and not a model of how things should be done. +A typical SSL server program would be much simpler. +.Pp +The output of common ciphers is wrong: it just gives the list of ciphers that +.Nm OpenSSL +recognizes and the client supports. +.Pp +There should be a way for the +.Nm s_server +program to print out details of any +unknown cipher suites a client says it supports. +.\" +.\" S_TIME +.\" +.Sh S_TIME +The +.Nm s_time +utility is undocumented. +.\" +.\" SESS_ID +.\" +.Sh SESS_ID +.Nm openssl sess_id +.Bk -words +.Op Fl inform Ar PEM|DER +.Op Fl outform Ar PEM|DER +.Op Fl in Ar filename +.Op Fl out Ar filename +.Op Fl text +.Op Fl noout +.Op Fl context Ar ID +.Ek +.Pp +The +.Nm sess_id +program processes the encoded version of the SSL +session structure and optionally prints out SSL +session details (for example the SSL +session master key) in human readable format. +Since this is a diagnostic tool that needs some knowledge of the SSL +protocol to use properly, most users will not need to use it. +.Pp +The options are as follows: +.Bd -ragged -offset indent +.It Fl inform Ar DER|PEM +This specifies the input format. +The +.Ar DER +argument uses an ASN1 DER encoded +format containing session details. +The precise format can vary from one version to the next. +The +.Ar PEM +form is the default format: it consists of the DER +format base64 encoded with additional header and footer lines. +.It Fl outform Ar DER|PEM +This specifies the output format, the options have the same meaning as the +.Fl inform +option. +.It Fl in Ar filename +This specifies the input +.Ar filename +to read session information from, or standard input by default. +.It Fl out Ar filename +This specifies the output +.Ar filename +to write session information to, or standard +output if this option is not specified. +.It Fl text +Prints out the various public or private key components in +plain text in addition to the encoded version. +.It Fl cert +If a certificate is present in the session it will be output using this option, +if the +.Fl text +option is also present then it will be printed out in text form. +.It Fl noout +This option prevents output of the encoded version of the session. +.It Fl context Ar ID +This option can set the session id so the output session information uses the +supplied +.Ar ID . +The +.Ar ID +can be any string of characters. +This option won't normally be used. +.Ed +.Sh SESS_ID OUTPUT +Typical output: +.Pp +.Bd -literal +\& SSL-Session: +\& Protocol : TLSv1 +\& Cipher : 0016 +\& Session-ID: 871E62626C554CE95488823752CBD5F3673A3EF3DCE9C67BD916C809914B40ED +\& Session-ID-ctx: 01000000 +\& Master-Key: A7CEFC571974BE02CAC305269DC59F76EA9F0B180CB6642697A68251F2D2BB57E51DBBB4C7885573192AE9AEE220FACD +\& Key-Arg : None +\& Start Time: 948459261 +\& Timeout : 300 (sec) +\& Verify return code 0 (ok) +.Ed +.Pp +These are described below in more detail. +.Bd -ragged -offset indent +.It Ar Protocol +This is the protocol in use: TLSv1, SSLv3 or SSLv2. +.It Ar Cipher +The cipher used is the actual raw SSL or TLS cipher code; +see the SSL or TLS specifications for more information. +.It Ar Session-ID +The SSL session ID in hex format. +.It Ar Session-ID-ctx +The session ID context in hex format. +.It Ar Master-Key +This is the SSL session master key. +.It Ar Key-Arg +The key argument, this is only used in SSL v2. +.It Ar Start Time +This is the session start time, represented as an integer +in standard Unix format. +.It Ar Timeout +The timeout in seconds. +.It Ar Verify return code +This is the return code when an SSL client certificate is verified. +.Ed +.Sh SESS_ID NOTES +The +.Em PEM +encoded session format uses the header and footer lines: +.Pp +.Bd -literal +\& -----BEGIN SSL SESSION PARAMETERS----- +\& -----END SSL SESSION PARAMETERS----- +.Ed +.Pp +Since the SSL session output contains the master key, it is possible to read +the contents of an encrypted session using this information. +Therefore appropriate security precautions +should be taken if the information is being output by a "real" application. +This is, however, strongly discouraged and should only be used for +debugging purposes. +.Sh SESS_ID BUGS +The cipher and start time should be printed out in human readable form. +.\" +.\" SMIME +.\" +.Sh SMIME +.Nm openssl smime +.Bk -words +.Op Fl encrypt +.Op Fl decrypt +.Op Fl sign +.Op Fl verify +.Op Fl pk7out +.Op Fl des +.Op Fl des3 +.Op Fl rc2-40 +.Op Fl rc2-64 +.Op Fl rc2-128 +.Op Fl in Ar file +.Op Fl certfile Ar file +.Op Fl signer Ar file +.Op Fl recip Ar file +.Op Fl inform Ar SMIME|PEM|DER +.Op Fl passin Ar arg +.Op Fl inkey Ar file +.Op Fl out Ar file +.Op Fl outform Ar SMIME|PEM|DER +.Op Fl content Ar file +.Op Fl to Ar addr +.Op Fl from Ar addr +.Op Fl subject Ar s +.Op Fl text +.Op Fl rand Ar file ... +.Op Ar cert.pem ... +.Ek +.Pp +The +.Nm smime +command handles +.Em S/MIME +mail. +It can encrypt, decrypt, sign and verify +.Em S/MIME +messages. +.Pp +There are five operation options that set the type of operation to be performed. +The meaning of the other options varies according to the operation type. +.Pp +The options are as follows: +.Bd -ragged -offset indent +.It Fl encrypt +Encrypt mail for the given recipient certificates. +Input file is the message to be encrypted. +The output file is the encrypted mail in +.Em MIME +format. +.It Fl decrypt +Decrypt mail using the supplied certificate and private key. +Expects an encrypted mail message in +.Em MIME +format for the input file. +The decrypted mail is written to the output file. +.It Fl sign +Sign mail using the supplied certificate and private key. +Input file is the message to be signed. +The signed message in +.Em MIME +format is written to the output file. +.It Fl verify +Verify signed mail. +Expects a signed mail message on input and outputs the signed data. +Both clear text and opaque signing is supported. +.It Fl pk7out +Takes an input message and writes out a +.Em PEM +encoded PKCS#7 structure. +.It Fl in Ar filename +The input message to be encrypted or signed or the +.Em MIME +message to +be decrypted or verified. +.It Fl inform Ar SMIME|PEM|DER +This specifies the input format for the PKCS#7 structure. +The default is +.Em SMIME +which reads an +.Em S/MIME +format message. +.Em PEM +and +.Em DER +format change this to expect PEM and DER format PKCS#7 structures +instead. +This currently only affects the input format of the PKCS#7 +structure, if no PKCS#7 structure is being input (for example with +.Fl encrypt +or +.Fl sign ) +this option has no effect. +.It Fl out Ar filename +The message text that has been decrypted or verified, or the output +.Em MIME +format message that has been signed or verified. +.It Fl outform Ar SMIME|PEM|DER +This specifies the output format for the PKCS#7 structure. +The default is +.Em SMIME +which writes an +.Em S/MIME +format message. +.Em PEM +and +.Em DER +format change this to write PEM and DER format PKCS#7 structures +instead. +This currently only affects the output format of the PKCS#7 +structure; if no PKCS#7 structure is being output (for example with +.Fl verify +or +.Fl decrypt ) +this option has no effect. +.It Fl content Ar filename +This specifies a file containing the detached content. +This is only useful with the +.Fl verify +command. +This is only usable if the PKCS#7 structure is using the detached +signature form where the content is not included. +This option will override any content if the input format is +.Em S/MIME +and it uses the multipart/signed +.Em MIME +content type. +.It Fl text +This option adds plain text (text/plain) +.Em MIME +headers to the supplied message if encrypting or signing. +If decrypting or verifying it strips off text headers: +if the decrypted or verified message is not of +.Em MIME +type text/plain then an error occurs. +.It Fl CAfile Ar file +A +.Ar file +containing trusted CA certificates, only used with +.Fl verify . +.It Fl CApath Ar dir +A +.Ar directory +containing trusted CA certificates, only used with +.Fl verify . +This directory must be a standard certificate directory; +that is, a hash of each subject name (using +.Nm x509 -hash ) +should be linked to each certificate. +.It Fl des des3 rc2-40 rc2-64 rc2-128 +The encryption algorithm to use. +DES (56 bits), triple DES\s0 (168 bits) +or 40, 64 or 128 bit RC2, respectively; if not specified 40 bit RC2 is +used. +Only used with +.Fl encrypt . +.It Fl nointern +When verifying a message, normally certificates (if any) included in +the message are searched for the signing certificate. +With this option only the certificates specified in the +.Fl certfile +option are used. +The supplied certificates can still be used as untrusted CAs however. +.It Fl noverify +Do not verify the signer's certificate of a signed message. +.It Fl nochain +Do not do chain verification of signers' certificates: that is don't +use the certificates in the signed message as untrusted CAs. +.It Fl nosigs +Don't try to verify the signatures on the message. +.It Fl nocerts +When signing a message, the signer's certificate is normally included; +with this option it is excluded. +This will reduce the size of the signed message but the verifier must +have a copy of the signer's certificate available locally (passed using the +.Fl certfile +option, for example). +.It Fl noattr +Normally, when a message is signed a set of attributes are included which +include the signing time and supported symmetric algorithms. +With this option they are not included. +.It Fl binary +Normally the input message is converted to "canonical" format which is +effectively using CR and LF as end of line: as required by the +.Em S/MIME +specification. +When this option is present no translation occurs. +This is useful when handling binary data which may not be in +.Em MIME +format. +.It Fl nodetach +When signing a message use opaque signing: this form is more resistant +to translation by mail relays but it cannot be read by mail agents that +do not support +.Em S/MIME . +Without this option cleartext signing with the +.Em MIME +type multipart/signed is used. +.It Fl certfile Ar file +Allows additional certificates to be specified. +When signing these will be included with the message. +When verifying these will be searched for the signers' certificates. +The certificates should be in +.Em PEM +format. +.It Fl signer Ar file +The signer's certificate when signing a message. +If a message is being verified, then the signer's certificates will be +written to this file if the verification was successful. +.It Fl recip Ar file +The recipients certificate when decrypting a message. +This certificate +must match one of the recipients of the message or an error occurs. +.It Fl inkey Ar file +The private key to use when signing or decrypting. +This must match the corresponding certificate. +If this option is not specified then the private key must be included +in the certificate file specified with +the +.Fl recip +or +.Fl signer +file. +.It Fl passin Ar arg +The private key password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl rand Ar file ... +A +.Ar file +or +.Ar file Ns Li s +containing random data used to seed the random number generator, +or an EGD socket (see +.Xr RAND_egd 3 ) . +Multiple files can be specified separated by an OS-dependent character. +The separator is +.Cm \&; +for MS-Windows, +.Cm \&, +for OpenVMS, and +.Cm \&: +for all others. +.It Ar cert.pem ... +One or more certificates of message recipients: used when encrypting +a message. +.It Fl to , from , subject +The relevant mail headers. +These are included outside the signed +portion of a message so they may be included manually. +If signing, then many +.Em S/MIME +mail clients check the signer's certificate email +address matches that specified in the From: address. +.Ed +.Sh SMIME NOTES +The +.Em MIME +message must be sent without any blank lines between the +headers and the output. +Some mail programs will automatically add a blank line. +Piping the mail directly to sendmail is one way to +achieve the correct format. +.Pp +The supplied message to be signed or encrypted must include the +necessary +.Em MIME +headers or many +.Em S/MIME +clients won't display it properly (if at all). +You can use the +.Fl text +option to automatically add plain text headers. +.Pp +A "signed and encrypted" message is one where a signed message is +then encrypted. +This can be produced by encrypting an already signed message: +see the +.Sx SMIME EXAMPLES +section. +.Pp +This version of the program only allows one signer per message, but it +will verify multiple signers on received messages. +Some +.Em S/MIME +clients choke if a message contains multiple signers. +It is possible to sign messages "in parallel" by signing an already +signed message. +.Pp +The options +.Fl encrypt +and +.Fl decrypt +reflect common usage in +.Em S/MIME +clients. +Strictly speaking these process PKCS#7 enveloped data: PKCS#7 +encrypted data is used for other purposes. +.Sh SMIME EXIT CODES +.Bd -ragged -offset indent +.It Ar 0 +The operation was completely successful. +.It Ar 1 +An error occurred parsing the command options. +.It Ar 2 +One of the input files could not be read. +.It Ar 3 +An error occurred creating the PKCS#7 file or when reading the +.Em MIME +message. +.It Ar 4 +An error occurred decrypting or verifying the message. +.It Ar 5 +The message was verified correctly, but an error occurred writing out +the signers certificates. +.Ed +.Sh SMIME EXAMPLES +Create a cleartext signed message: +.Pp +.Bd -literal +\& $ openssl smime -sign -in message.txt -text -out mail.msg \e +\& -signer mycert.pem +.Ed +.Pp +Create an opaque signed message: +.Pp +.Bd -literal +\& $ openssl smime -sign -in message.txt -text -out mail.msg -nodetach \e +\& -signer mycert.pem +.Ed +.Pp +Create a signed message, include some additional certificates and +read the private key from another file: +.Pp +.Bd -literal +\& $ openssl smime -sign -in in.txt -text -out mail.msg \e +\& -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem +.Ed +.Pp +Send a signed message under Unix directly to +.Xr sendmail 8 , +including headers: +.Pp +.Bd -literal +\& $ openssl smime -sign -in in.txt -text -signer mycert.pem \e +\& -from steve@openssl.org -to someone@somewhere \e +\& -subject "Signed message" | sendmail someone@somewhere +.Ed +.Pp +Verify a message and extract the signer's certificate if successful: +.Pp +.Bd -literal +\& $ openssl smime -verify -in mail.msg -signer user.pem \e +\& -out signedtext.txt +.Ed +.Pp +Send encrypted mail using triple DES: +.Pp +.Bd -literal +\& $ openssl smime -encrypt -in in.txt -from steve@openssl.org \e +\& -to someone@somewhere -subject "Encrypted message" \e +\& -des3 user.pem -out mail.msg +.Ed +.Pp +Sign and encrypt mail: +.Pp +.Bd -literal +\& $ openssl smime -sign -in ml.txt -signer my.pem -text \e +\& | openssl smime -encrypt -out mail.msg \e +\& -from steve@openssl.org -to someone@somewhere \e +\& -subject "Signed and Encrypted message" -des3 user.pem +.Ed +.Pp +.Sy Note : +The encryption command does not include the +.Fl text +option because the message being encrypted already has +.Em MIME +headers. +.Pp +Decrypt mail: +.Pp +\& $ openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem +.Pp +The output from Netscape form signing is a PKCS#7 structure with the +detached signature format. +You can use this program to verify the signature by line wrapping the +base64 encoded structure and surrounding it with: +.Pp +.Bd -literal +\& -----BEGIN PKCS7---- +\& -----END PKCS7---- +.Ed +.Pp +and using the command: +.br +.Pp +.Bd -literal +\& $ openssl smime -verify -inform PEM -in signature.pem +\& -content content.txt +.Ed +.Pp +Alternatively, you can base64 decode the signature and use: +.Pp +.Bd -literal +\& $ openssl smime -verify -inform DER -in signature.der +\& -content content.txt +.Ed +.Sh SMIME BUGS +The +.Em MIME +parser isn't very clever: it seems to handle most messages that I've thrown +at it, but it may choke on others. +.Pp +The code currently will only write out the signer's certificate to a file: +if the signer has a separate encryption certificate this must be manually +extracted. +There should be some heuristic that determines the correct encryption +certificate. +.Pp +Ideally a database should be maintained of a certificate for each email +address. +.Pp +The code doesn't currently take note of the permitted symmetric encryption +algorithms as supplied in the +.Em SMIMECapabilities +signed attribute. +This means the user has to manually include the correct encryption algorithm. +It should store the list of permitted ciphers in a database and only use those. +.Pp +No revocation checking is done on the signer's certificate. +.Pp +The current code can only handle +.Em S/MIME +v2 messages, the more complex +.Em S/MIME +v3 structures may cause parsing errors. +.\" +.\" SPEED +.\" +.Sh SPEED +.Nm openssl speed +.Op Fl engine Ar id +.Op Cm md2 +.Op Cm mdc2 +.Op Cm md5 +.Op Cm hmac +.Op Cm sha1 +.Op Cm rmd160 +.Op Cm idea-cbc +.Op Cm rc2-cbc +.Op Cm rc5-cbc +.Op Cm bf-cbc +.Op Cm des-cbc +.Op Cm des-ede3 +.Op Cm rc4 +.Op Cm rsa512 +.Op Cm rsa1024 +.Op Cm rsa2048 +.Op Cm rsa4096 +.Op Cm dsa512 +.Op Cm dsa1024 +.Op Cm dsa2048 +.Op Cm idea +.Op Cm rc2 +.Op Cm des +.Op Cm rsa +.Op Cm blowfish +.Pp +The +.Nm speed +command is used to test the performance of cryptographic algorithms. +.Pp +.Bd -ragged -offset indent +.It Fl engine Ar id +Specifying an engine (by it's unique +.Ar id +string) will cause +.Nm speed +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. +The engine will then be set as the default +for all available algorithms. +.It Cm [zero or more test algorithms] +If any options are given, +.Nm speed +tests those algorithms, otherwise all of the above are tested. +.Ed +.\" +.\" SPKAC +.\" +.Sh SPKAC +.Nm openssl spkac +.Op Fl in Ar filename +.Op Fl out Ar filename +.Op Fl key Ar keyfile +.Op Fl passin Ar arg +.Op Fl challenge Ar string +.Op Fl pubkey +.Op Fl spkac Ar spkacname +.Op Fl spksect Ar section +.Op Fl noout +.Op Fl verify +.Pp +The +.Nm spkac +command processes Netscape signed public key and challenge +(SPKAC) files. +It can print out their contents, verify the signature and +produce its own SPKACs from a supplied private key. +.Pp +The options are as follows: +.Bd -ragged -offset indent +.It Fl in Ar filename +This specifies the input +.Ar filename +to read from or standard input if this option is not specified. +Ignored if the +.Fl key +option is used. +.It Fl out Ar filename +Specifies the output +.Ar filename +to write to or standard output by default. +.It Fl key Ar keyfile +Create an SPKAC file using the private key in +.Ar keyfile . +The +.Fl in , noout , spksect +and +.Fl verify +options are ignored if present. +.It Fl passin Ar password +The input file password source. +For more information about the format of +.Ar arg +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.It Fl challenge Ar string +Specifies the challenge string if an SPKAC is being created. +.It Fl spkac Ar spkacname +Allows an alternative name for the variable containing the SPKAC. +The default is "SPKAC". +This option affects both generated and input SPKAC files. +.It Fl spksect Ar section +Allows an alternative name for the +.Ar section +containing the SPKAC. +The default is the default section. +.It Fl noout +Don't output the text version of the SPKAC (not used if an +SPKAC is being created). +.It Fl pubkey +Output the public key of an SPKAC (not used if an SPKAC is +being created). +.It Fl verify +Verifies the digital signature on the supplied SPKAC. +.Ed +.Sh SPKAC EXAMPLES +Print out the contents of an SPKAC: +.Pp +\& $ openssl spkac -in spkac.cnf +.Pp +Verify the signature of an SPKAC: +.Pp +\& $ openssl spkac -in spkac.cnf -noout -verify +.Pp +Create an SPKAC using the challenge string "hello": +.Pp +\& $ openssl spkac -key key.pem -challenge hello -out spkac.cnf +.Pp +Example of an SPKAC, (long lines split up for clarity): +.Pp +.Bd -literal +\& SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA1cCoq2Wa3Ixs47uI7F\e +\& PVwHVIPDx5yso105Y6zpozam135a8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03u\e +\& PFoQIDAQABFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJh1bEIYuc\e +\& 2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnDdq+NQ3F+X4deMx9AaEglZtULwV\e +\& 4= +.Ed +.Sh SPKAC NOTES +A created SPKAC with suitable DN components appended can be fed into +the +.Nm ca +utility. +.Pp +SPKACs are typically generated by Netscape when a form is submitted +containing the +.Em KEYGEN +tag as part of the certificate enrollment process. +.Pp +The challenge string permits a primitive form of proof of possession +of private key. +By checking the SPKAC signature and a random challenge +string, some guarantee is given that the user knows the private key +corresponding to the public key being certified. +This is important in some applications. +Without this it is possible for a previous SPKAC +to be used in a "replay attack". +.\" +.\" VERIFY +.\" +.Sh VERIFY +.Nm openssl verify +.Op Fl CApath Ar directory +.Op Fl CAfile Ar file +.Op Fl purpose Ar purpose +.Op Fl untrusted Ar file +.Op Fl help +.Op Fl issuer_checks +.Op Fl verbose +.Op Fl +.Op Ar certificates +.Pp +The +.Nm verify +command verifies certificate chains. +.Pp +The options are as follows: +.Bd -ragged -offset indent +.It Fl CApath directory +A +.Ar directory +of trusted certificates. +The certificates should have names of the form +.Em hash.0 , +or have symbolic links to them of this form. +("hash" is the hashed certificate subject name: see the +.Fl hash +option of the +.Nm x509 +utility). +Under Unix the +.Nm c_rehash +script will automatically create symbolic links to a directory of certificates. +.It Fl CAfile Ar file +A +.Ar file +of trusted certificates. +The +.Ar file +should contain multiple certificates in +.Em PEM +format concatenated together. +.It Fl untrusted Ar file +A +.Ar file +of untrusted certificates. +The +.Ar file +should contain multiple certificates. +.It Fl purpose Ar purpose +The intended use for the certificate. +Without this option no chain verification will be done. +Currently accepted uses are +.Ar sslclient , sslserver , +.Ar nssslserver , smimesign , +and +.Ar smimeencrypt . +See the +.Sx VERIFY OPERATION +section for more information. +.It Fl help +Prints out a usage message. +.It Fl verbose +Print extra information about the operations being performed. +.It Fl issuer_checks +Print out diagnostics relating to searches for the issuer certificate +of the current certificate. +This shows why each candidate issuer certificate was rejected. +However the presence of rejection messages +does not itself imply that anything is wrong: during the normal +verify process several rejections may take place. +.It Fl +Marks the last option. +All arguments following this are assumed to be certificate files. +This is useful if the first certificate filename begins with a +.Cm \&- . +.It Ar certificates +One or more +.Ar certificates +to verify. +If no certificate filenames are included then an attempt is made to read +a certificate from standard input. +They should all be in +.Em PEM +format. +.Ed +.Sh VERIFY OPERATION +The +.Nm verify +program uses the same functions as the internal SSL and S/MIME verification, +therefore this description applies to these verify operations too. +.Pp +There is one crucial difference between the verify operations performed +by the +.Nm verify +program: wherever possible an attempt is made to continue +after an error, whereas normally the verify operation would halt on the +first error. +This allows all the problems with a certificate chain to be determined. +.Pp +The verify operation consists of a number of separate steps. +.Pp +Firstly a certificate chain is built up starting from the supplied certificate +and ending in the root CA. +It is an error if the whole chain cannot be built up. +The chain is built up by looking up the issuers certificate of the current +certificate. +If a certificate is found which is its own issuer it is assumed +to be the root CA. +.Pp +The process of 'looking up the issuers certificate' itself involves a number +of steps. +In versions of +.Nm OpenSSL +before 0.9.5a the first certificate whose subject name matched the issuer +of the current certificate was assumed to be the issuers certificate. +In +.Nm OpenSSL +0.9.6 and later all certificates whose subject name matches the issuer name +of the current certificate are subject to further tests. +The relevant authority key identifier components of the current certificate +(if present) must match the subject key identifier (if present) +and issuer and serial number of the candidate issuer; in addition the +.Em keyUsage +extension of the candidate issuer (if present) must permit certificate signing. +.Pp +The lookup first looks in the list of untrusted certificates and if no match +is found the remaining lookups are from the trusted certificates. +The root CA is always looked up in the trusted certificate list: if the +certificate to verify is a root certificate, then an exact match must be +found in the trusted list. +.Pp +The second operation is to check every untrusted certificate's extensions for +consistency with the supplied purpose. +If the +.Fl purpose +option is not included, then no checks are done. +The supplied or "leaf" certificate must have extensions compatible with the +supplied purpose and all other certificates must also be valid +CA certificates. +The precise extensions required are described in more detail in +the +.Sx X509 CERTIFICATE EXTENSIONS +section below. +.Pp +The third operation is to check the trust settings on the root CA. +The root CA should be trusted for the supplied purpose. +For compatibility with previous versions of +.Nm SSLeay +and +.Nm OpenSSL , +a certificate with no trust settings is considered to be valid for +all purposes. +.Pp +The final operation is to check the validity of the certificate chain. +The validity period is checked against the current system time and the +.Em notBefore +and +.Em notAfter +dates in the certificate. +The certificate signatures are also checked at this point. +.Pp +If all operations complete successfully, then the certificate is considered +valid. +If any operation fails then the certificate is not valid. +.Sh VERIFY DIAGNOSTICS +When a verify operation fails, the output messages can be somewhat cryptic. +The general form of the error message is: +.Pp +.Bd -literal +\& server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit) +\& error 24 at 1 depth lookup:invalid CA certificate +.Ed +.Pp +The first line contains the name of the certificate being verified followed by +the subject name of the certificate. +The second line contains the error number and the depth. +The depth is number of the certificate being verified when a +problem was detected starting with zero for the certificate being verified +itself, then 1 for the CA that signed the certificate and so on. +Finally a text version of the error number is presented. +.Pp +An exhaustive list of the error codes and messages is shown below; this also +includes the name of the error code as defined in the header file +.Aq Pa x509_vfy.h . +Some of the error codes are defined but never returned: these are described +as "unused". +.Pp +.Bd -ragged -offset indent +.It Ar "0 X509_V_OK: ok" +The operation was successful. +.It Ar 2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate +The issuer certificate could not be found: this occurs if the issuer certificate +of an untrusted certificate cannot be found. +.It Ar 3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL +The CRL of a certificate could not be found. +Unused. +.It Ar 4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature +The certificate signature could not be decrypted. +This means that the actual signature value could not be determined rather +than it not matching the expected value. +This is only meaningful for RSA keys. +.It Ar 5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature +The CRL signature could not be decrypted: this means that the actual +signature value could not be determined rather than it not matching the +expected value. +Unused. +.It Ar 6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key +The public key in the certificate +.Em SubjectPublicKeyInfo +could not be read. +.It Ar 7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure +The signature of the certificate is invalid. +.It Ar 8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure +The signature of the certificate is invalid. +Unused. +.It Ar 9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid +The certificate is not yet valid: the +.Em notBefore +date is after the current time. +.It Ar 10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired +The certificate has expired; that is, the +.Em notAfter +date is before the current time. +.It Ar 11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid +The CRL is not yet valid. +Unused. +.It Ar 12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired +The CRL has expired. +Unused. +.It Ar 13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field +The certificate +.Em notBefore +field contains an invalid time. +.It Ar 14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field +The certificate +.Em notAfter +field contains an invalid time. +.It Ar 15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field +The CRL +.Em lastUpdate +field contains an invalid time. +Unused. +.It Ar 16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field +The CRL +.Em nextUpdate +field contains an invalid time. +Unused. +.It Ar 17 X509_V_ERR_OUT_OF_MEM: out of memory +An error occurred trying to allocate memory. +This should never happen. +.It Ar 18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate +The passed certificate is self-signed and the same certificate cannot be +found in the list of trusted certificates. +.It Ar 19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain +The certificate chain could be built up using the untrusted certificates but +the root could not be found locally. +.It Ar 20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate +The issuer certificate of a locally looked up certificate could not be found. +This normally means the list of trusted certificates is not complete. +.It Ar 21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate +No signatures could be verified because the chain contains only one +certificate and it is not self-signed. +.It Ar 22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long +The certificate chain length is greater than the supplied maximum depth. +Unused. +.It Ar 23 X509_V_ERR_CERT_REVOKED: certificate revoked +The certificate has been revoked. +Unused. +.It Ar 24 X509_V_ERR_INVALID_CA: invalid CA certificate +A CA certificate is invalid. +Either it is not a CA or its extensions are not consistent +with the supplied purpose. +.It Ar 25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded +The +.Em basicConstraints +pathlength parameter has been exceeded. +.It Ar 26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose +The supplied certificate cannot be used for the specified purpose. +.It Ar 27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted +The root CA is not marked as trusted for the specified purpose. +.It Ar 28 X509_V_ERR_CERT_REJECTED: certificate rejected +The root CA is marked to reject the specified purpose. +.It Ar 29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch +The current candidate issuer certificate was rejected because its subject name +did not match the issuer name of the current certificate. +Only displayed when the +.Fl issuer_checks +option is set. +.It Ar 30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch +The current candidate issuer certificate was rejected because its subject key +identifier was present and did not match the authority key identifier current +certificate. +Only displayed when the +.Fl issuer_checks +option is set. +.It Ar 31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch +The current candidate issuer certificate was rejected because its issuer name +and serial number were present and did not match the authority key identifier +of the current certificate. +Only displayed when the +.Fl issuer_checks +option is set. +.It Ar 32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing +The current candidate issuer certificate was rejected because its +.Em keyUsage +extension does not permit certificate signing. +.It Ar 50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure +An application specific error. +Unused. +.Ed +.Sh VERIFY BUGS +Although the issuer checks are a considerable improvement over the old +technique, they still suffer from limitations in the underlying +X509_LOOKUP API. +One consequence of this is that trusted certificates with matching subject +name must either appear in a file (as specified by the +.Fl CAfile +option) or a directory (as specified by +.Fl CApath ) . +If they occur in both, then only the certificates in the file will +be recognised. +.Pp +Previous versions of +.Nm OpenSSL +assume certificates with matching subject name are identical and +mishandled them. +.\" +.\" VERSION +.\" +.Sh VERSION +.Nm openssl version +.Op Fl a +.Op Fl v +.Op Fl b +.Op Fl o +.Op Fl f +.Op Fl p +.Pp +The +.Nm version +command is used to print out version information about +.Nm OpenSSL . +.Pp +The options are as follows: +.Bd -ragged -offset indent +.It Fl a +All information: this is the same as setting all the other flags. +.It Fl v +The current +.Nm OpenSSL +version. +.It Fl b +The date the current version of +.Nm OpenSSL +was built. +.It Fl o +Option information: various options set when the library was built. +.It Fl c +Compilation flags. +.It Fl p +Platform setting. +.It Fl d +.Em OPENSSLDIR +setting. +.Ed +.Sh VERSION NOTES +The output of +.Nm openssl version -a +would typically be used when sending in a bug report. +.Sh VERSION HISTORY +The +.Fl d +option was added in +.Nm OpenSSL +0.9.7. +.\" +.\" X509 +.\" +.Sh X509 +.Nm openssl x509 +.Bk -words +.Op Fl inform Ar DER|PEM|NET +.Op Fl outform Ar DER|PEM|NET +.Op Fl keyform Ar DER|PEM +.Op Fl CAform Ar DER|PEM +.Op Fl CAkeyform Ar DER|PEM +.Op Fl in Ar filename +.Op Fl out Ar filename +.Op Fl serial +.Op Fl hash +.Op Fl subject +.Op Fl issuer +.Op Fl nameopt Ar option +.Op Fl email +.Op Fl startdate +.Op Fl enddate +.Op Fl purpose +.Op Fl dates +.Op Fl modulus +.Op Fl fingerprint +.Op Fl alias +.Op Fl noout +.Op Fl trustout +.Op Fl clrtrust +.Op Fl clrreject +.Op Fl addtrust Ar arg +.Op Fl addreject Ar arg +.Op Fl setalias Ar arg +.Op Fl days Ar arg +.Op Fl set_serial Ar n +.Op Fl signkey Ar filename +.Op Fl x509toreq +.Op Fl req +.Op Fl CA Ar filename +.Op Fl CAkey Ar filename +.Op Fl CAcreateserial +.Op Fl CAserial Ar filename +.Op Fl text +.Op Fl C +.Op Cm -md2|-md5|-sha1|-mdc2 +.Op Fl clrext +.Op Fl extfile Ar filename +.Op Fl extensions Ar section +.Ek +.Pp +The +.Nm x509 +command is a multi-purpose certificate utility. +It can be used to display certificate information, convert certificates to +various forms, sign certificate requests like a "mini CA" or edit +certificate trust settings. +.Pp +Since there are a large number of options, they are split up into +various sections. +.Sh X509 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS +.Bd -ragged -offset indent +.It Fl inform Ar DER|PEM|NET +This specifies the input format. +Normally the command will expect an X509 certificate, +but this can change if other options such as +.Fl req +are present. +The +.Ar DER +format is the DER encoding of the certificate and +.Ar PEM +is the base64 encoding of the DER encoding with header and footer lines added. +The +.Ar NET +option is an obscure Netscape server format that is now +obsolete. +.It Fl outform Ar DER|PEM|NET +This specifies the output format; +the options have the same meaning as the +.Fl inform +option. +.It Fl in Ar filename +This specifies the input +.Ar filename +to read a certificate from or standard input if this option is not specified. +.It Fl out Ar filename +This specifies the output +.Ar filename +to write to or standard output by default. +.It Fl md2|-md5|-sha1|-mdc2 +The digest to use. +This affects any signing or display option that uses a message digest, +such as the +.Fl fingerprint , signkey +and +.Fl CA +options. +If not specified then MD5 is used. +If the key being used to sign with is a DSA key then +this option has no effect: SHA1 is always used with DSA keys. +.Ed +.Sh X509 DISPLAY OPTIONS +.Sy Note : +The +.Fl alias +and +.Fl purpose +options are also display options but are described in the +.Sx X509 TRUST OPTIONS +section. +.Bd -ragged -offset indent +.It Fl text +Prints out the certificate in text form. +Full details are output including the public key, signature algorithms, +issuer and subject names, serial number, any extensions present and any +trust settings. +.It Fl certopt Ar option +Customise the output format used with +.Fl text . +The +.Ar option +argument can be a single option or multiple options separated by commas. +The +.Fl certopt +switch may be also be used more than once to set multiple options. +See the +.Sx X509 TEXT OPTIONS +section for more information. +.It Fl noout +This option prevents output of the encoded version of the request. +.It Fl modulus +This option prints out the value of the modulus of the public key +contained in the certificate. +.It Fl serial +Outputs the certificate serial number. +.It Fl hash +Outputs the "hash" of the certificate subject name. +This is used in +.Nm OpenSSL +to form an index to allow certificates in a directory to be looked up +by subject name. +.It Fl subject +Outputs the subject name. +.It Fl issuer +Outputs the issuer name. +.It Fl nameopt Ar option +Option which determines how the subject or issuer names are displayed. +The +.Ar option +argument can be a single option or multiple options separated by commas. +Alternatively, the +.Fl nameopt +switch may be used more than once to set multiple options. +See the +.Sx X509 NAME OPTIONS +section for more information. +.It Fl email +Outputs the email address(es) if any. +.It Fl startdate +Prints out the start date of the certificate; that is, the +.Em notBefore +date. +.It Fl enddate +Prints out the expiry date of the certificate; that is, the +.Em notAfter +date. +.It Fl dates +Prints out the start and expiry dates of a certificate. +.It Fl fingerprint +Prints out the digest of the DER encoded version of the whole certificate +(see +.Sx DIGEST OPTIONS ) . +.It Fl C +This outputs the certificate in the form of a C source file. +.Ed +.Sh X509 TRUST SETTINGS +Please note these options are currently experimental and may well change. +.Pp +A +.Em trusted certificate +is an ordinary certificate which has several +additional pieces of information attached to it such as the permitted +and prohibited uses of the certificate and an "alias". +.Pp +Normally when a certificate is being verified at least one certificate +must be "trusted". +By default a trusted certificate must be stored +locally and must be a root CA: any certificate chain ending in this CA +is then usable for any purpose. +.Pp +Trust settings currently are only used with a root CA. +They allow a finer control over the purposes the root CA can be used for. +For example, a CA may be trusted for an SSL client but not for +SSL server use. +.Pp +See the description of the +.Nm verify +utility for more information on the meaning of trust settings. +.Pp +Future versions of +.Nm OpenSSL +will recognize trust settings on any certificate: not just root CAs. +.Bd -ragged -offset indent +.It Fl trustout +This causes +.Nm x509 +to output a +.Em trusted certificate . +An ordinary or trusted certificate can be input, but by default an ordinary +certificate is output and any trust settings are discarded. +With the +.Fl trustout +option a trusted certificate is output. +A trusted certificate is automatically output if any trust settings +are modified. +.It Fl setalias Ar arg +Sets the alias of the certificate. +This will allow the certificate to be referred to using a nickname, +for example "Steve's Certificate". +.It Fl alias +Outputs the certificate alias, if any. +.It Fl clrtrust +Clears all the permitted or trusted uses of the certificate. +.It Fl clrreject +Clears all the prohibited or rejected uses of the certificate. +.It Fl addtrust Ar arg +Adds a trusted certificate use. +Any object name can be used here, but currently only +.Ar clientAuth +.Po Em SSL + client use +.Pc , +.Ar serverAuth +.Po Em SSL + server use +.Pc +and +.Ar emailProtection +.Po Em S/MIME + email +.Pc +are used. +Other +.Nm OpenSSL +applications may define additional uses. +.It Fl addreject Ar arg +Adds a prohibited use. +It accepts the same values as the +.Fl addtrust +option. +.It Fl purpose +This option performs tests on the certificate extensions and outputs +the results. +For a more complete description see the +.Sx X509 CERTIFICATE EXTENSIONS +section. +.Ed +.Sh X509 SIGNING OPTIONS +The +.Nm x509 +utility can be used to sign certificates and requests: it +can thus behave like a "mini CA". +.Pp +.Bd -ragged -offset indent +.It Fl signkey Ar filename +This option causes the input file to be self-signed using the supplied +private key. +.Pp +If the input file is a certificate, it sets the issuer name to the +subject name (i.e. makes it self-signed), changes the public key to the +supplied value and changes the start and end dates. +The start date is set to the current time and the end date is set to +a value determined by the +.Fl days +option. +Any certificate extensions are retained unless the +.Fl clrext +option is supplied. +.Pp +If the input is a certificate request, then a self-signed certificate +is created using the supplied private key using the subject name in +the request. +.It Fl clrext +Delete any extensions from a certificate. +This option is used when a certificate is being created from another +certificate (for example with the +.Fl signkey +or the +.Fl CA +options). +Normally all extensions are retained. +.It Fl keyform Ar PEM|DER +Specifies the format +.Po Em DER + or +.Em PEM +.Pc +of the private key file used in the +.Fl signkey +option. +.It Fl days Ar arg +Specifies the number of days to make a certificate valid for. +The default is 30 days. +.It Fl x509toreq +Converts a certificate into a certificate request. +The +.Fl signkey +option is used to pass the required private key. +.It Fl req +By default a certificate is expected on input. +With this option a certificate request is expected instead. +.It Fl set_serial Ar n +Specifies the serial number to use. +This option can be used with either the +.Fl signkey +or +.Fl CA +options. +If used in conjunction with the +.Fl CA +option, the serial number file (as specified by the +.Fl CAserial +or +.Fl CAcreateserial +options) is not used. +.Pp +The serial number can be decimal or hex (if preceded by +.Em 0x ) . +Negative serial numbers can also be specified but their use is not recommended. +.It Fl CA Ar filename +Specifies the CA certificate to be used for signing. +When this option is present +.Nm x509 +behaves like a "mini CA". +The input file is signed by the CA using this option; +that is, its issuer name is set to the subject name of the CA and it is +digitally signed using the CAs private key. +.Pp +This option is normally combined with the +.Fl req +option. +Without the +.Fl req +option, the input is a certificate which must be self-signed. +.It Fl CAkey Ar filename +Sets the CA private key to sign a certificate with. +If this option is not specified then it is assumed that the CA private key +is present in the CA certificate file. +.It Fl CAserial Ar filename +Sets the CA serial number file to use. +.Pp +When the +.Fl CA +option is used to sign a certificate it uses a serial +number specified in a file. +This file consist of one line containing an even number of hex digits +with the serial number to use. +After each use the serial number is incremented and written out +to the file again. +.Pp +The default filename consists of the CA certificate file base name with +.Pa .srl +appended. +For example if the CA certificate file is called +.Pa mycacert.pem , +it expects to find a serial number file called +.Pa mycacert.srl . +.It Fl CAcreateserial Ar filename +With this option the CA serial number file is created if it does not exist: +it will contain the serial number "02" and the certificate being signed will +have 1 as its serial number. +Normally if the +.Fl CA +option is specified and the serial number file does not exist it is an error. +.It Fl extfile Ar filename +File containing certificate extensions to use. +If not specified, then no extensions are added to the certificate. +.It Fl extensions Ar section +The section to add certificate extensions from. +If this option is not specified then the extensions should either be +contained in the unnamed (default) section or the default section should +contain a variable called "extensions" which contains the section to use. +.Ed +.Sh X509 NAME OPTIONS +The +.Fl nameopt +command line switch determines how the subject and issuer +names are displayed. +If no +.Fl nameopt +switch is present, the default "oneline" +format is used which is compatible with previous versions of +.Nm OpenSSL . +Each option is described in detail below, all options can be preceded by +a +.Cm \&- +to turn the option off. +Only the first four will normally be used. +.Bd -ragged -offset indent +.It Ar compat +Use the old format. +This is equivalent to specifying no name options at all. +.It Ar RFC2253 +Displays names compatible with RFC2253; equivalent to +.Ar esc_2253 , esc_ctrl , +.Ar esc_msb , utf8 , dump_nostr , dump_unknown , +.Ar dump_der , sep_comma_plus , dn_rev and sname . +.It Ar oneline +A oneline format which is more readable than RFC2253. +It is equivalent to specifying the +.Ar esc_2253 , esc_ctrl , esc_msb , utf8 , +.Ar dump_nostr , dump_der , use_quote , sep_comma_plus_spc , +.Ar spc_eq +and +.Ar sname +options. +.It Ar multiline +A multiline format. +It is equivalent to +.Ar esc_ctrl , esc_msb , sep_multiline , +.Ar spc_eq , lname +and +.Ar align . +.It Ar esc_2253 +Escape the "special" characters required by RFC2253 in a field that is +.Cm \& ,+"<>; . +Additionally, +.Cm \&# +is escaped at the beginning of a string +and a space character at the beginning or end of a string. +.It Ar esc_ctrl +Escape control characters. +That is, those with ASCII values less than +0x20 (space) and the delete (0x7f) character. +They are escaped using the RFC2253 \eXX notation (where XX are two hex +digits representing the character value). +.It Ar esc_msb +Escape characters with the MSB set; that is, with ASCII values larger than +127. +.It Ar use_quote +Escapes some characters by surrounding the whole string with +.Cm \&" +characters. +Without the option, all escaping is done with the +.Cm \&\e +character. +.It Ar utf8 +Convert all strings to UTF8 format first. +This is required by RFC2253. +If you are lucky enough to have a UTF8 compatible terminal then the use +of this option (and +.Em not +setting +.Ar esc_msb ) +may result in the correct display of multibyte (international) characters. +If this option is not present, then multibyte characters larger than 0xff +will be represented using the format \eUXXXX for 16 bits and \eWXXXXXXXX +for 32 bits. +Also, if this option is off, any UTF8Strings will be converted to their +character form first. +.It Ar no_type +This option does not attempt to interpret multibyte characters in any +way. +That is, their content octets are merely dumped as though one octet +represents each character. +This is useful for diagnostic purposes but will result in rather odd +looking output. +.It Ar show_type +Show the type of the ASN1 character string. +The type precedes the field contents. +For example "BMPSTRING: Hello World". +.It Ar dump_der +When this option is set, any fields that need to be hexdumped will +be dumped using the DER encoding of the field. +Otherwise just the content octets will be displayed. +Both options use the RFC2253 #XXXX... format. +.It Ar dump_nostr +Dump non-character string types (for example OCTET STRING); if this +option is not set then non-character string types will be displayed +as though each content octet represents a single character. +.It Ar dump_all +Dump all fields. +This option, when used with +.Ar dump_der , +allows the DER encoding of the structure to be unambiguously determined. +.It Ar dump_unknown +Dump any field whose OID is not recognised by +.Nm OpenSSL . +.It Ar sep_comma_plus , sep_comma_plus_space , sep_semi_plus_space , sep_multiline +These options determine the field separators. +The first character is between RDNs and the second between multiple AVAs +(multiple AVAs are very rare and their use is discouraged). +The options ending in "space" additionally place a space after the +separator to make it more readable. +The +.Ar sep_multiline +uses a linefeed character for the RDN separator and a spaced +.Cm \&+ +for the AVA separator. +It also indents the fields by four characters. +.It Ar dn_rev +Reverse the fields of the DN. +This is required by RFC2253. +As a side effect, this also reverses the order of multiple AVAs but this is +permissible. +.It Ar nofname , sname , lname , oid +These options alter how the field name is displayed. +.Ar nofname +does not display the field at all. +.Ar sname +uses the "short name" form (CN for +.Ar commonName , +for example). +.Ar lname +uses the long form. +.Ar oid +represents the OID in numerical form and is useful for diagnostic purpose. +.It Ar align +Align field values for a more readable output. +Only usable with +.Ar sep_multiline . +.It Ar spc_eq +Places spaces round the +.Cm \&= +character which follows the field name. +.Ed +.Sh X509 TEXT OPTIONS +As well as customising the name output format, it is also possible to +customise the actual fields printed using the +.Fl certopt +options when the +.Fl text +option is present. +The default behaviour is to print all fields. +.Bd -ragged -offset indent +.It Ar compatible +Use the old format. +This is equivalent to specifying no output options at all. +.It Ar no_header +Don't print header information: that is, the lines saying "Certificate" +and "Data". +.It Ar no_version +Don't print out the version number. +.It Ar no_serial +Don't print out the serial number. +.It Ar no_signame +Don't print out the signature algorithm used. +.It Ar no_validity +Don't print the validity; that is, the +.Em notBefore +and +.Em notAfter +fields. +.It Ar no_subject +Don't print out the subject name. +.It Ar no_issuer +Don't print out the issuer name. +.It Ar no_pubkey +Don't print out the public key. +.It Ar no_sigdump +Don't give a hexadecimal dump of the certificate signature. +.It Ar no_aux +Don't print out certificate trust information. +.It Ar no_extensions +Don't print out any X509V3 extensions. +.It Ar ext_default +Retain default extension behaviour: attempt to print out unsupported +certificate extensions. +.It Ar ext_error +Print an error message for unsupported certificate extensions. +.It Ar ext_parse +ASN1 parse unsupported extensions. +.It Ar ext_dump +Hex dump unsupported extensions. +.It Ar ca_default +The value used by the +.Nm ca +utility, equivalent to +.Ar no_issuer , no_pubkey , no_header , +.Ar no_version , no_sigdump +and +.Ar no_signame . +.Ed +.Sh X509 EXAMPLES +.Sy Note : +In these examples the '\e' means the example should be all on one +line. +.Pp +Display the contents of a certificate: +.Pp +\& $ openssl x509 -in cert.pem -noout -text +.Pp +Display the certificate serial number: +.Pp +\& $ openssl x509 -in cert.pem -noout -serial +.Pp +Display the certificate subject name: +.Pp +\& $ openssl x509 -in cert.pem -noout -subject +.Pp +Display the certificate subject name in RFC2253 form: +.Pp +\& $ openssl x509 -in cert.pem -noout -subject -nameopt RFC2253 +.Pp +Display the certificate subject name in oneline form on a terminal +supporting UTF8: +.Pp +\& $ openssl x509 -in cert.pem -noout -subject -nameopt oneline,-escmsb +.Pp +Display the certificate MD5 fingerprint: +.Pp +\& $ openssl x509 -in cert.pem -noout -fingerprint +.Pp +Display the certificate SHA1 fingerprint: +.Pp +\& $ openssl x509 -sha1 -in cert.pem -noout -fingerprint +.Pp +Convert a certificate from +.Em PEM +to +.Em DER +format: +.Pp +\& $ openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER +.Pp +Convert a certificate to a certificate request: +.Pp +\& $ openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem +.Pp +Convert a certificate request into a self-signed certificate using +extensions for a CA: +.Pp +.Bd -literal +\& $ openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions \e +\& v3_ca -signkey key.pem -out cacert.pem +.Ed +.Pp +Sign a certificate request using the CA certificate above and add user +certificate extensions: +.Pp +.Bd -literal +\& $ openssl x509 -req -in req.pem -extfile openssl.cnf -extensions \e + v3_usr -CA cacert.pem -CAkey key.pem -CAcreateserial +.Ed +.Pp +Set a certificate to be trusted for SSL +client use and change set its alias to "Steve's Class 1 CA": +.Pp +.Bd -literal +\& $ openssl x509 -in cert.pem -addtrust sslclient \e +\& -alias "Steve's Class 1 CA" -out trust.pem +.Ed +.Sh X509 NOTES +The +.Em PEM +format uses the header and footer lines: +.Pp +.Bd -literal +\& -----BEGIN CERTIFICATE---- +\& -----END CERTIFICATE---- +.Ed +.Pp +It will also handle files containing: +.Pp +.Bd -literal +\& -----BEGIN X509 CERTIFICATE---- +\& -----END X509 CERTIFICATE---- +.Ed +.Pp +Trusted certificates have the lines: +.Pp +.Bd -literal +\& -----BEGIN TRUSTED CERTIFICATE---- +\& -----END TRUSTED CERTIFICATE---- +.Ed +.Pp +The conversion to UTF8 format used with the name options assumes that +T61Strings use the ISO8859-1 character set. +This is wrong, but Netscape and MSIE do this, as do many certificates. +So although this is incorrect +it is more likely to display the majority of certificates correctly. +.Pp +The +.Fl fingerprint +option takes the digest of the DER encoded certificate. +This is commonly called a "fingerprint". +Because of the nature of message digests, the fingerprint of a certificate +is unique to that certificate and two certificates with the same fingerprint +can be considered to be the same. +.Pp +The Netscape fingerprint uses MD5, whereas MSIE uses SHA1. +.Pp +The +.Fl email +option searches the subject name and the subject alternative +name extension. +Only unique email addresses will be printed out: it will +not print the same address more than once. +.Sh X509 CERTIFICATE EXTENSIONS +The +.Fl purpose +option checks the certificate extensions and determines +what the certificate can be used for. +The actual checks done are rather +complex and include various hacks and workarounds to handle broken +certificates and software. +.Pp +The same code is used when verifying untrusted certificates in chains, +so this section is useful if a chain is rejected by the verify code. +.Pp +The +.Em basicConstraints +extension CA flag is used to determine whether the +certificate can be used as a CA. +If the CA flag is true then it is a CA, +if the CA flag is false then it is not a CA. +.Em All +CAs should have the CA flag set to true. +.Pp +If the +.Em basicConstraints +extension is absent then the certificate is +considered to be a "possible CA"; other extensions are checked according +to the intended use of the certificate. +A warning is given in this case because the certificate should really not +be regarded as a CA: however, +it is allowed to be a CA to work around some broken software. +.Pp +If the certificate is a V1 certificate (and thus has no extensions) and +it is self-signed, it is also assumed to be a CA but a warning is again +given: this is to work around the problem of Verisign roots which are V1 +self-signed certificates. +.Pp +If the +.Em keyUsage +extension is present, then additional restraints are +made on the uses of the certificate. +A CA certificate +.Em must +have the +.Em keyCertSign +bit set if the +.Em keyUsage +extension is present. +.Pp +The extended key usage extension places additional restrictions on the +certificate uses. +If this extension is present (whether critical or not) +the key can only be used for the purposes specified. +.Pp +A complete description of each test is given below. +The comments about +.Em basicConstraints +and +.Em keyUsage +and V1 certificates above apply to +.Em all +CA certificates. +.Pp +.Bd -ragged -offset indent +.It Ar SSL Client +The extended key usage extension must be absent or include the +"web client authentication" OID. +.Ar keyUsage +must be absent or it must have the +.Em digitalSignature +bit set. +Netscape certificate type must be absent or it must have the SSL +client bit set. +.It Ar SSL Client CA +The extended key usage extension must be absent or include the +"web client authentication" OID. +Netscape certificate type must be absent or it must have the SSL CA +bit set: this is used as a work around if the +.Em basicConstraints +extension is absent. +.It Ar SSL Server +The extended key usage extension must be absent or include the +"web server authentication" and/or one of the SGC OIDs. +.Em keyUsage +must be absent or it must have the +.Em digitalSignature +set, the +.Em keyEncipherment +set, or both bits set. +Netscape certificate type must be absent or have the SSL server bit set. +.It Ar SSL Server CA +The extended key usage extension must be absent or include the +"web server authentication" and/or one of the SGC OIDs. +Netscape certificate type must be absent or the SSL CA +bit must be set: this is used as a work around if the +.Em basicConstraints +extension is absent. +.It Ar Netscape SSL Server +For Netscape SSL clients to connect to an SSL server; it must have the +.Em keyEncipherment +bit set if the +.Em keyUsage +extension is present. +This isn't always valid because some cipher suites use the key for +digital signing. +Otherwise it is the same as a normal SSL server. +.It Ar Common S/MIME Client Tests +The extended key usage extension must be absent or include the +"email protection" OID. +Netscape certificate type must be absent or should have the +.Em S/MIME +bit set. +If the +.Em S/MIME +bit is not set in netscape certificate type, then the SSL +client bit is tolerated as an alternative but a warning is shown: +this is because some Verisign certificates don't set the +.Em S/MIME +bit. +.It Ar S/MIME Signing +In addition to the common +.Em S/MIME +client tests, the +.Em digitalSignature +bit must be set if the +.Em keyUsage +extension is present. +.It Ar S/MIME Encryption +In addition to the common +.Em S/MIME +tests, the +.Em keyEncipherment +bit must be set if the +.Em keyUsage +extension is present. +.It Ar S/MIME CA +The extended key usage extension must be absent or include the +"email protection" OID. +Netscape certificate type must be absent or must have the +.Em S/MIME CA +bit set: this is used as a work around if the +.Em basicConstraints +extension is absent. +.It Ar CRL Signing +The +.Em keyUsage +extension must be absent or it must have the +.Em CRL +signing bit set. +.It Ar CRL Signing CA +The normal CA tests apply. +Except in this case the +.Em basicConstraints +extension must be present. +.Sh X509 BUGS +Extensions in certificates are not transferred to certificate requests and +vice versa. +.Pp +It is possible to produce invalid certificates or requests by specifying the +wrong private key or using inconsistent options in some cases: these should +be checked. +.Pp +There should be options to explicitly set such things as start and end dates, +rather than an offset from the current time. +.Pp +The code to implement the verify behaviour described in the +.Sx X509 TRUST SETTINGS +is currently being developed. +It thus describes the intended behaviour rather than the current behaviour. +It is hoped that it will represent reality in +.Nm OpenSSL +0.9.5 and later. +.\" +.\" OPENSSL HISTORY +.\" +.Sh "HISTORY" +The +.Xr openssl 1 +document appeared in +.Nm OpenSSL +0.9.2. +The +.Cm list- Ns Ar XXX Ns Cm -commands +pseudo-commands were added in +.Nm OpenSSL +0.9.3; +the +.Cm no- Ns Ar XXX +pseudo-commands were added in +.Nm OpenSSL +0.9.5a. |