diff options
Diffstat (limited to 'usr.bin/openssl/openssl.1')
| -rw-r--r-- | usr.bin/openssl/openssl.1 | 10407 |
1 files changed, 10407 insertions, 0 deletions
diff --git a/usr.bin/openssl/openssl.1 b/usr.bin/openssl/openssl.1 new file mode 100644 index 00000000000..b374728ba9e --- /dev/null +++ b/usr.bin/openssl/openssl.1 @@ -0,0 +1,10407 @@ +.\" $OpenBSD: openssl.1,v 1.1 2014/08/26 17:47:24 jsing Exp $ +.\" ==================================================================== +.\" 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.] +.\" +.\" OPENSSL +.\" +.Dd $Mdocdate: August 26 2014 $ +.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 +.Cm list-standard-commands \*(Ba +.Cm list-message-digest-commands \*(Ba +.Cm list-cipher-commands \*(Ba +.Cm list-cipher-algorithms \*(Ba +.Cm list-message-digest-algorithms \*(Ba +.Cm list-public-key-algorithms +.Pp +.Nm +.Cm no- Ns Ar XXX +.Op Ar arbitrary options +.Sh DESCRIPTION +.Nm OpenSSL +is a cryptography toolkit implementing the Secure Sockets Layer +.Pq SSL v3 +and Transport Layer Security +.Pq 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 -offset indent -compact +.It +Creation and management of private keys, public keys, and parameters +.It +Public key cryptographic operations +.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 +.It +Time stamp requests, generation, and verification +.El +.Sh COMMAND SUMMARY +The +.Nm +program provides a rich variety of commands +.Pf ( Cm command +in the +.Sx SYNOPSIS +above), +each of which often has a wealth of options and arguments +.Pf ( Ar command_opts +and +.Ar command_args +in the +.Sx SYNOPSIS ) . +.Pp +The pseudo-commands +.Cm list-standard-commands , list-message-digest-commands , +and +.Cm list-cipher-commands +output a list +.Pq 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-commands +.Cm list-cipher-algorithms +and +.Cm list-message-digest-algorithms +list all cipher and message digest names, +one entry per line. +Aliases are listed as: +.Pp +.D1 from =\*(Gt to +.Pp +The pseudo-command +.Cm list-public-key-algorithms +lists all supported public key algorithms. +.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 +.Pq 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 +.Pq CA +management. +.It Cm ciphers +Cipher suite description determination. +.It Cm crl +Certificate Revocation List +.Pq 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. +Superseded by +.Cm genpkey +and +.Cm pkeyparam . +.It Cm dsa +DSA data management. +.It Cm dsaparam +DSA parameter generation and management. +Superseded by +.Cm genpkey +and +.Cm pkeyparam . +.It Cm ec +Elliptic curve (EC) key processing. +.It Cm ecparam +EC parameter manipulation and generation. +.It Cm enc +Encoding with ciphers. +.It Cm engine +Engine (loadable module) information and manipulation. +.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 private key from parameters. +Superseded by +.Cm genpkey +and +.Cm pkey . +.It Cm genpkey +Generation of private keys or parameters. +.It Cm genrsa +Generation of RSA private key. +Superseded by +.Cm genpkey . +.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 pkey +Public and private key management. +.It Cm pkeyparam +Public key algorithm parameter management. +.It Cm pkeyutl +Public key algorithm cryptographic operation utility. +.It Cm prime +Generate prime numbers or test numbers for primality. +.It Cm rand +Generate pseudo-random bytes. +.It Cm req +PKCS#10 X.509 Certificate Signing Request +.Pq CSR +management. +.It Cm rsa +RSA key management. +.It Cm rsautl +RSA utility for signing, verification, encryption, and decryption. +Superseded by +.Cm pkeyutl . +.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 ts +Time stamping authority tool (client/server). +.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 md4 +MD4 digest. +.It Cm md5 +MD5 digest. +.It Cm ripemd160 +RIPEMD-160 digest. +.It Cm sha +SHA digest. +.It Cm sha1 +SHA-1 digest. +.El +.Sh ENCODING AND CIPHER COMMANDS +.Bl -tag -width Ds -compact +.It Cm aes-128-cbc | aes-128-ecb | aes-192-cbc | aes-192-ecb +.It Cm aes-256-cbc | aes-256-ecb +AES cipher. +.Pp +.It Cm base64 +Base64 encoding. +.Pp +.It Xo +.Cm bf | bf-cbc | bf-cfb | +.Cm bf-ecb | bf-ofb +.Xc +Blowfish cipher. +.Pp +.It Cm cast | cast-cbc +CAST cipher. +.Pp +.It Cm cast5-cbc | cast5-cfb | cast5-ecb | cast5-ofb +CAST5 cipher. +.Pp +.It Xo +.Cm des | des-cbc | des-cfb | des-ecb | +.Cm des-ede | des-ede-cbc +.Xc +.It Cm des-ede-cfb | des-ede-ofb | des-ofb +DES cipher. +.Pp +.It Xo +.Cm des3 | desx | des-ede3 | +.Cm des-ede3-cbc | des-ede3-cfb | des-ede3-ofb +.Xc +Triple DES cipher. +.Pp +.It Xo +.Cm rc2 | rc2-40-cbc | rc2-64-cbc | rc2-cbc | +.Cm rc2-cfb | rc2-ecb | rc2-ofb +.Xc +RC2 cipher. +.Pp +.It Cm rc4 | rc4-40 +RC4 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 : Ns Ar password +The actual password is +.Ar password . +Since the password is visible to utilities +(like +.Xr ps 1 +under +.Ux ) +this form should only be used where security is not important. +.It Ar env : Ns Ar 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 +.Ux +OSes) this option should be used with caution. +.It Ar file : Ns Ar path +The first line of +.Ar path +is the password. +If the same +.Ar path +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 path +need not refer to a regular file: +it could, for example, refer to a device or named pipe. +.It Ar fd : Ns Ar 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. +.El +.\" +.\" ASN1PARSE +.\" +.Sh ASN1PARSE +.nr nS 1 +.Nm "openssl asn1parse" +.Bk -words +.Op Fl i +.Op Fl dlimit Ar number +.Op Fl dump +.Op Fl genconf Ar file +.Op Fl genstr Ar str +.Op Fl in Ar file +.Op Fl inform Ar DER | PEM | TXT +.Op Fl length Ar number +.Op Fl noout +.Op Fl offset Ar number +.Op Fl oid Ar file +.Op Fl out Ar file +.Op Fl strparse Ar offset +.Ek +.nr nS 0 +.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 dlimit Ar number +Dump the first +.Ar number +bytes of unknown data in hex form. +.It Fl dump +Dump unknown data in hex form. +.It Fl genconf Ar file , Fl genstr Ar str +Generate encoded data based on string +.Ar str , +file +.Ar file , +or both using +.Xr ASN1_generate_nconf 3 +format. +If only +.Ar file +is present then the string is obtained from the default section +using the name +.Dq asn1 . +The encoded data is passed through the ASN1 parser and printed out as +though it came from a file; +the contents can thus be examined and written to a file using the +.Fl out +option. +.It Fl i +Indents the output according to the +.Qq depth +of the structures. +.It Fl in Ar file +The input file; default is standard input. +.It Fl inform Ar DER | PEM | TXT +The input format. +.Ar DER +.Pq Distinguished Encoding Rules +is binary format and +.Ar PEM +.Pq Privacy Enhanced Mail , +the default, is base64-encoded. +.Ar TXT +is plain text. +.It Fl length Ar number +Number of bytes to parse; default is until end of file. +.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 oid Ar file +A file containing additional object identifiers +.Pq OIDs . +The format of this file is described in the +.Sx ASN1PARSE NOTES +section below. +.It Fl out Ar file +Output file to place the DER-encoded data into. +If this option is not present, no encoded data will be output. +This is most useful when combined with the +.Fl strparse +option. +.It Fl strparse Ar offset +Parse the content octets of the ASN.1 object starting at +.Ar offset . +This option can be used multiple times to +.Qq drill down +into a nested structure. +.El +.Sh ASN1PARSE OUTPUT +The output will typically contain lines like this: +.Bd -literal -offset 2n +0:d=0 hl=4 l= 681 cons: SEQUENCE + +\&..... + +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 + +\&..... +.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 +.Pq tag and length octets +of the current type. +.Cm l=XX +gives the length of the content 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 content octets of this will contain the public key information. +This can be examined using the option +.Fl strparse Cm 229 +to yield: +.Bd -literal + 0:d=0 hl=3 l= 137 cons: SEQUENCE + 3:d=1 hl=3 l= 129 prim: INTEGER :E5D21E1F5C8D208EA7A2166C7FA +F9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A +9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58 +BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9 + 135:d=1 hl=2 l= 3 prim: INTEGER :010001 +.Ed +.Sh ASN1PARSE NOTES +If an OID +.Pq object identifier +is not part of +.Nm OpenSSL Ns Li 's +internal table it will be represented in +numerical form +.Pq 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 +.Qq short name +which is a single word followed by whitespace. +The final column is the rest of the line and is the +.Qq long name . +.Nm asn1parse +displays the long name. +Example: +.Pp +.Dl \&"1.2.3.4 shortname A long name\&" +.Sh ASN1 EXAMPLES +Parse a file: +.Pp +.Dl $ openssl asn1parse -in file.pem +.Pp +Parse a DER file: +.Pp +.Dl $ openssl asn1parse -inform DER -in file.der +.Sh ASN1PARSE BUGS +There should be options to change the format of output lines. +The output of some ASN.1 types is not well handled +.Pq if at all . +.\" +.\" CA +.\" +.Sh CA +.nr nS 1 +.Nm "openssl ca" +.Bk -words +.Op Fl batch +.Op Fl cert Ar file +.Op Fl config Ar file +.Op Fl crl_CA_compromise Ar time +.Op Fl crl_compromise Ar time +.Op Fl crl_hold Ar instruction +.Op Fl crl_reason Ar reason +.Op Fl crldays Ar days +.Op Fl crlexts Ar section +.Op Fl crlhours Ar hours +.Op Fl days Ar arg +.Op Fl enddate Ar date +.Op Fl engine Ar id +.Op Fl extensions Ar section +.Op Fl extfile Ar section +.Op Fl gencrl +.Op Fl in Ar file +.Op Fl infiles +.Op Fl key Ar keyfile +.Op Fl keyfile Ar arg +.Op Fl keyform Ar ENGINE | PEM +.Op Fl md Ar arg +.Op Fl msie_hack +.Op Fl name Ar section +.Op Fl noemailDN +.Op Fl notext +.Op Fl out Ar file +.Op Fl outdir Ar dir +.Op Fl passin Ar arg +.Op Fl policy Ar arg +.Op Fl preserveDN +.Op Fl revoke Ar file +.Op Fl spkac Ar file +.Op Fl ss_cert Ar file +.Op Fl startdate Ar date +.Op Fl status Ar serial +.Op Fl subj Ar arg +.Op Fl updatedb +.Op Fl verbose +.Ek +.nr nS 0 +.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 "XXXX" +.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 cert Ar file +The CA certificate file. +.It Fl config Ar file +Specifies the configuration file to use. +.It Fl days Ar arg +The number of days to certify the certificate for. +.It Fl enddate Ar date +This allows the expiry date to be explicitly set. +The format of the date is YYMMDDHHMMSSZ +.Pq the same as an ASN1 UTCTime structure . +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm ca +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 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, a V1 certificate is created. +If the extension section is present +.Pq 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). +.It Fl in Ar file +An input +.Ar file +containing a single certificate request to be signed by the CA. +.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 key Ar keyfile +The password used to encrypt the private key. +Since on some systems the command line arguments are visible +(e.g.\& +.Ux +with the +.Xr ps 1 +utility) this option should be used with caution. +.It Fl keyfile Ar file +The private key to sign requests with. +.It Fl keyform Ar ENGINE | PEM +Private key file format. +.It Fl md Ar alg +The message digest to use. +Possible values include +.Ar md5 +and +.Ar sha1 . +This option also applies to CRLs. +.It Fl msie_hack +This is a legacy option to make +.Nm ca +work with very old versions of the IE certificate enrollment control +.Qq certenr3 . +It used UniversalStrings for almost everything. +Since the old control has various security bugs, +its use is strongly discouraged. +The newer control +.Qq Xenroll +does not need this option. +.It Fl name Ar section +Specifies the configuration file +.Ar section +to use (overrides +.Cm default_ca +in the +.Cm ca +section). +.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 notext +Don't output the text form of a certificate to the output file. +.It Fl out Ar file +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 file consisting of the +serial number in hex with +.Qq .pem +appended. +.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 policy Ar arg +This option defines the CA +.Qq 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 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 spkac Ar file +A file containing a single Netscape signed public key and challenge, +and additional field values to be signed by the CA. +See the +.Sx SPKAC FORMAT +section for information on the required format. +.It Fl ss_cert Ar file +A single self-signed certificate to be signed by the CA. +.It Fl startdate Ar date +This allows the start date to be explicitly set. +The format of the date is YYMMDDHHMMSSZ +.Pq the same as an ASN1 UTCTime structure . +.It Fl status Ar serial +Show status of certificate with serial number +.Ar serial . +.It Fl updatedb +Update database for expired certificates. +.It Fl verbose +This prints extra details about the operations being performed. +.El +.Sh CRL OPTIONS +.Bl -tag -width "XXXX" +.It Fl crl_CA_compromise Ar time +This is the same as +.Fl crl_compromise , +except the revocation reason is set to CACompromise. +.It Fl crl_compromise Ar time +This sets the revocation reason to keyCompromise and the compromise time to +.Ar time . +.Ar time +should be in GeneralizedTime format, i.e. YYYYMMDDHHMMSSZ. +.It Fl crl_hold Ar instruction +This sets the CRL revocation reason code to certificateHold and the hold +instruction to +.Ar instruction +which must be an OID. +Although any OID can be used, only holdInstructionNone +(the use of which is discouraged by RFC 2459), holdInstructionCallIssuer or +holdInstructionReject will normally be used. +.It Fl crl_reason Ar reason +Revocation reason, where +.Ar reason +is one of: +unspecified, keyCompromise, CACompromise, affiliationChanged, superseded, +cessationOfOperation, certificateHold or removeFromCRL. +The matching of +.Ar reason +is case insensitive. +Setting any revocation reason will make the CRL v2. +In practice, removeFromCRL is not particularly useful because it is only used +in delta CRLs which are not currently implemented. +.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 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 +.Pq 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 +.Pq for example Netscape +can't handle V2 CRLs. +.It Fl crlhours Ar num +The number of hours before the next CRL is due. +.It Fl gencrl +This option generates a CRL based on information in the index file. +.It Fl revoke Ar file +A +.Ar file +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 +.Sq \e +.Pq backslash , +no spaces are skipped. +.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 +.Bl -tag -width Ds -offset indent -compact +.It preserve +.It msie_hack +.El +.Pp +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 +.Pq if any +used. +.Bl -tag -width "XXXX" +.It Ar certificate +The same as +.Fl cert . +It gives the file containing the CA certificate. +Mandatory. +.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 . +.It Ar crl_extensions +The same as +.Fl crlexts . +.It Ar crlnumber +A text file containing the next CRL number to use in hex. +The CRL number will be inserted in the CRLs only if this file exists. +If this file is present, it must contain a valid CRL number. +.It Ar database +The text database file to use. +Mandatory. +This file must be present, though initially it will be empty. +.It Ar default_crl_hours , default_crl_days +The same as the +.Fl crlhours +and +.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_days +The same as the +.Fl days +option. +The number of days to certify a certificate for. +.It Ar default_enddate +The same as the +.Fl enddate +option. +Either this option or +.Ar default_days +.Pq or the command line equivalents +must be present. +.It Ar default_md +The same as the +.Fl md +option. +The message digest to use. +Mandatory. +.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 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 +.Qq 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 name_opt , cert_opt +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 value +.Em ca_default +is 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 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 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 +.Sq = +and the numerical form. +The short and long names are the same when this option is used. +.It Ar policy +The same as +.Fl policy . +Mandatory. +See the +.Sx CA POLICY FORMAT +section for more information. +.It Ar preserve +The same as +.Fl preserveDN . +.It Ar private_key +Same as the +.Fl keyfile +option. +The file containing the CA private key. +Mandatory. +.It Ar serial +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 unique_subject +If the value +.Ar yes +is given, the valid certificate entries in the +database must have unique subjects. +If the value +.Ar no +is given, +several valid certificate entries may have the exact same subject. +The default value is +.Ar yes . +.It Ar x509_extensions +The same as +.Fl extensions . +.El +.Sh CA POLICY FORMAT +The policy section consists of a set of variables corresponding to +certificate DN fields. +If the value is +.Qq match , +then the field value must match the same field in the CA certificate. +If the value is +.Qq supplied , +then it must be present. +If the value is +.Qq 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 +.Sq \&. . +.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, +.Qq 01 +and the empty index file +.Pa demoCA/index.txt . +.Pp +Sign a certificate request: +.Pp +.Dl $ openssl ca -in req.pem -out newcert.pem +.Pp +Sign a certificate request, using CA extensions: +.Pp +.Dl $ openssl ca -in req.pem -extensions v3_ca -out newcert.pem +.Pp +Generate a CRL: +.Pp +.Dl $ openssl ca -gencrl -out crl.pem +.Pp +Sign several requests: +.Pp +.Dl $ openssl ca -infiles req1.pem req2.pem req3.pem +.Pp +Certify a Netscape SPKAC: +.Pp +.Dl $ openssl ca -spkac spkac.txt +.Pp +A sample SPKAC file +.Pq the SPKAC line has been truncated for clarity : +.Bd -literal -offset indent +SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK +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 : +.Bd -literal +\& [ ca ] +\& default_ca = CA_default # The default ca section + +\& [ CA_default ] + +\& dir = ./demoCA # top dir +\& database = $dir/index.txt # index file +\& new_certs_dir = $dir/newcerts # new certs dir + +\& certificate = $dir/cacert.pem # The CA cert +\& serial = $dir/serial # serial no file +\& private_key = $dir/private/cakey.pem# CA private key + +\& default_days = 365 # how long to certify for +\& default_crl_days= 30 # how long before next CRL +\& default_md = md5 # md to use + +\& policy = policy_any # default policy +\& email_in_dn = no # Don't add the email into cert DN + +\& name_opt = ca_default # Subject name display option +\& cert_opt = ca_default # Certificate display option +\& copy_extensions = none #Don't copy extensions from request + +\& [ policy_any ] +\& countryName = supplied +\& stateOrProvinceName = optional +\& organizationName = optional +\& organizationalUnitName = optional +\& commonName = supplied +\& emailAddress = optional +.Ed +.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. +.Bd -literal -offset indent +/etc/ssl/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 +.Ev 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 +V2 CRL features like delta CRLs 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 +.Pq 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 +.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. +.Pp +The +.Ar copy_extensions +option should be used with caution. +If care is not taken, 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 +.D1 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 hVv +.Op Fl ssl3 | tls1 +.Op Ar cipherlist +.Pp +The +.Nm ciphers +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 h , \&? +Print a brief usage message. +.It Fl ssl3 +Only include SSL v3 ciphers. +.It Fl tls1 +Only include TLS v1 ciphers. +.It Fl V +Like +.Fl v , +but include cipher suite codes in output (hex format). +.It Fl v +Verbose option. +List ciphers with a complete description of protocol version +.Pq SSLv3, which 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 v3/TLS v1. +.It Ar cipherlist +A cipher list to convert to a cipher preference list. +If it is not included, 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 +.Sq + +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 +.Sq \&! , +.Sq - , +or +.Sq + . +.Pp +If +.Sq !\& +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 +.Sq - +is used, then the ciphers are deleted from the list, but some or +all of the ciphers can be added again by later options. +.Pp +If +.Sq + +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, 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 "XXXX" +.It Ar DEFAULT +The default cipher list. +This is determined at compile time and is currently +.Ar ALL:!aNULL:!eNULL:!SSLv2 . +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 cipher 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 +.Qq High +encryption cipher suites. +This currently means those with key lengths larger than 128 bits. +.It Ar MEDIUM +.Qq Medium +encryption cipher suites, currently those using 128-bit encryption. +.It Ar LOW +.Qq 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-bit algorithms. +.It Ar EXPORT40 +40-bit export encryption algorithms. +.It Ar eNULL , NULL +The +.Qq 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 +.Qq man in the middle +attack, 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 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 TLSv1 , SSLv3 +TLS v1.0 or SSL v3.0 cipher suites, respectively. +.It Ar DH +Cipher suites using DH, including anonymous DH. +.It Ar ADH +Anonymous DH cipher suites. +.It Ar AES +Cipher suites using AES. +.It Ar 3DES +Cipher suites using triple DES. +.It Ar DES +Cipher suites using DES +.Pq not triple DES . +.It Ar RC4 +Cipher suites using RC4. +.It Ar RC2 +Cipher suites using RC2. +.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. +It should be noted that several cipher suite names do not include the +authentication used, e.g. DES-CBC3-SHA. +In these cases, RSA authentication is used. +.Ss SSL v3.0 cipher suites +.Bd -unfilled -offset indent +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 + +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 + +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 + +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 +.Ss TLS v1.0 cipher suites +.Bd -unfilled -offset indent +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 + +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 + +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 +.Ss AES ciphersuites from RFC 3268, extending TLS v1.0 +.Bd -unfilled -offset indent +TLS_RSA_WITH_AES_128_CBC_SHA AES128-SHA +TLS_RSA_WITH_AES_256_CBC_SHA AES256-SHA + +TLS_DH_DSS_WITH_AES_128_CBC_SHA Not implemented. +TLS_DH_DSS_WITH_AES_256_CBC_SHA Not implemented. +TLS_DH_RSA_WITH_AES_128_CBC_SHA Not implemented. +TLS_DH_RSA_WITH_AES_256_CBC_SHA Not implemented. + +TLS_DHE_DSS_WITH_AES_128_CBC_SHA DHE-DSS-AES128-SHA +TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-DSS-AES256-SHA +TLS_DHE_RSA_WITH_AES_128_CBC_SHA DHE-RSA-AES128-SHA +TLS_DHE_RSA_WITH_AES_256_CBC_SHA DHE-RSA-AES256-SHA + +TLS_DH_anon_WITH_AES_128_CBC_SHA ADH-AES128-SHA +TLS_DH_anon_WITH_AES_256_CBC_SHA ADH-AES256-SHA +.Ed +.Ss GOST ciphersuites from draft-chudov-cryptopro-cptls, extending TLS v1.0 +.Sy Note : +These ciphers require an engine which includes GOST cryptographic +algorithms, such as the +.Dq ccgost +engine, included in the OpenSSL distribution. +.Bd -unfilled -offset indent +TLS_GOSTR341094_WITH_28147_CNT_IMIT GOST94-GOST89-GOST89 +TLS_GOSTR341001_WITH_28147_CNT_IMIT GOST2001-GOST89-GOST89 +TLS_GOSTR341094_WITH_NULL_GOSTR3411 GOST94-NULL-GOST94 +TLS_GOSTR341001_WITH_NULL_GOSTR3411 GOST2001-NULL-GOST94 +.Ed +.Ss Additional Export 1024 and other cipher suites +.Sy Note : +These ciphers can also be used in SSL v3. +.Bd -unfilled -offset indent +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 +.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 +.Dl $ openssl ciphers -v 'ALL:eNULL' +.Pp +Include all ciphers except NULL and anonymous DH then sort by +strength: +.Pp +.Dl $ openssl ciphers -v 'ALL:!ADH:@STRENGTH' +.Pp +Include only 3DES ciphers and then place RSA ciphers last: +.Pp +.Dl $ openssl ciphers -v '3DES:+RSA' +.Pp +Include all RC4 ciphers but leave out those without authentication: +.Pp +.Dl $ openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT' +.Pp +Include all ciphers with RSA authentication but leave out ciphers without +encryption: +.Pp +.Dl $ openssl ciphers -v 'RSA:!COMPLEMENTOFALL' +.Sh CIPHERS HISTORY +The +.Ar COMPLEMENTOFALL +and +.Ar COMPLEMENTOFDEFAULT +selection options were added in +.Nm OpenSSL +0.9.7. +.Pp +The +.Fl V +option of the +.Nm ciphers +command was added in +.Nm OpenSSL +1.0.0. +.\" +.\" CRL +.\" +.Sh CRL +.nr nS 1 +.Nm "openssl crl" +.Bk -words +.Op Fl CAfile Ar file +.Op Fl CApath Ar dir +.Op Fl fingerprint +.Op Fl hash +.Op Fl in Ar file +.Op Fl inform Ar DER | PEM +.Op Fl issuer +.Op Fl lastupdate +.Op Fl nextupdate +.Op Fl noout +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM +.Op Fl text +.Ek +.nr nS 0 +.Pp +The +.Nm crl +command processes CRL files in DER or PEM format. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl CAfile Ar file +Verify the signature on a CRL by looking up the issuing certificate in +.Ar file . +.It Fl CApath Ar directory +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. +.It Fl fingerprint +Print the CRL fingerprint. +.It Fl hash +Output a hash of the issuer name. +This can be used to look up CRLs in a directory by issuer name. +.It Fl in Ar file +This specifies the input file to read from, or standard input if this +option is not specified. +.It Fl inform Ar DER | PEM +This specifies the input format. +.Ar DER +format is a DER-encoded CRL structure. +.Ar PEM +.Pq the default +is a base64-encoded version of the DER form with header and footer lines. +.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 noout +Don't output the encoded version of the CRL. +.It Fl out Ar file +Specifies the output file to write to, or standard output by +default. +.It Fl outform Ar DER | PEM +This specifies the output format; the options have the same meaning as the +.Fl inform +option. +.It Fl text +Print out the CRL in text form. +.El +.Sh CRL NOTES +The PEM CRL format uses the header and footer lines: +.Bd -unfilled -offset indent +-----BEGIN X509 CRL----- +-----END X509 CRL----- +.Ed +.Sh CRL EXAMPLES +Convert a CRL file from PEM to DER: +.Pp +.Dl $ openssl crl -in crl.pem -outform DER -out crl.der +.Pp +Output the text form of a DER-encoded certificate: +.Pp +.Dl $ openssl crl -in crl.der -inform DER -text -noout +.Sh CRL BUGS +Ideally, it should be possible to create a CRL using appropriate options +and files too. +.\" +.\" CRL2PKCS7 +.\" +.Sh CRL2PKCS7 +.nr nS 1 +.Nm "openssl crl2pkcs7" +.Bk -words +.Op Fl certfile Ar file +.Op Fl in Ar file +.Op Fl inform Ar DER | PEM +.Op Fl nocrl +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM +.Ek +.nr nS 0 +.Pp +The +.Nm crl2pkcs7 +command takes an optional CRL and one or more +certificates and converts them into a PKCS#7 degenerate +.Qq certificates only +structure. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl certfile Ar file +Specifies a +.Ar file +containing one or more certificates in 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 from multiple +files. +.It Fl in Ar file +This specifies the input +.Ar file +to read a CRL from, or standard input if this option is not specified. +.It Fl inform Ar DER | PEM +This specifies the CRL input format. +.Ar DER +format is a DER-encoded CRL structure. +.Ar PEM +.Pq the default +is a base64-encoded version of the DER form with header and footer lines. +.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. +.It Fl out Ar file +Specifies the output +.Ar file +to write the PKCS#7 structure to, or standard output by default. +.It Fl outform Ar DER | PEM +This specifies the PKCS#7 structure output format. +.Ar DER +format is a DER-encoded PKCS#7 structure. +.Ar PEM +.Pq the default +is a base64-encoded version of the DER form with header and footer lines. +.El +.Sh CRL2PKCS7 EXAMPLES +Create a PKCS#7 structure from a certificate and CRL: +.Pp +.Dl $ openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem +.Pp +Create a PKCS#7 structure in DER format with no CRL from several +different certificates: +.Bd -literal -offset indent +$ openssl crl2pkcs7 -nocrl -certfile newcert.pem \e + -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 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 +.nr nS 1 +.Nm "openssl dgst" +.Bk -words +.Oo +.Fl dss1 | md2 | md4 | md5 | +.Fl ripemd160 | sha | sha1 +.Oc +.Op Fl binary +.Op Fl cd +.Op Fl engine Ar id +.Op Fl hex +.Op Fl hmac Ar key +.Op Fl keyform Ar ENGINE | PEM +.Op Fl mac Ar algorithm +.Op Fl macopt Ar nm : Ns Ar v +.Op Fl out Ar file +.Op Fl passin Ar arg +.Op Fl prverify Ar file +.Op Fl sign Ar file +.Op Fl signature Ar file +.Op Fl sigopt Ar nm : Ns Ar v +.Op Fl verify Ar file +.Op Ar +.Ek +.nr nS 0 +.Pp +.Nm openssl +.Cm md2 | md4 | md5 | +.Cm ripemd160 | sha | sha1 +.Op Fl c +.Op Fl d +.Op Ar +.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 binary +Output the digest or signature in binary form. +.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 engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm dgst +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. +This engine is not used as a source for digest algorithms +unless it is also specified in the configuration file. +.It Fl hex +Digest is to be output as a hex dump. +This is the default case for a +.Qq normal +digest as opposed to a digital signature. +.It Fl hmac Ar key +Create a hashed MAC using +.Ar key . +.It Fl keyform Ar ENGINE | PEM +Specifies the key format to sign the digest with. +.It Fl mac Ar algorithm +Create a keyed Message Authentication Code (MAC). +The most popular MAC algorithm is HMAC (hash-based MAC), +but there are other MAC algorithms which are not based on hash. +MAC keys and other options should be set via the +.Fl macopt +parameter. +.It Fl macopt Ar nm : Ns Ar v +Passes options to the MAC algorithm, specified by +.Fl mac . +The following options are supported by HMAC: +.Bl -tag -width Ds +.It Ar key : Ns Ar string +Specifies the MAC key as an alphanumeric string +(use if the key contain printable characters only). +String length must conform to any restrictions of the MAC algorithm. +.It Ar hexkey : Ns Ar string +Specifies the MAC key in hexadecimal form (two hex digits per byte). +Key length must conform to any restrictions of the MAC algorithm. +.El +.It Fl out Ar file +The file to output to, or standard output by default. +.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 prverify Ar file +Verify the signature using the private key in +.Ar file . +The output is either +.Qq Verification OK +or +.Qq Verification Failure . +.It Fl sign Ar file +Digitally sign the digest using the private key in +.Ar file . +.It Fl signature Ar file +The actual signature to verify. +.It Fl sigopt Ar nm : Ns Ar v +Pass options to the signature algorithm during sign or verify operations. +The names and values of these options are algorithm-specific. +.It Fl verify Ar file +Verify the signature using the public key in +.Ar file . +The output is either +.Qq Verification OK +or +.Qq Verification Failure . +.It Ar +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, 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 +.nr nS 1 +.Nm "openssl dhparam" +.Bk -words +.Op Fl 2 | 5 +.Op Fl C +.Op Fl check +.Op Fl dsaparam +.Op Fl engine Ar id +.Op Fl in Ar file +.Op Fl inform Ar DER | PEM +.Op Fl noout +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM +.Op Fl text +.Op Ar numbits +.Ek +.nr nS 0 +.Pp +The +.Nm dhparam +command is used to manipulate DH parameter files. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl 2 , 5 +The generator to use, either 2 or 5. +2 is the default. +If present, the input file is ignored and parameters are generated instead. +.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. +.It Fl check +Check the DH parameters. +.It Fl dsaparam +If this option is used, DSA rather than DH parameters are read or created; +they are converted to DH format. +Otherwise, +.Qq strong +primes +.Pq 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 engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm dhparam +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 in Ar file +This specifies the input +.Ar file +to read parameters from, or standard input if this option is not specified. +.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 noout +This option inhibits the output of the encoded version of the parameters. +.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, a value of 512 is used. +If this value is present, the input file is ignored and +parameters are generated instead. +.It Fl out Ar file +This specifies the output +.Ar file +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 outform Ar DER | PEM +This specifies the output format; the options have the same meaning as the +.Fl inform +option. +.It Fl text +This option prints out the DH parameters in human readable form. +.El +.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 +PEM format DH parameters use the header and footer lines: +.Bd -unfilled -offset indent +-----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 +.nr nS 1 +.Nm "openssl dsa" +.Bk -words +.Oo +.Fl aes128 | aes192 | aes256 | +.Fl des | des3 +.Oc +.Op Fl engine Ar id +.Op Fl in Ar file +.Op Fl inform Ar DER | PEM +.Op Fl modulus +.Op Fl noout +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM +.Op Fl passin Ar arg +.Op Fl passout Ar arg +.Op Fl pubin +.Op Fl pubout +.Op Fl text +.Ek +.nr nS 0 +.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 Xo +.Fl aes128 | aes192 | aes256 | +.Fl des | des3 +.Xc +These options encrypt the private key with the AES, DES, or the triple DES +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 PEM format output files. +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm dsa +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 in Ar file +This specifies the input +.Ar file +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 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 +.Pq currently zero , +P, Q, G, +and 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 modulus +This option prints out the value of the public key component of the key. +.It Fl noout +This option prevents output of the encoded version of the key. +.It Fl out Ar file +This specifies the output +.Ar file +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 outform Ar DER | PEM +This specifies the output format; the options have the same meaning as the +.Fl inform +option. +.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 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 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. +.It Fl text +Prints out the public/private key components and parameters. +.El +.Sh DSA NOTES +The PEM private key format uses the header and footer lines: +.Bd -unfilled -offset indent +-----BEGIN DSA PRIVATE KEY----- +-----END DSA PRIVATE KEY----- +.Ed +.Pp +The PEM public key format uses the header and footer lines: +.Bd -unfilled -offset indent +-----BEGIN PUBLIC KEY----- +-----END PUBLIC KEY----- +.Ed +.Sh DSA EXAMPLES +To remove the pass phrase on a DSA private key: +.Pp +.Dl $ openssl dsa -in key.pem -out keyout.pem +.Pp +To encrypt a private key using triple DES: +.Pp +.Dl $ openssl dsa -in key.pem -des3 -out keyout.pem +.Pp +To convert a private key from PEM to DER format: +.Pp +.Dl $ openssl dsa -in key.pem -outform DER -out keyout.der +.Pp +To print out the components of a private key to standard output: +.Pp +.Dl $ openssl dsa -in key.pem -text -noout +.Pp +To just output the public part of a private key: +.Pp +.Dl $ openssl dsa -in key.pem -pubout -out pubkey.pem +.\" +.\" DSAPARAM +.\" +.Sh DSAPARAM +.nr nS 1 +.Nm "openssl dsaparam" +.Bk -words +.Op Fl C +.Op Fl engine Ar id +.Op Fl genkey +.Op Fl in Ar file +.Op Fl inform Ar DER | PEM +.Op Fl noout +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM +.Op Fl text +.Op Ar numbits +.Ek +.nr nS 0 +.Pp +The +.Nm dsaparam +command is used to manipulate or generate DSA parameter files. +.Pp +The options are as follows: +.Bl -tag -width Ds +.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 engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm dsaparam +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 genkey +This option will generate a DSA either using the specified or generated +parameters. +.It Fl in Ar file +This specifies the input +.Ar file +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 inform Ar DER | PEM +This specifies the input format. +The +.Ar DER +argument uses an ASN1 DER-encoded form compatible with RFC 2459 +.Pq 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 noout +This option inhibits the output of the encoded version of the parameters. +.It Ar numbits +This option specifies that a parameter set should be generated of size +.Ar numbits . +If this option is included, the input file +.Pq if any +is ignored. +.It Fl out Ar file +This specifies the output +.Ar file +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 outform Ar DER | PEM +This specifies the output format; the options have the same meaning as the +.Fl inform +option. +.It Fl text +This option prints out the DSA parameters in human readable form. +.El +.Sh DSAPARAM NOTES +PEM format DSA parameters use the header and footer lines: +.Bd -unfilled -offset indent +-----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. +.\" +.\" EC +.\" +.Sh EC +.nr nS 1 +.Nm "openssl ec" +.Bk -words +.Op Fl conv_form Ar arg +.Op Fl des +.Op Fl des3 +.Op Fl engine Ar id +.Op Fl in Ar file +.Op Fl inform Ar DER | PEM +.Op Fl noout +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM +.Op Fl param_enc Ar arg +.Op Fl param_out +.Op Fl passin Ar arg +.Op Fl passout Ar arg +.Op Fl pubin +.Op Fl pubout +.Op Fl text +.Ek +.nr nS 0 +.Pp +The +.Nm ec +command processes EC keys. +They can be converted between various +forms and their components printed out. +Note: +.Nm OpenSSL +uses the private key format specified in +.Dq SEC 1: Elliptic Curve Cryptography +.Pq Lk http://www.secg.org/ . +To convert an +.Nm OpenSSL +EC private key into the PKCS#8 private key format use the +.Nm pkcs8 +command. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl conv_form Ar arg +This specifies how the points on the elliptic curve are converted +into octet strings. +Possible values are: +.Cm compressed +(the default value), +.Cm uncompressed , +and +.Cm hybrid . +For more information regarding +the point conversion forms please read the X9.62 standard. +Note: +Due to patent issues the +.Cm compressed +option is disabled by default for binary curves +and can be enabled by defining the preprocessor macro +.Ar OPENSSL_EC_BIN_PT_COMP +at compile time. +.It Fl des | des3 +These options encrypt the private key with the DES, triple DES, or +any other cipher supported by +.Nm OpenSSL +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 ec +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 PEM format output files. +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm ec +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 in Ar file +This specifies the input 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 inform Ar DER | PEM +This specifies the input format. +DER with a private key uses +an ASN.1 DER-encoded SEC1 private key. +When used with a public key it +uses the SubjectPublicKeyInfo structure as specified in RFC 3280. +PEM 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 noout +Prevents output of the encoded version of the key. +.It Fl out Ar file +Specifies the output filename to write a key to, +or standard output if none is 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 outform Ar DER | PEM +This specifies the output format. +The options have the same meaning as the +.Fl inform +option. +.It Fl param_enc Ar arg +This specifies how the elliptic curve parameters are encoded. +Possible value are: +.Cm named_curve , +i.e. the EC parameters are specified by an OID; or +.Cm explicit , +where the EC parameters are explicitly given +(see RFC 3279 for the definition of the EC parameter structures). +The default value is +.Cm named_curve . +Note: the +.Cm implicitlyCA +alternative, +as specified in RFC 3279, +is currently not implemented in +.Nm OpenSSL . +.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 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 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 is output instead. +This option is automatically set if the input is a public key. +.It Fl text +Prints out the public/private key components and parameters. +.El +.Sh EC NOTES +The PEM private key format uses the header and footer lines: +.Bd -literal -offset indent +-----BEGIN EC PRIVATE KEY----- +-----END EC PRIVATE KEY----- +.Ed +.Pp +The PEM public key format uses the header and footer lines: +.Bd -literal -offset indent +-----BEGIN PUBLIC KEY----- +-----END PUBLIC KEY----- +.Ed +.Sh EC EXAMPLES +To encrypt a private key using triple DES: +.Bd -literal -offset indent +$ openssl ec -in key.pem -des3 -out keyout.pem +.Ed +.Pp +To convert a private key from PEM to DER format: +.Bd -literal -offset indent +$ openssl ec -in key.pem -outform DER -out keyout.der +.Ed +.Pp +To print out the components of a private key to standard output: +.Bd -literal -offset indent +$ openssl ec -in key.pem -text -noout +.Ed +.Pp +To just output the public part of a private key: +.Bd -literal -offset indent +$ openssl ec -in key.pem -pubout -out pubkey.pem +.Ed +.Pp +To change the parameter encoding to +.Cm explicit : +.Bd -literal -offset indent +$ openssl ec -in key.pem -param_enc explicit -out keyout.pem +.Ed +.Pp +To change the point conversion form to +.Cm compressed : +.Bd -literal -offset indent +$ openssl ec -in key.pem -conv_form compressed -out keyout.pem +.Ed +.Sh EC HISTORY +The +.Nm ec +command was first introduced in +.Nm OpenSSL +0.9.8. +.Sh EC AUTHORS +.An Nils Larsch . +.\" +.\" ECPARAM +.\" +.Sh ECPARAM +.nr nS 1 +.Nm "openssl ecparam" +.Bk -words +.Op Fl C +.Op Fl check +.Op Fl conv_form Ar arg +.Op Fl engine Ar id +.Op Fl genkey +.Op Fl in Ar file +.Op Fl inform Ar DER | PEM +.Op Fl list_curves +.Op Fl name Ar arg +.Op Fl no_seed +.Op Fl noout +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM +.Op Fl param_enc Ar arg +.Op Fl text +.Ek +.nr nS 0 +.Pp +This command is used to manipulate or generate EC parameter files. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl C +Convert the EC parameters into C code. +The parameters can then be loaded by calling the +.Fn get_ec_group_XXX +function. +.It Fl check +Validate the elliptic curve parameters. +.It Fl conv_form Ar arg +Specify how the points on the elliptic curve are converted +into octet strings. +Possible values are: +.Cm compressed +(the default value), +.Cm uncompressed , +and +.Cm hybrid . +For more information regarding +the point conversion forms please read the X9.62 standard. +Note: +Due to patent issues the +.Cm compressed +option is disabled by default for binary curves +and can be enabled by defining the preprocessor macro +.Ar OPENSSL_EC_BIN_PT_COMP +at compile time. +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm ecparam +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 genkey +Generate an EC private key using the specified parameters. +.It Fl in Ar file +Specify the input filename to read parameters from or standard input if +this option is not specified. +.It Fl inform Ar DER | PEM +Specify the input format. +DER uses an ASN.1 DER-encoded +form compatible with RFC 3279 EcpkParameters. +PEM is the default format: +it consists of the DER format base64 encoded with additional +header and footer lines. +.It Fl list_curves +Print out a list of all +currently implemented EC parameter names and exit. +.It Fl name Ar arg +Use the EC parameters with the specified 'short' name. +Use +.Fl list_curves +to get a list of all currently implemented EC parameters. +.It Fl no_seed +Inhibit that the 'seed' for the parameter generation +is included in the ECParameters structure (see RFC 3279). +.It Fl noout +Inhibit the output of the encoded version of the parameters. +.It Fl out Ar file +Specify the output filename parameters are written 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 outform Ar DER | PEM +Specify the output format; +the parameters have the same meaning as the +.Fl inform +option. +.It Fl param_enc Ar arg +This specifies how the elliptic curve parameters are encoded. +Possible value are: +.Cm named_curve , +i.e. the EC parameters are specified by an OID, or +.Cm explicit , +where the EC parameters are explicitly given +(see RFC 3279 for the definition of the EC parameter structures). +The default value is +.Cm named_curve . +Note: the +.Cm implicitlyCA +alternative, as specified in RFC 3279, +is currently not implemented in +.Nm OpenSSL . +.It Fl text +Print out the EC parameters in human readable form. +.El +.Sh ECPARAM NOTES +PEM format EC parameters use the header and footer lines: +.Bd -literal -offset indent +-----BEGIN EC PARAMETERS----- +-----END EC PARAMETERS----- +.Ed +.Pp +.Nm OpenSSL +is currently not able to generate new groups and therefore +.Nm ecparam +can only create EC parameters from known (named) curves. +.Sh ECPARAM EXAMPLES +To create EC parameters with the group 'prime192v1': +.Bd -literal -offset indent +$ openssl ecparam -out ec_param.pem -name prime192v1 +.Ed +.Pp +To create EC parameters with explicit parameters: +.Bd -literal -offset indent +$ openssl ecparam -out ec_param.pem -name prime192v1 \e + -param_enc explicit +.Ed +.Pp +To validate given EC parameters: +.Bd -literal -offset indent +$ openssl ecparam -in ec_param.pem -check +.Ed +.Pp +To create EC parameters and a private key: +.Bd -literal -offset indent +$ openssl ecparam -out ec_key.pem -name prime192v1 -genkey +.Ed +.Pp +To change the point encoding to 'compressed': +.Bd -literal -offset indent +$ openssl ecparam -in ec_in.pem -out ec_out.pem \e + -conv_form compressed +.Ed +.Pp +To print out the EC parameters to standard output: +.Bd -literal -offset indent +$ openssl ecparam -in ec_param.pem -noout -text +.Ed +.Sh ECPARAM HISTORY +The +.Nm ecparam +command was first introduced in +.Nm OpenSSL +0.9.8. +.Sh ECPARAM AUTHORS +.An Nils Larsch . +.\" +.\" ENC +.\" +.Sh ENC +.nr nS 1 +.Nm "openssl enc" +.Bk -words +.Fl ciphername +.Op Fl AadePp +.Op Fl base64 +.Op Fl bufsize Ar number +.Op Fl debug +.Op Fl engine Ar id +.Op Fl in Ar file +.Op Fl iv Ar IV +.Op Fl K Ar key +.Op Fl k Ar password +.Op Fl kfile Ar file +.Op Fl md Ar digest +.Op Fl none +.Op Fl nopad +.Op Fl nosalt +.Op Fl out Ar file +.Op Fl pass Ar arg +.Op Fl S Ar salt +.Op Fl salt +.Ek +.nr nS 0 +.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 A +If the +.Fl a +option is set, then base64 process the data on one line. +.It Fl a , base64 +Base64 process the data. +This means that if encryption is taking place, the data is base64-encoded +after encryption. +If decryption is set, the input data is base64 decoded before +being decrypted. +.It Fl bufsize Ar number +Set the buffer size for I/O. +.It Fl d +Decrypt the input data. +.It Fl debug +Debug the BIOs used for I/O. +.It Fl e +Encrypt the input data: this is the default. +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm enc +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 in Ar file +The input +.Ar file ; +standard input by default. +.It Fl iv Ar IV +The actual +.Ar IV +.Pq initialisation vector +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 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 be 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 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 file +Read the password to derive the key from the first line of +.Ar file . +This is for compatibility with previous versions of +.Nm OpenSSL . +Superseded by the +.Fl pass +option. +.It Fl md Ar digest +Use +.Ar digest +to create a key from a pass phrase. +.Ar digest +may be one of +.Dq md2 , +.Dq md5 , +.Dq sha , +or +.Dq sha1 . +.It Fl none +Use NULL cipher (no encryption or decryption of input). +.It Fl nopad +Disable standard block padding. +.It Fl nosalt +Don't use a +.Ar salt +in the key derivation routines. +This option should +.Em NEVER +be used unless compatibility with previous versions of +.Nm OpenSSL +or +.Nm SSLeay +is required. +.It Fl out Ar file +The output +.Ar file , +standard output by default. +.It Fl P +Print out the +.Ar salt , +.Ar key , +and +.Ar IV +used, then immediately exit; +don't do any encryption or decryption. +.It Fl p +Print out the +.Ar salt , +.Ar key , +and +.Ar IV +used. +.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 S Ar salt +The actual +.Ar salt +to use: +this must be represented as a string comprised only of hex digits. +.It Fl salt +Use a +.Ar salt +in the key derivation routines. +This is the default. +.El +.Sh ENC NOTES +The program can be called either as +.Nm openssl ciphername +or +.Nm openssl enc -ciphername . +But the first form doesn't work with engine-provided ciphers, +because this form is processed before the +configuration file is read and any engines loaded. +.Pp +Engines which provide entirely new encryption algorithms +should be configured in the configuration file. +Engines, specified on the command line using the +.Fl engine +option, +can only be used for hardware-assisted implementations of ciphers, +supported by +.Nm OpenSSL +core, or by other engines specified in the configuration file. +.Pp +When +.Nm enc +lists supported ciphers, +ciphers provided by engines specified in the configuration files +are listed too. +.Pp +A password will be prompted for to derive the +.Ar key +and +.Ar IV +if necessary. +.Pp +The +.Fl nosalt +option should +.Em NEVER +be used unless compatibility with previous versions of +.Nm OpenSSL +or +.Nm SSLeay +is required. +.Pp +With the +.Fl nosalt +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 salt +the same password always generates the same encryption key. +When the salt +is being used the first eight bytes of the encrypted data are reserved +for the 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, 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 -unfilled -offset indent +aes-[128|192|256]-cbc 128/192/256 bit AES in CBC mode +aes-[128|192|256] Alias for aes-[128|192|256]-cbc +aes-[128|192|256]-cfb 128/192/256 bit AES in 128 bit CFB mode +aes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode +aes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode +aes-[128|192|256]-ecb 128/192/256 bit AES in ECB mode +aes-[128|192|256]-ofb 128/192/256 bit AES in OFB mode + +base64 Base 64 + +bf Alias for bf-cbc +bf-cbc Blowfish in CBC mode +bf-cfb Blowfish in CFB mode +bf-ecb Blowfish in ECB mode +bf-ofb Blowfish in OFB mode + +cast Alias for cast-cbc +cast-cbc CAST in CBC mode +cast5-cbc CAST5 in CBC mode +cast5-cfb CAST5 in CFB mode +cast5-ecb CAST5 in ECB mode +cast5-ofb CAST5 in OFB mode + +des Alias for des-cbc +des-cbc DES in CBC mode +des-cfb DES in CBC mode +des-ecb DES in ECB mode +des-ofb DES in OFB mode + +des-ede Two key triple DES EDE in ECB mode +des-ede-cbc Two key triple DES EDE in CBC mode +des-ede-cfb Two key triple DES EDE in CFB mode +des-ede-ofb Two key triple DES EDE in OFB mode + +des3 Alias for des-ede3-cbc +des-ede3 Three key triple DES EDE in ECB mode +des-ede3-cbc Three key triple DES EDE in CBC mode +des-ede3-cfb Three key triple DES EDE CFB mode +des-ede3-ofb Three key triple DES EDE in OFB mode + +desx DESX algorithm + +rc2 Alias for rc2-cbc +rc2-cbc 128-bit RC2 in CBC mode +rc2-cfb 128-bit RC2 in CFB mode +rc2-ecb 128-bit RC2 in ECB mode +rc2-ofb 128-bit RC2 in OFB mode +rc2-64-cbc 64-bit RC2 in CBC mode +rc2-40-cbc 40-bit RC2 in CBC mode + +rc4 128-bit RC4 +rc4-40 40-bit RC4 +.Ed +.Sh ENC EXAMPLES +Just base64 encode a binary file: +.Pp +.Dl $ openssl base64 -in file.bin -out file.b64 +.Pp +Decode the same file: +.Pp +.Dl $ openssl base64 -d -in file.b64 -out file.bin +.Pp +Encrypt a file using triple DES in CBC mode using a prompted password: +.Pp +.Dl $ openssl des3 -salt -in file.txt -out file.des3 +.Pp +Decrypt a file using a supplied password: +.Pp +.Dl "$ openssl des3 -d -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 +.Dl $ openssl bf -a -salt -in file.txt -out file.bf +.Pp +Base64 decode a file then decrypt it: +.Pp +.Dl "$ openssl bf -d -a -in file.bf -out file.txt" +.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. +.\" +.\" ENGINE +.\" +.Sh ENGINE +.Nm openssl engine +.Op Fl ctv +.Op Fl post Ar cmd +.Op Fl pre Ar cmd +.Op Ar engine ... +.Pp +The +.Nm engine +command provides loadable module information and manipulation +of various engines. +Any options are applied to all engines supplied on the command line, +or all supported engines if none are specified. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl c +For each engine, also list the capabilities. +.It Fl post Ar cmd +Run command +.Ar cmd +against the engine after loading it +(only used if +.Fl t +is also provided). +.It Fl pre Ar cmd +Run command +.Ar cmd +against the engine before any attempts +to load it +(only used if +.Fl t +is also provided). +.It Fl t +For each engine, check that they are really available. +.Fl tt +will display an error trace for unavailable engines. +.It Fl v +Verbose mode. +For each engine, list its 'control commands'. +.Fl vv +will additionally display each command's description. +.Fl vvv +will also add the input flags for each command. +.Fl vvvv +will also show internal input flags. +.El +.\" +.\" ERRSTR +.\" +.Sh ERRSTR +.Nm openssl errstr +.Op Fl stats +.Ar errno ... +.Pp +The +.Nm errstr +command performs error number to error string conversion, +generating a human-readable string representing the error code +.Ar errno . +The string is obtained through the +.Xr ERR_error_string_n 3 +function and has the following format: +.Pp +.Dl error:[error code]:[library name]:[function name]:[reason string] +.Pp +.Bq error code +is an 8-digit hexadecimal number. +The remaining fields +.Bq library name , +.Bq function name , +and +.Bq reason string +are all ASCII text. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl stats +Print debugging statistics about various aspects of the hash table. +.El +.Sh ERRSTR EXAMPLES +The following error code: +.Pp +.Dl 27594:error:2006D080:lib(32):func(109):reason(128):bss_file.c:107: +.Pp +\&...can be displayed with: +.Pp +.Dl $ openssl errstr 2006D080 +.Pp +\&...to produce the error message: +.Pp +.Dl error:2006D080:BIO routines:BIO_new_file:no such file +.\" +.\" GENDH +.\" +.Sh GENDH +Generation of Diffie-Hellman Parameters. +Replaced by +.Nm dhparam . +See +.Sx DHPARAM +above. +.\" +.\" GENDSA +.\" +.Sh GENDSA +.nr nS 1 +.Nm "openssl gendsa" +.Bk -words +.Oo +.Fl aes128 | aes192 | aes256 | +.Fl des | des3 +.Oc +.Op Fl engine Ar id +.Op Fl out Ar file +.Op Ar paramfile +.Ek +.nr nS 0 +.Pp +The +.Nm gendsa +command generates a DSA private key from a DSA parameter file +(which will typically be generated by the +.Nm openssl dsaparam +command). +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Xo +.Fl aes128 | aes192 | aes256 | +.Fl des | des3 +.Xc +These options encrypt the private key with the AES, DES, +or the triple DES ciphers, respectively, before outputting it. +A pass phrase is prompted for. +If none of these options are specified, no encryption is used. +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm gendsa +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 out Ar file +The output +.Ar file . +If this argument is not specified, standard output is used. +.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. +.El +.Sh GENDSA NOTES +DSA key generation is little more than random number generation so it is +much quicker than RSA key generation, for example. +.\" +.\" GENPKEY +.\" +.Sh GENPKEY +.nr nS 1 +.Nm "openssl genpkey" +.Bk -words +.Op Fl algorithm Ar alg +.Op Ar cipher +.Op Fl engine Ar id +.Op Fl genparam +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM +.Op Fl paramfile Ar file +.Op Fl pass Ar arg +.Op Fl pkeyopt Ar opt : Ns Ar value +.Op Fl text +.Ek +.nr nS 0 +.Pp +The +.Nm genpkey +command generates private keys. +The use of this +program is encouraged over the algorithm specific utilities +because additional algorithm options +and engine-provided algorithms can be used. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl algorithm Ar alg +The public key algorithm to use, +such as RSA, DSA, or DH. +If used this option must precede any +.Fl pkeyopt +options. +The options +.Fl paramfile +and +.Fl algorithm +are mutually exclusive. +.It Ar cipher +Encrypt the private key with the supplied cipher. +Any algorithm name accepted by +.Fn EVP_get_cipherbyname +is acceptable, such as +.Cm des3 . +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm genpkey +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 genparam +Generate a set of parameters instead of a private key. +If used this option must precede any +.Fl algorithm , +.Fl paramfile , +or +.Fl pkeyopt +options. +.It Fl out Ar file +The output filename. +If this argument is not specified then standard output is used. +.It Fl outform Ar DER | PEM +This specifies the output format, DER or PEM. +.It Fl paramfile Ar file +Some public key algorithms generate a private key based on a set of parameters. +They can be supplied using this option. +If this option is used the public key +algorithm used is determined by the parameters. +If used this option must precede any +.Fl pkeyopt +options. +The options +.Fl paramfile +and +.Fl algorithm +are mutually exclusive. +.It Fl pass 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 pkeyopt Ar opt : Ns Ar value +Set the public key algorithm option +.Ar opt +to +.Ar value . +The precise set of options supported +depends on the public key algorithm used and its implementation. +See +.Sx GENPKEY KEY GENERATION OPTIONS +below for more details. +.It Fl text +Print an (unencrypted) text representation of private and public keys and +parameters along with the DER or PEM structure. +.El +.Sh GENPKEY KEY GENERATION OPTIONS +The options supported by each algorithm +and indeed each implementation of an algorithm can vary. +The options for the +.Nm OpenSSL +implementations are detailed below. +.Bl -tag -width Ds -offset indent +.It rsa_keygen_bits : Ns Ar numbits +(RSA) +The number of bits in the generated key. +If not specified 2048 is used. +.It rsa_keygen_pubexp : Ns Ar value +(RSA) +The RSA public exponent value. +This can be a large decimal or hexadecimal value if preceded by 0x. +The default value is 65537. +.It dsa_paramgen_bits : Ns Ar numbits +(DSA) +The number of bits in the generated parameters. +If not specified 1024 is used. +.It dh_paramgen_prime_len : Ns Ar numbits +(DH) +The number of bits in the prime parameter +.Ar p . +.It dh_paramgen_generator : Ns Ar value +(DH) +The value to use for the generator +.Ar g . +.It ec_paramgen_curve : Ns Ar curve +(EC) +The EC curve to use. +.El +.Sh GENPKEY EXAMPLES +Generate an RSA private key using default parameters: +.Bd -literal -offset indent +$ openssl genpkey -algorithm RSA -out key.pem +.Ed +.Pp +Encrypt and output a private key using 128-bit AES and the passphrase "hello": +.Bd -literal -offset indent +$ openssl genpkey -algorithm RSA -out key.pem \e + -aes-128-cbc -pass pass:hello +.Ed +.Pp +Generate a 2048-bit RSA key using 3 as the public exponent: +.Bd -literal -offset indent +$ openssl genpkey -algorithm RSA -out key.pem \e + -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:3 +.Ed +.Pp +Generate 1024-bit DSA parameters: +.Bd -literal -offset indent +$ openssl genpkey -genparam -algorithm DSA \e + -out dsap.pem -pkeyopt dsa_paramgen_bits:1024 +.Ed +.Pp +Generate a DSA key from parameters: +.Bd -literal -offset indent +$ openssl genpkey -paramfile dsap.pem -out dsakey.pem +.Ed +.Pp +Generate 1024-bit DH parameters: +.Bd -literal -offset indent +$ openssl genpkey -genparam -algorithm DH \e + -out dhp.pem -pkeyopt dh_paramgen_prime_len:1024 +.Ed +.Pp +Generate a DH key from parameters: +.Bd -literal -offset indent +$ openssl genpkey -paramfile dhp.pem -out dhkey.pem +.Ed +.\" +.\" GENRSA +.\" +.Sh GENRSA +.nr nS 1 +.Nm "openssl genrsa" +.Bk -words +.Op Fl 3 | f4 +.Oo +.Fl aes128 | aes192 | aes256 | +.Fl des | des3 +.Oc +.Op Fl engine Ar id +.Op Fl out Ar file +.Op Fl passout Ar arg +.Op Ar numbits +.Ek +.nr nS 0 +.Pp +The +.Nm genrsa +command generates an RSA private key. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl 3 | f4 +The public exponent to use, either 3 or 65537. +The default is 65537. +.It Xo +.Fl aes128 | aes192 | aes256 | +.Fl des | des3 +.Xc +These options encrypt the private key with the AES, DES, +or the triple DES ciphers, respectively, before outputting it. +If none of these options are 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 Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm genrsa +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 out Ar file +The output +.Ar file . +If this argument is not specified, 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 Ar numbits +The size of the private key to generate in bits. +This must be the last option specified. +The default is 2048. +.El +.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 +.Sq \&. +represents each number which has passed an initial sieve test; +.Sq + +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 +.Pq 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 +.Pq typically 2048 bits . +.\" +.\" NSEQ +.\" +.Sh NSEQ +.Nm openssl nseq +.Op Fl in Ar file +.Op Fl out Ar file +.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 file +This specifies the input +.Ar file +to read, or standard input if this option is not specified. +.It Fl out Ar file +Specifies the output +.Ar file , +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 -offset indent +$ openssl nseq -in nseq.pem -out certs.pem +.Ed +.Pp +Create a Netscape certificate sequence: +.Bd -literal -offset indent +$ openssl nseq -in certs.pem -toseq -out nseq.pem +.Ed +.Sh NSEQ NOTES +The PEM-encoded form uses the same headers and footers as a certificate: +.Bd -unfilled -offset indent +-----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 the Netscape certificate server, for example. +.Sh NSEQ BUGS +This program needs a few more options, +like allowing DER or PEM input and output files +and allowing multiple certificate files to be used. +.\" +.\" OCSP +.\" +.Sh OCSP +.nr nS 1 +.Nm "openssl ocsp" +.Bk -words +.Op Fl CA Ar file +.Op Fl CAfile Ar file +.Op Fl CApath Ar directory +.Op Fl cert Ar file +.Op Fl dgst Ar alg +.Oo +.Fl host +.Ar hostname : Ns Ar port +.Oc +.Op Fl index Ar indexfile +.Op Fl issuer Ar file +.Op Fl ndays Ar days +.Op Fl nmin Ar minutes +.Op Fl no_cert_checks +.Op Fl no_cert_verify +.Op Fl no_certs +.Op Fl no_chain +.Op Fl no_intern +.Op Fl no_nonce +.Op Fl no_signature_verify +.Op Fl nonce +.Op Fl noverify +.Op Fl nrequest Ar number +.Op Fl out Ar file +.Op Fl path Ar path +.Op Fl port Ar portnum +.Op Fl req_text +.Op Fl reqin Ar file +.Op Fl reqout Ar file +.Op Fl resp_key_id +.Op Fl resp_no_certs +.Op Fl resp_text +.Op Fl respin Ar file +.Op Fl respout Ar file +.Op Fl rkey Ar file +.Op Fl rother Ar file +.Op Fl rsigner Ar file +.Op Fl serial Ar number +.Op Fl sign_other Ar file +.Op Fl signer Ar file +.Op Fl signkey Ar file +.Op Fl status_age Ar age +.Op Fl text +.Op Fl trust_other +.Op Fl url Ar responder_url +.Op Fl VAfile Ar file +.Op Fl validity_period Ar nsec +.Op Fl verify_other Ar file +.Ek +.nr nS 0 +.Pp +The Online Certificate Status Protocol +.Pq OCSP +enables applications to determine the +.Pq revocation +state of an identified certificate +.Pq 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 CAfile Ar file , Fl CApath Ar directory +.Ar file +or +.Ar path +containing trusted CA certificates. +These are used to verify the signature on the OCSP response. +.It Fl cert Ar file +Add the certificate +.Ar file +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 dgst Ar alg +Sets the digest algorithm to use for certificate identification +in the OCSP request. +By default SHA-1 is used. +.It Xo +.Fl host Ar hostname : Ns Ar port , +.Fl path Ar path +.Xc +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 +.Sq / +by default. +.It Fl issuer Ar file +This specifies the current issuer certificate. +This option can be used multiple times. +The certificate specified in +.Ar file +must be in PEM format. +This option +.Em must +come before any +.Fl cert +options. +.It Fl no_cert_checks +Don't perform any additional checks on the OCSP response signer's certificate. +That is, do not make any checks to see if the signer's certificate is +authorised to provide the necessary status information: +as a result this option should only be used for testing purposes. +.It Fl no_cert_verify +Don't verify the OCSP response signer's 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_certs +Don't include any certificates in signed request. +.It Fl no_chain +Do not use certificates in the response as additional untrusted CA +certificates. +.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_other +or +.Fl VAfile +options. +.It Fl no_signature_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 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 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 responder's certificate. +.It Fl out Ar file +Specify output +.Ar file ; +default is standard output. +.It Fl req_text , resp_text , text +Print out the text form of the OCSP request, response, or both, respectively. +.It Fl reqin Ar file , Fl respin Ar file +Read an OCSP request or response file from +.Ar file . +These options 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 reqout Ar file , Fl respout Ar file +Write out the DER-encoded certificate request or response to +.Ar file . +.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 +.Sq 0x . +Negative integers can also be specified by preceding the value with a +.Sq - +sign. +.It Fl sign_other Ar file +Additional certificates to include in the signed request. +.It Fl signer Ar file , Fl signkey Ar file +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, the OCSP request is not signed. +.It Fl trust_other +The certificates specified by the +.Fl verify_other +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 url Ar responder_url +Specify the responder URL. +Both HTTP and HTTPS +.Pq SSL/TLS +URLs can be specified. +.It Fl VAfile Ar file +.Ar file +containing explicitly trusted responder certificates. +Equivalent to the +.Fl verify_other +and +.Fl trust_other +options. +.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. +.It Fl verify_other 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. +.El +.Sh OCSP SERVER OPTIONS +.Bl -tag -width "XXXX" +.It Fl CA Ar file +CA certificate corresponding to the revocation information in +.Ar indexfile . +.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 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, the +.Em nextUpdate +field is omitted, meaning fresh revocation information is immediately available. +.It Fl nrequest Ar number +The OCSP server will exit after receiving +.Ar number +requests, default unlimited. +.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 resp_key_id +Identify the signer certificate using the key ID; +default is to use the subject name. +.It Fl resp_no_certs +Don't include any certificates in the OCSP response. +.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 rother Ar file +Additional certificates to include in the OCSP response. +.It Fl rsigner Ar file +The certificate to sign OCSP responses with. +.El +.Sh OCSP RESPONSE VERIFICATION +OCSP Response follows the rules specified in RFC 2560. +.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, 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 responder's 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, 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 +.Pq 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: +.Bd -literal -offset indent +$ openssl x509 -in ocspCA.pem -addtrust OCSPSigning \e + -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 +.Pq 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: +.Bd -literal -offset indent +$ openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \e + -reqout 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: +.Bd -literal -offset indent +$ 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 in text form: +.Pp +.Dl $ openssl ocsp -respin resp.der -text +.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: +.Bd -literal -offset indent +$ openssl ocsp -index demoCA/index.txt -port 8888 -rsigner \e + rcert.pem -CA demoCA/cacert.pem -text -out log.txt +.Ed +.Pp +As above, but exit after processing one request: +.Bd -literal -offset indent +$ openssl ocsp -index demoCA/index.txt -port 8888 -rsigner \e + rcert.pem -CA demoCA/cacert.pem -nrequest 1 +.Ed +.Pp +Query status information using internally generated request: +.Bd -literal -offset indent +$ 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 and write +the response to a second file: +.Bd -literal -offset indent +$ openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA \e + demoCA/cacert.pem -reqin req.der -respout resp.der +.Ed +.\" +.\" PASSWD +.\" +.Sh PASSWD +.nr nS 1 +.Nm "openssl passwd" +.Op Fl 1 | apr1 | crypt +.Op Fl in Ar file +.Op Fl noverify +.Op Fl quiet +.Op Fl reverse +.Op Fl salt Ar string +.Op Fl stdin +.Op Fl table +.Op Ar password +.nr nS 0 +.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 +.Ux +standard algorithm +.Em crypt +and the MD5-based +.Bx +password algorithm +.Em 1 +and its Apache variant +.Em apr1 +are available. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl 1 +Use the MD5 based +.Bx +password algorithm +.Em 1 . +.It Fl apr1 +Use the +.Em apr1 +algorithm +.Pq Apache variant of the +.Bx +algorithm. +.It Fl crypt +Use the +.Em crypt +algorithm +.Pq default . +.It Fl in Ar file +Read passwords from +.Ar file . +.It Fl noverify +Don't verify when reading a password from the terminal. +.It Fl quiet +Don't output warnings when passwords given on the command line are truncated. +.It Fl reverse +Switch table columns. +This only makes sense in conjunction with the +.Fl table +option. +.It Fl salt Ar string +Use the specified +.Ar salt . +When reading a password from the terminal, this implies +.Fl noverify . +.It Fl stdin +Read passwords from +.Em stdin . +.It Fl table +In the output list, prepend the cleartext password and a TAB character +to each password hash. +.El +.Sh PASSWD EXAMPLES +.Dl $ openssl passwd -crypt -salt xx password +prints +.Qq xxj31ZMTZzkVA . +.Pp +.Dl $ openssl passwd -1 -salt xxxxxxxx password +prints +.Qq $1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a. . +.Pp +.Dl $ openssl passwd -apr1 -salt xxxxxxxx password +prints +.Qq $apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0 . +.\" +.\" PKCS7 +.\" +.Sh PKCS7 +.nr nS 1 +.Nm "openssl pkcs7" +.Bk -words +.Op Fl engine Ar id +.Op Fl in Ar file +.Op Fl inform Ar DER | PEM +.Op Fl noout +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM +.Op Fl print_certs +.Op Fl text +.Ek +.nr nS 0 +.Pp +The +.Nm pkcs7 +command processes PKCS#7 files in DER or PEM format. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm pkcs7 +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 in Ar file +This specifies the input +.Ar file +to read from, or standard input if this option is not specified. +.It Fl inform Ar DER | PEM +This specifies the input format. +.Ar DER +format is a DER-encoded PKCS#7 v1.5 structure. +.Ar PEM +.Pq the default +is a base64-encoded version of the DER form with header and footer lines. +.It Fl noout +Don't output the encoded version of the PKCS#7 structure +(or certificates if +.Fl print_certs +is set). +.It Fl out Ar file +Specifies the output +.Ar file +to write to, or standard output by default. +.It Fl outform Ar DER | PEM +This specifies the output format; the options have the same meaning as the +.Fl inform +option. +.It Fl print_certs +Prints out any certificates or CRLs contained in the file. +They are preceded by their subject and issuer names in a one-line format. +.It Fl text +Prints out certificate details in full rather than just subject and +issuer names. +.El +.Sh PKCS7 EXAMPLES +Convert a PKCS#7 file from PEM to DER: +.Pp +.Dl $ openssl pkcs7 -in file.pem -outform DER -out file.der +.Pp +Output all certificates in a file: +.Pp +.Dl $ openssl pkcs7 -in file.pem -print_certs -out certs.pem +.Sh PKCS7 NOTES +The PEM PKCS#7 format uses the header and footer lines: +.Bd -unfilled -offset indent +-----BEGIN PKCS7----- +-----END PKCS7----- +.Ed +.Pp +For compatibility with some CAs it will also accept: +.Bd -unfilled -offset indent +-----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 RFC 2315. +They cannot currently parse, for example, the new CMS as described in RFC 2630. +.\" +.\" PKCS8 +.\" +.Sh PKCS8 +.nr nS 1 +.Nm "openssl pkcs8" +.Bk -words +.Op Fl embed +.Op Fl engine Ar id +.Op Fl in Ar file +.Op Fl inform Ar DER | PEM +.Op Fl nocrypt +.Op Fl noiter +.Op Fl nooct +.Op Fl nsdb +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM +.Op Fl passin Ar arg +.Op Fl passout Ar arg +.Op Fl topk8 +.Op Fl v1 Ar alg +.Op Fl v2 Ar alg +.Ek +.nr nS 0 +.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 +.Pq v1.5 and v2.0 +and PKCS#12 algorithms. +.Pp +The options are as follows: +.Bl -tag -width Ds +.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 engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm pkcs8 +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 in Ar file +This specifies the input +.Ar file +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 inform Ar DER | PEM +This specifies the input format. +If a PKCS#8 format key is expected on input, +then either a +DER- or PEM-encoded version of a PKCS#8 key will be expected. +Otherwise the DER or PEM format of the traditional format private key is used. +.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 use +unencrypted private keys. +.It Fl noiter +Use an iteration count of 1. +See the +.Sx PKCS12 +section below for a detailed explanation of this option. +.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 an OCTET STRING, +but some software just includes the structure itself without the +surrounding OCTET STRING. +.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 out Ar file +This specifies the output +.Ar file +to write a key to, or standard output by default. +If any encryption options are set, a pass phrase will be prompted for. +The output filename should +.Em not +be the same as the input filename. +.It Fl outform Ar DER | PEM +This specifies the output format; the options have the same meaning as the +.Fl inform +option. +.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 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 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 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. +.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. +.El +.Sh PKCS8 NOTES +The encrypted form of a PEM-encoded PKCS#8 file uses the following +headers and footers: +.Bd -unfilled -offset indent +-----BEGIN ENCRYPTED PRIVATE KEY----- +-----END ENCRYPTED PRIVATE KEY----- +.Ed +.Pp +The unencrypted form uses: +.Bd -unfilled -offset indent +-----BEGIN PRIVATE KEY----- +-----END PRIVATE KEY----- +.Ed +.Pp +Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration +counts are more secure than 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 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 +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 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 +.Bl -tag -width "XXXX" -compact +.It Ar PBE-MD2-DES | PBE-MD5-DES +These algorithms were included in the original PKCS#5 v1.5 specification. +They only offer 56 bits of protection since they both use DES. +.Pp +.It Ar PBE-SHA1-RC2-64 | PBE-MD2-RC2-64 | PBE-MD5-RC2-64 | PBE-SHA1-DES +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. +.Pp +.It Ar PBE-SHA1-RC4-128 | PBE-SHA1-RC4-40 | PBE-SHA1-3DES | PBE-SHA1-2DES +.It Ar PBE-SHA1-RC2-128 | PBE-SHA1-RC2-40 +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. +.El +.Sh PKCS8 EXAMPLES +Convert a private key from traditional to PKCS#5 v2.0 format using triple DES: +.Pp +.Dl "$ 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 +.Pq DES : +.Pp +.Dl $ openssl pkcs8 -in key.pem -topk8 -out enckey.pem +.Pp +Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm +.Pq 3DES : +.Bd -literal -offset indent +$ openssl pkcs8 -in key.pem -topk8 -out enckey.pem \e + -v1 PBE-SHA1-3DES +.Ed +.Pp +Read a DER-unencrypted PKCS#8 format private key: +.Pp +.Dl "$ 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 +.Dl $ 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 +.Pq 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 +.nr nS 1 +.Nm "openssl pkcs12" +.Bk -words +.Oo +.Fl aes128 | aes192 | aes256 | +.Fl des | des3 +.Oc +.Op Fl cacerts +.Op Fl CAfile Ar file +.Op Fl caname Ar name +.Op Fl CApath Ar directory +.Op Fl certfile Ar file +.Op Fl certpbe Ar alg +.Op Fl chain +.Op Fl clcerts +.Op Fl CSP Ar name +.Op Fl descert +.Op Fl engine Ar id +.Op Fl export +.Op Fl in Ar file +.Op Fl info +.Op Fl inkey Ar file +.Op Fl keyex +.Op Fl keypbe Ar alg +.Op Fl keysig +.Op Fl macalg Ar alg +.Op Fl maciter +.Op Fl name Ar name +.Op Fl nocerts +.Op Fl nodes +.Op Fl noiter +.Op Fl nokeys +.Op Fl nomac +.Op Fl nomaciter +.Op Fl nomacver +.Op Fl noout +.Op Fl out Ar file +.Op Fl passin Ar arg +.Op Fl passout Ar arg +.Op Fl twopass +.Ek +.nr nS 0 +.Pp +The +.Nm pkcs12 +command allows PKCS#12 files +.Pq 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 +.Pq see below . +.Sh PKCS12 PARSING OPTIONS +.Bl -tag -width "XXXX" +.It Xo +.Fl aes128 | aes192 | aes256 | +.Fl des | des3 +.Xc +Use AES, DES, or triple DES, respectively, +to encrypt private keys before outputting. +The default is triple DES. +.It Fl cacerts +Only output CA certificates +.Pq not client certificates . +.It Fl clcerts +Only output client certificates +.Pq not CA certificates . +.It Fl in Ar file +This specifies the +.Ar file +of the PKCS#12 file to be parsed. +Standard input is used by default. +.It Fl info +Output additional information about the PKCS#12 file structure, +algorithms used, and iteration counts. +.It Fl nocerts +No certificates at all will be output. +.It Fl nodes +Don't encrypt the private keys at all. +.It Fl nokeys +No private keys will be output. +.It Fl nomacver +Don't attempt to verify the integrity MAC before reading the file. +.It Fl noout +This option inhibits output of the keys and certificates to the output file +version of the PKCS#12 file. +.It Fl out Ar file +The +.Ar file +to write certificates and private keys to, standard output by default. +They are all written in PEM format. +.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 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 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. +.El +.Sh PKCS12 FILE CREATION OPTIONS +.Bl -tag -width "XXXX" +.It Fl CAfile Ar file +CA storage as a file. +.It Fl CApath Ar directory +CA storage as a directory. +This directory must be a standard certificate directory: +that is, a hash of each subject name (using +.Cm x509 -hash ) +should be linked to each certificate. +.It Fl caname Ar name +This specifies the +.Qq 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 certfile Ar file +A file to read additional certificates from. +.It Fl certpbe Ar alg , Fl keypbe Ar alg +These options allow the algorithm used to encrypt the private key and +certificates to be selected. +Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name can be used (see the +.Sx PKCS12 NOTES +section for more information). +If a cipher name +(as output by the +.Cm list-cipher-algorithms +command) is specified then it +is used with PKCS#5 v2.0. +For interoperability reasons it is advisable to only use PKCS#12 algorithms. +.It Fl chain +If this option is present, 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 CSP Ar name +Write +.Ar name +as a Microsoft CSP name. +.It Fl descert +Encrypt the certificate using triple DES; this may render the PKCS#12 +file unreadable by some +.Qq export grade +software. +By default, the private key is encrypted using triple DES and the +certificate using 40-bit RC2. +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm pkcs12 +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 export +This option specifies that a PKCS#12 file will be created rather than +parsed. +.It Fl in Ar file +The +.Ar file +to read certificates and private keys from, standard input by default. +They must all be in 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 file +File to read private key from. +If not present, a private key must be present in the input file. +.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, +.Qq 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 +.Pq 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 macalg Ar alg +Specify the MAC digest algorithm. +If not included then SHA1 is used. +.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 name Ar name +This specifies the +.Qq friendly name +for the certificate and private key. +This name is typically displayed in list boxes by software importing the file. +.It Fl nomac +Don't attempt to provide the MAC integrity. +.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 out Ar file +This specifies +.Ar file +to write the PKCS#12 file to. +Standard output is used by default. +.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 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. +.El +.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, 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 +.Dl $ openssl pkcs12 -in file.p12 -out file.pem +.Pp +Output only client certificates to a file: +.Pp +.Dl $ openssl pkcs12 -in file.p12 -clcerts -out file.pem +.Pp +Don't encrypt the private key: +.Pp +.Dl $ openssl pkcs12 -in file.p12 -out file.pem -nodes +.Pp +Print some info about a PKCS#12 file: +.Pp +.Dl $ openssl pkcs12 -in file.p12 -info -noout +.Pp +Create a PKCS#12 file: +.Bd -literal -offset indent +$ openssl pkcs12 -export -in file.pem -out file.p12 \e + -name "My Certificate" +.Ed +.Pp +Include some extra certificates: +.Bd -literal -offset indent +$ 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 +.Pq 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: +.Bd -literal -offset indent +$ old-openssl -in bad.p12 -out keycerts.pem +$ openssl -in keycerts.pem -export -name "My PKCS#12 file" \e + -out fixed.p12 +.Ed +.\" +.\" PKEY +.\" +.Sh PKEY +.nr nS 1 +.Nm "openssl pkey" +.Bk -words +.Op Ar cipher +.Op Fl engine Ar id +.Op Fl in Ar file +.Op Fl inform Ar DER | PEM +.Op Fl noout +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM +.Op Fl passin Ar arg +.Op Fl passout Ar arg +.Op Fl pubin +.Op Fl pubout +.Op Fl text +.Op Fl text_pub +.Ek +.nr nS 0 +.Pp +The +.Nm pkey +command processes public or private keys. +They can be converted between various forms +and their components printed out. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Ar cipher +These options encrypt the private key with the supplied cipher. +Any algorithm name accepted by +.Fn EVP_get_cipherbyname +is acceptable, such as +.Cm des3 . +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm pkey +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 in Ar file +This specifies the input 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 inform Ar DER | PEM +This specifies the input format, DER or PEM. +.It Fl noout +Do not output the encoded version of the key. +.It Fl out Ar file +This specifies the output 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 outform Ar DER | PEM +This specifies the output format; +the options have the same meaning as the +.Fl inform +option. +.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 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 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. +.It Fl text +Print out the various public or private key components in +plain text in addition to the encoded version. +.It Fl text_pub +Print out only public key components +even if a private key is being processed. +.El +.Sh PKEY EXAMPLES +To remove the pass phrase on an RSA private key: +.Bd -literal -offset indent +$ openssl pkey -in key.pem -out keyout.pem +.Ed +.Pp +To encrypt a private key using triple DES: +.Bd -literal -offset indent +$ openssl pkey -in key.pem -des3 -out keyout.pem +.Ed +.Pp +To convert a private key from PEM to DER format: +.Bd -literal -offset indent +$ openssl pkey -in key.pem -outform DER -out keyout.der +.Ed +.Pp +To print the components of a private key to standard output: +.Bd -literal -offset indent +$ openssl pkey -in key.pem -text -noout +.Ed +.Pp +To print the public components of a private key to standard output: +.Bd -literal -offset indent +$ openssl pkey -in key.pem -text_pub -noout +.Ed +.Pp +To just output the public part of a private key: +.Bd -literal -offset indent +$ openssl pkey -in key.pem -pubout -out pubkey.pem +.Ed +.\" +.\" PKEYPARAM +.\" +.Sh PKEYPARAM +.Cm openssl pkeyparam +.Op Fl engine Ar id +.Op Fl in Ar file +.Op Fl noout +.Op Fl out Ar file +.Op Fl text +.Pp +The +.Nm pkey +command processes public or private keys. +They can be converted between various forms and their components printed out. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm pkeyparam +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 in Ar file +This specifies the input filename to read parameters from, +or standard input if this option is not specified. +.It Fl noout +Do not output the encoded version of the parameters. +.It Fl out Ar file +This specifies the output filename to write parameters to, +or standard output if this option is not specified. +.It Fl text +Prints out the parameters in plain text in addition to the encoded version. +.El +.Sh PKEYPARAM EXAMPLES +Print out text version of parameters: +.Bd -literal -offset indent +$ openssl pkeyparam -in param.pem -text +.Ed +.Sh PKEYPARAM NOTES +There are no +.Fl inform +or +.Fl outform +options for this command because only PEM format is supported +because the key type is determined by the PEM headers. +.\" +.\" PKEYUTL +.\" +.Sh PKEYUTL +.nr nS 1 +.Nm "openssl pkeyutl" +.Bk -words +.Op Fl asn1parse +.Op Fl certin +.Op Fl decrypt +.Op Fl derive +.Op Fl encrypt +.Op Fl engine Ar id +.Op Fl hexdump +.Op Fl in Ar file +.Op Fl inkey Ar file +.Op Fl keyform Ar DER | ENGINE | PEM +.Op Fl out Ar file +.Op Fl passin Ar arg +.Op Fl peerform Ar DER | ENGINE | PEM +.Op Fl peerkey Ar file +.Op Fl pkeyopt Ar opt : Ns Ar value +.Op Fl pubin +.Op Fl rev +.Op Fl sigfile Ar file +.Op Fl sign +.Op Fl verify +.Op Fl verifyrecover +.Ek +.nr nS 0 +.Pp +The +.Nm pkeyutl +command can be used to perform public key operations using +any supported algorithm. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl asn1parse +ASN1parse the output data. +This is useful when combined with the +.Fl verifyrecover +option when an ASN1 structure is signed. +.It Fl certin +The input is a certificate containing a public key. +.It Fl decrypt +Decrypt the input data using a private key. +.It Fl derive +Derive a shared secret using the peer key. +.It Fl encrypt +Encrypt the input data using a public key. +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm pkeyutl +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 hexdump +Hex dump the output data. +.It Fl in Ar file +Specify the input filename to read data from, +or standard input if this option is not specified. +.It Fl inkey Ar file +The input key file. +By default it should be a private key. +.It Fl keyform Ar DER | ENGINE | PEM +The key format DER, ENGINE, or PEM. +.It Fl out Ar file +Specify the output filename to write to, +or standard output by default. +.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 peerform Ar DER | ENGINE | PEM +The peer key format DER, ENGINE, or PEM. +.It Fl peerkey Ar file +The peer key file, used by key derivation (agreement) operations. +.It Fl pkeyopt Ar opt : Ns Ar value +Public key options. +.It Fl pubin +The input file is a public key. +.It Fl rev +Reverse the order of the input buffer. +This is useful for some libraries (such as CryptoAPI) +which represent the buffer in little endian format. +.It Fl sigfile Ar file +Signature file (verify operation only). +.It Fl sign +Sign the input data and output the signed result. +This requires a private key. +.It Fl verify +Verify the input data against the signature file and indicate if the +verification succeeded or failed. +.It Fl verifyrecover +Verify the input data and output the recovered data. +.El +.Sh PKEYUTL NOTES +The operations and options supported vary according to the key algorithm +and its implementation. +The +.Nm OpenSSL +operations and options are indicated below. +.Pp +Unless otherwise mentioned all algorithms support the +.Ar digest : Ns Ar alg +option which specifies the digest in use +for sign, verify, and verifyrecover operations. +The value +.Ar alg +should represent a digest name as used in the +.Fn EVP_get_digestbyname +function, for example +.Cm sha1 . +.Ss RSA algorithm +The RSA algorithm supports the +encrypt, decrypt, sign, verify, and verifyrecover operations in general. +Some padding modes only support some of these +operations however. +.Bl -tag -width Ds +.It rsa_padding_mode : Ns Ar mode +This sets the RSA padding mode. +Acceptable values for +.Ar mode +are +.Cm pkcs1 +for PKCS#1 padding; +.Cm sslv3 +for SSLv3 padding; +.Cm none +for no padding; +.Cm oaep +for OAEP mode; +.Cm x931 +for X9.31 mode; +and +.Cm pss +for PSS. +.Pp +In PKCS#1 padding if the message digest is not set then the supplied data is +signed or verified directly instead of using a DigestInfo structure. +If a digest is set then a DigestInfo +structure is used and its length +must correspond to the digest type. +.Pp +For oeap mode only encryption and decryption is supported. +.Pp +For x931 if the digest type is set it is used to format the block data; +otherwise the first byte is used to specify the X9.31 digest ID. +Sign, verify, and verifyrecover can be performed in this mode. +.Pp +For pss mode only sign and verify are supported and the digest type must be +specified. +.It rsa_pss_saltlen : Ns Ar len +For pss +mode only this option specifies the salt length. +Two special values are supported: +-1 sets the salt length to the digest length. +When signing -2 sets the salt length to the maximum permissible value. +When verifying -2 causes the salt length to be automatically determined +based on the PSS block structure. +.El +.Ss DSA algorithm +The DSA algorithm supports the sign and verify operations. +Currently there are no additional options other than +.Ar digest . +Only the SHA1 digest can be used and this digest is assumed by default. +.Ss DH algorithm +The DH algorithm supports the derive operation +and no additional options. +.Ss EC algorithm +The EC algorithm supports the sign, verify, and derive operations. +The sign and verify operations use ECDSA and derive uses ECDH. +Currently there are no additional options other than +.Ar digest . +Only the SHA1 digest can be used and this digest is assumed by default. +.Sh PKEYUTL EXAMPLES +Sign some data using a private key: +.Bd -literal -offset indent +$ openssl pkeyutl -sign -in file -inkey key.pem -out sig +.Ed +.Pp +Recover the signed data (e.g. if an RSA key is used): +.Bd -literal -offset indent +$ openssl pkeyutl -verifyrecover -in sig -inkey key.pem +.Ed +.Pp +Verify the signature (e.g. a DSA key): +.Bd -literal -offset indent +$ openssl pkeyutl -verify -in file -sigfile sig \e + -inkey key.pem +.Ed +.Pp +Sign data using a message digest value (this is currently only valid for RSA): +.Bd -literal -offset indent +$ openssl pkeyutl -sign -in file -inkey key.pem \e + -out sig -pkeyopt digest:sha256 +.Ed +.Pp +Derive a shared secret value: +.Bd -literal -offset indent +$ openssl pkeyutl -derive -inkey key.pem \e + -peerkey pubkey.pem -out secret +.Ed +.\" +.\" PRIME +.\" +.Sh PRIME +.Cm openssl prime +.Op Fl bits Ar n +.Op Fl checks Ar n +.Op Fl generate +.Op Fl hex +.Op Fl safe +.Ar p +.Pp +The +.Nm prime +command is used to generate prime numbers, +or to check numbers for primality. +Results are probabilistic: +they have an exceedingly high likelihood of being correct, +but are not guaranteed. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl bits Ar n +Specify the number of bits in the generated prime number. +Must be used in conjunction with +.Fl generate . +.It Fl checks Ar n +Perform a Miller-Rabin probabilistic primality test with +.Ar n +iterations. +The default is 20. +.It Fl generate +Generate a pseudo-random prime number. +Must be used in conjunction with +.Fl bits . +.It Fl hex +Output in hex format. +.It Fl safe +Generate only +.Qq safe +prime numbers +(i.e. a prime p so that (p-1)/2 is also prime). +.It Ar p +Test if number +.Ar p +is prime. +.El +.\" +.\" RAND +.\" +.Sh RAND +.nr nS 1 +.Nm "openssl rand" +.Op Fl base64 +.Op Fl engine Ar id +.Op Fl hex +.Op Fl out Ar file +.Ar num +.nr nS 0 +.Pp +The +.Nm rand +command outputs +.Ar num +pseudo-random bytes. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl base64 +Perform +.Em base64 +encoding on the output. +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm rand +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 hex +Specify hexadecimal output. +.It Fl out Ar file +Write to +.Ar file +instead of standard output. +.El +.\" +.\" REQ +.\" +.Sh REQ +.nr nS 1 +.Nm "openssl req" +.Bk -words +.Op Fl asn1-kludge +.Op Fl batch +.Op Fl config Ar file +.Op Fl days Ar n +.Op Fl engine Ar id +.Op Fl extensions Ar section +.Op Fl in Ar file +.Op Fl inform Ar DER | PEM +.Op Fl key Ar keyfile +.Op Fl keyform Ar DER | PEM +.Op Fl keyout Ar file +.Op Fl md4 | md5 | sha1 +.Op Fl modulus +.Op Fl nameopt Ar option +.Op Fl new +.Op Fl newhdr +.Op Fl newkey Ar arg +.Op Fl no-asn1-kludge +.Op Fl nodes +.Op Fl noout +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM +.Op Fl passin Ar arg +.Op Fl passout Ar arg +.Op Fl pubkey +.Op Fl reqexts Ar section +.Op Fl reqopt Ar option +.Op Fl set_serial Ar n +.Op Fl subj Ar arg +.Op Fl subject +.Op Fl text +.Op Fl utf8 +.Op Fl verbose +.Op Fl verify +.Op Fl x509 +.Ek +.nr nS 0 +.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: +.Bl -tag -width Ds +.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 batch +Non-interactive mode. +.It Fl config Ar file +This allows an alternative configuration file to be specified; +this overrides the compile time filename or any specified in +the +.Ev OPENSSL_CONF +environment variable. +.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 engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm req +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 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 in Ar file +This specifies the input +.Ar file +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 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 key Ar keyfile +This specifies the file to read the private key from. +It also accepts PKCS#8 format private keys for PEM format files. +.It Fl keyform Ar DER | PEM +The format of the private key file specified in the +.Fl key +argument. +.Ar PEM +is the default. +.It Fl keyout Ar file +This gives the +.Ar file +to write the newly created private key to. +If this option is not specified, the filename present in the +configuration file is used. +.It Fl md4 | md5 | sha1 +This specifies the message digest to sign the request with. +This overrides the digest algorithm specified in the configuration file. +.Pp +Some public key algorithms may override this choice. +For instance, DSA signatures always use SHA1. +.It Fl modulus +This option prints out the value of the modulus of the public key +contained in the request. +.It Fl nameopt Ar option , Fl reqopt Ar option +These options determine how the subject or issuer names are displayed. +The +.Ar option +argument can be a single option or multiple options separated by commas. +Alternatively, these options may be used more than once to set multiple options. +See the +.Sx X509 +section below for details. +.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 newhdr +Adds the word NEW to the PEM file header and footer lines +on the outputed request. +Some software +.Pq Netscape certificate server +and some CAs need this. +.It Fl newkey Ar arg +This option creates a new certificate request and a new private key. +The argument takes one of several forms. +.Ar rsa : Ns Ar nbits , +where +.Ar nbits +is the number of bits, generates an RSA key +.Ar nbits +in size. +If +.Ar nbits +is omitted, i.e.\& +.Cm -newkey rsa +specified, +the default key size, specified in the configuration file, is used. +.Pp +All other algorithms support the +.Ar alg : Ns Ar file +form, +where file may be an algorithm parameter file, +created by the +.Cm genpkey -genparam +command or an X.509 certificate for a key with approriate algorithm. +.Pp +.Ar param : Ns Ar file +generates a key using the parameter file or certificate +.Ar file ; +the algorithm is determined by the parameters. +.Ar algname : Ns Ar file +use algorithm +.Ar algname +and parameter file +.Ar file : +the two algorithms must match or an error occurs. +.Ar algname +just uses algorithm +.Ar algname , +and parameters, if necessary, +should be specified via the +.Fl pkeyopt +option. +.Pp +.Ar dsa : Ns Ar file +generates a DSA key using the parameters in the file +.Ar file . +.It Fl no-asn1-kludge +Reverses the effect of +.Fl asn1-kludge . +.It Fl nodes +If this option is specified and a private key is created, it +will not be encrypted. +.It Fl noout +This option prevents output of the encoded version of the request. +.It Fl out Ar file +This specifies the output +.Ar file +to write to, or standard output by default. +.It Fl outform Ar DER | PEM +This specifies the output format; the options have the same meaning as the +.Fl inform +option. +.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 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 pubkey +Outputs the public key. +.It Fl reqopt 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. +.Pp +See the discussion of the +.Fl certopt +option in the +.Nm x509 +command. +.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 +.Sq 0x . +It is possible to use negative serial numbers but this is not recommended. +.It Fl subj Ar arg +Replaces subject field of input request with specified data and outputs +modified request. +The arg must be formatted as +.Em /type0=value0/type1=value1/type2=... ; +characters may be escaped by +.Sq \e +.Pq backslash ; +no spaces are skipped. +.It Fl subject +Prints out the request subject (or certificate subject if +.Fl x509 +is specified. +.It Fl text +Prints out the certificate request in text form. +.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 verbose +Print extra details about the operations being performed. +.It Fl verify +Verifies the signature on the request. +.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 +.Pq if any +are specified in the configuration file. +Unless specified using the +.Fl set_serial +option, 0 will be used for the serial number. +.El +.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. +.Bl -tag -width "XXXX" +.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 default_bits +This specifies the default key size in bits. +If not specified, 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 file 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 default_md +This option specifies the digest algorithm to use. +Possible values include +.Ar md5 +and +.Ar sha1 . +If not present, MD5 is used. +This option can be overridden on the command line. +.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. +.It Ar encrypt_key +If this is set to +.Em no +and 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 input_password | output_password +The passwords for the input private key file +.Pq if present +and the output private key file +.Pq if one will be created . +The command line options +.Fl passin +and +.Fl passout +override the configuration file values. +.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 +.Sq = +and the numerical form. +The short and long names are the same when this option is used. +.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 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 string_mask +This option limits the string types for encoding certain +fields. +The following values may be used, limiting strings to the indicated types: +.Bl -tag -width "MASK:number" +.It Ar utf8only +.Em UTF8String. +This is the default, as recommended by PKIX in RFC 2459. +.It Ar default +.Em PrintableString , IA5String , T61String , BMPString , UTF8String . +.It Ar pkix +.Em PrintableString , IA5String , BMPString , UTF8String . +This was inspired by the PKIX recommendation in RFC 2459 for certificates +generated before 2004, but differs by also permitting +.Em IA5String . +.It Ar nombstr +.Em PrintableString , IA5String , T61String , UniversalString . +This was a workaround for some ancient software that had problems +with the variable-sized +.Em BMPString +and +.Em UTF8String +types. +.It Cm MASK : Ns Ar number +This is an explicit bitmask of permitted types, where +.Ar number +is a C-style hex, decimal, or octal number that's a bit-wise OR of +.Dv B_ASN1_* +values from +.In openssl/asn1.h . +.El +.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 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. +.El +.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, +.Bd -unfilled -offset indent +CN=My Name +OU=My Organization +emailAddress=someone@somewhere.org +.Ed +.Pp +This allows external programs +.Pq 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: +.Bd -unfilled -offset indent +fieldName="prompt" +fieldName_default="default field value" +fieldName_min= 2 +fieldName_max= 4 +.Ed +.Pp +.Qq fieldName +is the field name being used, for example +.Em commonName +.Pq or CN . +The +.Qq prompt +string is used to ask the user to enter the relevant details. +If the user enters nothing, the default value is used; +if no default value is present, the field is omitted. +A field can still be omitted if a default value is present, +if the user just enters the +.Sq \&. +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 +.Qq 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 , stateOrProvinceName . +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 a certificate request: +.Pp +.Dl $ openssl req -in req.pem -text -verify -noout +.Pp +Create a private key and then generate a certificate request from it: +.Bd -literal -offset indent +$ openssl genrsa -out key.pem 2048 +$ openssl req -new -key key.pem -out req.pem +.Ed +.Pp +The same but just using req: +.Pp +.Dl $ openssl req -newkey rsa:2048 -keyout key.pem -out req.pem +.Pp +Generate a self-signed root certificate: +.Pp +.Dl "$ openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem" +.Pp +Example of a file pointed to by the +.Ar oid_file +option: +.Bd -unfilled -offset indent +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: +.Bd -unfilled -offset indent +testoid1=1.2.3.5 +testoid2=${testoid1}.6 +.Ed +.Pp +Sample configuration file prompting for field values: +.Bd -literal +\& [ req ] +\& default_bits = 1024 +\& default_keyfile = privkey.pem +\& distinguished_name = req_distinguished_name +\& attributes = req_attributes +\& x509_extensions = v3_ca + +\& dirstring_type = nobmp + +\& [ req_distinguished_name ] +\& countryName = Country Name (2 letter code) +\& countryName_default = AU +\& countryName_min = 2 +\& countryName_max = 2 + +\& localityName = Locality Name (eg, city) + +\& organizationalUnitName = Organizational Unit Name (eg, section) + +\& commonName = Common Name (eg, YOUR name) +\& commonName_max = 64 + +\& emailAddress = Email Address +\& emailAddress_max = 40 + +\& [ req_attributes ] +\& challengePassword = A challenge password +\& challengePassword_min = 4 +\& challengePassword_max = 20 + +\& [ v3_ca ] + +\& subjectKeyIdentifier=hash +\& authorityKeyIdentifier=keyid:always,issuer:always +\& basicConstraints = CA:true +.Ed +.Pp +Sample configuration containing all field values: +.Bd -literal + +\& [ req ] +\& default_bits = 1024 +\& default_keyfile = keyfile.pem +\& distinguished_name = req_distinguished_name +\& attributes = req_attributes +\& prompt = no +\& output_password = mypass + +\& [ 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 + +\& [ req_attributes ] +\& challengePassword = A challenge password +.Ed +.Sh REQ NOTES +The header and footer lines in the PEM format are normally: +.Bd -unfilled -offset indent +-----BEGIN CERTIFICATE REQUEST----- +-----END CERTIFICATE REQUEST----- +.Ed +.Pp +Some software +.Pq some versions of Netscape certificate server +instead needs: +.Bd -unfilled -offset indent +-----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 +.Pq 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: +.Bd -unfilled -offset indent +Using configuration from /some/path/openssl.cnf +Unable to load config info +.Ed +.Pp +This is followed some time later by... +.Bd -unfilled -offset indent +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 +.Pq 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: +.Bd -unfilled -offset indent +Attributes: + a0:00 +.Ed +.Pp +This is displayed when no attributes are present and the request includes +the correct empty SET OF structure +.Pq the DER encoding of which is 0xa0 0x00 . +If you just see: +.Pp +.D1 Attributes: +.Pp +then the SET OF is missing and the encoding is technically invalid +.Pq but it is tolerated . +See the description of the command line option +.Fl asn1-kludge +for more information. +.Sh REQ ENVIRONMENT VARIABLES +The variable +.Ev 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 +.Ev SSLEAY_CONF +environment variable serves the same purpose but its use is discouraged. +.Sh REQ BUGS +.Nm OpenSSL Ns Li 's +handling of T61Strings +.Pq aka TeletexStrings +is broken: it effectively treats them as ISO 8859-1 +.Pq 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 +.nr nS 1 +.Nm "openssl rsa" +.Bk -words +.Oo +.Fl aes128 | aes192 | aes256 | +.Fl des | des3 +.Oc +.Op Fl check +.Op Fl engine Ar id +.Op Fl in Ar file +.Op Fl inform Ar DER | NET | PEM +.Op Fl modulus +.Op Fl noout +.Op Fl out Ar file +.Op Fl outform Ar DER | NET | PEM +.Op Fl passin Ar arg +.Op Fl passout Ar arg +.Op Fl pubin +.Op Fl pubout +.Op Fl sgckey +.Op Fl text +.nr nS 0 +.Ek +.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: +.Bl -tag -width Ds +.It Xo +.Fl aes128 | aes192 | aes256 | +.Fl des | des3 +.Xc +These options encrypt the private key with the AES, DES, +or the triple DES ciphers, respectively, before outputting it. +A pass phrase is prompted for. +If none of these options are 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 PEM format output files. +.It Fl check +This option checks the consistency of an RSA private key. +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm rsa +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 in Ar file +This specifies the input +.Ar file +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 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 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 out Ar file +This specifies the output +.Ar file +to write a key to, or standard output if this option is not specified. +If any encryption options are set, a pass phrase will be prompted for. +The output filename should +.Em not +be the same as the input filename. +.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 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 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 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. +.It Fl sgckey +Use the modified +.Em NET +algorithm used with some versions of Microsoft IIS and SGC keys. +.It Fl text +Prints out the various public or private key components in +plain text, in addition to the encoded version. +.El +.Sh RSA NOTES +The PEM private key format uses the header and footer lines: +.Bd -unfilled -offset indent +-----BEGIN RSA PRIVATE KEY----- +-----END RSA PRIVATE KEY----- +.Ed +.Pp +The PEM public key format uses the header and footer lines: +.Bd -unfilled -offset indent +-----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 +.Qq private-key , +then trace back to the byte sequence 0x30, 0x82 +.Pq 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 +.Dl $ openssl rsa -in key.pem -out keyout.pem +.Pp +To encrypt a private key using triple DES: +.Pp +.Dl $ openssl rsa -in key.pem -des3 -out keyout.pem +.Pp +To convert a private key from PEM to DER format: +.Pp +.Dl $ openssl rsa -in key.pem -outform DER -out keyout.der +.Pp +To print out the components of a private key to standard output: +.Pp +.Dl $ openssl rsa -in key.pem -text -noout +.Pp +To just output the public part of a private key: +.Pp +.Dl $ 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 +.nr nS 1 +.Nm "openssl rsautl" +.Bk -words +.Op Fl asn1parse +.Op Fl certin +.Op Fl decrypt +.Op Fl encrypt +.Op Fl engine Ar id +.Op Fl hexdump +.Op Fl in Ar file +.Op Fl inkey Ar file +.Op Fl keyform Ar DER | PEM +.Op Fl oaep | pkcs | raw | ssl +.Op Fl out Ar file +.Op Fl pubin +.Op Fl sign +.Op Fl verify +.Ek +.nr nS 0 +.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: +.Bl -tag -width Ds +.It Fl asn1parse +Asn1parse the output data; this is useful when combined with the +.Fl verify +option. +.It Fl certin +The input is a certificate containing an RSA public key. +.It Fl decrypt +Decrypt the input data using an RSA private key. +.It Fl encrypt +Encrypt the input data using an RSA public key. +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm rsautl +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 hexdump +Hex dump the output data. +.It Fl in Ar file +This specifies the input +.Ar file +to read data from, or standard input +if this option is not specified. +.It Fl inkey Ar file +The input key file, by default it should be an RSA private key. +.It Fl keyform Ar DER | PEM +Private ket format. +Default is +.Ar PEM . +.It Fl oaep | pkcs | raw | ssl +The padding to use: +PKCS#1 OAEP, PKCS#1 v1.5 +.Pq the default , +or no padding, respectively. +For signatures, only +.Fl pkcs +and +.Fl raw +can be used. +.It Fl out Ar file +Specifies the output +.Ar file +to write to, or standard output by +default. +.It Fl pubin +The input file is 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. +.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 +.Dl "$ openssl rsautl -sign -in file -inkey key.pem -out sig" +.Pp +Recover the signed data: +.Pp +.Dl $ openssl rsautl -verify -in sig -inkey key.pem +.Pp +Examine the raw signed data: +.Pp +.Li "\ \&$ openssl rsautl -verify -in file -inkey key.pem -raw -hexdump" +.Bd -unfilled +\& 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 +.Pq 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 +.Li "\ \&$ openssl asn1parse -in pca-cert.pem" +.Bd -unfilled +\& 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 +.Dl "$ openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614" +.Pp +The certificate public key can be extracted with: +.Pp +.Dl $ openssl x509 -in test/testx509.pem -pubkey -noout \*(Gtpubkey.pem +.Pp +The signature can be analysed with: +.Pp +.Li "\ \&$ openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin" +.Bd -unfilled +\& 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 +.Dl "$ openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4" +.Pp +and its digest computed with: +.Pp +.Dl $ openssl md5 -c tbs +.D1 MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5 +.Pp +which it can be seen agrees with the recovered value above. +.\" +.\" S_CLIENT +.\" +.Sh S_CLIENT +.nr nS 1 +.Nm "openssl s_client" +.Bk -words +.Op Fl 4 | 6 +.Op Fl bugs +.Op Fl CAfile Ar file +.Op Fl CApath Ar directory +.Op Fl cert Ar file +.Op Fl check_ss_sig +.Op Fl cipher Ar cipherlist +.Oo +.Fl connect Ar host : Ns Ar port | +.Ar host Ns / Ns Ar port +.Oc +.Op Fl crl_check +.Op Fl crl_check_all +.Op Fl crlf +.Op Fl debug +.Op Fl engine Ar id +.Op Fl extended_crl +.Op Fl ign_eof +.Op Fl ignore_critical +.Op Fl issuer_checks +.Op Fl key Ar keyfile +.Op Fl msg +.Op Fl nbio +.Op Fl nbio_test +.Op Fl no_ssl3 +.Op Fl no_ticket +.Op Fl no_tls1 +.Op Fl pause +.Op Fl policy_check +.Op Fl prexit +.Op Fl psk Ar key +.Op Fl psk_identity Ar identity +.Op Fl quiet +.Op Fl reconnect +.Op Fl showcerts +.Op Fl ssl3 +.Op Fl starttls Ar protocol +.Op Fl state +.Op Fl tls1 +.Op Fl tlsextdebug +.Op Fl verify Ar depth +.Op Fl x509_strict +.Ek +.nr nS 0 +.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: +.Bl -tag -width Ds +.It Fl 4 +Specify that +.Nm s_client +should attempt connections using IPv4 only. +.It Fl 6 +Specify that +.Nm s_client +should attempt connections using IPv6 only. +.It Fl bugs +There are several known bugs in SSL and TLS implementations. +Adding this option enables various workarounds. +.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 CApath Ar directory +The +.Ar directory +to use for server certificate verification. +This directory must be in +.Qq hash format ; +see +.Fl verify +for more information. +These are also used when building the client certificate chain. +.It Fl cert Ar file +The certificate to use, if one is requested by the server. +The default is not to use a certificate. +.It Xo +.Fl check_ss_sig , +.Fl crl_check , +.Fl crl_check_all , +.Fl extended_crl , +.Fl ignore_critical , +.Fl issuer_checks , +.Fl policy_check , +.Fl x509_strict +.Xc +Set various certificate chain validation options. +See the +.Nm VERIFY +command for details. +.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 Xo +.Fl connect Ar host : Ns Ar port | +.Ar host Ns / Ns Ar port +.Xc +This specifies the +.Ar host +and optional +.Ar port +to connect to. +If not specified, an attempt is made to connect to the local host +on port 4433. +Alternatively, the host and port pair may be separated using a forward-slash +character. +This form is useful for numeric IPv6 addresses. +.It Fl crlf +This option translates a line feed from the terminal into CR+LF as required +by some servers. +.It Fl debug +Print extensive debugging information including a hex dump of all traffic. +.It Fl engine Ar id +Specifying an engine (by its 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 ign_eof +Inhibit shutting down the connection when end of file is reached in the +input. +.It Fl key Ar keyfile +The private key to use. +If not specified, the certificate file will be used. +.It Fl msg +Show all protocol messages with hex dump. +.It Fl nbio +Turns on non-blocking I/O. +.It Fl nbio_test +Tests non-blocking I/O. +.It Xo +.Fl no_ssl3 | no_tls1 | +.Fl ssl3 | tls1 +.Xc +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 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. +.It Fl no_ticket +Disable RFC 4507 session ticket support. +.It Fl pause +Pauses 1 second between each read and write call. +.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 psk Ar key +Use the PSK key +.Ar key +when using a PSK cipher suite. +The key is given as a hexadecimal number without the leading 0x, +for example -psk 1a2b3c4d. +.It Fl psk_identity Ar identity +Use the PSK identity +.Ar identity +when using a PSK cipher suite. +.It Fl quiet +Inhibit printing of session and certificate information. +This implicitly turns on +.Fl ign_eof +as well. +.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 showcerts +Display the whole server certificate chain: normally only the server +certificate itself is displayed. +.It Fl starttls Ar protocol +Send the protocol-specific message(s) to switch to TLS for communication. +.Ar protocol +is a keyword for the intended protocol. +Currently, the supported keywords are +.Qq ftp , +.Qq imap , +.Qq smtp , +.Qq pop3 , +and +.Qq xmpp . +.It Fl state +Prints out the SSL session states. +.It Fl tlsextdebug +Print out a hex dump of any TLS extensions received from the server. +.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. +.El +.Sh S_CLIENT CONNECTED COMMANDS +If a connection is established with an SSL server, 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 ; +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 +.Dl $ openssl s_client -connect servername:443 +.Pp +would typically be used +.Pq HTTPS uses port 443 . +If the connection succeeds, an HTTP command can be given such as +.Qq GET +to retrieve a web page. +.Pp +If the handshake fails, there are several possible causes; if it is +nothing obvious like no client certificate, then the +.Fl bugs , ssl3 , tls1 , 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 client's certificate +authority in its +.Qq 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 +option 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, the +.Fl showcerts +option can be used to show the whole chain. +.Pp +Compression methods are only supported for +.Fl tls1 . +.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 +.nr nS 1 +.Nm "openssl s_server" +.Bk -words +.Op Fl accept Ar port +.Op Fl bugs +.Op Fl CAfile Ar file +.Op Fl CApath Ar directory +.Op Fl cert Ar file +.Op Fl cipher Ar cipherlist +.Op Fl context Ar id +.Op Fl crl_check +.Op Fl crl_check_all +.Op Fl crlf +.Op Fl dcert Ar file +.Op Fl debug +.Op Fl dhparam Ar file +.Op Fl dkey Ar file +.Op Fl engine Ar id +.Op Fl hack +.Op Fl HTTP +.Op Fl id_prefix Ar arg +.Op Fl key Ar keyfile +.Op Fl msg +.Op Fl nbio +.Op Fl nbio_test +.Op Fl no_dhe +.Op Fl no_ssl3 +.Op Fl no_tls1 +.Op Fl no_tmp_rsa +.Op Fl nocert +.Op Fl psk Ar key +.Op Fl psk_hint Ar hint +.Op Fl quiet +.Op Fl serverpref +.Op Fl ssl3 +.Op Fl state +.Op Fl tls1 +.Op Fl Verify Ar depth +.Op Fl verify Ar depth +.Op Fl WWW +.Op Fl www +.Ek +.nr nS 0 +.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: +.Bl -tag -width Ds +.It Fl accept Ar port +The TCP +.Ar port +to listen on for connections. +If not specified, 4433 is used. +.It Fl bugs +There are several known bugs in SSL and TLS implementations. +Adding this option enables various workarounds. +.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 CApath Ar directory +The +.Ar directory +to use for client certificate verification. +This directory must be in +.Qq hash format ; +see +.Fl verify +for more information. +These are also used when building the server certificate chain. +.It Fl cert Ar file +The certificate to use; most server's 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 +.Pq DSA +key. +If not specified, the file +.Pa server.pem +will be used. +.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 is irrelevant. +See the +.Sx CIPHERS +section for more information. +.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 crl_check , crl_check_all +Check the peer certificate has not been revoked by its CA. +The CRLs are appended to the certificate file. +With the +.Fl crl_check_all +option, all CRLs of all CAs in the chain are checked. +.It Fl crlf +This option translates a line feed from the terminal into CR+LF. +.It Fl dcert Ar file , Fl dkey Ar file +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 +.Pq no additional certificate or 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 +.Pq 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 debug +Print extensive debugging information including a hex dump of all traffic. +.It Fl dhparam Ar file +The DH parameter file to use. +The ephemeral DH cipher suites generate keys +using a set of DH parameters. +If not specified, an attempt is made to +load the parameters from the server certificate file. +If this fails, a static set of parameters hard coded into the +.Nm s_server +program will be used. +.It Fl engine Ar id +Specifying an engine (by its 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 hack +This option enables a further workaround for some early Netscape +SSL code +.Pq \&? . +.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 id_prefix Ar arg +Generate SSL/TLS session IDs prefixed by +.Ar arg . +This is mostly useful for testing any SSL/TLS code +.Pq e.g. proxies +that wish to deal with multiple servers, when each of which might be +generating a unique range of session IDs +.Pq e.g. with a certain prefix . +.It Fl key Ar keyfile +The private key to use. +If not specified, the certificate file will be used. +.It Fl msg +Show all protocol messages with hex dump. +.It Fl nbio +Turns on non-blocking I/O. +.It Fl nbio_test +Tests non-blocking I/O. +.It Fl no_dhe +If this option is set, no DH parameters will be loaded, effectively +disabling the ephemeral DH cipher suites. +.It Xo +.Fl no_ssl3 | no_tls1 | +.Fl ssl3 | tls1 +.Xc +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 or TLS as appropriate. +.It Fl no_tmp_rsa +Certain export cipher suites sometimes use a temporary RSA key; this option +disables temporary RSA key generation. +.It Fl nocert +If this option is set, no certificate is used. +This restricts the cipher suites available to the anonymous ones +.Pq currently just anonymous DH . +.It Fl psk Ar key +Use the PSK key +.Ar key +when using a PSK cipher suite. +The key is given as a hexadecimal number without the leading 0x, +for example -psk 1a2b3c4d. +.It Fl psk_hint Ar hint +Use the PSK identity hint +.Ar hint +when using a PSK cipher suite. +.It Fl quiet +Inhibit printing of session and certificate information. +.It Fl serverpref +Use server's cipher preferences. +.It Fl state +Prints out the SSL session states. +.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 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 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, the client must supply a certificate or an error occurs. +With the +.Fl verify +option, a certificate is requested but the client does not have to send one. +.El +.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. +.Bl -tag -width "XXXX" +.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 Q +End the current SSL connection and exit. +.It Ar q +End the current SSL connection, but still accept new connections. +.It Ar R +Renegotiate the SSL session and request a client certificate. +.It Ar r +Renegotiate the SSL session. +.It Ar S +Print out some session cache status information. +.El +.Sh S_SERVER NOTES +.Nm s_server +can be used to debug SSL clients. +To accept connections from a web browser the command: +.Pp +.Dl $ openssl s_server -accept 443 -www +.Pp +can be used, for example. +.Pp +Most web browsers +.Pq 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 +.nr nS 1 +.Nm "openssl s_time" +.Bk -words +.Op Fl bugs +.Op Fl CAfile Ar file +.Op Fl CApath Ar directory +.Op Fl cert Ar file +.Op Fl cipher Ar cipherlist +.Op Fl connect Ar host : Ns Ar port +.Op Fl key Ar keyfile +.Op Fl nbio +.Op Fl new +.Op Fl reuse +.Op Fl ssl3 +.Op Fl time Ar seconds +.Op Fl verify Ar depth +.Op Fl www Ar page +.Ek +.nr nS 0 +.Pp +The +.Nm s_client +command implements a generic SSL/TLS client which connects to a +remote host using SSL/TLS. +It can request a page from the server and includes +the time to transfer the payload data in its timing measurements. +It measures the number of connections within a given timeframe, +the amount of data transferred +.Pq if any , +and calculates the average time spent for one connection. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl bugs +There are several known bugs in SSL and TLS implementations. +Adding this option enables various workarounds. +.It Fl CAfile Ar file +A file containing trusted certificates to use during server authentication +and to use when attempting to build the client certificate chain. +.It Fl CApath Ar directory +The directory to use for server certificate verification. +This directory must be in +.Qq hash format ; +see +.Nm verify +for more information. +These are also used when building the client certificate chain. +.It Fl cert Ar file +The certificate to use, if one is requested by the server. +The default is not to use a certificate. +The file is in PEM format. +.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 +.Nm ciphers +command for more information. +.It Fl connect Ar host : Ns Ar port +This specifies the host and optional port to connect to. +.It Fl key Ar keyfile +The private key to use. +If not specified, the certificate file will be used. +The file is in PEM format. +.It Fl nbio +Turns on non-blocking I/O. +.It Fl new +Performs the timing test using a new session ID for each connection. +If neither +.Fl new +nor +.Fl reuse +are specified, +they are both on by default and executed in sequence. +.It Fl reuse +Performs the timing test using the same session ID; +this can be used as a test that session caching is working. +If neither +.Fl new +nor +.Fl reuse +are specified, +they are both on by default and executed in sequence. +.It Fl ssl3 +This option disables 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 or TLS as appropriate. +The timing program is not as rich in options to turn protocols on and off as +the +.Nm s_client +program and may not connect to all servers. +.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 ssl3 +option. +.It Fl time Ar seconds +Specifies how long +.Pq in seconds +.Nm s_time +should establish connections and +optionally transfer payload data from a server. +The default is 30 seconds. +Server and client performance and the link speed +determine how many connections +.Nm s_time +can establish. +.It Fl verify Ar depth +The verify 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 www Ar page +This specifies the page to GET from the server. +A value of +.Sq / +gets the index.htm[l] page. +If this parameter is not specified, +.Nm s_time +will only perform the handshake to establish SSL connections +but not transfer any payload data. +.El +.Sh S_TIME NOTES +.Nm s_client +can be used to measure the performance of an SSL connection. +To connect to an SSL HTTP server and get the default page the command +.Bd -literal -offset indent +$ openssl s_time -connect servername:443 -www / -CApath yourdir \e + -CAfile yourfile.pem -cipher commoncipher [-ssl3] +.Ed +.Pp +would typically be used +.Pq HTTPS uses port 443 . +.Dq commoncipher +is a cipher to which both client and server can agree; +see the +.Nm ciphers +command for details. +.Pp +If the handshake fails, there are several possible causes: +if it is nothing obvious like no client certificate, the +.Fl bugs +and +.Fl ssl3 +options can be tried in case it is a buggy server. +In particular you should play with these options +.Em before +submitting a bug report to an 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 +.Qq 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 +option of +.Nm s_client +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. +.Sh S_TIME BUGS +Because this program does not have all the options of the +.Nm s_client +program to turn protocols on and off, +you may not be able to measure the performance +of all protocols with all servers. +.Pp +The +.Fl verify +option should really exit if the server verification fails. +.\" +.\" SESS_ID +.\" +.Sh SESS_ID +.nr nS 1 +.Nm "openssl sess_id" +.Bk -words +.Op Fl cert +.Op Fl context Ar ID +.Op Fl in Ar file +.Op Fl inform Ar DER | PEM +.Op Fl noout +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM +.Op Fl text +.Ek +.nr nS 0 +.Pp +The +.Nm sess_id +program processes the encoded version of the SSL session structure and +optionally prints out SSL session details +.Pq 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: +.Bl -tag -width Ds +.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 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. +.It Fl in Ar file +This specifies the input +.Ar file +to read session information from, or standard input by default. +.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 noout +This option prevents output of the encoded version of the session. +.It Fl out Ar file +This specifies the output +.Ar file +to write session information to, or standard +output if this option is not specified. +.It Fl outform Ar DER | PEM +This specifies the output format; the options have the same meaning as the +.Fl inform +option. +.It Fl text +Prints out the various public or private key components in +plain text in addition to the encoded version. +.El +.Sh SESS_ID OUTPUT +Typical output: +.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. +.Pp +.Bl -tag -width "Verify return code " -compact +.It Ar Protocol +This is the protocol in use: TLSv1 or SSLv3. +.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 +.Ux +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. +.El +.Sh SESS_ID NOTES +The PEM-encoded session format uses the header and footer lines: +.Bd -unfilled -offset indent +-----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 +.Qq 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 +.nr nS 1 +.Nm "openssl smime" +.Bk -words +.Oo +.Fl aes128 | aes192 | aes256 | des | +.Fl des3 | rc2-40 | rc2-64 | rc2-128 +.Oc +.Op Fl binary +.Op Fl CAfile Ar file +.Op Fl CApath Ar directory +.Op Fl certfile Ar file +.Op Fl check_ss_sig +.Op Fl content Ar file +.Op Fl crl_check +.Op Fl crl_check_all +.Op Fl decrypt +.Op Fl encrypt +.Op Fl engine Ar id +.Op Fl extended_crl +.Op Fl from Ar addr +.Op Fl ignore_critical +.Op Fl in Ar file +.Op Fl indef +.Op Fl inform Ar DER | PEM | SMIME +.Op Fl inkey Ar file +.Op Fl issuer_checks +.Op Fl keyform Ar ENGINE | PEM +.Op Fl md Ar digest +.Op Fl noattr +.Op Fl nocerts +.Op Fl nochain +.Op Fl nodetach +.Op Fl noindef +.Op Fl nointern +.Op Fl nosigs +.Op Fl noverify +.Op Fl out Ar file +.Op Fl outform Ar DER | PEM | SMIME +.Op Fl passin Ar arg +.Op Fl pk7out +.Op Fl policy_check +.Op Fl recip Ar file +.Op Fl resign +.Op Fl sign +.Op Fl signer Ar file +.Op Fl stream +.Op Fl subject Ar s +.Op Fl text +.Op Fl to Ar addr +.Op Fl verify +.Op Fl x509_strict +.Op Ar cert.pem ... +.Ek +.nr nS 0 +.Pp +The +.Nm smime +command handles +.Em S/MIME +mail. +It can encrypt, decrypt, sign, and verify +.Em S/MIME +messages. +.Pp +There are six 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 six operation options are as follows: +.Bl -tag -width "XXXX" +.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 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 pk7out +Takes an input message and writes out a PEM-encoded PKCS#7 structure. +.It Fl resign +Resign a message: take an existing message and one or more new signers. +.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. +.El +.Pp +The reamaining options are as follows: +.Bl -tag -width "XXXX" +.It Xo +.Fl aes128 | aes192 | aes256 | des | +.Fl des3 | rc2-40 | rc2-64 | rc2-128 +.Xc +The encryption algorithm to use. +128-, 192-, or 256-bit AES, +DES +.Pq 56 bits , +triple DES +.Pq 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 binary +Normally, the input message is converted to +.Qq 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 CAfile Ar file +A +.Ar file +containing trusted CA certificates; only used with +.Fl verify . +.It Fl CApath Ar directory +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 Ar cert.pem ... +One or more certificates of message recipients: used when encrypting +a message. +.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 PEM format. +.It Xo +.Fl check_ss_sig , +.Fl crl_check , +.Fl crl_check_all , +.Fl extended_crl , +.Fl ignore_critical , +.Fl issuer_checks , +.Fl policy_check , +.Fl x509_strict +.Xc +Set various certificate chain validation options. +See the +.Nm VERIFY +command for details. +.It Fl content Ar file +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 engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm smime +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 Xo +.Fl from Ar addr , +.Fl subject Ar s , +.Fl to Ar addr +.Xc +The relevant mail headers. +These are included outside the signed +portion of a message so they may be included manually. +When signing, many +.Em S/MIME +mail clients check that the signer's certificate email +address matches the From: address. +.It Fl in Ar file +The input message to be encrypted or signed or the +.Em MIME +message to +be decrypted or verified. +.It Fl indef +Enable streaming I/O for encoding operations. +This permits single pass processing of data without +the need to hold the entire contents in memory, +potentially supporting very large files. +Streaming is automatically set for S/MIME signing with detached +data if the output format is SMIME; +it is currently off by default for all other operations. +.It Fl inform Ar DER | PEM | SMIME +This specifies the input format for the PKCS#7 structure. +The default is +.Em SMIME , +which reads an +.Em S/MIME +format message. +.Ar PEM +and +.Ar 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 inkey Ar file +The private key to use when signing or decrypting. +This must match the corresponding certificate. +If this option is not specified, the private key must be included +in the certificate file specified with +the +.Fl recip +or +.Fl signer +file. +When signing, +this option can be used multiple times to specify successive keys. +.It Fl keyform Ar ENGINE | PEM +Input private key format. +.It Fl md Ar digest +The digest algorithm to use when signing or resigning. +If not present then the default digest algorithm for the signing key is used +(usually SHA1). +.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 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 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 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 noindef +Disable streaming I/O where it would produce an encoding of indefinite length. +This option currently has no effect. +In future streaming will be enabled by default on all relevant operations +and this option will disable it. +.It Fl nointern +When verifying a message, normally certificates +.Pq 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 nosigs +Don't try to verify the signatures on the message. +.It Fl noverify +Do not verify the signer's certificate of a signed message. +.It Fl out Ar file +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 DER | PEM | SMIME +This specifies the output format for the PKCS#7 structure. +The default is +.Em SMIME , +which writes an +.Em S/MIME +format message. +.Ar PEM +and +.Ar 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 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 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 signer Ar file +A signing certificate when signing or resigning a message; +this option can be used multiple times if more than one signer is required. +If a message is being verified, the signer's certificates will be +written to this file if the verification was successful. +.It Fl stream +The same as +.Fl indef . +.It Fl text +This option adds plain text +.Pq 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. +.El +.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 +.Pq if at all . +You can use the +.Fl text +option to automatically add plain text headers. +.Pp +A +.Qq 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 +.Qq 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. +.Pp +The +.Fl resign +option uses an existing message digest when adding a new signer. +This means that attributes must be present in at least one existing +signer using the same message digest or this operation will fail. +.Pp +The +.Fl stream +and +.Fl indef +options enable experimental streaming I/O support. +As a result the encoding is BER using indefinite length constructed encoding +and no longer DER. +Streaming is supported for the +.Fl encrypt +and +.Fl sign +operations if the content is not detached. +.Pp +Streaming is always used for the +.Fl sign +operation with detached data +but since the content is no longer part of the PKCS#7 structure +the encoding remains DER. +.Sh SMIME EXIT CODES +.Bl -tag -width "XXXX" +.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 signer's certificates. +.El +.Sh SMIME EXAMPLES +Create a cleartext signed message: +.Bd -literal -offset indent +$ openssl smime -sign -in message.txt -text -out mail.msg \e + -signer mycert.pem +.Ed +.Pp +Create an opaque signed message: +.Bd -literal -offset indent +$ openssl smime -sign -in message.txt -text -out mail.msg \e + -nodetach -signer mycert.pem +.Ed +.Pp +Create a signed message, include some additional certificates and +read the private key from another file: +.Bd -literal -offset indent +$ openssl smime -sign -in in.txt -text -out mail.msg \e + -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem +.Ed +.Pp +Create a signed message with two signers: +.Bd -literal -offset indent +openssl smime -sign -in message.txt -text -out mail.msg \e + -signer mycert.pem -signer othercert.pem +.Ed +.Pp +Send a signed message under +.Ux +directly to +.Xr sendmail 8 , +including headers: +.Bd -literal -offset indent +$ 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: +.Bd -literal -offset indent +$ openssl smime -verify -in mail.msg -signer user.pem \e + -out signedtext.txt +.Ed +.Pp +Send encrypted mail using triple DES: +.Bd -literal -offset indent +$ openssl smime -encrypt -in in.txt -from steve@openssl.org \e + -to someone@somewhere -subject "Encrypted message" \e + -des3 -out mail.msg user.pem +.Ed +.Pp +Sign and encrypt mail: +.Bd -literal -offset indent +$ 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: +.Bd -literal -offset indent +$ openssl smime -decrypt -in mail.msg -recip mycert.pem \e + -inkey key.pem" +.Ed +.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: +.Bd -unfilled -offset indent +-----BEGIN PKCS7----- +-----END PKCS7----- +.Ed +.Pp +and using the command: +.Bd -literal -offset indent +$ openssl smime -verify -inform PEM -in signature.pem \e + -content content.txt +.Ed +.Pp +Alternatively, you can base64 decode the signature and use: +.Bd -literal -offset indent +$ openssl smime -verify -inform DER -in signature.der \e + -content content.txt +.Ed +.Pp +Create an encrypted message using 128-bit AES: +.Bd -literal -offset indent +openssl smime -encrypt -in plain.txt -aes128 \e + -out mail.msg cert.pem +.Ed +.Pp +Add a signer to an existing message: +.Bd -literal -offset indent +openssl smime -resign -in mail.msg -signer newsign.pem \e + -out mail2.msg +.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. +.Sh SMIME HISTORY +The use of multiple +.Fl signer +options and the +.Fl resign +command were first added in +.Nm OpenSSL +1.0.0. +.\" +.\" SPEED +.\" +.Sh SPEED +.nr nS 1 +.Nm "openssl speed" +.Bk -words +.Op Cm aes +.Op Cm aes-128-cbc +.Op Cm aes-192-cbc +.Op Cm aes-256-cbc +.Op Cm blowfish +.Op Cm bf-cbc +.Op Cm cast +.Op Cm cast-cbc +.Op Cm des +.Op Cm des-cbc +.Op Cm des-ede3 +.Op Cm dsa +.Op Cm dsa512 +.Op Cm dsa1024 +.Op Cm dsa2048 +.Op Cm hmac +.Op Cm md2 +.Op Cm md4 +.Op Cm md5 +.Op Cm rc2 +.Op Cm rc2-cbc +.Op Cm rc4 +.Op Cm rmd160 +.Op Cm rsa +.Op Cm rsa512 +.Op Cm rsa1024 +.Op Cm rsa2048 +.Op Cm rsa4096 +.Op Cm sha1 +.Op Fl decrypt +.Op Fl elapsed +.Op Fl engine Ar id +.Op Fl evp Ar e +.Op Fl mr +.Op Fl multi Ar number +.Ek +.nr nS 0 +.Pp +The +.Nm speed +command is used to test the performance of cryptographic algorithms. +.Bl -tag -width "XXXX" +.It Bq Cm zero or more test algorithms +If any options are given, +.Nm speed +tests those algorithms, otherwise all of the above are tested. +.It Fl decrypt +Time decryption instead of encryption +.Pq only EVP . +.It Fl engine Ar id +Specifying an engine (by its 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 Fl elapsed +Measure time in real time instead of CPU user time. +.It Fl evp Ar e +Use EVP +.Ar e . +.It Fl mr +Produce machine readable output. +.It Fl multi Ar number +Run +.Ar number +benchmarks in parallel. +.El +.\" +.\" TS +.\" +.Sh TS +.nr nS 1 +.Nm "openssl ts" +.Bk -words +.Fl query +.Op Fl md4 | md5 | ripemd160 | sha | sha1 +.Op Fl cert +.Op Fl config Ar configfile +.Op Fl data Ar file_to_hash +.Op Fl digest Ar digest_bytes +.Op Fl in Ar request.tsq +.Op Fl no_nonce +.Op Fl out Ar request.tsq +.Op Fl policy Ar object_id +.Op Fl text +.Ek +.nr nS 0 +.Pp +.nr nS 1 +.Nm "openssl ts" +.Bk -words +.Fl reply +.Op Fl chain Ar certs_file.pem +.Op Fl config Ar configfile +.Op Fl engine Ar id +.Op Fl in Ar response.tsr +.Op Fl inkey Ar private.pem +.Op Fl out Ar response.tsr +.Op Fl passin Ar arg +.Op Fl policy Ar object_id +.Op Fl queryfile Ar request.tsq +.Op Fl section Ar tsa_section +.Op Fl signer Ar tsa_cert.pem +.Op Fl text +.Op Fl token_in +.Op Fl token_out +.Ek +.nr nS 0 +.Pp +.nr nS 1 +.Nm "openssl ts" +.Bk -words +.Fl verify +.Op Fl CAfile Ar trusted_certs.pem +.Op Fl CApath Ar trusted_cert_path +.Op Fl data Ar file_to_hash +.Op Fl digest Ar digest_bytes +.Op Fl in Ar response.tsr +.Op Fl queryfile Ar request.tsq +.Op Fl token_in +.Op Fl untrusted Ar cert_file.pem +.Ek +.nr nS 0 +.Pp +The +.Nm ts +command is a basic Time Stamping Authority (TSA) client and server +application as specified in RFC 3161 (Time-Stamp Protocol, TSP). +A TSA can be part of a PKI deployment and its role is to provide long +term proof of the existence of a certain datum before a particular time. +Here is a brief description of the protocol: +.Bl -enum +.It +The TSA client computes a one-way hash value for a data file and sends +the hash to the TSA. +.It +The TSA attaches the current date and time to the received hash value, +signs them and sends the time stamp token back to the client. +By creating this token the TSA certifies the existence of the original +data file at the time of response generation. +.It +The TSA client receives the time stamp token and verifies the +signature on it. +It also checks if the token contains the same hash +value that it had sent to the TSA. +.El +.Pp +There is one DER-encoded protocol data unit defined for transporting a time +stamp request to the TSA and one for sending the time stamp response +back to the client. +The +.Nm ts +command has three main functions: +creating a time stamp request based on a data file; +creating a time stamp response based on a request; +and verifying if a response corresponds +to a particular request or a data file. +.Pp +There is no support for sending the requests/responses automatically +over HTTP or TCP yet as suggested in RFC 3161. +Users must send the requests either by FTP or email. +.Pp +The +.Fl query +switch can be used for creating and printing a time stamp +request with the following options: +.Bl -tag -width Ds +.It Fl cert +The TSA is expected to include its signing certificate in the +response. +.It Fl config Ar configfile +The configuration file to use. +This option overrides the +.Ev OPENSSL_CONF +environment variable. +Only the OID section of the config file is used with the +.Fl query +command. +.It Fl data Ar file_to_hash +The data file for which the time stamp request needs to be created. +stdin is the default if neither the +.Fl data +nor the +.Fl digest +option is specified. +.It Fl digest Ar digest_bytes +It is possible to specify the message imprint explicitly without the data +file. +The imprint must be specified in a hexadecimal format, +two characters per byte, +the bytes optionally separated by colons (e.g. 1A:F6:01:... or 1AF601...). +The number of bytes must match the message digest algorithm in use. +.It Fl in Ar request.tsq +This option specifies a previously created time stamp request in DER +format that will be printed into the output file. +Useful when you need to examine the content of a request in human-readable +format. +.It Fl md4|md5|ripemd160|sha|sha1 +The message digest to apply to the data file. +It supports all the message digest algorithms that are supported by the +.Nm dgst +command. +The default is SHA-1. +.It Fl no_nonce +No nonce is specified in the request if this option is given. +Otherwise a 64-bit long pseudo-random none is +included in the request. +It is recommended to use nonce to protect against replay-attacks. +.It Fl out Ar request.tsq +Name of the output file to which the request will be written. +The default is stdout. +.It Fl policy Ar object_id +The policy that the client expects the TSA to use for creating the +time stamp token. +Either the dotted OID notation or OID names defined +in the config file can be used. +If no policy is requested the TSA will +use its own default policy. +.It Fl text +If this option is specified the output is in human-readable text format +instead of DER. +.El +.Pp +A time stamp response (TimeStampResp) consists of a response status +and the time stamp token itself (ContentInfo), +if the token generation was successful. +The +.Fl reply +command is for creating a time stamp +response or time stamp token based on a request and printing the +response/token in human-readable format. +If +.Fl token_out +is not specified the output is always a time stamp response (TimeStampResp), +otherwise it is a time stamp token (ContentInfo). +.Bl -tag -width Ds +.It Fl chain Ar certs_file.pem +The collection of certificates, in PEM format, +that will be included in the response +in addition to the signer certificate if the +.Fl cert +option was used for the request. +This file is supposed to contain the certificate chain +for the signer certificate from its issuer upwards. +The +.Fl reply +command does not build a certificate chain automatically. +.It Fl config Ar configfile +The configuration file to use. +This option overrides the +.Ev OPENSSL_CONF +environment variable. +See +.Sx TS CONFIGURATION FILE OPTIONS +for configurable variables. +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm ts +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 in Ar response.tsr +Specifies a previously created time stamp response or time stamp token, if +.Fl token_in +is also specified, +in DER format that will be written to the output file. +This option does not require a request; +it is useful, for example, +when you need to examine the content of a response or token +or you want to extract the time stamp token from a response. +If the input is a token and the output is a time stamp response a default +.Dq granted +status info is added to the token. +.It Fl inkey Ar private.pem +The signer private key of the TSA in PEM format. +Overrides the +.Cm signer_key +config file option. +.It Fl out Ar response.tsr +The response is written to this file. +The format and content of the file depends on other options (see +.Fl text +and +.Fl token_out ) . +The default is stdout. +.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 policy Ar object_id +The default policy to use for the response unless the client +explicitly requires a particular TSA policy. +The OID can be specified either in dotted notation or with its name. +Overrides the +.Cm default_policy +config file option. +.It Fl queryfile Ar request.tsq +The name of the file containing a DER-encoded time stamp request. +.It Fl section Ar tsa_section +The name of the config file section containing the settings for the +response generation. +If not specified the default TSA section is used; see +.Sx TS CONFIGURATION FILE OPTIONS +for details. +.It Fl signer Ar tsa_cert.pem +The signer certificate of the TSA in PEM format. +The TSA signing certificate must have exactly one extended key usage +assigned to it: timeStamping. +The extended key usage must also be critical, +otherwise the certificate is going to be refused. +Overrides the +.Cm signer_cert +variable of the config file. +.It Fl text +If this option is specified the output is human-readable text format +instead of DER. +.It Fl token_in +This flag can be used together with the +.Fl in +option and indicates that the input is a DER-encoded time stamp token +(ContentInfo) instead of a time stamp response (TimeStampResp). +.It Fl token_out +The output is a time stamp token (ContentInfo) instead of time stamp +response (TimeStampResp). +.El +.Pp +The +.Fl verify +command is for verifying if a time stamp response or time stamp token +is valid and matches a particular time stamp request or data file. +The +.Fl verify +command does not use the configuration file. +.Bl -tag -width Ds +.It Fl CAfile Ar trusted_certs.pem +The name of the file containing a set of trusted self-signed CA +certificates in PEM format. +See the similar option of +.Nm verify +for additional details. +Either this option or +.Fl CApath +must be specified. +.It Fl CApath Ar trusted_cert_path +The name of the directory containing the trused CA certificates of the +client. +See the similar option of +.Nm verify +for additional details. +Either this option or +.Fl CAfile +must be specified. +.It Fl data Ar file_to_hash +The response or token must be verified against +.Ar file_to_hash . +The file is hashed with the message digest algorithm specified in the token. +The +.Fl digest +and +.Fl queryfile +options must not be specified with this one. +.It Fl digest Ar digest_bytes +The response or token must be verified against the message digest specified +with this option. +The number of bytes must match the message digest algorithm +specified in the token. +The +.Fl data +and +.Fl queryfile +options must not be specified with this one. +.It Fl in Ar response.tsr +The time stamp response that needs to be verified, in DER format. +This option in mandatory. +.It Fl queryfile Ar request.tsq +The original time stamp request, in DER format. +The +.Fl data +and +.Fl digest +options must not be specified with this one. +.It Fl token_in +This flag can be used together with the +.Fl in +option and indicates that the input is a DER-encoded time stamp token +(ContentInfo) instead of a time stamp response (TimeStampResp). +.It Fl untrusted Ar cert_file.pem +Set of additional untrusted certificates in PEM format which may be +needed when building the certificate chain for the TSA's signing +certificate. +This file must contain the TSA signing certificate and +all intermediate CA certificates unless the response includes them. +.El +.Sh TS CONFIGURATION FILE OPTIONS +The +.Fl query +and +.Fl reply +options make use of a configuration file defined by the +.Ev OPENSSL_CONF +environment variable. +The +.Fl query +option uses only the symbolic OID names section +and it can work without it. +However, the +.Fl reply +option needs the config file for its operation. +.Pp +When there is a command line switch equivalent of a variable the +switch always overrides the settings in the config file. +.Bl -tag -width Ds +.It Cm tsa Ar section , Cm default_tsa +This is the main section and it specifies the name of another section +that contains all the options for the +.Fl reply +option. +This default section can be overridden with the +.Fl section +command line switch. +.It Cm oid_file +See +.Nm ca +for a description. +.It Cm oid_section +See +.Nm ca +for a description. +.It Cm serial +The name of the file containing the hexadecimal serial number of the +last time stamp response created. +This number is incremented by 1 for each response. +If the file does not exist at the time of response +generation a new file is created with serial number 1. +This parameter is mandatory. +.It Cm crypto_device +Specifies the +.Nm OpenSSL +engine that will be set as the default for +all available algorithms. +.It Cm signer_cert +TSA signing certificate, in PEM format. +The same as the +.Fl signer +command line option. +.It Cm certs +A file containing a set of PEM-encoded certificates that need to be +included in the response. +The same as the +.Fl chain +command line option. +.It Cm signer_key +The private key of the TSA, in PEM format. +The same as the +.Fl inkey +command line option. +.It Cm default_policy +The default policy to use when the request does not mandate any policy. +The same as the +.Fl policy +command line option. +.It Cm other_policies +Comma separated list of policies that are also acceptable by the TSA +and used only if the request explicitly specifies one of them. +.It Cm digests +The list of message digest algorithms that the TSA accepts. +At least one algorithm must be specified. +This parameter is mandatory. +.It Cm accuracy +The accuracy of the time source of the TSA in seconds, milliseconds +and microseconds. +For example, secs:1, millisecs:500, microsecs:100. +If any of the components is missing, +zero is assumed for that field. +.It Cm clock_precision_digits +Specifies the maximum number of digits, which represent the fraction of +seconds, that need to be included in the time field. +The trailing zeroes must be removed from the time, +so there might actually be fewer digits, +or no fraction of seconds at all. +The maximum value is 6; +the default is 0. +.It Cm ordering +If this option is yes, +the responses generated by this TSA can always be ordered, +even if the time difference between two responses is less +than the sum of their accuracies. +The default is no. +.It Cm tsa_name +Set this option to yes if the subject name of the TSA must be included in +the TSA name field of the response. +The default is no. +.It Cm ess_cert_id_chain +The SignedData objects created by the TSA always contain the +certificate identifier of the signing certificate in a signed +attribute (see RFC 2634, Enhanced Security Services). +If this option is set to yes and either the +.Cm certs +variable or the +.Fl chain +option is specified then the certificate identifiers of the chain will also +be included in the SigningCertificate signed attribute. +If this variable is set to no, +only the signing certificate identifier is included. +The default is no. +.El +.Sh TS ENVIRONMENT VARIABLES +.Ev OPENSSL_CONF +contains the path of the configuration file and can be +overridden by the +.Fl config +command line option. +.Sh TS EXAMPLES +All the examples below presume that +.Ev OPENSSL_CONF +is set to a proper configuration file, +e.g. the example configuration file +.Pa openssl/apps/openssl.cnf +will do. +.Pp +To create a time stamp request for design1.txt with SHA-1 +without nonce and policy and no certificate is required in the response: +.Bd -literal -offset indent +$ openssl ts -query -data design1.txt -no_nonce \e + -out design1.tsq +.Ed +.Pp +To create a similar time stamp request but specifying the message imprint +explicitly: +.Bd -literal -offset indent +$ openssl ts -query \e + -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e + -no_nonce -out design1.tsq +.Ed +.Pp +To print the content of the previous request in human readable format: +.Bd -literal -offset indent +$ openssl ts -query -in design1.tsq -text +.Ed +.Pp +To create a time stamp request which includes the MD5 digest +of design2.txt, requests the signer certificate and nonce, +specifies a policy ID +(assuming the tsa_policy1 name is defined in the +OID section of the config file): +.Bd -literal -offset indent +$ openssl ts -query -data design2.txt -md5 \e + -policy tsa_policy1 -cert -out design2.tsq +.Ed +.Pp +Before generating a response, +a signing certificate must be created for the TSA that contains the +.Cm timeStamping +critical extended key usage extension +without any other key usage extensions. +You can add the +.Dq extendedKeyUsage = critical,timeStamping +line to the user certificate section +of the config file to generate a proper certificate. +See the +.Nm req , +.Nm ca , +and +.Nm x509 +commands for instructions. +The examples below assume that cacert.pem contains the certificate of the CA, +tsacert.pem is the signing certificate issued by cacert.pem and +tsakey.pem is the private key of the TSA. +.Pp +To create a time stamp response for a request: +.Bd -literal -offset indent +$ openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \e + -signer tsacert.pem -out design1.tsr +.Ed +.Pp +If you want to use the settings in the config file you could just write: +.Bd -literal -offset indent +$ openssl ts -reply -queryfile design1.tsq -out design1.tsr +.Ed +.Pp +To print a time stamp reply to stdout in human readable format: +.Bd -literal -offset indent +$ openssl ts -reply -in design1.tsr -text +.Ed +.Pp +To create a time stamp token instead of time stamp response: +.Bd -literal -offset indent +$ openssl ts -reply -queryfile design1.tsq \e + -out design1_token.der -token_out +.Ed +.Pp +To print a time stamp token to stdout in human readable format: +.Bd -literal -offset indent +$ openssl ts -reply -in design1_token.der -token_in \e + -text -token_out +.Ed +.Pp +To extract the time stamp token from a response: +.Bd -literal -offset indent +$ openssl ts -reply -in design1.tsr -out design1_token.der \e + -token_out +.Ed +.Pp +To add +.Dq granted +status info to a time stamp token thereby creating a valid response: +.Bd -literal -offset indent +$ openssl ts -reply -in design1_token.der \e + -token_in -out design1.tsr +.Ed +.Pp +To verify a time stamp reply against a request: +.Bd -literal -offset indent +$ openssl ts -verify -queryfile design1.tsq -in design1.tsr \e + -CAfile cacert.pem -untrusted tsacert.pem +.Ed +.Pp +To verify a time stamp reply that includes the certificate chain: +.Bd -literal -offset indent +$ openssl ts -verify -queryfile design2.tsq -in design2.tsr \e + -CAfile cacert.pem +.Ed +.Pp +To verify a time stamp token against the original data file: +.Bd -literal -offset indent +$ openssl ts -verify -data design2.txt -in design2.tsr \e + -CAfile cacert.pem +.Ed +.Pp +To verify a time stamp token against a message imprint: +.Bd -literal -offset indent +$ openssl ts -verify \e + -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \e + -in design2.tsr -CAfile cacert.pem +.Ed +.Sh TS BUGS +No support for time stamps over SMTP, though it is quite easy +to implement an automatic email-based TSA with +.Xr procmail +and +.Xr perl 1 . +Pure TCP/IP is not supported. +.Pp +The file containing the last serial number of the TSA is not +locked when being read or written. +This is a problem if more than one instance of +.Nm OpenSSL +is trying to create a time stamp +response at the same time. +.Pp +Look for the FIXME word in the source files. +.Pp +The source code should really be reviewed by somebody else, too. +.Pp +More testing is needed. +.Sh TS AUTHORS +.An Zoltan Glozik Aq Mt zglozik@opentsa.org , +OpenTSA project +.Pq Lk http://www.opentsa.org . +.\" +.\" SPKAC +.\" +.Sh SPKAC +.nr nS 1 +.Nm "openssl spkac" +.Bk -words +.Op Fl challenge Ar string +.Op Fl engine Ar id +.Op Fl in Ar file +.Op Fl key Ar keyfile +.Op Fl noout +.Op Fl out Ar file +.Op Fl passin Ar arg +.Op Fl pubkey +.Op Fl spkac Ar spkacname +.Op Fl spksect Ar section +.Op Fl verify +.Ek +.nr nS 0 +.Pp +The +.Nm spkac +command processes Netscape signed public key and challenge +.Pq 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: +.Bl -tag -width Ds +.It Fl challenge Ar string +Specifies the challenge string if an SPKAC is being created. +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm spkac +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 in Ar file +This specifies the input +.Ar file +to read from, or standard input if this option is not specified. +Ignored if the +.Fl key +option is used. +.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 noout +Don't output the text version of the SPKAC +.Pq not used if an SPKAC is being created . +.It Fl out Ar file +Specifies the output +.Ar file +to write to, or standard output by default. +.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 pubkey +Output the public key of an SPKAC +.Pq not used 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 verify +Verifies the digital signature on the supplied SPKAC. +.El +.Sh SPKAC EXAMPLES +Print out the contents of an SPKAC: +.Pp +.Dl $ openssl spkac -in spkac.cnf +.Pp +Verify the signature of an SPKAC: +.Pp +.Dl $ openssl spkac -in spkac.cnf -noout -verify +.Pp +Create an SPKAC using the challenge string +.Qq hello : +.Pp +.Dl $ openssl spkac -key key.pem -challenge hello -out spkac.cnf +.Pp +Example of an SPKAC, +.Pq long lines split up for clarity : +.Bd -unfilled -offset indent +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 +.Qq replay attack . +.\" +.\" VERIFY +.\" +.Sh VERIFY +.nr nS 1 +.Nm "openssl verify" +.Bk -words +.Op Fl CAfile Ar file +.Op Fl CApath Ar directory +.Op Fl check_ss_sig +.Op Fl crl_check +.Op Fl crl_check_all +.Op Fl engine Ar id +.Op Fl explicit_policy +.Op Fl extended_crl +.Op Fl help +.Op Fl ignore_critical +.Op Fl inhibit_any +.Op Fl inhibit_map +.Op Fl issuer_checks +.Op Fl policy_check +.Op Fl purpose Ar purpose +.Op Fl untrusted Ar file +.Op Fl verbose +.Op Fl x509_strict +.Op Fl +.Op Ar certificates +.Ek +.nr nS 0 +.Pp +The +.Nm verify +command verifies certificate chains. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl check_ss_sig +Verify the signature on the self-signed root CA. +This is disabled by default +because it doesn't add any security. +.It Fl CAfile Ar file +A +.Ar file +of trusted certificates. +The +.Ar file +should contain multiple certificates in PEM format, concatenated together. +.It Fl CApath Ar 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). +The +.Nm c_rehash +script distributed with OpenSSL +will automatically create symbolic links to a directory of certificates. +.It Fl crl_check +Checks end entity certificate validity by attempting to look up a valid CRL. +If a valid CRL cannot be found an error occurs. +.It Fl crl_check_all +Checks the validity of all certificates in the chain by attempting +to look up valid CRLs. +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm verify +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 explicit_policy +Set policy variable require-explicit-policy (see RFC 3280 et al). +.It Fl extended_crl +Enable extended CRL features such as indirect CRLs and alternate CRL +signing keys. +.It Fl help +Prints out a usage message. +.It Fl ignore_critical +Normally if an unhandled critical extension is present which is not +supported by +.Nm OpenSSL , +the certificate is rejected (as required by RFC 3280 et al). +If this option is set, critical extensions are ignored. +.It Fl inhibit_any +Set policy variable inhibit-any-policy (see RFC 3280 et al). +.It Fl inhibit_map +Set policy variable inhibit-policy-mapping (see RFC 3280 et al). +.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 policy_check +Enables certificate policy processing. +.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 , +.Ar smimeencrypt , crlsign , +.Ar any , +and +.Ar ocsphelper . +See the +.Sx VERIFY OPERATION +section for more information. +.It Fl untrusted Ar file +A +.Ar file +of untrusted certificates. +The +.Ar file +should contain multiple certificates. +.It Fl verbose +Print extra information about the operations being performed. +.It Fl x509_strict +Disable workarounds for broken certificates which have to be disabled +for strict X.509 compliance. +.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 +.Sq - . +.It Ar certificates +One or more +.Ar certificates +to verify. +If no certificate files are included, an attempt is made to read +a certificate from standard input. +They should all be in PEM format. +.El +.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 issuer's 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 +.Qq looking up the issuer's 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 issuer's 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 +.Pq if present +must match the subject key identifier +.Pq if present +and issuer and serial number of the candidate issuer; in addition the +.Em keyUsage +extension of the candidate issuer +.Pq 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 +.Qq 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 X.509 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, 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: +.Bd -unfilled +\& 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 the 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 openssl/x509_vfy.h . +Some of the error codes are defined but never returned: these are described +as +.Qq unused . +.Bl -tag -width "XXXX" +.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. +.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. +.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. +.It Ar 12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired +The CRL has expired. +.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. +.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. +.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. +.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. +.El +.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, only the certificates in the file will +be recognised. +.Pp +Previous versions of +.Nm OpenSSL +assumed certificates with matching subject name were identical and +mishandled them. +.\" +.\" VERSION +.\" +.Sh VERSION +.Nm openssl version +.Op Fl abdfopv +.Pp +The +.Nm version +command is used to print out version information about +.Nm OpenSSL . +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl a +All information: this is the same as setting all the other flags. +.It Fl b +The date the current version of +.Nm OpenSSL +was built. +.It Fl d +.Ev OPENSSLDIR +setting. +.It Fl f +Compilation flags. +.It Fl o +Option information: various options set when the library was built. +.It Fl p +Platform setting. +.It Fl v +The current +.Nm OpenSSL +version. +.El +.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 +.nr nS 1 +.Nm "openssl x509" +.Bk -words +.Op Fl C +.Op Fl addreject Ar arg +.Op Fl addtrust Ar arg +.Op Fl alias +.Op Fl CA Ar file +.Op Fl CAcreateserial +.Op Fl CAform Ar DER | PEM +.Op Fl CAkey Ar file +.Op Fl CAkeyform Ar DER | PEM +.Op Fl CAserial Ar file +.Op Fl certopt Ar option +.Op Fl checkend Ar arg +.Op Fl clrext +.Op Fl clrreject +.Op Fl clrtrust +.Op Fl dates +.Op Fl days Ar arg +.Op Fl email +.Op Fl enddate +.Op Fl engine Ar id +.Op Fl extensions Ar section +.Op Fl extfile Ar file +.Op Fl fingerprint +.Op Fl hash +.Op Fl in Ar file +.Op Fl inform Ar DER | NET | PEM +.Op Fl issuer +.Op Fl issuer_hash +.Op Fl issuer_hash_old +.Op Fl keyform Ar DER | PEM +.Op Fl md2 | md5 | sha1 +.Op Fl modulus +.Op Fl nameopt Ar option +.Op Fl noout +.Op Fl ocsp_uri +.Op Fl ocspid +.Op Fl out Ar file +.Op Fl outform Ar DER | NET | PEM +.Op Fl passin Ar arg +.Op Fl pubkey +.Op Fl purpose +.Op Fl req +.Op Fl serial +.Op Fl set_serial Ar n +.Op Fl setalias Ar arg +.Op Fl signkey Ar file +.Op Fl startdate +.Op Fl subject +.Op Fl subject_hash +.Op Fl subject_hash_old +.Op Fl text +.Op Fl trustout +.Op Fl x509toreq +.Ek +.nr nS 0 +.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 +.Qq 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 +.Bl -tag -width "XXXX" +.It Fl engine Ar id +Specifying an engine (by its unique +.Ar id +string) will cause +.Nm x509 +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 in Ar file +This specifies the input +.Ar file +to read a certificate from, or standard input if this option is not specified. +.It Fl inform Ar DER | NET | PEM +This specifies the input format. +Normally, the command will expect an X.509 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 md2 | md5 | sha1 +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, MD5 is used. +If the key being used to sign with is a DSA key, +this option has no effect: SHA1 is always used with DSA keys. +.It Fl out Ar file +This specifies the output +.Ar file +to write to, or standard output by default. +.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 passin Ar arg +The key password source. +For more information about the format of +.Ar arg , +see the +.Sx PASS PHRASE ARGUMENTS +section above. +.El +.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 SETTINGS +section. +.Bl -tag -width "XXXX" +.It Fl C +This outputs the certificate in the form of a C source file. +.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 also be used more than once to set multiple options. +See the +.Sx X509 TEXT OPTIONS +section for more information. +.It Fl dates +Prints out the start and expiry dates of a certificate. +.It Fl email +Outputs the email address(es), if any. +.It Fl enddate +Prints out the expiry date of the certificate; that is, the +.Em notAfter +date. +.It Fl fingerprint +Prints out the digest of the DER-encoded version of the whole certificate +(see +.Sx DIGEST OPTIONS ) . +.It Fl hash +A synonym for +.Fl subject_hash , +for backwards compatibility. +.It Fl issuer +Outputs the issuer name. +.It Fl issuer_hash +Outputs the +.Qq hash +of the certificate issuer name. +.It Fl issuer_hash_old +Outputs the +.Qq hash +of the certificate issuer name using the older algorithm +as used by +.Nm OpenSSL +versions before 1.0.0. +.It Fl modulus +This option prints out the value of the modulus of the public key +contained in the certificate. +.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 noout +This option prevents output of the encoded version of the request. +.It Fl ocsp_uri +Outputs the OCSP responder addresses, if any. +.It Fl ocspid +Print OCSP hash values for the subject name and public key. +.It Fl pubkey +Output the public key. +.It Fl serial +Outputs the certificate serial number. +.It Fl startdate +Prints out the start date of the certificate; that is, the +.Em notBefore +date. +.It Fl subject +Outputs the subject name. +.It Fl subject_hash +Outputs the +.Qq 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_hash_old +Outputs the +.Qq hash +of the certificate subject name using the older algorithm +as used by +.Nm OpenSSL +versions before 1.0.0. +.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. +.El +.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 +.Qq alias . +.Pp +Normally, when a certificate is being verified at least one certificate +must be +.Qq 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. +.Bl -tag -width "XXXX" +.It Fl addreject Ar arg +Adds a prohibited use. +It accepts the same values as the +.Fl addtrust +option. +.It Fl addtrust Ar arg +Adds a trusted certificate use. +Any object name can be used here, but currently only +.Ar clientAuth +.Pq SSL client use , +.Ar serverAuth +.Pq SSL server use , +and +.Ar emailProtection +.Pq S/MIME email +are used. +Other +.Nm OpenSSL +applications may define additional uses. +.It Fl alias +Outputs the certificate alias, if any. +.It Fl clrreject +Clears all the prohibited or rejected uses of the certificate. +.It Fl clrtrust +Clears all the permitted or trusted uses of the certificate. +.It Fl purpose +This option performs tests on the certificate extensions and outputs +the results. +For a more complete description, see the +.Sx X.509 CERTIFICATE EXTENSIONS +section. +.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 +.Qq Steve's Certificate . +.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. +.El +.Sh X509 SIGNING OPTIONS +The +.Nm x509 +utility can be used to sign certificates and requests: it +can thus behave like a +.Qq mini CA . +.Bl -tag -width "XXXX" +.It Fl CA Ar file +Specifies the CA certificate to be used for signing. +When this option is present, +.Nm x509 +behaves like a +.Qq 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 CA's 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 CAcreateserial +With this option the CA serial number file is created if it does not exist: +it will contain the serial number +.Sq 02 +and the certificate being signed will have +.Sq 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 CAform Ar DER | PEM +The format of the CA certificate file. +The default is +.Ar PEM . +.It Fl CAkey Ar file +Sets the CA private key to sign a certificate with. +If this option is not specified, it is assumed that the CA private key +is present in the CA certificate file. +.It Fl CAkeyform Ar DER | PEM +The format of the CA private key. +The default is +.Ar PEM . +.It Fl CAserial Ar file +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 consists 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 checkend Ar arg +Check whether the certificate expires in the next +.Ar arg +seconds. +If so, exit with return value 1; +otherwise exit with return value 0. +.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 days Ar arg +Specifies the number of days to make a certificate valid for. +The default is 30 days. +.It Fl extensions Ar section +The section to add certificate extensions from. +If this option is not specified, the extensions should either be +contained in the unnamed +.Pq default +section or the default section should contain a variable called +.Qq extensions +which contains the section to use. +.It Fl extfile Ar file +File containing certificate extensions to use. +If not specified, no extensions are added to the certificate. +.It Fl keyform Ar DER | PEM +Specifies the format +.Pq DER or PEM +of the private key file used in the +.Fl signkey +option. +.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 +.Sq 0x ) . +Negative serial numbers can also be specified but their use is not recommended. +.It Fl signkey Ar file +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 +.Pq 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, a self-signed certificate +is created using the supplied private key using the subject name in +the request. +.It Fl x509toreq +Converts a certificate into a certificate request. +The +.Fl signkey +option is used to pass the required private key. +.El +.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 +.Qq 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 +.Sq - +to turn the option off. +Only +.Ar compat , +.Ar RFC2253 , +.Ar oneline , +and +.Ar multiline +will normally be used. +.Bl -tag -width "XXXX" +.It Ar align +Align field values for a more readable output. +Only usable with +.Ar sep_multiline . +.It Ar compat +Use the old format. +This is equivalent to specifying no name options at all. +.It Ar dn_rev +Reverse the fields of the DN. +This is required by RFC 2253. +As a side effect, this also reverses the order of multiple AVAs but this is +permissible. +.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_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 RFC 2253 #XXXX... format. +.It Ar dump_nostr +Dump non-character string types +.Pq for example OCTET STRING ; +if this option is not set, non-character string types will be displayed +as though each content octet represents a single character. +.It Ar dump_unknown +Dump any field whose OID is not recognised by +.Nm OpenSSL . +.It Ar esc_2253 +Escape the +.Qq special +characters required by RFC 2253 in a field that is +.Dq \& ,+"\*(Lt\*(Gt; . +Additionally, +.Sq # +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 +.Pq space +and the delete +.Pq 0x7f +character. +They are escaped using the RFC 2253 \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 multiline +A multiline format. +It is equivalent to +.Ar esc_ctrl , esc_msb , sep_multiline , +.Ar space_eq , lname , +and +.Ar align . +.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 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 +.Qq 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 oneline +A oneline format which is more readable than +.Ar 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 space_eq , +and +.Ar sname +options. +.It Ar RFC2253 +Displays names compatible with RFC 2253; equivalent to +.Ar esc_2253 , esc_ctrl , +.Ar esc_msb , utf8 , dump_nostr , dump_unknown , +.Ar dump_der , sep_comma_plus , dn_rev , +and +.Ar sname . +.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 +.Qq 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 +.Sq + +for the AVA separator. +It also indents the fields by four characters. +.It Ar show_type +Show the type of the ASN1 character string. +The type precedes the field contents. +For example +.Qq BMPSTRING: Hello World . +.It Ar space_eq +Places spaces round the +.Sq = +character which follows the field name. +.It Ar use_quote +Escapes some characters by surrounding the whole string with +.Sq \&" +characters. +Without the option, all escaping is done with the +.Sq \e +character. +.It Ar utf8 +Convert all strings to UTF8 format first. +This is required by RFC 2253. +If you are lucky enough to have a UTF8 compatible terminal, +the use of this option (and +.Em not +setting +.Ar esc_msb ) +may result in the correct display of multibyte +.Pq international +characters. +If this option is not present, 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. +.El +.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. +.Bl -tag -width "XXXX" +.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 . +.It Ar compatible +Use the old format. +This is equivalent to specifying no output options at all. +.It Ar ext_default +Retain default extension behaviour: attempt to print out unsupported +certificate extensions. +.It Ar ext_dump +Hex dump unsupported extensions. +.It Ar ext_error +Print an error message for unsupported certificate extensions. +.It Ar ext_parse +ASN1 parse unsupported extensions. +.It Ar no_aux +Don't print out certificate trust information. +.It Ar no_extensions +Don't print out any X509V3 extensions. +.It Ar no_header +Don't print header information: that is, the lines saying +.Qq Certificate +and +.Qq Data . +.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_serial +Don't print out the serial number. +.It Ar no_sigdump +Don't give a hexadecimal dump of the certificate signature. +.It Ar no_signame +Don't print out the signature algorithm used. +.It Ar no_subject +Don't print out the subject name. +.It Ar no_validity +Don't print the validity; that is, the +.Em notBefore +and +.Em notAfter +fields. +.It Ar no_version +Don't print out the version number. +.El +.Sh X509 EXAMPLES +Display the contents of a certificate: +.Pp +.Dl $ openssl x509 -in cert.pem -noout -text +.Pp +Display the certificate serial number: +.Pp +.Dl $ openssl x509 -in cert.pem -noout -serial +.Pp +Display the certificate subject name: +.Pp +.Dl $ openssl x509 -in cert.pem -noout -subject +.Pp +Display the certificate subject name in RFC 2253 form: +.Pp +.Dl $ openssl x509 -in cert.pem -noout -subject -nameopt RFC2253 +.Pp +Display the certificate subject name in oneline form on a terminal +supporting UTF8: +.Bd -literal -offset indent +$ openssl x509 -in cert.pem -noout -subject \e + -nameopt oneline,-esc_msb +.Ed +.Pp +Display the certificate MD5 fingerprint: +.Pp +.Dl $ openssl x509 -in cert.pem -noout -fingerprint +.Pp +Display the certificate SHA1 fingerprint: +.Pp +.Dl $ openssl x509 -sha1 -in cert.pem -noout -fingerprint +.Pp +Convert a certificate from PEM to DER format: +.Pp +.Dl "$ openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER" +.Pp +Convert a certificate to a certificate request: +.Bd -literal -offset indent +$ openssl x509 -x509toreq -in cert.pem -out req.pem \e + -signkey key.pem +.Ed +.Pp +Convert a certificate request into a self-signed certificate using +extensions for a CA: +.Bd -literal -offset indent +$ 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: +.Bd -literal -offset indent +$ 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 set its alias to +.Qq Steve's Class 1 CA : +.Bd -literal -offset indent +$ openssl x509 -in cert.pem -addtrust clientAuth \e + -setalias "Steve's Class 1 CA" -out trust.pem +.Ed +.Sh X509 NOTES +The PEM format uses the header and footer lines: +.Bd -unfilled -offset indent +-----BEGIN CERTIFICATE----- +-----END CERTIFICATE----- +.Ed +.Pp +It will also handle files containing: +.Bd -unfilled -offset indent +-----BEGIN X509 CERTIFICATE----- +-----END X509 CERTIFICATE----- +.Ed +.Pp +Trusted certificates have the lines: +.Bd -unfilled -offset indent +-----BEGIN TRUSTED CERTIFICATE----- +-----END TRUSTED CERTIFICATE----- +.Ed +.Pp +The conversion to UTF8 format used with the name options assumes that +T61Strings use the ISO 8859-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 +.Qq 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 X.509 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, it is a CA; +if the CA flag is false, 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 +.Qq 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 +.Pq 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 +.Pq 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. +.Bl -tag -width "XXXX" +.It Ar SSL Client +The extended key usage extension must be absent or include the +.Qq 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 +.Qq 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 +.Qq 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 +.Qq 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 +.Qq 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 +.Qq 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. +.El +.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. +.Sh X509 HISTORY +Before +.Nm OpenSSL +0.9.8, +the default digest for RSA keys was MD5. +.Pp +The hash algorithm used in the +.Fl subject_hash +and +.Fl issuer_hash +options before +.Nm OpenSSL +1.0.0 was based on the deprecated MD5 algorithm and the encoding +of the distinguished name. +In +.Nm OpenSSL +1.0.0 and later it is based on a canonical version of the DN using SHA1. +This means that any directories using the old form +must have their links rebuilt using +.Ar c_rehash +or similar. +.\" +.\" FILES +.\" +.Sh FILES +.Bl -tag -width "/etc/ssl/openssl.cnf" -compact +.It /etc/ssl/ +Default config directory for +.Nm openssl . +.It /etc/ssl/lib/ +Unused. +.It /etc/ssl/private/ +Default private key directory. +.It /etc/ssl/openssl.cnf +Default configuration file for +.Nm openssl . +.It /etc/ssl/x509v3.cnf +Default configuration file for +.Nm x509 +certificates. +.El +.\" +.\" SEE ALSO +.\" +.Sh SEE ALSO +.Xr nginx 8 , +.Xr sendmail 8 , +.Xr ssl 8 , +.Xr starttls 8 +.Sh STANDARDS +.Rs +.%D February 1995 +.%Q Netscape Communications Corp. +.%T The SSL Protocol +.Re +.Pp +.Rs +.%D November 1996 +.%Q Netscape Communications Corp. +.%T The SSL 3.0 Protocol +.Re +.Pp +.Rs +.%A T. Dierks +.%A C. Allen +.%D January 1999 +.%R RFC 2246 +.%T The TLS Protocol Version 1.0 +.Re +.Pp +.Rs +.%A M. Wahl +.%A S. Killie +.%A T. Howes +.%D December 1997 +.%R RFC 2253 +.%T Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names +.Re +.Pp +.Rs +.%A B. Kaliski +.%D March 1998 +.%R RFC 2315 +.%T PKCS #7: Cryptographic Message Syntax Version 1.5 +.Re +.Pp +.Rs +.%A R. Housley +.%A W. Ford +.%A W. Polk +.%A D. Solo +.%D January 1999 +.%R RFC 2459 +.%T Internet X.509 Public Key Infrastructure Certificate and CRL Profile +.Re +.Pp +.Rs +.%A M. Myers +.%A R. Ankney +.%A A. Malpani +.%A S. Galperin +.%A C. Adams +.%D June 1999 +.%R RFC 2560 +.%T X.509 Internet Public Key Infrastructure Online Certificate Status Protocol \(en OCSP +.Re +.Pp +.Rs +.%A R. Housley +.%D June 1999 +.%R RFC 2630 +.%T Cryptographic Message Syntax +.Re +.Pp +.Rs +.%A P. Chown +.%D June 2002 +.%R RFC 3268 +.%T Advanced Encryption Standard (AES) Ciphersuites for Transport Layer Security(TLS) +.Re +.\" +.\" OPENSSL HISTORY +.\" +.Sh HISTORY +The +.Xr openssl 1 +document appeared in +.Nm OpenSSL +0.9.2. +The +.Cm list- Ns XXX Ns Cm -commands +pseudo-commands were added in +.Nm OpenSSL +0.9.3; +the +.Cm no- Ns XXX +pseudo-commands were added in +.Nm OpenSSL +0.9.5a; +the +.Cm list- Ns XXX Ns Cm -algorithms +pseudo-commands were added in +.Nm OpenSSL +1.0.0. |