ag/cpython-source-deps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Import OpenSSL 1.0.2k (as of svn r86089)

Browse Source
This commit is contained in:
Zachary Ware
2017-05-22 14:30:47 -05:00
parent d239d63057
commit ccd3ab4aff
2486 changed files with 943951 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
doc/apps/CA.pl.pod Normal file
View File

@@ -0,0 +1,179 @@
=pod
=head1 NAME
CA.pl - friendlier interface for OpenSSL certificate programs
=head1 SYNOPSIS
B<CA.pl>
[B<-?>]
[B<-h>]
[B<-help>]
[B<-newcert>]
[B<-newreq>]
[B<-newreq-nodes>]
[B<-newca>]
[B<-xsign>]
[B<-sign>]
[B<-signreq>]
[B<-signcert>]
[B<-verify>]
[B<files>]
=head1 DESCRIPTION
The B<CA.pl> script is a perl script that supplies the relevant command line
arguments to the B<openssl> command for some common certificate operations.
It is intended to simplify the process of certificate creation and management
by the use of some simple options.
=head1 COMMAND OPTIONS
=over 4
=item B<?>, B<-h>, B<-help>
prints a usage message.
=item B<-newcert>
creates a new self signed certificate. The private key is written to the file
"newkey.pem" and the request written to the file "newreq.pem".
=item B<-newreq>
creates a new certificate request. The private key is written to the file
"newkey.pem" and the request written to the file "newreq.pem".
=item B<-newreq-nodes>
is like B<-newreq> except that the private key will not be encrypted.
=item B<-newca>
creates a new CA hierarchy for use with the B<ca> program (or the B<-signcert>
and B<-xsign> options). The user is prompted to enter the filename of the CA
certificates (which should also contain the private key) or by hitting ENTER
details of the CA will be prompted for. The relevant files and directories
are created in a directory called "demoCA" in the current directory.
=item B<-pkcs12>
create a PKCS#12 file containing the user certificate, private key and CA
certificate. It expects the user certificate and private key to be in the
file "newcert.pem" and the CA certificate to be in the file demoCA/cacert.pem,
it creates a file "newcert.p12". This command can thus be called after the
B<-sign> option. The PKCS#12 file can be imported directly into a browser.
If there is an additional argument on the command line it will be used as the
"friendly name" for the certificate (which is typically displayed in the browser
list box), otherwise the name "My Certificate" is used.
=item B<-sign>, B<-signreq>, B<-xsign>
calls the B<ca> program to sign a certificate request. It expects the request
to be in the file "newreq.pem". The new certificate is written to the file
"newcert.pem" except in the case of the B<-xsign> option when it is written
to standard output.
=item B<-signCA>
this option is the same as the B<-signreq> option except it uses the configuration
file section B<v3_ca> and so makes the signed request a valid CA certificate. This
is useful when creating intermediate CA from a root CA.
=item B<-signcert>
this option is the same as B<-sign> except it expects a self signed certificate
to be present in the file "newreq.pem".
=item B<-verify>
verifies certificates against the CA certificate for "demoCA". If no certificates
are specified on the command line it tries to verify the file "newcert.pem".
=item B<files>
one or more optional certificate file names for use with the B<-verify> command.
=back
=head1 EXAMPLES
Create a CA hierarchy:
CA.pl -newca
Complete certificate creation example: create a CA, create a request, sign
the request and finally create a PKCS#12 file containing it.
CA.pl -newca
CA.pl -newreq
CA.pl -signreq
CA.pl -pkcs12 "My Test Certificate"
=head1 DSA CERTIFICATES
Although the B<CA.pl> creates RSA CAs and requests it is still possible to
use it with DSA certificates and requests using the L<req(1)|req(1)> command
directly. The following example shows the steps that would typically be taken.
Create some DSA parameters:
openssl dsaparam -out dsap.pem 1024
Create a DSA CA certificate and private key:
openssl req -x509 -newkey dsa:dsap.pem -keyout cacert.pem -out cacert.pem
Create the CA directories and files:
CA.pl -newca
enter cacert.pem when prompted for the CA file name.
Create a DSA certificate request and private key (a different set of parameters
can optionally be created first):
openssl req -out newreq.pem -newkey dsa:dsap.pem
Sign the request:
CA.pl -signreq
=head1 NOTES
Most of the filenames mentioned can be modified by editing the B<CA.pl> script.
If the demoCA directory already exists then the B<-newca> command will not
overwrite it and will do nothing. This can happen if a previous call using
the B<-newca> option terminated abnormally. To get the correct behaviour
delete the demoCA directory if it already exists.
Under some environments it may not be possible to run the B<CA.pl> script
directly (for example Win32) and the default configuration file location may
be wrong. In this case the command:
perl -S CA.pl
can be used and the B<OPENSSL_CONF> environment variable changed to point to
the correct path of the configuration file "openssl.cnf".
The script is intended as a simple front end for the B<openssl> program for use
by a beginner. Its behaviour isn't always what is wanted. For more control over the
behaviour of the certificate commands call the B<openssl> command directly.
=head1 ENVIRONMENT VARIABLES
The variable B<OPENSSL_CONF> if defined allows an alternative configuration
file location to be specified, it should contain the full path to the
configuration file, not just its directory.
=head1 SEE ALSO
L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<req(1)|req(1)>, L<pkcs12(1)|pkcs12(1)>,
L<config(5)|config(5)>
=cut

185
doc/apps/asn1parse.pod Normal file
View File

@@ -0,0 +1,185 @@
=pod
=head1 NAME
asn1parse - ASN.1 parsing tool
=head1 SYNOPSIS
B<openssl> B<asn1parse>
[B<-inform PEM|DER>]
[B<-in filename>]
[B<-out filename>]
[B<-noout>]
[B<-offset number>]
[B<-length number>]
[B<-i>]
[B<-oid filename>]
[B<-dump>]
[B<-dlimit num>]
[B<-strparse offset>]
[B<-genstr string>]
[B<-genconf file>]
=head1 DESCRIPTION
The B<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.
=head1 OPTIONS
=over 4
=item B<-inform> B<DER|PEM>
the input format. B<DER> is binary format and B<PEM> (the default) is base64
encoded.
=item B<-in filename>
the input file, default is standard input
=item B<-out filename>
output file to place the DER encoded data into. If this
option is not present then no data will be output. This is most useful when
combined with the B<-strparse> option.
=item B<-noout>
don't output the parsed version of the input file.
=item B<-offset number>
starting offset to begin parsing, default is start of file.
=item B<-length number>
number of bytes to parse, default is until end of file.
=item B<-i>
indents the output according to the "depth" of the structures.
=item B<-oid filename>
a file containing additional OBJECT IDENTIFIERs (OIDs). The format of this
file is described in the NOTES section below.
=item B<-dump>
dump unknown data in hex format.
=item B<-dlimit num>
like B<-dump>, but only the first B<num> bytes are output.
=item B<-strparse offset>
parse the contents octets of the ASN.1 object starting at B<offset>. This
option can be used multiple times to "drill down" into a nested structure.
=item B<-genstr string>, B<-genconf file>
generate encoded data based on B<string>, B<file> or both using
L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format. If B<file> only is
present then the string is obtained from the default section using the name
B<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 B<out> option.
=back
=head2 OUTPUT
The output will typically contain lines like this:
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
.....
This example is part of a self signed certificate. Each line starts with the
offset in decimal. B<d=XX> specifies the current depth. The depth is increased
within the scope of any SET or SEQUENCE. B<hl=XX> gives the header length
(tag and length octets) of the current type. B<l=XX> gives the length of
the contents octets.
The B<-i> option can be used to make the output more readable.
Some knowledge of the ASN.1 structure is needed to interpret the output.
In this example the BIT STRING at offset 229 is the certificate public key.
The contents octets of this will contain the public key information. This can
be examined using the option B<-strparse 229> to yield:
0:d=0 hl=3 l= 137 cons: SEQUENCE
3:d=1 hl=3 l= 129 prim: INTEGER :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897
135:d=1 hl=2 l= 3 prim: INTEGER :010001
=head1 NOTES
If an OID is not part of OpenSSL's internal table it will be represented in
numerical form (for example 1.2.3.4). The file passed to the B<-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 white
space. The second column is the "short name" which is a single word followed
by white space. The final column is the rest of the line and is the
"long name". B<asn1parse> displays the long name. Example:
C<1.2.3.4 shortName A long name>
=head1 EXAMPLES
Parse a file:
openssl asn1parse -in file.pem
Parse a DER file:
openssl asn1parse -inform DER -in file.der
Generate a simple UTF8String:
openssl asn1parse -genstr 'UTF8:Hello World'
Generate and write out a UTF8String, don't print parsed output:
openssl asn1parse -genstr 'UTF8:Hello World' -noout -out utf8.der
Generate using a config file:
openssl asn1parse -genconf asn1.cnf -noout -out asn1.der
Example config file:
asn1=SEQUENCE:seq_sect
[seq_sect]
field1=BOOL:TRUE
field2=EXP:0, UTF8:some random string
=head1 BUGS
There should be options to change the format of output lines. The output of some
ASN.1 types is not well handled (if at all).
=head1 SEE ALSO
L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>
=cut

114
doc/apps/c_rehash.pod Normal file
View File

@@ -0,0 +1,114 @@
=pod
=for comment
Original text by James Westby, contributed under the OpenSSL license.
=head1 NAME
c_rehash - Create symbolic links to files named by the hash values
=head1 SYNOPSIS
B<c_rehash>
B<[-old]>
B<[-h]>
B<[-n]>
B<[-v]>
[ I<directory>...]
=head1 DESCRIPTION
B<c_rehash> scans directories and calculates a hash value of each
C<.pem>, C<.crt>, C<.cer>, or C<.crl>
file in the specified directory list and creates symbolic links
for each file, where the name of the link is the hash value.
(If the platform does not support symbolic links, a copy is made.)
This utility is useful as many programs that use OpenSSL require
directories to be set up like this in order to find certificates.
If any directories are named on the command line, then those are
processed in turn. If not, then the B<SSL_CERT_DIR> environment variable
is consulted; this shold be a colon-separated list of directories,
like the Unix B<PATH> variable.
If that is not set then the default directory (installation-specific
but often B</usr/local/ssl/certs>) is processed.
In order for a directory to be processed, the user must have write
permissions on that directory, otherwise it will be skipped.
The links created are of the form C<HHHHHHHH.D>, where each B<H>
is a hexadecimal character and B<D> is a single decimal digit.
When processing a directory, B<c_rehash> will first remove all links
that have a name in that syntax. If you have links in that format
used for other purposes, they will be removed.
To skip the removal step, use the B<-n> flag.
Hashes for CRL's look similar except the letter B<r> appears after
the period, like this: C<HHHHHHHH.rD>.
Multiple objects may have the same hash; they will be indicated by
incrementing the B<D> value. Duplicates are found by comparing the
full SHA-1 fingerprint. A warning will be displayed if a duplicate
is found.
A warning will also be displayed if there are files that
cannot be parsed as either a certificate or a CRL.
The program uses the B<openssl> program to compute the hashes and
fingerprints. If not found in the user's B<PATH>, then set the
B<OPENSSL> environment variable to the full pathname.
Any program can be used, it will be invoked as follows for either
a certificate or CRL:
$OPENSSL x509 -hash -fingerprint -noout -in FILENAME
$OPENSSL crl -hash -fingerprint -noout -in FILENAME
where B<FILENAME> is the filename. It must output the hash of the
file on the first line, and the fingerprint on the second,
optionally prefixed with some text and an equals sign.
=head1 OPTIONS
=over 4
=item B<-old>
Use old-style hashing (MD5, as opposed to SHA-1) for generating
links for releases before 1.0.0. Note that current versions will
not use the old style.
=item B<-h>
Display a brief usage message.
=item B<-n>
Do not remove existing links.
This is needed when keeping new and old-style links in the same directory.
=item B<-v>
Print messages about old links removed and new links created.
By default, B<c_rehash> only lists each directory as it is processed.
=back
=head1 ENVIRONMENT
=over
=item B<OPENSSL>
The path to an executable to use to generate hashes and
fingerprints (see above).
=item B<SSL_CERT_DIR>
Colon separated list of directories to operate on.
Ignored if directories are listed on the command line.
=back
=head1 SEE ALSO
L<openssl(1)|openssl(1)>,
L<crl(1)|crl(1)>.
L<x509(1)|x509(1)>.

696
doc/apps/ca.pod Normal file
View File

@@ -0,0 +1,696 @@
=pod
=head1 NAME
ca - sample minimal CA application
=head1 SYNOPSIS
B<openssl> B<ca>
[B<-verbose>]
[B<-config filename>]
[B<-name section>]
[B<-gencrl>]
[B<-revoke file>]
[B<-status serial>]
[B<-updatedb>]
[B<-crl_reason reason>]
[B<-crl_hold instruction>]
[B<-crl_compromise time>]
[B<-crl_CA_compromise time>]
[B<-crldays days>]
[B<-crlhours hours>]
[B<-crlexts section>]
[B<-startdate date>]
[B<-enddate date>]
[B<-days arg>]
[B<-md arg>]
[B<-policy arg>]
[B<-keyfile arg>]
[B<-keyform PEM|DER>]
[B<-key arg>]
[B<-passin arg>]
[B<-cert file>]
[B<-selfsign>]
[B<-in file>]
[B<-out file>]
[B<-notext>]
[B<-outdir dir>]
[B<-infiles>]
[B<-spkac file>]
[B<-ss_cert file>]
[B<-preserveDN>]
[B<-noemailDN>]
[B<-batch>]
[B<-msie_hack>]
[B<-extensions section>]
[B<-extfile section>]
[B<-engine id>]
[B<-subj arg>]
[B<-utf8>]
[B<-multivalue-rdn>]
=head1 DESCRIPTION
The B<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.
The options descriptions will be divided into each purpose.
=head1 CA OPTIONS
=over 4
=item B<-config filename>
specifies the configuration file to use.
=item B<-name section>
specifies the configuration file section to use (overrides
B<default_ca> in the B<ca> section).
=item B<-in filename>
an input filename containing a single certificate request to be
signed by the CA.
=item B<-ss_cert filename>
a single self signed certificate to be signed by the CA.
=item B<-spkac filename>
a file containing a single Netscape signed public key and challenge
and additional field values to be signed by the CA. See the B<SPKAC FORMAT>
section for information on the required input and output format.
=item B<-infiles>
if present this should be the last option, all subsequent arguments
are assumed to the the names of files containing certificate requests.
=item B<-out filename>
the output file to output certificates to. The default is standard
output. The certificate details will also be printed out to this
file in PEM format (except that B<-spkac> outputs DER format).
=item B<-outdir directory>
the directory to output certificates to. The certificate will be
written to a filename consisting of the serial number in hex with
".pem" appended.
=item B<-cert>
the CA certificate file.
=item B<-keyfile filename>
the private key to sign requests with.
=item B<-keyform PEM|DER>
the format of the data in the private key file.
The default is PEM.
=item B<-key password>
the password used to encrypt the private key. Since on some
systems the command line arguments are visible (e.g. Unix with
the 'ps' utility) this option should be used with caution.
=item B<-selfsign>
indicates the issued certificates are to be signed with the key
the certificate requests were signed with (given with B<-keyfile>).
Cerificate requests signed with a different key are ignored. If
B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is
ignored.
A consequence of using B<-selfsign> is that the self-signed
certificate appears among the entries in the certificate database
(see the configuration option B<database>), and uses the same
serial number counter as all other certificates sign with the
self-signed certificate.
=item B<-passin arg>
the key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-verbose>
this prints extra details about the operations being performed.
=item B<-notext>
don't output the text form of a certificate to the output file.
=item B<-startdate date>
this allows the start date to be explicitly set. The format of the
date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
=item B<-enddate date>
this allows the expiry date to be explicitly set. The format of the
date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
=item B<-days arg>
the number of days to certify the certificate for.
=item B<-md alg>
the message digest to use. Possible values include md5, sha1 and mdc2.
This option also applies to CRLs.
=item B<-policy arg>
this option defines the CA "policy" to use. This is a section in
the configuration file which decides which fields should be mandatory
or match the CA certificate. Check out the B<POLICY FORMAT> section
for more information.
=item B<-msie_hack>
this is a legacy option to make B<ca> work with very old versions of
the IE certificate enrollment control "certenr3". It used UniversalStrings
for almost everything. Since the old control has various security bugs
its use is strongly discouraged. The newer control "Xenroll" does not
need this option.
=item B<-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 match the order of the request. This is not needed for Xenroll.
=item B<-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 altName extension of the certificate. When this option is set the
EMAIL field is removed from the certificate' subject and set only in
the, eventually present, extensions. The B<email_in_dn> keyword can be
used in the configuration file to enable this behaviour.
=item B<-batch>
this sets the batch mode. In this mode no questions will be asked
and all certificates will be certified automatically.
=item B<-extensions section>
the section of the configuration file containing certificate extensions
to be added when a certificate is issued (defaults to B<x509_extensions>
unless the B<-extfile> option is used). If no extension section is
present then, a V1 certificate is created. If the extension section
is present (even if it is empty), then a V3 certificate is created. See the:w
L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
extension section format.
=item B<-extfile file>
an additional configuration file to read certificate extensions from
(using the default section unless the B<-extensions> option is also
used).
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=item B<-subj arg>
supersedes subject name given in the request.
The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
characters may be escaped by \ (backslash), no spaces are skipped.
=item B<-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.
=item B<-multivalue-rdn>
this option causes the -subj argument to be interpretedt with full
support for multivalued RDNs. Example:
I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
=back
=head1 CRL OPTIONS
=over 4
=item B<-gencrl>
this option generates a CRL based on information in the index file.
=item B<-crldays num>
the number of days before the next CRL is due. That is the days from
now to place in the CRL nextUpdate field.
=item B<-crlhours num>
the number of hours before the next CRL is due.
=item B<-revoke filename>
a filename containing a certificate to revoke.
=item B<-status serial>
displays the revocation status of the certificate with the specified
serial number and exits.
=item B<-updatedb>
Updates the database index to purge expired certificates.
=item B<-crl_reason reason>
revocation reason, where B<reason> is one of: B<unspecified>, B<keyCompromise>,
B<CACompromise>, B<affiliationChanged>, B<superseded>, B<cessationOfOperation>,
B<certificateHold> or B<removeFromCRL>. The matching of B<reason> is case
insensitive. Setting any revocation reason will make the CRL v2.
In practive B<removeFromCRL> is not particularly useful because it is only used
in delta CRLs which are not currently implemented.
=item B<-crl_hold instruction>
This sets the CRL revocation reason code to B<certificateHold> and the hold
instruction to B<instruction> which must be an OID. Although any OID can be
used only B<holdInstructionNone> (the use of which is discouraged by RFC2459)
B<holdInstructionCallIssuer> or B<holdInstructionReject> will normally be used.
=item B<-crl_compromise time>
This sets the revocation reason to B<keyCompromise> and the compromise time to
B<time>. B<time> should be in GeneralizedTime format that is B<YYYYMMDDHHMMSSZ>.
=item B<-crl_CA_compromise time>
This is the same as B<crl_compromise> except the revocation reason is set to
B<CACompromise>.
=item B<-crlexts section>
the section of the configuration file containing CRL extensions to
include. If no CRL extension section is present then a V1 CRL is
created, if the CRL extension section is present (even if it is
empty) then a V2 CRL is created. The CRL extensions specified are
CRL extensions and B<not> CRL entry extensions. It should be noted
that some software (for example Netscape) can't handle V2 CRLs. See
L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
extension section format.
=back
=head1 CONFIGURATION FILE OPTIONS
The section of the configuration file containing options for B<ca>
is found as follows: If the B<-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 B<default_ca> option of the B<ca> section
of the configuration file (or in the default section of the
configuration file). Besides B<default_ca>, the following options are
read directly from the B<ca> section:
RANDFILE
preserve
msie_hack
With the exception of B<RANDFILE>, this is probably a bug and may
change in future releases.
Many of the configuration file options are identical to command line
options. Where the option is present in the configuration file
and the command line the command line value is used. Where an
option is described as mandatory then it must be present in
the configuration file or the command line equivalent (if
any) used.
=over 4
=item B<oid_file>
This specifies a file containing additional B<OBJECT IDENTIFIERS>.
Each line of the file should consist of the numerical form of the
object identifier followed by white space then the short name followed
by white space and finally the long name.
=item B<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 B<=> and the numerical form. The short
and long names are the same when this option is used.
=item B<new_certs_dir>
the same as the B<-outdir> command line option. It specifies
the directory where new certificates will be placed. Mandatory.
=item B<certificate>
the same as B<-cert>. It gives the file containing the CA
certificate. Mandatory.
=item B<private_key>
same as the B<-keyfile> option. The file containing the
CA private key. Mandatory.
=item B<RANDFILE>
a file used to read and write random number seed information, or
an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
=item B<default_days>
the same as the B<-days> option. The number of days to certify
a certificate for.
=item B<default_startdate>
the same as the B<-startdate> option. The start date to certify
a certificate for. If not set the current time is used.
=item B<default_enddate>
the same as the B<-enddate> option. Either this option or
B<default_days> (or the command line equivalents) must be
present.
=item B<default_crl_hours default_crl_days>
the same as the B<-crlhours> and the B<-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.
=item B<default_md>
the same as the B<-md> option. The message digest to use. Mandatory.
=item B<database>
the text database file to use. Mandatory. This file must be present
though initially it will be empty.
=item B<unique_subject>
if the value B<yes> is given, the valid certificate entries in the
database must have unique subjects. if the value B<no> is given,
several valid certificate entries may have the exact same subject.
The default value is B<yes>, to be compatible with older (pre 0.9.8)
versions of OpenSSL. However, to make CA certificate roll-over easier,
it's recommended to use the value B<no>, especially if combined with
the B<-selfsign> command line option.
=item B<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.
=item B<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.
=item B<x509_extensions>
the same as B<-extensions>.
=item B<crl_extensions>
the same as B<-crlexts>.
=item B<preserve>
the same as B<-preserveDN>
=item B<email_in_dn>
the same as B<-noemailDN>. If you want the EMAIL field to be removed
from the DN of the certificate simply set this to 'no'. If not present
the default is to allow for the EMAIL filed in the certificate's DN.
=item B<msie_hack>
the same as B<-msie_hack>
=item B<policy>
the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
for more information.
=item B<name_opt>, B<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 B<x509> utilities B<-nameopt> and B<-certopt> switches can be used
here, except the B<no_signame> and B<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).
For convenience the values B<ca_default> are accepted by both to produce
a reasonable output.
If neither option is present the format used in earlier versions of
OpenSSL is used. Use of the old format is B<strongly> discouraged because
it only displays fields mentioned in the B<policy> section, mishandles
multicharacter string types and does not display extensions.
=item B<copy_extensions>
determines how extensions in certificate requests should be handled.
If set to B<none> or this option is not present then extensions are
ignored and not copied to the certificate. If set to B<copy> then any
extensions present in the request that are not already present are copied
to the certificate. If set to B<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 B<WARNINGS> section before
using this option.
The main use of this option is to allow a certificate request to supply
values for certain extensions such as subjectAltName.
=back
=head1 POLICY FORMAT
The policy section consists of a set of variables corresponding to
certificate DN fields. If the value is "match" then the field value
must match the same field in the CA certificate. If the value is
"supplied" then it must be present. If the value is "optional" then
it may be present. Any fields not mentioned in the policy section
are silently deleted, unless the B<-preserveDN> option is set but
this can be regarded more of a quirk than intended behaviour.
=head1 SPKAC FORMAT
The input to the B<-spkac> command line option is a Netscape
signed public key and challenge. This will usually come from
the B<KEYGEN> tag in an HTML form to create a new private key.
It is however possible to create SPKACs using the B<spkac> utility.
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 you need to include the same component twice then it can be
preceded by a number and a '.'.
When processing SPKAC format, the output is DER if the B<-out>
flag is used, but PEM format if sending to stdout or the B<-outdir>
flag is used.
=head1 EXAMPLES
Note: these examples assume that the B<ca> directory structure is
already set up and the relevant files already exist. This usually
involves creating a CA certificate and private key with B<req>, a
serial number file and an empty index file and placing them in
the relevant directories.
To use the sample configuration file below the directories demoCA,
demoCA/private and demoCA/newcerts would be created. The CA
certificate would be copied to demoCA/cacert.pem and its private
key to demoCA/private/cakey.pem. A file demoCA/serial would be
created containing for example "01" and the empty index file
demoCA/index.txt.
Sign a certificate request:
openssl ca -in req.pem -out newcert.pem
Sign a certificate request, using CA extensions:
openssl ca -in req.pem -extensions v3_ca -out newcert.pem
Generate a CRL
openssl ca -gencrl -out crl.pem
Sign several requests:
openssl ca -infiles req1.pem req2.pem req3.pem
Certify a Netscape SPKAC:
openssl ca -spkac spkac.txt
A sample SPKAC file (the SPKAC line has been truncated for clarity):
SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
CN=Steve Test
emailAddress=steve@openssl.org
0.OU=OpenSSL Group
1.OU=Another Group
A sample configuration file with the relevant sections for B<ca>:
[ 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
RANDFILE = $dir/private/.rand # random number file
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
=head1 FILES
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.
/usr/local/ssl/lib/openssl.cnf - master configuration file
./demoCA - main CA directory
./demoCA/cacert.pem - CA certificate
./demoCA/private/cakey.pem - CA private key
./demoCA/serial - CA serial number file
./demoCA/serial.old - CA serial number backup file
./demoCA/index.txt - CA text database file
./demoCA/index.txt.old - CA text database backup file
./demoCA/certs - certificate output file
./demoCA/.rnd - CA random seed information
=head1 ENVIRONMENT VARIABLES
B<OPENSSL_CONF> reflects the location of master configuration file it can
be overridden by the B<-config> command line option.
=head1 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.
V2 CRL features like delta CRLs are not currently supported.
Although several requests can be input and handled at once it is only
possible to include one SPKAC or self signed certificate.
=head1 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.
The B<ca> command really needs rewriting or the required functionality
exposed at either a command or interface level so a more friendly utility
(perl script or GUI) can handle things properly. The scripts B<CA.sh> and
B<CA.pl> help a little but not very much.
Any fields in a request that are not present in a policy are silently
deleted. This does not happen if the B<-preserveDN> option is used. To
enforce the absence of the EMAIL field within the DN, as suggested by
RFCs, regardless the contents of the request' subject the B<-noemailDN>
option can be used. The behaviour should be more friendly and
configurable.
Cancelling some commands by refusing to certify a certificate can
create an empty file.
=head1 WARNINGS
The B<ca> command is quirky and at times downright unfriendly.
The B<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.
The B<ca> command is effectively a single user command: no locking is
done on the various files and attempts to run more than one B<ca> command
on the same database can have unpredictable results.
The B<copy_extensions> option should be used with caution. If care is
not taken then it can be a security risk. For example if a certificate
request contains a basicConstraints extension with CA:TRUE and the
B<copy_extensions> value is set to B<copyall> and the user does not spot
this when the certificate is displayed then this will hand the requestor
a valid CA certificate.
This situation can be avoided by setting B<copy_extensions> to B<copy>
and including basicConstraints with CA:FALSE in the configuration file.
Then if the request contains a basicConstraints extension it will be
ignored.
It is advisable to also include values for other extensions such
as B<keyUsage> to prevent a request supplying its own values.
Additional restrictions can be placed on the CA certificate itself.
For example if the CA certificate has:
basicConstraints = CA:TRUE, pathlen:0
then even if a certificate is issued with CA:TRUE it will not be valid.
=head1 SEE ALSO
L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>,
L<config(5)|config(5)>, L<x509v3_config(5)|x509v3_config(5)>
=cut

645
doc/apps/ciphers.pod Normal file
View File

@@ -0,0 +1,645 @@
=pod
=head1 NAME
ciphers - SSL cipher display and cipher list tool.
=head1 SYNOPSIS
B<openssl> B<ciphers>
[B<-v>]
[B<-V>]
[B<-ssl2>]
[B<-ssl3>]
[B<-tls1>]
[B<cipherlist>]
=head1 DESCRIPTION
The B<ciphers> command converts textual OpenSSL cipher lists into ordered
SSL cipher preference lists. It can be used as a test tool to determine
the appropriate cipherlist.
=head1 COMMAND OPTIONS
=over 4
=item B<-v>
Verbose option. List ciphers with a complete description of
protocol version (SSLv2 or SSLv3; the latter includes TLS), key exchange,
authentication, encryption and mac algorithms used along with any key size
restrictions and whether the algorithm is classed as an "export" cipher.
Note that without the B<-v> option, ciphers may seem to appear twice
in a cipher list; this is when similar ciphers are available for
SSL v2 and for SSL v3/TLS v1.
=item B<-V>
Like B<-v>, but include cipher suite codes in output (hex format).
=item B<-ssl3>, B<-tls1>
This lists ciphers compatible with any of SSLv3, TLSv1, TLSv1.1 or TLSv1.2.
=item B<-ssl2>
Only include SSLv2 ciphers.
=item B<-h>, B<-?>
Print a brief usage message.
=item B<cipherlist>
A cipher list to convert to a cipher preference list. If it is not included
then the default cipher list will be used. The format is described below.
=back
=head1 CIPHER LIST FORMAT
The cipher list consists of one or more I<cipher strings> separated by colons.
Commas or spaces are also acceptable separators but colons are normally used.
The actual cipher string can take several different forms.
It can consist of a single cipher suite such as B<RC4-SHA>.
It can represent a list of cipher suites containing a certain algorithm, or
cipher suites of a certain type. For example B<SHA1> represents all ciphers
suites using the digest algorithm SHA1 and B<SSLv3> represents all SSL v3
algorithms.
Lists of cipher suites can be combined in a single cipher string using the
B<+> character. This is used as a logical B<and> operation. For example
B<SHA1+DES> represents all cipher suites containing the SHA1 B<and> the DES
algorithms.
Each cipher string can be optionally preceded by the characters B<!>,
B<-> or B<+>.
If B<!> 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.
If B<-> is used then the ciphers are deleted from the list, but some or
all of the ciphers can be added again by later options.
If B<+> 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.
If none of these characters is present then the string is just interpreted
as a list of ciphers to be appended to the current preference list. If the
list includes any ciphers already present they will be ignored: that is they
will not moved to the end of the list.
Additionally the cipher string B<@STRENGTH> can be used at any point to sort
the current cipher list in order of encryption algorithm key length.
=head1 CIPHER STRINGS
The following is a list of all permitted cipher strings and their meanings.
=over 4
=item B<DEFAULT>
The default cipher list.
This is determined at compile time and is normally
B<ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2>.
When used, this must be the first cipherstring specified.
=item B<COMPLEMENTOFDEFAULT>
the ciphers included in B<ALL>, but not enabled by default. Currently
this is B<ADH> and B<AECDH>. Note that this rule does not cover B<eNULL>,
which is not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary).
=item B<ALL>
all cipher suites except the B<eNULL> ciphers which must be explicitly enabled;
as of OpenSSL, the B<ALL> cipher suites are reasonably ordered by default
=item B<COMPLEMENTOFALL>
the cipher suites not enabled by B<ALL>, currently being B<eNULL>.
=item B<HIGH>
"high" encryption cipher suites. This currently means those with key lengths larger
than 128 bits, and some cipher suites with 128-bit keys.
=item B<MEDIUM>
"medium" encryption cipher suites, currently some of those using 128 bit encryption.
=item B<LOW>
Low strength encryption cipher suites, currently those using 64 or 56 bit
encryption algorithms but excluding export cipher suites.
As of OpenSSL 1.0.2g, these are disabled in default builds.
=item B<EXP>, B<EXPORT>
Export strength encryption algorithms. Including 40 and 56 bits algorithms.
As of OpenSSL 1.0.2g, these are disabled in default builds.
=item B<EXPORT40>
40-bit export encryption algorithms
As of OpenSSL 1.0.2g, these are disabled in default builds.
=item B<EXPORT56>
56-bit export encryption algorithms. In OpenSSL 0.9.8c and later the set of
56 bit export ciphers is empty unless OpenSSL has been explicitly configured
with support for experimental ciphers.
As of OpenSSL 1.0.2g, these are disabled in default builds.
=item B<eNULL>, B<NULL>
The "NULL" ciphers that is those offering no encryption. Because these offer no
encryption at all and are a security risk they are not enabled via either the
B<DEFAULT> or B<ALL> cipher strings.
Be careful when building cipherlists out of lower-level primitives such as
B<kRSA> or B<aECDSA> as these do overlap with the B<eNULL> ciphers.
When in doubt, include B<!eNULL> in your cipherlist.
=item B<aNULL>
The cipher suites offering no authentication. This is currently the anonymous
DH algorithms and anonymous ECDH algorithms. These cipher suites are vulnerable
to a "man in the middle" attack and so their use is normally discouraged.
These are excluded from the B<DEFAULT> ciphers, but included in the B<ALL>
ciphers.
Be careful when building cipherlists out of lower-level primitives such as
B<kDHE> or B<AES> as these do overlap with the B<aNULL> ciphers.
When in doubt, include B<!aNULL> in your cipherlist.
=item B<kRSA>, B<RSA>
cipher suites using RSA key exchange.
=item B<kDHr>, B<kDHd>, B<kDH>
cipher suites using DH key agreement and DH certificates signed by CAs with RSA
and DSS keys or either respectively.
=item B<kDHE>, B<kEDH>
cipher suites using ephemeral DH key agreement, including anonymous cipher
suites.
=item B<DHE>, B<EDH>
cipher suites using authenticated ephemeral DH key agreement.
=item B<ADH>
anonymous DH cipher suites, note that this does not include anonymous Elliptic
Curve DH (ECDH) cipher suites.
=item B<DH>
cipher suites using DH, including anonymous DH, ephemeral DH and fixed DH.
=item B<kECDHr>, B<kECDHe>, B<kECDH>
cipher suites using fixed ECDH key agreement signed by CAs with RSA and ECDSA
keys or either respectively.
=item B<kECDHE>, B<kEECDH>
cipher suites using ephemeral ECDH key agreement, including anonymous
cipher suites.
=item B<ECDHE>, B<EECDH>
cipher suites using authenticated ephemeral ECDH key agreement.
=item B<AECDH>
anonymous Elliptic Curve Diffie Hellman cipher suites.
=item B<ECDH>
cipher suites using ECDH key exchange, including anonymous, ephemeral and
fixed ECDH.
=item B<aRSA>
cipher suites using RSA authentication, i.e. the certificates carry RSA keys.
=item B<aDSS>, B<DSS>
cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
=item B<aDH>
cipher suites effectively using DH authentication, i.e. the certificates carry
DH keys.
=item B<aECDH>
cipher suites effectively using ECDH authentication, i.e. the certificates
carry ECDH keys.
=item B<aECDSA>, B<ECDSA>
cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA
keys.
=item B<kFZA>, B<aFZA>, B<eFZA>, B<FZA>
ciphers suites using FORTEZZA key exchange, authentication, encryption or all
FORTEZZA algorithms. Not implemented.
=item B<TLSv1.2>, B<TLSv1>, B<SSLv3>, B<SSLv2>
TLS v1.2, TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites respectively. Note:
there are no ciphersuites specific to TLS v1.1.
=item B<AES128>, B<AES256>, B<AES>
cipher suites using 128 bit AES, 256 bit AES or either 128 or 256 bit AES.
=item B<AESGCM>
AES in Galois Counter Mode (GCM): these ciphersuites are only supported
in TLS v1.2.
=item B<CAMELLIA128>, B<CAMELLIA256>, B<CAMELLIA>
cipher suites using 128 bit CAMELLIA, 256 bit CAMELLIA or either 128 or 256 bit
CAMELLIA.
=item B<3DES>
cipher suites using triple DES.
=item B<DES>
cipher suites using DES (not triple DES).
=item B<RC4>
cipher suites using RC4.
=item B<RC2>
cipher suites using RC2.
=item B<IDEA>
cipher suites using IDEA.
=item B<SEED>
cipher suites using SEED.
=item B<MD5>
cipher suites using MD5.
=item B<SHA1>, B<SHA>
cipher suites using SHA1.
=item B<SHA256>, B<SHA384>
ciphersuites using SHA256 or SHA384.
=item B<aGOST>
cipher suites using GOST R 34.10 (either 2001 or 94) for authenticaction
(needs an engine supporting GOST algorithms).
=item B<aGOST01>
cipher suites using GOST R 34.10-2001 authentication.
=item B<aGOST94>
cipher suites using GOST R 34.10-94 authentication (note that R 34.10-94
standard has been expired so use GOST R 34.10-2001)
=item B<kGOST>
cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357.
=item B<GOST94>
cipher suites, using HMAC based on GOST R 34.11-94.
=item B<GOST89MAC>
cipher suites using GOST 28147-89 MAC B<instead of> HMAC.
=item B<PSK>
cipher suites using pre-shared keys (PSK).
=item B<SUITEB128>, B<SUITEB128ONLY>, B<SUITEB192>
enables suite B mode operation using 128 (permitting 192 bit mode by peer)
128 bit (not permitting 192 bit by peer) or 192 bit level of security
respectively. If used these cipherstrings should appear first in the cipher
list and anything after them is ignored. Setting Suite B mode has additional
consequences required to comply with RFC6460. In particular the supported
signature algorithms is reduced to support only ECDSA and SHA256 or SHA384,
only the elliptic curves P-256 and P-384 can be used and only the two suite B
compliant ciphersuites (ECDHE-ECDSA-AES128-GCM-SHA256 and
ECDHE-ECDSA-AES256-GCM-SHA384) are permissible.
=back
=head1 CIPHER SUITE NAMES
The following lists give the SSL or TLS cipher suites names from the
relevant specification and their 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.
=head2 SSL v3.0 cipher suites.
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_WITH_DES_CBC_SHA DH-DSS-DES-CBC-SHA
SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA DH-DSS-DES-CBC3-SHA
SSL_DH_RSA_WITH_DES_CBC_SHA DH-RSA-DES-CBC-SHA
SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA DH-RSA-DES-CBC3-SHA
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.
=head2 TLS v1.0 cipher suites.
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
=head2 AES ciphersuites from RFC3268, extending TLS v1.0
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 DH-DSS-AES128-SHA
TLS_DH_DSS_WITH_AES_256_CBC_SHA DH-DSS-AES256-SHA
TLS_DH_RSA_WITH_AES_128_CBC_SHA DH-RSA-AES128-SHA
TLS_DH_RSA_WITH_AES_256_CBC_SHA DH-RSA-AES256-SHA
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
=head2 Camellia ciphersuites from RFC4132, extending TLS v1.0
TLS_RSA_WITH_CAMELLIA_128_CBC_SHA CAMELLIA128-SHA
TLS_RSA_WITH_CAMELLIA_256_CBC_SHA CAMELLIA256-SHA
TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA DH-DSS-CAMELLIA128-SHA
TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA DH-DSS-CAMELLIA256-SHA
TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA DH-RSA-CAMELLIA128-SHA
TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA DH-RSA-CAMELLIA256-SHA
TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA DHE-DSS-CAMELLIA128-SHA
TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA DHE-DSS-CAMELLIA256-SHA
TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA DHE-RSA-CAMELLIA128-SHA
TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA DHE-RSA-CAMELLIA256-SHA
TLS_DH_anon_WITH_CAMELLIA_128_CBC_SHA ADH-CAMELLIA128-SHA
TLS_DH_anon_WITH_CAMELLIA_256_CBC_SHA ADH-CAMELLIA256-SHA
=head2 SEED ciphersuites from RFC4162, extending TLS v1.0
TLS_RSA_WITH_SEED_CBC_SHA SEED-SHA
TLS_DH_DSS_WITH_SEED_CBC_SHA DH-DSS-SEED-SHA
TLS_DH_RSA_WITH_SEED_CBC_SHA DH-RSA-SEED-SHA
TLS_DHE_DSS_WITH_SEED_CBC_SHA DHE-DSS-SEED-SHA
TLS_DHE_RSA_WITH_SEED_CBC_SHA DHE-RSA-SEED-SHA
TLS_DH_anon_WITH_SEED_CBC_SHA ADH-SEED-SHA
=head2 GOST ciphersuites from draft-chudov-cryptopro-cptls, extending TLS v1.0
Note: these ciphers require an engine which including GOST cryptographic
algorithms, such as the B<ccgost> engine, included in the OpenSSL distribution.
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
=head2 Additional Export 1024 and other cipher suites
Note: these ciphers can also be used in SSL v3.
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
=head2 Elliptic curve cipher suites.
TLS_ECDH_RSA_WITH_NULL_SHA ECDH-RSA-NULL-SHA
TLS_ECDH_RSA_WITH_RC4_128_SHA ECDH-RSA-RC4-SHA
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA ECDH-RSA-DES-CBC3-SHA
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA ECDH-RSA-AES128-SHA
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA ECDH-RSA-AES256-SHA
TLS_ECDH_ECDSA_WITH_NULL_SHA ECDH-ECDSA-NULL-SHA
TLS_ECDH_ECDSA_WITH_RC4_128_SHA ECDH-ECDSA-RC4-SHA
TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA ECDH-ECDSA-DES-CBC3-SHA
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA ECDH-ECDSA-AES128-SHA
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA ECDH-ECDSA-AES256-SHA
TLS_ECDHE_RSA_WITH_NULL_SHA ECDHE-RSA-NULL-SHA
TLS_ECDHE_RSA_WITH_RC4_128_SHA ECDHE-RSA-RC4-SHA
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ECDHE-RSA-DES-CBC3-SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA ECDHE-RSA-AES128-SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ECDHE-RSA-AES256-SHA
TLS_ECDHE_ECDSA_WITH_NULL_SHA ECDHE-ECDSA-NULL-SHA
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA ECDHE-ECDSA-RC4-SHA
TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA ECDHE-ECDSA-DES-CBC3-SHA
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA ECDHE-ECDSA-AES128-SHA
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ECDHE-ECDSA-AES256-SHA
TLS_ECDH_anon_WITH_NULL_SHA AECDH-NULL-SHA
TLS_ECDH_anon_WITH_RC4_128_SHA AECDH-RC4-SHA
TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA AECDH-DES-CBC3-SHA
TLS_ECDH_anon_WITH_AES_128_CBC_SHA AECDH-AES128-SHA
TLS_ECDH_anon_WITH_AES_256_CBC_SHA AECDH-AES256-SHA
=head2 TLS v1.2 cipher suites
TLS_RSA_WITH_NULL_SHA256 NULL-SHA256
TLS_RSA_WITH_AES_128_CBC_SHA256 AES128-SHA256
TLS_RSA_WITH_AES_256_CBC_SHA256 AES256-SHA256
TLS_RSA_WITH_AES_128_GCM_SHA256 AES128-GCM-SHA256
TLS_RSA_WITH_AES_256_GCM_SHA384 AES256-GCM-SHA384
TLS_DH_RSA_WITH_AES_128_CBC_SHA256 DH-RSA-AES128-SHA256
TLS_DH_RSA_WITH_AES_256_CBC_SHA256 DH-RSA-AES256-SHA256
TLS_DH_RSA_WITH_AES_128_GCM_SHA256 DH-RSA-AES128-GCM-SHA256
TLS_DH_RSA_WITH_AES_256_GCM_SHA384 DH-RSA-AES256-GCM-SHA384
TLS_DH_DSS_WITH_AES_128_CBC_SHA256 DH-DSS-AES128-SHA256
TLS_DH_DSS_WITH_AES_256_CBC_SHA256 DH-DSS-AES256-SHA256
TLS_DH_DSS_WITH_AES_128_GCM_SHA256 DH-DSS-AES128-GCM-SHA256
TLS_DH_DSS_WITH_AES_256_GCM_SHA384 DH-DSS-AES256-GCM-SHA384
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 DHE-RSA-AES128-SHA256
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 DHE-RSA-AES256-SHA256
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 DHE-RSA-AES128-GCM-SHA256
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 DHE-RSA-AES256-GCM-SHA384
TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 DHE-DSS-AES128-SHA256
TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 DHE-DSS-AES256-SHA256
TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 DHE-DSS-AES128-GCM-SHA256
TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 DHE-DSS-AES256-GCM-SHA384
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 ECDH-RSA-AES128-SHA256
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 ECDH-RSA-AES256-SHA384
TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 ECDH-RSA-AES128-GCM-SHA256
TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 ECDH-RSA-AES256-GCM-SHA384
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 ECDH-ECDSA-AES128-SHA256
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 ECDH-ECDSA-AES256-SHA384
TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 ECDH-ECDSA-AES128-GCM-SHA256
TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 ECDH-ECDSA-AES256-GCM-SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 ECDHE-RSA-AES128-SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 ECDHE-RSA-AES256-SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ECDHE-RSA-AES128-GCM-SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ECDHE-RSA-AES256-GCM-SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 ECDHE-ECDSA-AES128-SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 ECDHE-ECDSA-AES256-SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ECDHE-ECDSA-AES128-GCM-SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 ECDHE-ECDSA-AES256-GCM-SHA384
TLS_DH_anon_WITH_AES_128_CBC_SHA256 ADH-AES128-SHA256
TLS_DH_anon_WITH_AES_256_CBC_SHA256 ADH-AES256-SHA256
TLS_DH_anon_WITH_AES_128_GCM_SHA256 ADH-AES128-GCM-SHA256
TLS_DH_anon_WITH_AES_256_GCM_SHA384 ADH-AES256-GCM-SHA384
=head2 Pre shared keying (PSK) cipheruites
TLS_PSK_WITH_RC4_128_SHA PSK-RC4-SHA
TLS_PSK_WITH_3DES_EDE_CBC_SHA PSK-3DES-EDE-CBC-SHA
TLS_PSK_WITH_AES_128_CBC_SHA PSK-AES128-CBC-SHA
TLS_PSK_WITH_AES_256_CBC_SHA PSK-AES256-CBC-SHA
=head2 Deprecated SSL v2.0 cipher suites.
SSL_CK_RC4_128_WITH_MD5 RC4-MD5
SSL_CK_RC4_128_EXPORT40_WITH_MD5 Not implemented.
SSL_CK_RC2_128_CBC_WITH_MD5 RC2-CBC-MD5
SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5 Not implemented.
SSL_CK_IDEA_128_CBC_WITH_MD5 IDEA-CBC-MD5
SSL_CK_DES_64_CBC_WITH_MD5 Not implemented.
SSL_CK_DES_192_EDE3_CBC_WITH_MD5 DES-CBC3-MD5
=head1 NOTES
Some compiled versions of OpenSSL may not include all the ciphers
listed here because some ciphers were excluded at compile time.
=head1 EXAMPLES
Verbose listing of all OpenSSL ciphers including NULL ciphers:
openssl ciphers -v 'ALL:eNULL'
Include all ciphers except NULL and anonymous DH then sort by
strength:
openssl ciphers -v 'ALL:!ADH:@STRENGTH'
Include all ciphers except ones with no encryption (eNULL) or no
authentication (aNULL):
openssl ciphers -v 'ALL:!aNULL'
Include only 3DES ciphers and then place RSA ciphers last:
openssl ciphers -v '3DES:+RSA'
Include all RC4 ciphers but leave out those without authentication:
openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT'
Include all chiphers with RSA authentication but leave out ciphers without
encryption.
openssl ciphers -v 'RSA:!COMPLEMENTOFALL'
=head1 SEE ALSO
L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ssl(3)|ssl(3)>
=head1 HISTORY
The B<COMPLENTOFALL> and B<COMPLEMENTOFDEFAULT> selection options
for cipherlist strings were added in OpenSSL 0.9.7.
The B<-V> option for the B<ciphers> command was added in OpenSSL 1.0.0.
=cut

664
doc/apps/cms.pod Normal file
View File

@@ -0,0 +1,664 @@
=pod
=head1 NAME
cms - CMS utility
=head1 SYNOPSIS
B<openssl> B<cms>
[B<-encrypt>]
[B<-decrypt>]
[B<-sign>]
[B<-verify>]
[B<-cmsout>]
[B<-resign>]
[B<-data_create>]
[B<-data_out>]
[B<-digest_create>]
[B<-digest_verify>]
[B<-compress>]
[B<-uncompress>]
[B<-EncryptedData_encrypt>]
[B<-sign_receipt>]
[B<-verify_receipt receipt>]
[B<-in filename>]
[B<-inform SMIME|PEM|DER>]
[B<-rctform SMIME|PEM|DER>]
[B<-out filename>]
[B<-outform SMIME|PEM|DER>]
[B<-stream -indef -noindef>]
[B<-noindef>]
[B<-content filename>]
[B<-text>]
[B<-noout>]
[B<-print>]
[B<-CAfile file>]
[B<-CApath dir>]
[B<-no_alt_chains>]
[B<-md digest>]
[B<-[cipher]>]
[B<-nointern>]
[B<-no_signer_cert_verify>]
[B<-nocerts>]
[B<-noattr>]
[B<-nosmimecap>]
[B<-binary>]
[B<-nodetach>]
[B<-certfile file>]
[B<-certsout file>]
[B<-signer file>]
[B<-recip file>]
[B<-keyid>]
[B<-receipt_request_all -receipt_request_first>]
[B<-receipt_request_from emailaddress>]
[B<-receipt_request_to emailaddress>]
[B<-receipt_request_print>]
[B<-secretkey key>]
[B<-secretkeyid id>]
[B<-econtent_type type>]
[B<-inkey file>]
[B<-keyopt name:parameter>]
[B<-passin arg>]
[B<-rand file(s)>]
[B<cert.pem...>]
[B<-to addr>]
[B<-from addr>]
[B<-subject subj>]
[cert.pem]...
=head1 DESCRIPTION
The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and
verify, compress and uncompress S/MIME messages.
=head1 COMMAND OPTIONS
There are fourteen operation options that set the type of operation to be
performed. The meaning of the other options varies according to the operation
type.
=over 4
=item B<-encrypt>
encrypt mail for the given recipient certificates. Input file is the message
to be encrypted. The output file is the encrypted mail in MIME format. The
actual CMS type is <B>EnvelopedData<B>.
Note that no revocation check is done for the recipient cert, so if that
key has been compromised, others may be able to decrypt the text.
=item B<-decrypt>
decrypt mail using the supplied certificate and private key. Expects an
encrypted mail message in MIME format for the input file. The decrypted mail
is written to the output file.
=item B<-debug_decrypt>
this option sets the B<CMS_DEBUG_DECRYPT> flag. This option should be used
with caution: see the notes section below.
=item B<-sign>
sign mail using the supplied certificate and private key. Input file is
the message to be signed. The signed message in MIME format is written
to the output file.
=item B<-verify>
verify signed mail. Expects a signed mail message on input and outputs
the signed data. Both clear text and opaque signing is supported.
=item B<-cmsout>
takes an input message and writes out a PEM encoded CMS structure.
=item B<-resign>
resign a message: take an existing message and one or more new signers.
=item B<-data_create>
Create a CMS B<Data> type.
=item B<-data_out>
B<Data> type and output the content.
=item B<-digest_create>
Create a CMS B<DigestedData> type.
=item B<-digest_verify>
Verify a CMS B<DigestedData> type and output the content.
=item B<-compress>
Create a CMS B<CompressedData> type. OpenSSL must be compiled with B<zlib>
support for this option to work, otherwise it will output an error.
=item B<-uncompress>
Uncompress a CMS B<CompressedData> type and output the content. OpenSSL must be
compiled with B<zlib> support for this option to work, otherwise it will
output an error.
=item B<-EncryptedData_encrypt>
Encrypt content using supplied symmetric key and algorithm using a CMS
B<EncrytedData> type and output the content.
=item B<-sign_receipt>
Generate and output a signed receipt for the supplied message. The input
message B<must> contain a signed receipt request. Functionality is otherwise
similar to the B<-sign> operation.
=item B<-verify_receipt receipt>
Verify a signed receipt in filename B<receipt>. The input message B<must>
contain the original receipt request. Functionality is otherwise similar
to the B<-verify> operation.
=item B<-in filename>
the input message to be encrypted or signed or the message to be decrypted
or verified.
=item B<-inform SMIME|PEM|DER>
this specifies the input format for the CMS structure. The default
is B<SMIME> which reads an S/MIME format message. B<PEM> and B<DER>
format change this to expect PEM and DER format CMS structures
instead. This currently only affects the input format of the CMS
structure, if no CMS structure is being input (for example with
B<-encrypt> or B<-sign>) this option has no effect.
=item B<-rctform SMIME|PEM|DER>
specify the format for a signed receipt for use with the B<-receipt_verify>
operation.
=item B<-out filename>
the message text that has been decrypted or verified or the output MIME
format message that has been signed or verified.
=item B<-outform SMIME|PEM|DER>
this specifies the output format for the CMS structure. The default
is B<SMIME> which writes an S/MIME format message. B<PEM> and B<DER>
format change this to write PEM and DER format CMS structures
instead. This currently only affects the output format of the CMS
structure, if no CMS structure is being output (for example with
B<-verify> or B<-decrypt>) this option has no effect.
=item B<-stream -indef -noindef>
the B<-stream> and B<-indef> options are equivalent and 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 B<SMIME> it is currently off by default for all
other operations.
=item B<-noindef>
disable streaming I/O where it would produce and indefinite length constructed
encoding. This option currently has no effect. In future streaming will be
enabled by default on all relevant operations and this option will disable it.
=item B<-content filename>
This specifies a file containing the detached content, this is only
useful with the B<-verify> command. This is only usable if the CMS
structure is using the detached signature form where the content is
not included. This option will override any content if the input format
is S/MIME and it uses the multipart/signed MIME content type.
=item B<-text>
this option adds plain text (text/plain) 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 MIME
type text/plain then an error occurs.
=item B<-noout>
for the B<-cmsout> operation do not output the parsed CMS structure. This
is useful when combined with the B<-print> option or if the syntax of the CMS
structure is being checked.
=item B<-print>
for the B<-cmsout> operation print out all fields of the CMS structure. This
is mainly useful for testing purposes.
=item B<-CAfile file>
a file containing trusted CA certificates, only used with B<-verify>.
=item B<-CApath dir>
a directory containing trusted CA certificates, only used with
B<-verify>. This directory must be a standard certificate directory: that
is a hash of each subject name (using B<x509 -hash>) should be linked
to each certificate.
=item B<-md digest>
digest algorithm to use when signing or resigning. If not present then the
default digest algorithm for the signing key will be used (usually SHA1).
=item B<-[cipher]>
the encryption algorithm to use. For example triple DES (168 bits) - B<-des3>
or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the
EVP_get_cipherbyname() function) can also be used preceded by a dash, for
example B<-aes_128_cbc>. See L<B<enc>|enc(1)> for a list of ciphers
supported by your version of OpenSSL.
If not specified triple DES is used. Only used with B<-encrypt> and
B<-EncryptedData_create> commands.
=item B<-nointern>
when verifying a message normally certificates (if any) included in
the message are searched for the signing certificate. With this option
only the certificates specified in the B<-certfile> option are used.
The supplied certificates can still be used as untrusted CAs however.
=item B<-no_signer_cert_verify>
do not verify the signers certificate of a signed message.
=item B<-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 signers certificate
available locally (passed using the B<-certfile> option for example).
=item B<-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.
=item B<-nosmimecap>
exclude the list of supported algorithms from signed attributes, other options
such as signing time and content type are still included.
=item B<-binary>
normally the input message is converted to "canonical" format which is
effectively using CR and LF as end of line: as required by the S/MIME
specification. When this option is present no translation occurs. This
is useful when handling binary data which may not be in MIME format.
=item B<-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 S/MIME. Without this option cleartext signing with
the MIME type multipart/signed is used.
=item B<-certfile 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.
=item B<-certsout file>
any certificates contained in the message are written to B<file>.
=item B<-signer 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 then the signers certificates will be written to this file if the
verification was successful.
=item B<-recip file>
when decrypting a message this specifies the recipients certificate. The
certificate must match one of the recipients of the message or an error
occurs.
When encrypting a message this option may be used multiple times to specify
each recipient. This form B<must> be used if customised parameters are
required (for example to specify RSA-OAEP).
=item B<-keyid>
use subject key identifier to identify certificates instead of issuer name and
serial number. The supplied certificate B<must> include a subject key
identifier extension. Supported by B<-sign> and B<-encrypt> options.
=item B<-receipt_request_all -receipt_request_first>
for B<-sign> option include a signed receipt request. Indicate requests should
be provided by all receipient or first tier recipients (those mailed directly
and not from a mailing list). Ignored it B<-receipt_request_from> is included.
=item B<-receipt_request_from emailaddress>
for B<-sign> option include a signed receipt request. Add an explicit email
address where receipts should be supplied.
=item B<-receipt_request_to emailaddress>
Add an explicit email address where signed receipts should be sent to. This
option B<must> but supplied if a signed receipt it requested.
=item B<-receipt_request_print>
For the B<-verify> operation print out the contents of any signed receipt
requests.
=item B<-secretkey key>
specify symmetric key to use. The key must be supplied in hex format and be
consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt>
B<-EncrryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used
with B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the
content encryption key using an AES key in the B<KEKRecipientInfo> type.
=item B<-secretkeyid id>
the key identifier for the supplied symmetric key for B<KEKRecipientInfo> type.
This option B<must> be present if the B<-secretkey> option is used with
B<-encrypt>. With B<-decrypt> operations the B<id> is used to locate the
relevant key if it is not supplied then an attempt is used to decrypt any
B<KEKRecipientInfo> structures.
=item B<-econtent_type type>
set the encapsulated content type to B<type> if not supplied the B<Data> type
is used. The B<type> argument can be any valid OID name in either text or
numerical format.
=item B<-inkey file>
the private key to use when signing or decrypting. This must match the
corresponding certificate. If this option is not specified then the
private key must be included in the certificate file specified with
the B<-recip> or B<-signer> file. When signing this option can be used
multiple times to specify successive keys.
=item B<-keyopt name:opt>
for signing and encryption this option can be used multiple times to
set customised parameters for the preceding key or certificate. It can
currently be used to set RSA-PSS for signing, RSA-OAEP for encryption
or to modify default parameters for ECDH.
=item B<-passin arg>
the private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<cert.pem...>
one or more certificates of message recipients: used when encrypting
a message.
=item B<-to, -from, -subject>
the relevant mail headers. These are included outside the signed
portion of a message so they may be included manually. If signing
then many S/MIME mail clients check the signers certificate's email
address matches that specified in the From: address.
=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains>
Set various certificate chain valiadition option. See the
L<B<verify>|verify(1)> manual page for details.
=back
=head1 NOTES
The 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.
The supplied message to be signed or encrypted must include the
necessary MIME headers or many S/MIME clients wont display it
properly (if at all). You can use the B<-text> option to automatically
add plain text headers.
A "signed and encrypted" message is one where a signed message is
then encrypted. This can be produced by encrypting an already signed
message: see the examples section.
This version of the program only allows one signer per message but it
will verify multiple signers on received messages. Some S/MIME clients
choke if a message contains multiple signers. It is possible to sign
messages "in parallel" by signing an already signed message.
The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
clients. Strictly speaking these process CMS enveloped data: CMS
encrypted data is used for other purposes.
The B<-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.
The B<-stream> and B<-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 B<-encrypt> operation and the
B<-sign> operation if the content is not detached.
Streaming is always used for the B<-sign> operation with detached data but
since the content is no longer part of the CMS structure the encoding
remains DER.
If the B<-decrypt> option is used without a recipient certificate then an
attempt is made to locate the recipient by trying each potential recipient
in turn using the supplied private key. To thwart the MMA attack
(Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are
tried whether they succeed or not and if no recipients match the message
is "decrypted" using a random key which will typically output garbage.
The B<-debug_decrypt> option can be used to disable the MMA attack protection
and return an error if no recipient can be found: this option should be used
with caution. For a fuller description see L<CMS_decrypt(3)|CMS_decrypt(3)>).
=head1 EXIT CODES
=over 4
=item Z<>0
the operation was completely successfully.
=item Z<>1
an error occurred parsing the command options.
=item Z<>2
one of the input files could not be read.
=item Z<>3
an error occurred creating the CMS file or when reading the MIME
message.
=item Z<>4
an error occurred decrypting or verifying the message.
=item Z<>5
the message was verified correctly but an error occurred writing out
the signers certificates.
=back
=head1 COMPATIBILITY WITH PKCS#7 format.
The B<smime> utility can only process the older B<PKCS#7> format. The B<cms>
utility supports Cryptographic Message Syntax format. Use of some features
will result in messages which cannot be processed by applications which only
support the older format. These are detailed below.
The use of the B<-keyid> option with B<-sign> or B<-encrypt>.
The B<-outform PEM> option uses different headers.
The B<-compress> option.
The B<-secretkey> option when used with B<-encrypt>.
The use of PSS with B<-sign>.
The use of OAEP or non-RSA keys with B<-encrypt>.
Additionally the B<-EncryptedData_create> and B<-data_create> type cannot
be processed by the older B<smime> command.
=head1 EXAMPLES
Create a cleartext signed message:
openssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem
Create an opaque signed message
openssl cms -sign -in message.txt -text -out mail.msg -nodetach \
-signer mycert.pem
Create a signed message, include some additional certificates and
read the private key from another file:
openssl cms -sign -in in.txt -text -out mail.msg \
-signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
Create a signed message with two signers, use key identifier:
openssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -signer othercert.pem -keyid
Send a signed message under Unix directly to sendmail, including headers:
openssl cms -sign -in in.txt -text -signer mycert.pem \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed message" | sendmail someone@somewhere
Verify a message and extract the signer's certificate if successful:
openssl cms -verify -in mail.msg -signer user.pem -out signedtext.txt
Send encrypted mail using triple DES:
openssl cms -encrypt -in in.txt -from steve@openssl.org \
-to someone@somewhere -subject "Encrypted message" \
-des3 user.pem -out mail.msg
Sign and encrypt mail:
openssl cms -sign -in ml.txt -signer my.pem -text \
| openssl cms -encrypt -out mail.msg \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed and Encrypted message" -des3 user.pem
Note: the encryption command does not include the B<-text> option because the
message being encrypted already has MIME headers.
Decrypt mail:
openssl cms -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
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:
-----BEGIN PKCS7-----
-----END PKCS7-----
and using the command,
openssl cms -verify -inform PEM -in signature.pem -content content.txt
alternatively you can base64 decode the signature and use
openssl cms -verify -inform DER -in signature.der -content content.txt
Create an encrypted message using 128 bit Camellia:
openssl cms -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
Add a signer to an existing message:
openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg
Sign mail using RSA-PSS:
openssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -keyopt rsa_padding_mode:pss
Create encrypted mail using RSA-OAEP:
openssl cms -encrypt -in plain.txt -out mail.msg \
-recip cert.pem -keyopt rsa_padding_mode:oaep
Use SHA256 KDF with an ECDH certificate:
openssl cms -encrypt -in plain.txt -out mail.msg \
-recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
=head1 BUGS
The MIME parser isn't very clever: it seems to handle most messages that I've
thrown at it but it may choke on others.
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.
Ideally a database should be maintained of a certificates for each email
address.
The code doesn't currently take note of the permitted symmetric encryption
algorithms as supplied in the 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.
No revocation checking is done on the signer's certificate.
=head1 HISTORY
The use of multiple B<-signer> options and the B<-resign> command were first
added in OpenSSL 1.0.0
The B<keyopt> option was first added in OpenSSL 1.1.0
The use of B<-recip> to specify the recipient when encrypting mail was first
added to OpenSSL 1.1.0
Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0.
The use of non-RSA keys with B<-encrypt> and B<-decrypt> was first added
to OpenSSL 1.1.0.
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
=cut

350
doc/apps/config.pod Normal file
View File

@@ -0,0 +1,350 @@
=pod
=for comment openssl_manual_section:5
=head1 NAME
config - OpenSSL CONF library configuration files
=head1 DESCRIPTION
The OpenSSL CONF library can be used to read configuration files.
It is used for the OpenSSL master configuration file B<openssl.cnf>
and in a few other places like B<SPKAC> files and certificate extension
files for the B<x509> utility. OpenSSL applications can also use the
CONF library for their own purposes.
A configuration file is divided into a number of sections. Each section
starts with a line B<[ section_name ]> and ends when a new section is
started or end of file is reached. A section name can consist of
alphanumeric characters and underscores.
The first section of a configuration file is special and is referred
to as the B<default> section this is usually unnamed and is from the
start of file until the first named section. When a name is being looked up
it is first looked up in a named section (if any) and then the
default section.
The environment is mapped onto a section called B<ENV>.
Comments can be included by preceding them with the B<#> character
Each section in a configuration file consists of a number of name and
value pairs of the form B<name=value>
The B<name> string can contain any alphanumeric characters as well as
a few punctuation symbols such as B<.> B<,> B<;> and B<_>.
The B<value> string consists of the string following the B<=> character
until end of line with any leading and trailing white space removed.
The value string undergoes variable expansion. This can be done by
including the form B<$var> or B<${var}>: this will substitute the value
of the named variable in the current section. It is also possible to
substitute a value from another section using the syntax B<$section::name>
or B<${section::name}>. By using the form B<$ENV::name> environment
variables can be substituted. It is also possible to assign values to
environment variables by using the name B<ENV::name>, this will work
if the program looks up environment variables using the B<CONF> library
instead of calling B<getenv()> directly.
It is possible to escape certain characters by using any kind of quote
or the B<\> character. By making the last character of a line a B<\>
a B<value> string can be spread across multiple lines. In addition
the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized.
=head1 OPENSSL LIBRARY CONFIGURATION
In OpenSSL 0.9.7 and later applications can automatically configure certain
aspects of OpenSSL using the master OpenSSL configuration file, or optionally
an alternative configuration file. The B<openssl> utility includes this
functionality: any sub command uses the master OpenSSL configuration file
unless an option is used in the sub command to use an alternative configuration
file.
To enable library configuration the default section needs to contain an
appropriate line which points to the main configuration section. The default
name is B<openssl_conf> which is used by the B<openssl> utility. Other
applications may use an alternative name such as B<myapplicaton_conf>.
The configuration section should consist of a set of name value pairs which
contain specific module configuration information. The B<name> represents
the name of the I<configuration module> the meaning of the B<value> is
module specific: it may, for example, represent a further configuration
section containing configuration module specific information. E.g.
openssl_conf = openssl_init
[openssl_init]
oid_section = new_oids
engines = engine_section
[new_oids]
... new oids here ...
[engine_section]
... engine stuff here ...
The features of each configuration module are described below.
=head2 ASN1 OBJECT CONFIGURATION MODULE
This module has the name B<oid_section>. The value of this variable points
to a section containing name value pairs of OIDs: the name is the OID short
and long name, the value is the numerical form of the OID. Although some of
the B<openssl> utility sub commands already have their own ASN1 OBJECT section
functionality not all do. By using the ASN1 OBJECT configuration module
B<all> the B<openssl> utility sub commands can see the new objects as well
as any compliant applications. For example:
[new_oids]
some_new_oid = 1.2.3.4
some_other_oid = 1.2.3.5
In OpenSSL 0.9.8 it is also possible to set the value to the long name followed
by a comma and the numerical OID form. For example:
shortName = some object long name, 1.2.3.4
=head2 ENGINE CONFIGURATION MODULE
This ENGINE configuration module has the name B<engines>. The value of this
variable points to a section containing further ENGINE configuration
information.
The section pointed to by B<engines> is a table of engine names (though see
B<engine_id> below) and further sections containing configuration information
specific to each ENGINE.
Each ENGINE specific section is used to set default algorithms, load
dynamic, perform initialization and send ctrls. The actual operation performed
depends on the I<command> name which is the name of the name value pair. The
currently supported commands are listed below.
For example:
[engine_section]
# Configure ENGINE named "foo"
foo = foo_section
# Configure ENGINE named "bar"
bar = bar_section
[foo_section]
... foo ENGINE specific commands ...
[bar_section]
... "bar" ENGINE specific commands ...
The command B<engine_id> is used to give the ENGINE name. If used this
command must be first. For example:
[engine_section]
# This would normally handle an ENGINE named "foo"
foo = foo_section
[foo_section]
# Override default name and use "myfoo" instead.
engine_id = myfoo
The command B<dynamic_path> loads and adds an ENGINE from the given path. It
is equivalent to sending the ctrls B<SO_PATH> with the path argument followed
by B<LIST_ADD> with value 2 and B<LOAD> to the dynamic ENGINE. If this is
not the required behaviour then alternative ctrls can be sent directly
to the dynamic ENGINE using ctrl commands.
The command B<init> determines whether to initialize the ENGINE. If the value
is B<0> the ENGINE will not be initialized, if B<1> and attempt it made to
initialized the ENGINE immediately. If the B<init> command is not present
then an attempt will be made to initialize the ENGINE after all commands in
its section have been processed.
The command B<default_algorithms> sets the default algorithms an ENGINE will
supply using the functions B<ENGINE_set_default_string()>
If the name matches none of the above command names it is assumed to be a
ctrl command which is sent to the ENGINE. The value of the command is the
argument to the ctrl command. If the value is the string B<EMPTY> then no
value is sent to the command.
For example:
[engine_section]
# Configure ENGINE named "foo"
foo = foo_section
[foo_section]
# Load engine from DSO
dynamic_path = /some/path/fooengine.so
# A foo specific ctrl.
some_ctrl = some_value
# Another ctrl that doesn't take a value.
other_ctrl = EMPTY
# Supply all default algorithms
default_algorithms = ALL
=head2 EVP CONFIGURATION MODULE
This modules has the name B<alg_section> which points to a section containing
algorithm commands.
Currently the only algorithm command supported is B<fips_mode> whose
value should be a boolean string such as B<on> or B<off>. If the value is
B<on> this attempt to enter FIPS mode. If the call fails or the library is
not FIPS capable then an error occurs.
For example:
alg_section = evp_settings
[evp_settings]
fips_mode = on
=head1 NOTES
If a configuration file attempts to expand a variable that doesn't exist
then an error is flagged and the file will not load. This can happen
if an attempt is made to expand an environment variable that doesn't
exist. For example in a previous version of OpenSSL the default OpenSSL
master configuration file used the value of B<HOME> which may not be
defined on non Unix systems and would cause an error.
This can be worked around by including a B<default> section to provide
a default value: then if the environment lookup fails the default value
will be used instead. For this to work properly the default value must
be defined earlier in the configuration file than the expansion. See
the B<EXAMPLES> section for an example of how to do this.
If the same variable exists in the same section then all but the last
value will be silently ignored. In certain circumstances such as with
DNs the same field may occur multiple times. This is usually worked
around by ignoring any characters before an initial B<.> e.g.
1.OU="My first OU"
2.OU="My Second OU"
=head1 EXAMPLES
Here is a sample configuration file using some of the features
mentioned above.
# This is the default section.
HOME=/temp
RANDFILE= ${ENV::HOME}/.rnd
configdir=$ENV::HOME/config
[ section_one ]
# We are now in section one.
# Quotes permit leading and trailing whitespace
any = " any variable name "
other = A string that can \
cover several lines \
by including \\ characters
message = Hello World\n
[ section_two ]
greeting = $section_one::message
This next example shows how to expand environment variables safely.
Suppose you want a variable called B<tmpfile> to refer to a
temporary filename. The directory it is placed in can determined by
the the B<TEMP> or B<TMP> environment variables but they may not be
set to any value at all. If you just include the environment variable
names and the variable doesn't exist then this will cause an error when
an attempt is made to load the configuration file. By making use of the
default section both values can be looked up with B<TEMP> taking
priority and B</tmp> used if neither is defined:
TMP=/tmp
# The above value is used if TMP isn't in the environment
TEMP=$ENV::TMP
# The above value is used if TEMP isn't in the environment
tmpfile=${ENV::TEMP}/tmp.filename
Simple OpenSSL library configuration example to enter FIPS mode:
# Default appname: should match "appname" parameter (if any)
# supplied to CONF_modules_load_file et al.
openssl_conf = openssl_conf_section
[openssl_conf_section]
# Configuration module list
alg_section = evp_sect
[evp_sect]
# Set to "yes" to enter FIPS mode if supported
fips_mode = yes
Note: in the above example you will get an error in non FIPS capable versions
of OpenSSL.
More complex OpenSSL library configuration. Add OID and don't enter FIPS mode:
# Default appname: should match "appname" parameter (if any)
# supplied to CONF_modules_load_file et al.
openssl_conf = openssl_conf_section
[openssl_conf_section]
# Configuration module list
alg_section = evp_sect
oid_section = new_oids
[evp_sect]
# This will have no effect as FIPS mode is off by default.
# Set to "yes" to enter FIPS mode, if supported
fips_mode = no
[new_oids]
# New OID, just short name
newoid1 = 1.2.3.4.1
# New OID shortname and long name
newoid2 = New OID 2 long name, 1.2.3.4.2
The above examples can be used with with any application supporting library
configuration if "openssl_conf" is modified to match the appropriate "appname".
For example if the second sample file above is saved to "example.cnf" then
the command line:
OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1
will output:
0:d=0 hl=2 l= 4 prim: OBJECT :newoid1
showing that the OID "newoid1" has been added as "1.2.3.4.1".
=head1 BUGS
Currently there is no way to include characters using the octal B<\nnn>
form. Strings are all null terminated so nulls cannot form part of
the value.
The escaping isn't quite right: if you want to use sequences like B<\n>
you can't use any quote escaping on the same line.
Files are loaded in a single pass. This means that an variable expansion
will only work if the variables referenced are defined earlier in the
file.
=head1 SEE ALSO
L<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)>
=cut

128
doc/apps/crl.pod Normal file
View File

@@ -0,0 +1,128 @@
=pod
=head1 NAME
crl - CRL utility
=head1 SYNOPSIS
B<openssl> B<crl>
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-text>]
[B<-in filename>]
[B<-out filename>]
[B<-nameopt option>]
[B<-noout>]
[B<-hash>]
[B<-issuer>]
[B<-lastupdate>]
[B<-nextupdate>]
[B<-CAfile file>]
[B<-CApath dir>]
=head1 DESCRIPTION
The B<crl> command processes CRL files in DER or PEM format.
=head1 COMMAND OPTIONS
=over 4
=item B<-inform DER|PEM>
This specifies the input format. B<DER> format is DER encoded CRL
structure. B<PEM> (the default) is a base64 encoded version of
the DER form with header and footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
This specifies the input filename to read from or standard input if this
option is not specified.
=item B<-out filename>
specifies the output filename to write to or standard output by
default.
=item B<-text>
print out the CRL in text form.
=item B<-nameopt option>
option which determines how the subject or issuer names are displayed. See
the description of B<-nameopt> in L<x509(1)|x509(1)>.
=item B<-noout>
don't output the encoded version of the CRL.
=item B<-hash>
output a hash of the issuer name. This can be use to lookup CRLs in
a directory by issuer name.
=item B<-hash_old>
outputs the "hash" of the CRL issuer name using the older algorithm
as used by OpenSSL versions before 1.0.0.
=item B<-issuer>
output the issuer name.
=item B<-lastupdate>
output the lastUpdate field.
=item B<-nextupdate>
output the nextUpdate field.
=item B<-CAfile file>
verify the signature on a CRL by looking up the issuing certificate in
B<file>
=item B<-CApath dir>
verify the signature on a CRL by looking up the issuing certificate in
B<dir>. This directory must be a standard certificate directory: that
is a hash of each subject name (using B<x509 -hash>) should be linked
to each certificate.
=back
=head1 NOTES
The PEM CRL format uses the header and footer lines:
-----BEGIN X509 CRL-----
-----END X509 CRL-----
=head1 EXAMPLES
Convert a CRL file from PEM to DER:
openssl crl -in crl.pem -outform DER -out crl.der
Output the text form of a DER encoded certificate:
openssl crl -in crl.der -text -noout
=head1 BUGS
Ideally it should be possible to create a CRL using appropriate options
and files too.
=head1 SEE ALSO
L<crl2pkcs7(1)|crl2pkcs7(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>
=cut

91
doc/apps/crl2pkcs7.pod Normal file
View File

@@ -0,0 +1,91 @@
=pod
=head1 NAME
crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates.
=head1 SYNOPSIS
B<openssl> B<crl2pkcs7>
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
[B<-out filename>]
[B<-certfile filename>]
[B<-nocrl>]
=head1 DESCRIPTION
The B<crl2pkcs7> command takes an optional CRL and one or more
certificates and converts them into a PKCS#7 degenerate "certificates
only" structure.
=head1 COMMAND OPTIONS
=over 4
=item B<-inform DER|PEM>
This specifies the CRL input format. B<DER> format is DER encoded CRL
structure.B<PEM> (the default) is a base64 encoded version of
the DER form with header and footer lines.
=item B<-outform DER|PEM>
This specifies the PKCS#7 structure output format. B<DER> format is DER
encoded PKCS#7 structure.B<PEM> (the default) is a base64 encoded version of
the DER form with header and footer lines.
=item B<-in filename>
This specifies the input filename to read a CRL from or standard input if this
option is not specified.
=item B<-out filename>
specifies the output filename to write the PKCS#7 structure to or standard
output by default.
=item B<-certfile filename>
specifies a filename containing one or more certificates in B<PEM> format.
All certificates in the file will be added to the PKCS#7 structure. This
option can be used more than once to read certificates form multiple
files.
=item B<-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.
=back
=head1 EXAMPLES
Create a PKCS#7 structure from a certificate and CRL:
openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem
Creates a PKCS#7 structure in DER format with no CRL from several
different certificates:
openssl crl2pkcs7 -nocrl -certfile newcert.pem
-certfile demoCA/cacert.pem -outform DER -out p7.der
=head1 NOTES
The output file is a PKCS#7 signed data structure containing no signers and
just certificates and an optional CRL.
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 application/x-x509-user-cert.
The B<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.
=head1 SEE ALSO
L<pkcs7(1)|pkcs7(1)>
=cut

208
doc/apps/dgst.pod Normal file
View File

@@ -0,0 +1,208 @@
=pod
=head1 NAME
dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md2, md4, md5, dss1 - message digests
=head1 SYNOPSIS
B<openssl> B<dgst>
[B<-sha|-sha1|-mdc2|-ripemd160|-sha224|-sha256|-sha384|-sha512|-md2|-md4|-md5|-dss1>]
[B<-c>]
[B<-d>]
[B<-hex>]
[B<-binary>]
[B<-r>]
[B<-non-fips-allow>]
[B<-out filename>]
[B<-sign filename>]
[B<-keyform arg>]
[B<-passin arg>]
[B<-verify filename>]
[B<-prverify filename>]
[B<-signature filename>]
[B<-hmac key>]
[B<-non-fips-allow>]
[B<-fips-fingerprint>]
[B<file...>]
B<openssl>
[I<digest>]
[B<...>]
=head1 DESCRIPTION
The digest functions output the message digest of a supplied file or files
in hexadecimal. The digest functions also generate and verify digital
signatures using message digests.
=head1 OPTIONS
=over 4
=item B<-c>
print out the digest in two digit groups separated by colons, only relevant if
B<hex> format output is used.
=item B<-d>
print out BIO debugging information.
=item B<-hex>
digest is to be output as a hex dump. This is the default case for a "normal"
digest as opposed to a digital signature. See NOTES below for digital
signatures using B<-hex>.
=item B<-binary>
output the digest or signature in binary form.
=item B<-r>
output the digest in the "coreutils" format used by programs like B<sha1sum>.
=item B<-non-fips-allow>
Allow use of non FIPS digest when in FIPS mode. This has no effect when not in
FIPS mode.
=item B<-out filename>
filename to output to, or standard output by default.
=item B<-sign filename>
digitally sign the digest using the private key in "filename".
=item B<-keyform arg>
Specifies the key format to sign digest with. The DER, PEM, P12,
and ENGINE formats are supported.
=item B<-engine id>
Use engine B<id> for operations (including private key storage).
This engine is not used as source for digest algorithms, unless it is
also specified in the configuration file.
=item B<-sigopt nm:v>
Pass options to the signature algorithm during sign or verify operations.
Names and values of these options are algorithm-specific.
=item B<-passin arg>
the private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-verify filename>
verify the signature using the the public key in "filename".
The output is either "Verification OK" or "Verification Failure".
=item B<-prverify filename>
verify the signature using the the private key in "filename".
=item B<-signature filename>
the actual signature to verify.
=item B<-hmac key>
create a hashed MAC using "key".
=item B<-mac alg>
create MAC (keyed Message Authentication Code). The most popular MAC
algorithm is HMAC (hash-based MAC), but there are other MAC algorithms
which are not based on hash, for instance B<gost-mac> algorithm,
supported by B<ccgost> engine. MAC keys and other options should be set
via B<-macopt> parameter.
=item B<-macopt nm:v>
Passes options to MAC algorithm, specified by B<-mac> key.
Following options are supported by both by B<HMAC> and B<gost-mac>:
=over 8
=item B<key:string>
Specifies MAC key as alphnumeric string (use if key contain printable
characters only). String length must conform to any restrictions of
the MAC algorithm for example exactly 32 chars for gost-mac.
=item B<hexkey:string>
Specifies MAC key in hexadecimal form (two hex digits per byte).
Key length must conform to any restrictions of the MAC algorithm
for example exactly 32 chars for gost-mac.
=back
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-non-fips-allow>
enable use of non-FIPS algorithms such as MD5 even in FIPS mode.
=item B<-fips-fingerprint>
compute HMAC using a specific key
for certain OpenSSL-FIPS operations.
=item B<file...>
file or files to digest. If no files are specified then standard input is
used.
=back
=head1 EXAMPLES
To create a hex-encoded message digest of a file:
openssl dgst -md5 -hex file.txt
To sign a file using SHA-256 with binary file output:
openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt
To verify a signature:
openssl dgst -sha256 -verify publickey.pem \
-signature signature.sign \
file.txt
=head1 NOTES
The digest of choice for all new applications is SHA1. Other digests are
however still widely used.
When signing a file, B<dgst> will automatically determine the algorithm
(RSA, ECC, etc) to use for signing based on the private key's ASN.1 info.
When verifying signatures, it only handles the RSA, DSA, or ECDSA signature
itself, not the related data to identify the signer and algorithm used in
formats such as x.509, CMS, and S/MIME.
A source of random numbers is required for certain signing algorithms, in
particular ECDSA and DSA.
The signing and verify options should only be used if a single file is
being signed or verified.
Hex signatures cannot be verified using B<openssl>. Instead, use "xxd -r"
or similar program to transform the hex signature into a binary signature
prior to verification.
=cut

149
doc/apps/dhparam.pod Normal file
View File

@@ -0,0 +1,149 @@
=pod
=head1 NAME
dhparam - DH parameter manipulation and generation
=head1 SYNOPSIS
B<openssl dhparam>
[B<-inform DER|PEM>]
[B<-outform DER|PEM>]
[B<-in> I<filename>]
[B<-out> I<filename>]
[B<-dsaparam>]
[B<-check>]
[B<-noout>]
[B<-text>]
[B<-C>]
[B<-2>]
[B<-5>]
[B<-rand> I<file(s)>]
[B<-engine id>]
[I<numbits>]
=head1 DESCRIPTION
This command is used to manipulate DH parameter files.
=head1 OPTIONS
=over 4
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
form compatible with the PKCS#3 DHparameter structure. The PEM form is the
default format: it consists of the B<DER> format base64 encoded with
additional header and footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in> I<filename>
This specifies the input filename to read parameters from or standard input if
this option is not specified.
=item B<-out> I<filename>
This specifies the output filename parameters to. Standard output is used
if this option is not present. The output filename should B<not> be the same
as the input filename.
=item B<-dsaparam>
If this option is used, DSA rather than DH parameters are read or created;
they are converted to DH format. Otherwise, "strong" primes (such
that (p-1)/2 is also prime) will be used for DH parameter generation.
DH parameter generation with the B<-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.
=item B<-check>
check if the parameters are valid primes and generator.
=item B<-2>, B<-5>
The generator to use, either 2 or 5. If present then the
input file is ignored and parameters are generated instead. If not
present but B<numbits> is present, parameters are generated with the
default generator 2.
=item B<-rand> I<file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item I<numbits>
this option specifies that a parameter set should be generated of size
I<numbits>. It must be the last option. If this option is present then
the input file is ignored and parameters are generated instead. If
this option is not present but a generator (B<-2> or B<-5>) is
present, parameters are generated with a default length of 2048 bits.
=item B<-noout>
this option inhibits the output of the encoded version of the parameters.
=item B<-text>
this option prints out the DH parameters in human readable form.
=item B<-C>
this option converts the parameters into C code. The parameters can then
be loaded by calling the B<get_dh>I<numbits>B<()> function.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=back
=head1 WARNINGS
The program B<dhparam> combines the functionality of the programs B<dh> and
B<gendh> in previous versions of OpenSSL and SSLeay. The B<dh> and B<gendh>
programs are retained for now but may have different purposes in future
versions of OpenSSL.
=head1 NOTES
PEM format DH parameters use the header and footer lines:
-----BEGIN DH PARAMETERS-----
-----END DH PARAMETERS-----
OpenSSL currently only supports the older PKCS#3 DH, not the newer X9.42
DH.
This program manipulates DH parameters not keys.
=head1 BUGS
There should be a way to generate and manipulate DH keys.
=head1 SEE ALSO
L<dsaparam(1)|dsaparam(1)>
=head1 HISTORY
The B<dhparam> command was added in OpenSSL 0.9.5.
The B<-dsaparam> option was added in OpenSSL 0.9.6.
=cut

164
doc/apps/dsa.pod Normal file
View File

@@ -0,0 +1,164 @@
=pod
=head1 NAME
dsa - DSA key processing
=head1 SYNOPSIS
B<openssl> B<dsa>
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
[B<-camellia128>]
[B<-camellia192>]
[B<-camellia256>]
[B<-des>]
[B<-des3>]
[B<-idea>]
[B<-text>]
[B<-noout>]
[B<-modulus>]
[B<-pubin>]
[B<-pubout>]
[B<-engine id>]
=head1 DESCRIPTION
The B<dsa> command processes DSA keys. They can be converted between various
forms and their components printed out. B<Note> This command uses the
traditional SSLeay compatible format for private key encryption: newer
applications should use the more secure PKCS#8 format using the B<pkcs8>
=head1 COMMAND OPTIONS
=over 4
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option with a private key uses
an ASN1 DER encoded form of an ASN.1 SEQUENCE consisting of the values of
version (currently zero), p, q, g, the public and private key components
respectively as ASN.1 INTEGERs. When used with a public key it uses a
SubjectPublicKeyInfo structure: it is an error if the key is not DSA.
The B<PEM> form is the default format: it consists of the B<DER> format base64
encoded with additional header and footer lines. In the case of a private key
PKCS#8 format is also accepted.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
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.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-out filename>
This specifies the output filename to write a key to or standard output by
is not specified. If any encryption options are set then a pass phrase will be
prompted for. The output filename should B<not> be the same as the input
filename.
=item B<-passout arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
These options encrypt the private key with the specified
cipher 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 B<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.
=item B<-text>
prints out the public, private key components and parameters.
=item B<-noout>
this option prevents output of the encoded version of the key.
=item B<-modulus>
this option prints out the value of the public key component of the key.
=item B<-pubin>
by default a private key is read from the input file: with this option a
public key is read instead.
=item B<-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.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=back
=head1 NOTES
The PEM private key format uses the header and footer lines:
-----BEGIN DSA PRIVATE KEY-----
-----END DSA PRIVATE KEY-----
The PEM public key format uses the header and footer lines:
-----BEGIN PUBLIC KEY-----
-----END PUBLIC KEY-----
=head1 EXAMPLES
To remove the pass phrase on a DSA private key:
openssl dsa -in key.pem -out keyout.pem
To encrypt a private key using triple DES:
openssl dsa -in key.pem -des3 -out keyout.pem
To convert a private key from PEM to DER format:
openssl dsa -in key.pem -outform DER -out keyout.der
To print out the components of a private key to standard output:
openssl dsa -in key.pem -text -noout
To just output the public part of a private key:
openssl dsa -in key.pem -pubout -out pubkey.pem
=head1 SEE ALSO
L<dsaparam(1)|dsaparam(1)>, L<gendsa(1)|gendsa(1)>, L<rsa(1)|rsa(1)>,
L<genrsa(1)|genrsa(1)>
=cut

110
doc/apps/dsaparam.pod Normal file
View File

@@ -0,0 +1,110 @@
=pod
=head1 NAME
dsaparam - DSA parameter manipulation and generation
=head1 SYNOPSIS
B<openssl dsaparam>
[B<-inform DER|PEM>]
[B<-outform DER|PEM>]
[B<-in filename>]
[B<-out filename>]
[B<-noout>]
[B<-text>]
[B<-C>]
[B<-rand file(s)>]
[B<-genkey>]
[B<-engine id>]
[B<numbits>]
=head1 DESCRIPTION
This command is used to manipulate or generate DSA parameter files.
=head1 OPTIONS
=over 4
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
form compatible with RFC2459 (PKIX) DSS-Parms that is a SEQUENCE consisting
of p, q and g respectively. The PEM form is the default format: it consists
of the B<DER> format base64 encoded with additional header and footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
This specifies the input filename to read parameters from or standard input if
this option is not specified. If the B<numbits> parameter is included then
this option will be ignored.
=item B<-out filename>
This specifies the output filename parameters to. Standard output is used
if this option is not present. The output filename should B<not> be the same
as the input filename.
=item B<-noout>
this option inhibits the output of the encoded version of the parameters.
=item B<-text>
this option prints out the DSA parameters in human readable form.
=item B<-C>
this option converts the parameters into C code. The parameters can then
be loaded by calling the B<get_dsaXXX()> function.
=item B<-genkey>
this option will generate a DSA either using the specified or generated
parameters.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<numbits>
this option specifies that a parameter set should be generated of size
B<numbits>. It must be the last option. If this option is included then
the input file (if any) is ignored.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=back
=head1 NOTES
PEM format DSA parameters use the header and footer lines:
-----BEGIN DSA PARAMETERS-----
-----END DSA PARAMETERS-----
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.
=head1 SEE ALSO
L<gendsa(1)|gendsa(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>,
L<rsa(1)|rsa(1)>
=cut

190
doc/apps/ec.pod Normal file
View File

@@ -0,0 +1,190 @@
=pod
=head1 NAME
ec - EC key processing
=head1 SYNOPSIS
B<openssl> B<ec>
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-des>]
[B<-des3>]
[B<-idea>]
[B<-text>]
[B<-noout>]
[B<-param_out>]
[B<-pubin>]
[B<-pubout>]
[B<-conv_form arg>]
[B<-param_enc arg>]
[B<-engine id>]
=head1 DESCRIPTION
The B<ec> command processes EC keys. They can be converted between various
forms and their components printed out. B<Note> OpenSSL uses the
private key format specified in 'SEC 1: Elliptic Curve Cryptography'
(http://www.secg.org/). To convert a OpenSSL EC private key into the
PKCS#8 private key format use the B<pkcs8> command.
=head1 COMMAND OPTIONS
=over 4
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option 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.
The B<PEM> form is the default format: it consists of the B<DER> format base64
encoded with additional header and footer lines. In the case of a private key
PKCS#8 format is also accepted.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
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.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-out filename>
This specifies the output filename to write a key to or standard output by
is not specified. If any encryption options are set then a pass phrase will be
prompted for. The output filename should B<not> be the same as the input
filename.
=item B<-passout arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-des|-des3|-idea>
These options encrypt the private key with the DES, triple DES, IDEA or
any other cipher supported by 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 B<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.
=item B<-text>
prints out the public, private key components and parameters.
=item B<-noout>
this option prevents output of the encoded version of the key.
=item B<-modulus>
this option prints out the value of the public key component of the key.
=item B<-pubin>
by default a private key is read from the input file: with this option a
public key is read instead.
=item B<-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.
=item B<-conv_form>
This specifies how the points on the elliptic curve are converted
into octet strings. Possible values are: B<compressed> (the default
value), B<uncompressed> and B<hybrid>. For more information regarding
the point conversion forms please read the X9.62 standard.
B<Note> Due to patent issues the B<compressed> option is disabled
by default for binary curves and can be enabled by defining
the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
=item B<-param_enc arg>
This specifies how the elliptic curve parameters are encoded.
Possible value are: B<named_curve>, i.e. the ec parameters are
specified by a OID, or B<explicit> where the ec parameters are
explicitly given (see RFC 3279 for the definition of the
EC parameters structures). The default value is B<named_curve>.
B<Note> the B<implicitlyCA> alternative ,as specified in RFC 3279,
is currently not implemented in OpenSSL.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=back
=head1 NOTES
The PEM private key format uses the header and footer lines:
-----BEGIN EC PRIVATE KEY-----
-----END EC PRIVATE KEY-----
The PEM public key format uses the header and footer lines:
-----BEGIN PUBLIC KEY-----
-----END PUBLIC KEY-----
=head1 EXAMPLES
To encrypt a private key using triple DES:
openssl ec -in key.pem -des3 -out keyout.pem
To convert a private key from PEM to DER format:
openssl ec -in key.pem -outform DER -out keyout.der
To print out the components of a private key to standard output:
openssl ec -in key.pem -text -noout
To just output the public part of a private key:
openssl ec -in key.pem -pubout -out pubkey.pem
To change the parameters encoding to B<explicit>:
openssl ec -in key.pem -param_enc explicit -out keyout.pem
To change the point conversion form to B<compressed>:
openssl ec -in key.pem -conv_form compressed -out keyout.pem
=head1 SEE ALSO
L<ecparam(1)|ecparam(1)>, L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>
=head1 HISTORY
The ec command was first introduced in OpenSSL 0.9.8.
=head1 AUTHOR
Nils Larsch for the OpenSSL project (http://www.openssl.org).
=cut

179
doc/apps/ecparam.pod Normal file
View File

@@ -0,0 +1,179 @@
=pod
=head1 NAME
ecparam - EC parameter manipulation and generation
=head1 SYNOPSIS
B<openssl ecparam>
[B<-inform DER|PEM>]
[B<-outform DER|PEM>]
[B<-in filename>]
[B<-out filename>]
[B<-noout>]
[B<-text>]
[B<-C>]
[B<-check>]
[B<-name arg>]
[B<-list_curves>]
[B<-conv_form arg>]
[B<-param_enc arg>]
[B<-no_seed>]
[B<-rand file(s)>]
[B<-genkey>]
[B<-engine id>]
=head1 DESCRIPTION
This command is used to manipulate or generate EC parameter files.
=head1 OPTIONS
=over 4
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN.1 DER encoded
form compatible with RFC 3279 EcpkParameters. The PEM form is the default
format: it consists of the B<DER> format base64 encoded with additional
header and footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
This specifies the input filename to read parameters from or standard input if
this option is not specified.
=item B<-out filename>
This specifies the output filename parameters to. Standard output is used
if this option is not present. The output filename should B<not> be the same
as the input filename.
=item B<-noout>
This option inhibits the output of the encoded version of the parameters.
=item B<-text>
This option prints out the EC parameters in human readable form.
=item B<-C>
This option converts the EC parameters into C code. The parameters can then
be loaded by calling the B<get_ec_group_XXX()> function.
=item B<-check>
Validate the elliptic curve parameters.
=item B<-name arg>
Use the EC parameters with the specified 'short' name. Use B<-list_curves>
to get a list of all currently implemented EC parameters.
=item B<-list_curves>
If this options is specified B<ecparam> will print out a list of all
currently implemented EC parameters names and exit.
=item B<-conv_form>
This specifies how the points on the elliptic curve are converted
into octet strings. Possible values are: B<compressed> (the default
value), B<uncompressed> and B<hybrid>. For more information regarding
the point conversion forms please read the X9.62 standard.
B<Note> Due to patent issues the B<compressed> option is disabled
by default for binary curves and can be enabled by defining
the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
=item B<-param_enc arg>
This specifies how the elliptic curve parameters are encoded.
Possible value are: B<named_curve>, i.e. the ec parameters are
specified by a OID, or B<explicit> where the ec parameters are
explicitly given (see RFC 3279 for the definition of the
EC parameters structures). The default value is B<named_curve>.
B<Note> the B<implicitlyCA> alternative ,as specified in RFC 3279,
is currently not implemented in OpenSSL.
=item B<-no_seed>
This option inhibits that the 'seed' for the parameter generation
is included in the ECParameters structure (see RFC 3279).
=item B<-genkey>
This option will generate a EC private key using the specified parameters.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=back
=head1 NOTES
PEM format EC parameters use the header and footer lines:
-----BEGIN EC PARAMETERS-----
-----END EC PARAMETERS-----
OpenSSL is currently not able to generate new groups and therefore
B<ecparam> can only create EC parameters from known (named) curves.
=head1 EXAMPLES
To create EC parameters with the group 'prime192v1':
openssl ecparam -out ec_param.pem -name prime192v1
To create EC parameters with explicit parameters:
openssl ecparam -out ec_param.pem -name prime192v1 -param_enc explicit
To validate given EC parameters:
openssl ecparam -in ec_param.pem -check
To create EC parameters and a private key:
openssl ecparam -out ec_key.pem -name prime192v1 -genkey
To change the point encoding to 'compressed':
openssl ecparam -in ec_in.pem -out ec_out.pem -conv_form compressed
To print out the EC parameters to standard output:
openssl ecparam -in ec_param.pem -noout -text
=head1 SEE ALSO
L<ec(1)|ec(1)>, L<dsaparam(1)|dsaparam(1)>
=head1 HISTORY
The ecparam command was first introduced in OpenSSL 0.9.8.
=head1 AUTHOR
Nils Larsch for the OpenSSL project (http://www.openssl.org)
=cut

333
doc/apps/enc.pod Normal file
View File

@@ -0,0 +1,333 @@
=pod
=head1 NAME
enc - symmetric cipher routines
=head1 SYNOPSIS
B<openssl enc -ciphername>
[B<-in filename>]
[B<-out filename>]
[B<-pass arg>]
[B<-e>]
[B<-d>]
[B<-a/-base64>]
[B<-A>]
[B<-k password>]
[B<-kfile filename>]
[B<-K key>]
[B<-iv IV>]
[B<-S salt>]
[B<-salt>]
[B<-nosalt>]
[B<-z>]
[B<-md>]
[B<-p>]
[B<-P>]
[B<-bufsize number>]
[B<-nopad>]
[B<-debug>]
[B<-none>]
[B<-engine id>]
=head1 DESCRIPTION
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.
=head1 OPTIONS
=over 4
=item B<-in filename>
the input filename, standard input by default.
=item B<-out filename>
the output filename, standard output by default.
=item B<-pass arg>
the password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-salt>
use a salt in the key derivation routines. This is the default.
=item B<-nosalt>
don't use a salt in the key derivation routines. This option B<SHOULD NOT> be
used except for test purposes or compatibility with ancient versions of OpenSSL
and SSLeay.
=item B<-e>
encrypt the input data: this is the default.
=item B<-d>
decrypt the input data.
=item B<-a>
base64 process the data. This means that if encryption is taking place
the data is base64 encoded after encryption. If decryption is set then
the input data is base64 decoded before being decrypted.
=item B<-base64>
same as B<-a>
=item B<-A>
if the B<-a> option is set then base64 process the data on one line.
=item B<-k password>
the password to derive the key from. This is for compatibility with previous
versions of OpenSSL. Superseded by the B<-pass> argument.
=item B<-kfile filename>
read the password to derive the key from the first line of B<filename>.
This is for compatibility with previous versions of OpenSSL. Superseded by
the B<-pass> argument.
=item B<-nosalt>
do not use a salt
=item B<-salt>
use salt (randomly generated or provide with B<-S> option) when
encrypting (this is the default).
=item B<-S salt>
the actual salt to use: this must be represented as a string of hex digits.
=item B<-K key>
the actual key to use: this must be represented as a string comprised only
of hex digits. If only the key is specified, the IV must additionally specified
using the B<-iv> option. When both a key and a password are specified, the
key given with the B<-K> option will be used and the IV generated from the
password will be taken. It probably does not make much sense to specify
both key and password.
=item B<-iv IV>
the actual IV to use: this must be represented as a string comprised only
of hex digits. When only the key is specified using the B<-K> option, the
IV must explicitly be defined. When a password is being specified using
one of the other options, the IV is generated from this password.
=item B<-p>
print out the key and IV used.
=item B<-P>
print out the key and IV used then immediately exit: don't do any encryption
or decryption.
=item B<-bufsize number>
set the buffer size for I/O
=item B<-nopad>
disable standard block padding
=item B<-debug>
debug the BIOs used for I/O.
=item B<-z>
Compress or decompress clear text using zlib before encryption or after
decryption. This option exists only if OpenSSL with compiled with zlib
or zlib-dynamic option.
=item B<-none>
Use NULL cipher (no encryption or decryption of input).
=back
=head1 NOTES
The program can be called either as B<openssl ciphername> or
B<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.
Engines which provide entirely new encryption algorithms (such as ccgost
engine which provides gost89 algorithm) should be configured in the
configuration file. Engines, specified in the command line using -engine
options can only be used for hadrware-assisted implementations of
ciphers, which are supported by OpenSSL core or other engine, specified
in the configuration file.
When enc command lists supported ciphers, ciphers provided by engines,
specified in the configuration files are listed too.
A password will be prompted for to derive the key and IV if necessary.
The B<-salt> option should B<ALWAYS> be used if the key is being derived
from a password unless you want compatibility with previous versions of
OpenSSL and SSLeay.
Without the B<-salt> option it is possible to perform efficient dictionary
attacks on the password and to attack stream cipher encrypted data. The reason
for this is that without the 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.
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.
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.
If padding is disabled then the input data must be a multiple of the cipher
block length.
All RC2 ciphers have the same key and effective key length.
Blowfish and RC5 algorithms use a 128 bit key.
=head1 SUPPORTED CIPHERS
Note that some of these ciphers can be disabled at compile time
and some are available only if an appropriate engine is configured
in the configuration file. The output of the B<enc> command run with
unsupported options (for example B<openssl enc -help>) includes a
list of ciphers, supported by your versesion of OpenSSL, including
ones provided by configured engines.
The B<enc> program does not support authenticated encryption modes
like CCM and GCM. The utility does not store or retrieve the
authentication tag.
base64 Base 64
bf-cbc Blowfish in CBC mode
bf Alias for bf-cbc
bf-cfb Blowfish in CFB mode
bf-ecb Blowfish in ECB mode
bf-ofb Blowfish in OFB mode
cast-cbc CAST in CBC mode
cast Alias for cast-cbc
cast5-cbc CAST5 in CBC mode
cast5-cfb CAST5 in CFB mode
cast5-ecb CAST5 in ECB mode
cast5-ofb CAST5 in OFB mode
des-cbc DES in CBC mode
des Alias for des-cbc
des-cfb DES in CBC mode
des-ofb DES in OFB mode
des-ecb DES in ECB mode
des-ede-cbc Two key triple DES EDE in CBC mode
des-ede Two key triple DES EDE in ECB mode
des-ede-cfb Two key triple DES EDE in CFB mode
des-ede-ofb Two key triple DES EDE in OFB mode
des-ede3-cbc Three key triple DES EDE in CBC mode
des-ede3 Three key triple DES EDE in ECB mode
des3 Alias for des-ede3-cbc
des-ede3-cfb Three key triple DES EDE CFB mode
des-ede3-ofb Three key triple DES EDE in OFB mode
desx DESX algorithm.
gost89 GOST 28147-89 in CFB mode (provided by ccgost engine)
gost89-cnt `GOST 28147-89 in CNT mode (provided by ccgost engine)
idea-cbc IDEA algorithm in CBC mode
idea same as idea-cbc
idea-cfb IDEA in CFB mode
idea-ecb IDEA in ECB mode
idea-ofb IDEA in OFB mode
rc2-cbc 128 bit RC2 in CBC mode
rc2 Alias for rc2-cbc
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-64 64 bit RC4
rc4-40 40 bit RC4
rc5-cbc RC5 cipher in CBC mode
rc5 Alias for rc5-cbc
rc5-cfb RC5 cipher in CFB mode
rc5-ecb RC5 cipher in ECB mode
rc5-ofb RC5 cipher in OFB mode
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
=head1 EXAMPLES
Just base64 encode a binary file:
openssl base64 -in file.bin -out file.b64
Decode the same file
openssl base64 -d -in file.b64 -out file.bin
Encrypt a file using triple DES in CBC mode using a prompted password:
openssl des3 -salt -in file.txt -out file.des3
Decrypt a file using a supplied password:
openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword
Encrypt a file then base64 encode it (so it can be sent via mail for example)
using Blowfish in CBC mode:
openssl bf -a -salt -in file.txt -out file.bf
Base64 decode a file then decrypt it:
openssl bf -d -salt -a -in file.bf -out file.txt
Decrypt some data using a supplied 40 bit RC4 key:
openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405
=head1 BUGS
The B<-A> option when used with large files doesn't work properly.
There should be an option to allow an iteration count to be included.
The B<enc> program only supports a fixed number of algorithms with
certain parameters. So if, for example, you want to use RC2 with a
76 bit key or RC4 with an 84 bit key you can't use this program.
=cut

39
doc/apps/errstr.pod Normal file
View File

@@ -0,0 +1,39 @@
=pod
=head1 NAME
errstr - lookup error codes
=head1 SYNOPSIS
B<openssl errstr error_code>
=head1 DESCRIPTION
Sometimes an application will not load error message and only
numerical forms will be available. The B<errstr> utility can be used to
display the meaning of the hex code. The hex code is the hex digits after the
second colon.
=head1 EXAMPLE
The error code:
27594:error:2006D080:lib(32):func(109):reason(128):bss_file.c:107:
can be displayed with:
openssl errstr 2006D080
to produce the error message:
error:2006D080:BIO routines:BIO_new_file:no such file
=head1 SEE ALSO
L<err(3)|err(3)>,
L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>,
L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>
=cut

72
doc/apps/gendsa.pod Normal file
View File

@@ -0,0 +1,72 @@
=pod
=head1 NAME
gendsa - generate a DSA private key from a set of parameters
=head1 SYNOPSIS
B<openssl> B<gendsa>
[B<-out filename>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
[B<-camellia128>]
[B<-camellia192>]
[B<-camellia256>]
[B<-des>]
[B<-des3>]
[B<-idea>]
[B<-rand file(s)>]
[B<-engine id>]
[B<paramfile>]
=head1 DESCRIPTION
The B<gendsa> command generates a DSA private key from a DSA parameter file
(which will be typically generated by the B<openssl dsaparam> command).
=head1 OPTIONS
=over 4
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
These options encrypt the private key with specified
cipher before outputting it. A pass phrase is prompted for.
If none of these options is specified no encryption is used.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=item B<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 B<openssl dsaparam> command.
=back
=head1 NOTES
DSA key generation is little more than random number generation so it is
much quicker that RSA key generation for example.
=head1 SEE ALSO
L<dsaparam(1)|dsaparam(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>,
L<rsa(1)|rsa(1)>
=cut

228
doc/apps/genpkey.pod Normal file
View File

@@ -0,0 +1,228 @@
=pod
=head1 NAME
genpkey - generate a private key
=head1 SYNOPSIS
B<openssl> B<genpkey>
[B<-out filename>]
[B<-outform PEM|DER>]
[B<-pass arg>]
[B<-cipher>]
[B<-engine id>]
[B<-paramfile file>]
[B<-algorithm alg>]
[B<-pkeyopt opt:value>]
[B<-genparam>]
[B<-text>]
=head1 DESCRIPTION
The B<genpkey> command generates a private key.
=head1 OPTIONS
=over 4
=item B<-out filename>
the output filename. If this argument is not specified then standard output is
used.
=item B<-outform DER|PEM>
This specifies the output format DER or PEM.
=item B<-pass arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-cipher>
This option encrypts the private key with the supplied cipher. Any algorithm
name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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. If used this option should precede all other
options.
=item B<-algorithm alg>
public key algorithm to use such as RSA, DSA or DH. If used this option must
precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
are mutually exclusive.
=item B<-pkeyopt opt:value>
set the public key algorithm option B<opt> to B<value>. The precise set of
options supported depends on the public key algorithm used and its
implementation. See B<KEY GENERATION OPTIONS> below for more details.
=item B<-genparam>
generate a set of parameters instead of a private key. If used this option must
precede and B<-algorithm>, B<-paramfile> or B<-pkeyopt> options.
=item B<-paramfile filename>
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 and B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
are mutually exclusive.
=item B<-text>
Print an (unencrypted) text representation of private and public keys and
parameters along with the PEM or DER structure.
=back
=head1 KEY GENERATION OPTIONS
The options supported by each algorith and indeed each implementation of an
algorithm can vary. The options for the OpenSSL implementations are detailed
below.
=head1 RSA KEY GENERATION OPTIONS
=over 4
=item B<rsa_keygen_bits:numbits>
The number of bits in the generated key. If not specified 1024 is used.
=item B<rsa_keygen_pubexp:value>
The RSA public exponent value. This can be a large decimal or
hexadecimal value if preceded by B<0x>. Default value is 65537.
=back
=head1 DSA PARAMETER GENERATION OPTIONS
=over 4
=item B<dsa_paramgen_bits:numbits>
The number of bits in the generated parameters. If not specified 1024 is used.
=back
=head1 DH PARAMETER GENERATION OPTIONS
=over 4
=item B<dh_paramgen_prime_len:numbits>
The number of bits in the prime parameter B<p>.
=item B<dh_paramgen_generator:value>
The value to use for the generator B<g>.
=item B<dh_rfc5114:num>
If this option is set then the appropriate RFC5114 parameters are used
instead of generating new parameters. The value B<num> can take the
values 1, 2 or 3 corresponding to RFC5114 DH parameters consisting of
1024 bit group with 160 bit subgroup, 2048 bit group with 224 bit subgroup
and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections
2.1, 2.2 and 2.3 respectively.
=back
=head1 EC PARAMETER GENERATION OPTIONS
=over 4
=item B<ec_paramgen_curve:curve>
the EC curve to use.
=back
=head1 GOST2001 KEY GENERATION AND PARAMETER OPTIONS
Gost 2001 support is not enabled by default. To enable this algorithm,
one should load the ccgost engine in the OpenSSL configuration file.
See README.gost file in the engines/ccgost directiry of the source
distribution for more details.
Use of a parameter file for the GOST R 34.10 algorithm is optional.
Parameters can be specified during key generation directly as well as
during generation of parameter file.
=over 4
=item B<paramset:name>
Specifies GOST R 34.10-2001 parameter set according to RFC 4357.
Parameter set can be specified using abbreviated name, object short name or
numeric OID. Following parameter sets are supported:
paramset OID Usage
A 1.2.643.2.2.35.1 Signature
B 1.2.643.2.2.35.2 Signature
C 1.2.643.2.2.35.3 Signature
XA 1.2.643.2.2.36.0 Key exchange
XB 1.2.643.2.2.36.1 Key exchange
test 1.2.643.2.2.35.0 Test purposes
=back
=head1 NOTES
The use of the genpkey program is encouraged over the algorithm specific
utilities because additional algorithm options and ENGINE provided algorithms
can be used.
=head1 EXAMPLES
Generate an RSA private key using default parameters:
openssl genpkey -algorithm RSA -out key.pem
Encrypt output private key using 128 bit AES and the passphrase "hello":
openssl genpkey -algorithm RSA -out key.pem -aes-128-cbc -pass pass:hello
Generate a 2048 bit RSA key using 3 as the public exponent:
openssl genpkey -algorithm RSA -out key.pem -pkeyopt rsa_keygen_bits:2048 \
-pkeyopt rsa_keygen_pubexp:3
Generate 1024 bit DSA parameters:
openssl genpkey -genparam -algorithm DSA -out dsap.pem \
-pkeyopt dsa_paramgen_bits:1024
Generate DSA key from parameters:
openssl genpkey -paramfile dsap.pem -out dsakey.pem
Generate 1024 bit DH parameters:
openssl genpkey -genparam -algorithm DH -out dhp.pem \
-pkeyopt dh_paramgen_prime_len:1024
Output RFC5114 2048 bit DH parameters with 224 bit subgroup:
openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2
Generate DH key from parameters:
openssl genpkey -paramfile dhp.pem -out dhkey.pem
=cut

102
doc/apps/genrsa.pod Normal file
View File

@@ -0,0 +1,102 @@
=pod
=head1 NAME
genrsa - generate an RSA private key
=head1 SYNOPSIS
B<openssl> B<genrsa>
[B<-out filename>]
[B<-passout arg>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
[B<-camellia128>]
[B<-camellia192>]
[B<-camellia256>]
[B<-des>]
[B<-des3>]
[B<-idea>]
[B<-f4>]
[B<-3>]
[B<-rand file(s)>]
[B<-engine id>]
[B<numbits>]
=head1 DESCRIPTION
The B<genrsa> command generates an RSA private key.
=head1 OPTIONS
=over 4
=item B<-out filename>
the output filename. If this argument is not specified then standard output is
used.
=item B<-passout arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
These options encrypt the private key with specified
cipher before outputting it. If none of these options is
specified no encryption is used. If encryption is used a pass phrase is prompted
for if it is not supplied via the B<-passout> argument.
=item B<-F4|-3>
the public exponent to use, either 65537 or 3. The default is 65537.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=item B<numbits>
the size of the private key to generate in bits. This must be the last option
specified. The default is 512.
=back
=head1 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 B<.> represents each number which
has passed an initial sieve test, B<+> means a number has passed a single
round of the Miller-Rabin primality test. A newline means that the number has
passed all the prime tests (the actual number depends on the key size).
Because key generation is a random process the time taken to generate a key
may vary somewhat.
=head1 BUGS
A quirk of the prime generation algorithm is that it cannot generate small
primes. Therefore the number of bits should not be less that 64. For typical
private keys this will not matter because for security reasons they will
be much larger (typically 1024 bits).
=head1 SEE ALSO
L<gendsa(1)|gendsa(1)>
=cut

70
doc/apps/nseq.pod Normal file
View File

@@ -0,0 +1,70 @@
=pod
=head1 NAME
nseq - create or examine a netscape certificate sequence
=head1 SYNOPSIS
B<openssl> B<nseq>
[B<-in filename>]
[B<-out filename>]
[B<-toseq>]
=head1 DESCRIPTION
The B<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.
=head1 COMMAND OPTIONS
=over 4
=item B<-in filename>
This specifies the input filename to read or standard input if this
option is not specified.
=item B<-out filename>
specifies the output filename or standard output by default.
=item B<-toseq>
normally a Netscape certificate sequence will be input and the output
is the certificates contained in it. With the B<-toseq> option the
situation is reversed: a Netscape certificate sequence is created from
a file of certificates.
=back
=head1 EXAMPLES
Output the certificates in a Netscape certificate sequence
openssl nseq -in nseq.pem -out certs.pem
Create a Netscape certificate sequence
openssl nseq -in certs.pem -toseq -out nseq.pem
=head1 NOTES
The B<PEM> encoded form uses the same headers and footers as a certificate:
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
A Netscape certificate sequence is a Netscape specific form that can be sent
to browsers as an alternative to the standard PKCS#7 format when several
certificates are sent to the browser: for example during certificate enrollment.
It is used by Netscape certificate server for example.
=head1 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.
=cut

401
doc/apps/ocsp.pod Normal file
View File

@@ -0,0 +1,401 @@
=pod
=head1 NAME
ocsp - Online Certificate Status Protocol utility
=head1 SYNOPSIS
B<openssl> B<ocsp>
[B<-out file>]
[B<-issuer file>]
[B<-cert file>]
[B<-serial n>]
[B<-signer file>]
[B<-signkey file>]
[B<-sign_other file>]
[B<-no_certs>]
[B<-req_text>]
[B<-resp_text>]
[B<-text>]
[B<-reqout file>]
[B<-respout file>]
[B<-reqin file>]
[B<-respin file>]
[B<-nonce>]
[B<-no_nonce>]
[B<-url URL>]
[B<-host host:n>]
[B<-header name value>]
[B<-path>]
[B<-CApath dir>]
[B<-CAfile file>]
[B<-no_alt_chains>]
[B<-VAfile file>]
[B<-validity_period n>]
[B<-status_age n>]
[B<-noverify>]
[B<-verify_other file>]
[B<-trust_other>]
[B<-no_intern>]
[B<-no_signature_verify>]
[B<-no_cert_verify>]
[B<-no_chain>]
[B<-no_cert_checks>]
[B<-no_explicit>]
[B<-port num>]
[B<-index file>]
[B<-CA file>]
[B<-rsigner file>]
[B<-rkey file>]
[B<-rother file>]
[B<-resp_no_certs>]
[B<-nmin n>]
[B<-ndays n>]
[B<-resp_key_id>]
[B<-nrequest n>]
[B<-md5|-sha1|...>]
=head1 DESCRIPTION
The Online Certificate Status Protocol (OCSP) enables applications to
determine the (revocation) state of an identified certificate (RFC 2560).
The B<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.
=head1 OCSP CLIENT OPTIONS
=over 4
=item B<-out filename>
specify output filename, default is standard output.
=item B<-issuer filename>
This specifies the current issuer certificate. This option can be used
multiple times. The certificate specified in B<filename> must be in
PEM format. This option B<MUST> come before any B<-cert> options.
=item B<-cert filename>
Add the certificate B<filename> to the request. The issuer certificate
is taken from the previous B<issuer> option, or an error occurs if no
issuer certificate is specified.
=item B<-serial num>
Same as the B<cert> option except the certificate with serial number
B<num> is added to the request. The serial number is interpreted as a
decimal integer unless preceded by B<0x>. Negative integers can also
be specified by preceding the value by a B<-> sign.
=item B<-signer filename>, B<-signkey filename>
Sign the OCSP request using the certificate specified in the B<signer>
option and the private key specified by the B<signkey> option. If
the B<signkey> option is not present then the private key is read
from the same file as the certificate. If neither option is specified then
the OCSP request is not signed.
=item B<-sign_other filename>
Additional certificates to include in the signed request.
=item B<-nonce>, B<-no_nonce>
Add an OCSP nonce extension to a request or disable OCSP nonce addition.
Normally if an OCSP request is input using the B<respin> option no
nonce is added: using the B<nonce> option will force addition of a nonce.
If an OCSP request is being created (using B<cert> and B<serial> options)
a nonce is automatically added specifying B<no_nonce> overrides this.
=item B<-req_text>, B<-resp_text>, B<-text>
print out the text form of the OCSP request, response or both respectively.
=item B<-reqout file>, B<-respout file>
write out the DER encoded certificate request or response to B<file>.
=item B<-reqin file>, B<-respin file>
read OCSP request or response file from B<file>. These option are ignored
if OCSP request or response creation is implied by other options (for example
with B<serial>, B<cert> and B<host> options).
=item B<-url responder_url>
specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified.
=item B<-host hostname:port>, B<-path pathname>
if the B<host> option is present then the OCSP request is sent to the host
B<hostname> on port B<port>. B<path> specifies the HTTP path name to use
or "/" by default.
=item B<-header name value>
If sending a request to an OCSP server, then the specified header name and
value are added to the HTTP request. Note that the B<name> and B<value> must
be specified as two separate parameters, not as a single quoted string, and
that the header name does not have the trailing colon.
Some OCSP responders require a Host header; use this flag to provide it.
=item B<-timeout seconds>
connection timeout to the OCSP responder in seconds
=item B<-CAfile file>, B<-CApath pathname>
file or pathname containing trusted CA certificates. These are used to verify
the signature on the OCSP response.
=item B<-no_alt_chains>
See L<B<verify>|verify(1)> manual page for details.
=item B<-verify_other file>
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.
=item B<-trust_other>
the certificates specified by the B<-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.
=item B<-VAfile file>
file containing explicitly trusted responder certificates. Equivalent to the
B<-verify_other> and B<-trust_other> options.
=item B<-noverify>
don't attempt to verify the OCSP response signature or the nonce values. This
option will normally only be used for debugging since it disables all verification
of the responders certificate.
=item B<-no_intern>
ignore certificates contained in the OCSP response when searching for the
signers certificate. With this option the signers certificate must be specified
with either the B<-verify_other> or B<-VAfile> options.
=item B<-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.
=item B<-no_cert_verify>
don't verify the OCSP response signers certificate at all. Since this option allows
the OCSP response to be signed by any certificate it should only be used for
testing purposes.
=item B<-no_chain>
do not use certificates in the response as additional untrusted CA
certificates.
=item B<-no_explicit>
do not explicitly trust the root CA if it is set to be trusted for OCSP signing.
=item B<-no_cert_checks>
don't perform any additional checks on the OCSP response signers certificate.
That is do not make any checks to see if the signers certificate is authorised
to provide the necessary status information: as a result this option should
only be used for testing purposes.
=item B<-validity_period nsec>, B<-status_age age>
these options specify the range of times, in seconds, which will be tolerated
in an OCSP response. Each certificate status response includes a B<notBefore> time and
an optional B<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 B<-validity_period> option can be used to specify an
acceptable error range in seconds, the default value is 5 minutes.
If the B<notAfter> time is omitted from a response then this means that new status
information is immediately available. In this case the age of the B<notBefore> field
is checked to see it is not older than B<age> seconds old. By default this additional
check is not performed.
=item B<-md5|-sha1|-sha256|-ripemod160|...>
this option sets digest algorithm to use for certificate identification
in the OCSP request. By default SHA-1 is used.
=back
=head1 OCSP SERVER OPTIONS
=over 4
=item B<-index indexfile>
B<indexfile> is a text index file in B<ca> format containing certificate revocation
information.
If the B<index> option is specified the B<ocsp> utility is in responder mode, otherwise
it is in client mode. The request(s) the responder processes can be either specified on
the command line (using B<issuer> and B<serial> options), supplied in a file (using the
B<respin> option) or via external OCSP clients (if B<port> or B<url> is specified).
If the B<index> option is present then the B<CA> and B<rsigner> options must also be
present.
=item B<-CA file>
CA certificate corresponding to the revocation information in B<indexfile>.
=item B<-rsigner file>
The certificate to sign OCSP responses with.
=item B<-rother file>
Additional certificates to include in the OCSP response.
=item B<-resp_no_certs>
Don't include any certificates in the OCSP response.
=item B<-resp_key_id>
Identify the signer certificate using the key ID, default is to use the subject name.
=item B<-rkey file>
The private key to sign OCSP responses with: if not present the file specified in the
B<rsigner> option is used.
=item B<-port portnum>
Port to listen for OCSP requests on. The port may also be specified using the B<url>
option.
=item B<-nrequest number>
The OCSP server will exit after receiving B<number> requests, default unlimited.
=item B<-nmin minutes>, B<-ndays days>
Number of minutes or days when fresh revocation information is available: used in the
B<nextUpdate> field. If neither option is present then the B<nextUpdate> field is
omitted meaning fresh revocation information is immediately available.
=back
=head1 OCSP Response verification.
OCSP Response follows the rules specified in RFC2560.
Initially the OCSP responder certificate is located and the signature on
the OCSP request checked using the responder certificate's public key.
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 B<CAfile>
and B<CApath> options or they will be looked for in the standard OpenSSL
certificates directory.
If the initial verify fails then the OCSP verify process halts with an
error.
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.
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.
Otherwise, if B<-no_explicit> is B<not> set the root CA of the OCSP responders
CA is checked to see if it is trusted for OCSP signing. If it is the OCSP
verify succeeds.
If none of these checks is successful then the OCSP verify fails.
What this effectively means if that if the OCSP responder certificate is
authorised directly by the CA it is issuing revocation information about
(and it is correctly configured) then verification will succeed.
If the OCSP responder is a "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:
openssl x509 -in ocspCA.pem -addtrust OCSPSigning -out trustedCA.pem
Alternatively the responder certificate itself can be explicitly trusted
with the B<-VAfile> option.
=head1 NOTES
As noted, most of the verify options are for testing or debugging purposes.
Normally only the B<-CApath>, B<-CAfile> and (if the responder is a 'global
VA') B<-VAfile> options need to be used.
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.
It is possible to run the B<ocsp> application in responder mode via a CGI
script using the B<respin> and B<respout> options.
=head1 EXAMPLES
Create an OCSP request and write it to a file:
openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der
Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the
response to a file and print it out in text form
openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \
-url http://ocsp.myhost.com/ -resp_text -respout resp.der
Read in an OCSP response and print out text form:
openssl ocsp -respin resp.der -text
OCSP server on port 8888 using a standard B<ca> configuration, and a separate
responder certificate. All requests and responses are printed to a file.
openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
-text -out log.txt
As above but exit after processing one request:
openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
-nrequest 1
Query status information using internally generated request:
openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
-issuer demoCA/cacert.pem -serial 1
Query status information using request read from a file, write response to a
second file.
openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
-reqin req.der -respout resp.der
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
=cut

422
doc/apps/openssl.pod Normal file
View File

@@ -0,0 +1,422 @@
=pod
=head1 NAME
openssl - OpenSSL command line tool
=head1 SYNOPSIS
B<openssl>
I<command>
[ I<command_opts> ]
[ I<command_args> ]
B<openssl> [ B<list-standard-commands> | B<list-message-digest-commands> | B<list-cipher-commands> | B<list-cipher-algorithms> | B<list-message-digest-algorithms> | B<list-public-key-algorithms>]
B<openssl> B<no->I<XXX> [ I<arbitrary options> ]
=head1 DESCRIPTION
OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL
v2/v3) and Transport Layer Security (TLS v1) network protocols and related
cryptography standards required by them.
The B<openssl> program is a command line tool for using the various
cryptography functions of OpenSSL's B<crypto> library from the shell.
It can be used for
o Creation and management of private keys, public keys and parameters
o Public key cryptographic operations
o Creation of X.509 certificates, CSRs and CRLs
o Calculation of Message Digests
o Encryption and Decryption with Ciphers
o SSL/TLS Client and Server Tests
o Handling of S/MIME signed or encrypted mail
o Time Stamp requests, generation and verification
=head1 COMMAND SUMMARY
The B<openssl> program provides a rich variety of commands (I<command> in the
SYNOPSIS above), each of which often has a wealth of options and arguments
(I<command_opts> and I<command_args> in the SYNOPSIS).
The pseudo-commands B<list-standard-commands>, B<list-message-digest-commands>,
and B<list-cipher-commands> output a list (one entry per line) of the names
of all standard commands, message digest commands, or cipher commands,
respectively, that are available in the present B<openssl> utility.
The pseudo-commands B<list-cipher-algorithms> and
B<list-message-digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as:
from => to
The pseudo-command B<list-public-key-algorithms> lists all supported public
key algorithms.
The pseudo-command B<no->I<XXX> tests whether a command of the
specified name is available. If no command named I<XXX> exists, it
returns 0 (success) and prints B<no->I<XXX>; otherwise it returns 1
and prints I<XXX>. In both cases, the output goes to B<stdout> and
nothing is printed to B<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 B<openssl> program. (B<no->I<XXX> is
not able to detect pseudo-commands such as B<quit>,
B<list->I<...>B<-commands>, or B<no->I<XXX> itself.)
=head2 STANDARD COMMANDS
=over 10
=item L<B<asn1parse>|asn1parse(1)>
Parse an ASN.1 sequence.
=item L<B<ca>|ca(1)>
Certificate Authority (CA) Management.
=item L<B<ciphers>|ciphers(1)>
Cipher Suite Description Determination.
=item L<B<cms>|cms(1)>
CMS (Cryptographic Message Syntax) utility
=item L<B<crl>|crl(1)>
Certificate Revocation List (CRL) Management.
=item L<B<crl2pkcs7>|crl2pkcs7(1)>
CRL to PKCS#7 Conversion.
=item L<B<dgst>|dgst(1)>
Message Digest Calculation.
=item B<dh>
Diffie-Hellman Parameter Management.
Obsoleted by L<B<dhparam>|dhparam(1)>.
=item L<B<dhparam>|dhparam(1)>
Generation and Management of Diffie-Hellman Parameters. Superseded by
L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>
=item L<B<dsa>|dsa(1)>
DSA Data Management.
=item L<B<dsaparam>|dsaparam(1)>
DSA Parameter Generation and Management. Superseded by
L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>
=item L<B<ec>|ec(1)>
EC (Elliptic curve) key processing
=item L<B<ecparam>|ecparam(1)>
EC parameter manipulation and generation
=item L<B<enc>|enc(1)>
Encoding with Ciphers.
=item L<B<engine>|engine(1)>
Engine (loadble module) information and manipulation.
=item L<B<errstr>|errstr(1)>
Error Number to Error String Conversion.
=item B<gendh>
Generation of Diffie-Hellman Parameters.
Obsoleted by L<B<dhparam>|dhparam(1)>.
=item L<B<gendsa>|gendsa(1)>
Generation of DSA Private Key from Parameters. Superseded by
L<B<genpkey>|genpkey(1)> and L<B<pkey>|pkey(1)>
=item L<B<genpkey>|genpkey(1)>
Generation of Private Key or Parameters.
=item L<B<genrsa>|genrsa(1)>
Generation of RSA Private Key. Superceded by L<B<genpkey>|genpkey(1)>.
=item L<B<nseq>|nseq(1)>
Create or examine a netscape certificate sequence
=item L<B<ocsp>|ocsp(1)>
Online Certificate Status Protocol utility.
=item L<B<passwd>|passwd(1)>
Generation of hashed passwords.
=item L<B<pkcs12>|pkcs12(1)>
PKCS#12 Data Management.
=item L<B<pkcs7>|pkcs7(1)>
PKCS#7 Data Management.
=item L<B<pkey>|pkey(1)>
Public and private key management.
=item L<B<pkeyparam>|pkeyparam(1)>
Public key algorithm parameter management.
=item L<B<pkeyutl>|pkeyutl(1)>
Public key algorithm cryptographic operation utility.
=item L<B<rand>|rand(1)>
Generate pseudo-random bytes.
=item L<B<req>|req(1)>
PKCS#10 X.509 Certificate Signing Request (CSR) Management.
=item L<B<rsa>|rsa(1)>
RSA key management.
=item L<B<rsautl>|rsautl(1)>
RSA utility for signing, verification, encryption, and decryption. Superseded
by L<B<pkeyutl>|pkeyutl(1)>
=item L<B<s_client>|s_client(1)>
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 OpenSSL B<ssl> library.
=item L<B<s_server>|s_server(1)>
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 OpenSSL B<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.
=item L<B<s_time>|s_time(1)>
SSL Connection Timer.
=item L<B<sess_id>|sess_id(1)>
SSL Session Data Management.
=item L<B<smime>|smime(1)>
S/MIME mail processing.
=item L<B<speed>|speed(1)>
Algorithm Speed Measurement.
=item L<B<spkac>|spkac(1)>
SPKAC printing and generating utility
=item L<B<ts>|ts(1)>
Time Stamping Authority tool (client/server)
=item L<B<verify>|verify(1)>
X.509 Certificate Verification.
=item L<B<version>|version(1)>
OpenSSL Version Information.
=item L<B<x509>|x509(1)>
X.509 Certificate Data Management.
=back
=head2 MESSAGE DIGEST COMMANDS
=over 10
=item B<md2>
MD2 Digest
=item B<md5>
MD5 Digest
=item B<mdc2>
MDC2 Digest
=item B<rmd160>
RMD-160 Digest
=item B<sha>
SHA Digest
=item B<sha1>
SHA-1 Digest
=item B<sha224>
SHA-224 Digest
=item B<sha256>
SHA-256 Digest
=item B<sha384>
SHA-384 Digest
=item B<sha512>
SHA-512 Digest
=back
=head2 ENCODING AND CIPHER COMMANDS
=over 10
=item B<base64>
Base64 Encoding
=item B<bf bf-cbc bf-cfb bf-ecb bf-ofb>
Blowfish Cipher
=item B<cast cast-cbc>
CAST Cipher
=item B<cast5-cbc cast5-cfb cast5-ecb cast5-ofb>
CAST5 Cipher
=item B<des des-cbc des-cfb des-ecb des-ede des-ede-cbc des-ede-cfb des-ede-ofb des-ofb>
DES Cipher
=item B<des3 desx des-ede3 des-ede3-cbc des-ede3-cfb des-ede3-ofb>
Triple-DES Cipher
=item B<idea idea-cbc idea-cfb idea-ecb idea-ofb>
IDEA Cipher
=item B<rc2 rc2-cbc rc2-cfb rc2-ecb rc2-ofb>
RC2 Cipher
=item B<rc4>
RC4 Cipher
=item B<rc5 rc5-cbc rc5-cfb rc5-ecb rc5-ofb>
RC5 Cipher
=back
=head1 PASS PHRASE ARGUMENTS
Several commands accept password arguments, typically using B<-passin>
and B<-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.
=over 10
=item B<pass:password>
the actual password is B<password>. Since the password is visible
to utilities (like 'ps' under Unix) this form should only be used
where security is not important.
=item B<env:var>
obtain the password from the environment variable B<var>. Since
the environment of other processes is visible on certain platforms
(e.g. ps under certain Unix OSes) this option should be used with caution.
=item B<file:pathname>
the first line of B<pathname> is the password. If the same B<pathname>
argument is supplied to B<-passin> and B<-passout> arguments then the first
line will be used for the input password and the next line for the output
password. B<pathname> need not refer to a regular file: it could for example
refer to a device or named pipe.
=item B<fd:number>
read the password from the file descriptor B<number>. This can be used to
send the data via a pipe for example.
=item B<stdin>
read the password from standard input.
=back
=head1 SEE ALSO
L<asn1parse(1)|asn1parse(1)>, L<ca(1)|ca(1)>, L<config(5)|config(5)>,
L<crl(1)|crl(1)>, L<crl2pkcs7(1)|crl2pkcs7(1)>, L<dgst(1)|dgst(1)>,
L<dhparam(1)|dhparam(1)>, L<dsa(1)|dsa(1)>, L<dsaparam(1)|dsaparam(1)>,
L<enc(1)|enc(1)>, L<gendsa(1)|gendsa(1)>, L<genpkey(1)|genpkey(1)>,
L<genrsa(1)|genrsa(1)>, L<nseq(1)|nseq(1)>, L<openssl(1)|openssl(1)>,
L<passwd(1)|passwd(1)>,
L<pkcs12(1)|pkcs12(1)>, L<pkcs7(1)|pkcs7(1)>, L<pkcs8(1)|pkcs8(1)>,
L<rand(1)|rand(1)>, L<req(1)|req(1)>, L<rsa(1)|rsa(1)>,
L<rsautl(1)|rsautl(1)>, L<s_client(1)|s_client(1)>,
L<s_server(1)|s_server(1)>, L<s_time(1)|s_time(1)>,
L<smime(1)|smime(1)>, L<spkac(1)|spkac(1)>,
L<verify(1)|verify(1)>, L<version(1)|version(1)>, L<x509(1)|x509(1)>,
L<crypto(3)|crypto(3)>, L<ssl(3)|ssl(3)>, L<x509v3_config(5)|x509v3_config(5)>
=head1 HISTORY
The openssl(1) document appeared in OpenSSL 0.9.2.
The B<list->I<XXX>B<-commands> pseudo-commands were added in OpenSSL 0.9.3;
The B<list->I<XXX>B<-algorithms> pseudo-commands were added in OpenSSL 1.0.0;
the B<no->I<XXX> pseudo-commands were added in OpenSSL 0.9.5a.
For notes on the availability of other commands, see their individual
manual pages.
=cut

82
doc/apps/passwd.pod Normal file
View File

@@ -0,0 +1,82 @@
=pod
=head1 NAME
passwd - compute password hashes
=head1 SYNOPSIS
B<openssl passwd>
[B<-crypt>]
[B<-1>]
[B<-apr1>]
[B<-salt> I<string>]
[B<-in> I<file>]
[B<-stdin>]
[B<-noverify>]
[B<-quiet>]
[B<-table>]
{I<password>}
=head1 DESCRIPTION
The B<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 file for option B<-in file>, from stdin for
option B<-stdin>, or from the command line, or from the terminal otherwise.
The Unix standard algorithm B<crypt> and the MD5-based BSD password
algorithm B<1> and its Apache variant B<apr1> are available.
=head1 OPTIONS
=over 4
=item B<-crypt>
Use the B<crypt> algorithm (default).
=item B<-1>
Use the MD5 based BSD password algorithm B<1>.
=item B<-apr1>
Use the B<apr1> algorithm (Apache variant of the BSD algorithm).
=item B<-salt> I<string>
Use the specified salt.
When reading a password from the terminal, this implies B<-noverify>.
=item B<-in> I<file>
Read passwords from I<file>.
=item B<-stdin>
Read passwords from B<stdin>.
=item B<-noverify>
Don't verify when reading a password from the terminal.
=item B<-quiet>
Don't output warnings when passwords given at the command line are truncated.
=item B<-table>
In the output list, prepend the cleartext password and a TAB character
to each password hash.
=back
=head1 EXAMPLES
B<openssl passwd -crypt -salt xx password> prints B<xxj31ZMTZzkVA>.
B<openssl passwd -1 -salt xxxxxxxx password> prints B<$1$xxxxxxxx$UYCIxa628.9qXjpQCjM4a.>.
B<openssl passwd -apr1 -salt xxxxxxxx password> prints B<$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0>.
=cut

368
doc/apps/pkcs12.pod Normal file
View File

@@ -0,0 +1,368 @@
=pod
=head1 NAME
pkcs12 - PKCS#12 file utility
=head1 SYNOPSIS
B<openssl> B<pkcs12>
[B<-export>]
[B<-chain>]
[B<-inkey filename>]
[B<-certfile filename>]
[B<-name name>]
[B<-caname name>]
[B<-in filename>]
[B<-out filename>]
[B<-noout>]
[B<-nomacver>]
[B<-nocerts>]
[B<-clcerts>]
[B<-cacerts>]
[B<-nokeys>]
[B<-info>]
[B<-des | -des3 | -idea | -aes128 | -aes192 | -aes256 | -camellia128 | -camellia192 | -camellia256 | -nodes>]
[B<-noiter>]
[B<-maciter | -nomaciter | -nomac>]
[B<-twopass>]
[B<-descert>]
[B<-certpbe cipher>]
[B<-keypbe cipher>]
[B<-macalg digest>]
[B<-keyex>]
[B<-keysig>]
[B<-password arg>]
[B<-passin arg>]
[B<-passout arg>]
[B<-rand file(s)>]
[B<-CAfile file>]
[B<-CApath dir>]
[B<-CSP name>]
=head1 DESCRIPTION
The B<pkcs12> command allows PKCS#12 files (sometimes referred to as
PFX files) to be created and parsed. PKCS#12 files are used by several
programs including Netscape, MSIE and MS Outlook.
=head1 COMMAND OPTIONS
There are a lot of options the meaning of some depends of 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 B<-export> option (see below).
=head1 PARSING OPTIONS
=over 4
=item B<-in filename>
This specifies filename of the PKCS#12 file to be parsed. Standard input is used
by default.
=item B<-out filename>
The filename to write certificates and private keys to, standard output by
default. They are all written in PEM format.
=item B<-passin arg>
the PKCS#12 file (i.e. input file) password source. For more information about
the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
L<openssl(1)|openssl(1)>.
=item B<-passout arg>
pass phrase source to encrypt any outputted private keys with. For more
information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section
in L<openssl(1)|openssl(1)>.
=item B<-password arg>
With -export, -password is equivalent to -passout.
Otherwise, -password is equivalent to -passin.
=item B<-noout>
this option inhibits output of the keys and certificates to the output file
version of the PKCS#12 file.
=item B<-clcerts>
only output client certificates (not CA certificates).
=item B<-cacerts>
only output CA certificates (not client certificates).
=item B<-nocerts>
no certificates at all will be output.
=item B<-nokeys>
no private keys will be output.
=item B<-info>
output additional information about the PKCS#12 file structure, algorithms used and
iteration counts.
=item B<-des>
use DES to encrypt private keys before outputting.
=item B<-des3>
use triple DES to encrypt private keys before outputting, this is the default.
=item B<-idea>
use IDEA to encrypt private keys before outputting.
=item B<-aes128>, B<-aes192>, B<-aes256>
use AES to encrypt private keys before outputting.
=item B<-camellia128>, B<-camellia192>, B<-camellia256>
use Camellia to encrypt private keys before outputting.
=item B<-nodes>
don't encrypt the private keys at all.
=item B<-nomacver>
don't attempt to verify the integrity MAC before reading the file.
=item B<-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.
=back
=head1 FILE CREATION OPTIONS
=over 4
=item B<-export>
This option specifies that a PKCS#12 file will be created rather than
parsed.
=item B<-out filename>
This specifies filename to write the PKCS#12 file to. Standard output is used
by default.
=item B<-in filename>
The filename 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.
=item B<-inkey filename>
file to read private key from. If not present then a private key must be present
in the input file.
=item B<-name friendlyname>
This specifies the "friendly name" for the certificate and private key. This
name is typically displayed in list boxes by software importing the file.
=item B<-certfile filename>
A filename to read additional certificates from.
=item B<-caname friendlyname>
This specifies the "friendly name" for other certificates. This option may be
used multiple times to specify names for all certificates in the order they
appear. Netscape ignores friendly names on other certificates whereas MSIE
displays them.
=item B<-pass arg>, B<-passout arg>
the PKCS#12 file (i.e. output file) password source. For more information about
the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
L<openssl(1)|openssl(1)>.
=item B<-passin password>
pass phrase source to decrypt any input private keys with. For more information
about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
L<openssl(1)|openssl(1)>.
=item B<-chain>
if this option is present then an attempt is made to include the entire
certificate chain of the user certificate. The standard CA store is used
for this search. If the search fails it is considered a fatal error.
=item B<-descert>
encrypt the certificate using triple DES, this may render the PKCS#12
file unreadable by some "export grade" software. By default the private
key is encrypted using triple DES and the certificate using 40 bit RC2.
=item B<-keypbe alg>, B<-certpbe 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 B<NOTES> section for more information). If a cipher name
(as output by the B<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.
=item B<-keyex|-keysig>
specifies that the private key is to be used for key exchange or just signing.
This option is only interpreted by MSIE and similar MS software. Normally
"export grade" software will only allow 512 bit RSA keys to be used for
encryption purposes but arbitrary length keys for signing. The B<-keysig>
option marks the key for signing only. Signing only keys can be used for
S/MIME signing, authenticode (ActiveX control signing) and SSL client
authentication, however due to a bug only MSIE 5.0 and later support
the use of signing only keys for SSL client authentication.
=item B<-macalg digest>
specify the MAC digest algorithm. If not included them SHA1 will be used.
=item B<-nomaciter>, B<-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.
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 B<-nomaciter>
option.
=item B<-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.
=item B<-nomac>
don't attempt to provide the MAC integrity.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-CAfile file>
CA storage as a file.
=item B<-CApath dir>
CA storage as a directory. This directory must be a standard certificate
directory: that is a hash of each subject name (using B<x509 -hash>) should be
linked to each certificate.
=item B<-CSP name>
write B<name> as a Microsoft CSP name.
=back
=head1 NOTES
Although there are a large number of options most of them are very rarely
used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used
for PKCS#12 file creation B<-export> and B<-name> are also used.
If none of the B<-clcerts>, B<-cacerts> or B<-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 B<-clcerts> option will solve this problem by only
outputting the certificate corresponding to the private key. If the CA
certificates are required then they can be output to a separate file using
the B<-nokeys -cacerts> options to just output CA certificates.
The B<-keypbe> and B<-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 B<-keypbe 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 B<pkcs8> manual page.
=head1 EXAMPLES
Parse a PKCS#12 file and output it to a file:
openssl pkcs12 -in file.p12 -out file.pem
Output only client certificates to a file:
openssl pkcs12 -in file.p12 -clcerts -out file.pem
Don't encrypt the private key:
openssl pkcs12 -in file.p12 -out file.pem -nodes
Print some info about a PKCS#12 file:
openssl pkcs12 -in file.p12 -info -noout
Create a PKCS#12 file:
openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate"
Include some extra certificates:
openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \
-certfile othercerts.pem
=head1 BUGS
Some would argue that the PKCS#12 standard is one big bug :-)
Versions of OpenSSL before 0.9.6a had a bug in the PKCS#12 key generation
routines. Under rare circumstances this could produce a PKCS#12 file encrypted
with an invalid key. As a result some PKCS#12 files which triggered this bug
from other implementations (MSIE or Netscape) could not be decrypted
by OpenSSL and similarly 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.
A side effect of fixing this bug is that any old invalidly encrypted PKCS#12
files cannot no longer be parsed by the fixed version. Under such circumstances
the B<pkcs12> utility will report that the MAC is OK but fail with a decryption
error when extracting private keys.
This problem can be resolved by extracting the private keys and certificates
from the PKCS#12 file using an older version of OpenSSL and recreating the PKCS#12
file from the keys and certificates using a newer version of OpenSSL. For example:
old-openssl -in bad.p12 -out keycerts.pem
openssl -in keycerts.pem -export -name "My PKCS#12 file" -out fixed.p12
=head1 SEE ALSO
L<pkcs8(1)|pkcs8(1)>

105
doc/apps/pkcs7.pod Normal file
View File

@@ -0,0 +1,105 @@
=pod
=head1 NAME
pkcs7 - PKCS#7 utility
=head1 SYNOPSIS
B<openssl> B<pkcs7>
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
[B<-out filename>]
[B<-print_certs>]
[B<-text>]
[B<-noout>]
[B<-engine id>]
=head1 DESCRIPTION
The B<pkcs7> command processes PKCS#7 files in DER or PEM format.
=head1 COMMAND OPTIONS
=over 4
=item B<-inform DER|PEM>
This specifies the input format. B<DER> format is DER encoded PKCS#7
v1.5 structure.B<PEM> (the default) is a base64 encoded version of
the DER form with header and footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
This specifies the input filename to read from or standard input if this
option is not specified.
=item B<-out filename>
specifies the output filename to write to or standard output by
default.
=item B<-print_certs>
prints out any certificates or CRLs contained in the file. They are
preceded by their subject and issuer names in one line format.
=item B<-text>
prints out certificates details in full rather than just subject and
issuer names.
=item B<-noout>
don't output the encoded version of the PKCS#7 structure (or certificates
is B<-print_certs> is set).
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=back
=head1 EXAMPLES
Convert a PKCS#7 file from PEM to DER:
openssl pkcs7 -in file.pem -outform DER -out file.der
Output all certificates in a file:
openssl pkcs7 -in file.pem -print_certs -out certs.pem
=head1 NOTES
The PEM PKCS#7 format uses the header and footer lines:
-----BEGIN PKCS7-----
-----END PKCS7-----
For compatibility with some CAs it will also accept:
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
=head1 RESTRICTIONS
There is no option to print out all the fields of a PKCS#7 file.
This PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315 they
cannot currently parse, for example, the new CMS as described in RFC2630.
=head1 SEE ALSO
L<crl2pkcs7(1)|crl2pkcs7(1)>
=cut

255
doc/apps/pkcs8.pod Normal file
View File

@@ -0,0 +1,255 @@
=pod
=head1 NAME
pkcs8 - PKCS#8 format private key conversion tool
=head1 SYNOPSIS
B<openssl> B<pkcs8>
[B<-topk8>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-noiter>]
[B<-nocrypt>]
[B<-nooct>]
[B<-embed>]
[B<-nsdb>]
[B<-v2 alg>]
[B<-v2prf alg>]
[B<-v1 alg>]
[B<-engine id>]
=head1 DESCRIPTION
The B<pkcs8> command processes private keys in PKCS#8 format. It can handle
both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
=head1 COMMAND OPTIONS
=over 4
=item B<-topk8>
Normally a PKCS#8 private key is expected on input and a traditional format
private key will be written. With the B<-topk8> option the situation is
reversed: it reads a traditional format private key and writes a PKCS#8
format key.
=item B<-inform DER|PEM>
This specifies the input format. If a PKCS#8 format key is expected on input
then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be
expected. Otherwise the B<DER> or B<PEM> format of the traditional format
private key is used.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
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.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-out filename>
This specifies the output filename to write a key to or standard output by
default. If any encryption options are set then a pass phrase will be
prompted for. The output filename should B<not> be the same as the input
filename.
=item B<-passout arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-nocrypt>
PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
structures using an appropriate password based encryption algorithm. With
this option an unencrypted PrivateKeyInfo structure is expected or output.
This option does not encrypt private keys at all and should only be used
when absolutely necessary. Certain software such as some versions of Java
code signing software used unencrypted private keys.
=item B<-nooct>
This option generates RSA private keys in a broken format that some software
uses. Specifically the private key should be enclosed in a OCTET STRING
but some software just includes the structure itself without the
surrounding OCTET STRING.
=item B<-embed>
This option generates DSA keys in a broken format. The DSA parameters are
embedded inside the 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.
=item B<-nsdb>
This option generates DSA keys in a broken format compatible with Netscape
private key databases. The PrivateKey contains a SEQUENCE consisting of
the public and private keys respectively.
=item B<-v2 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 B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it
was the strongest encryption algorithm supported in PKCS#5 v1.5. Using
the B<-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 you are just using
private keys with OpenSSL then this doesn't matter.
The B<alg> argument is the encryption algorithm to use, valid values include
B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used.
=item B<-v2prf alg>
This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value
values would be B<hmacWithSHA256>. If this option isn't set then the default
for the cipher is used or B<hmacWithSHA1> if there is no default.
=item B<-v1 alg>
This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete
list of possible algorithms is included below.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=back
=head1 NOTES
The encrypted form of a PEM encode PKCS#8 files uses the following
headers and footers:
-----BEGIN ENCRYPTED PRIVATE KEY-----
-----END ENCRYPTED PRIVATE KEY-----
The unencrypted form uses:
-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----
Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
counts are more secure that those encrypted using the traditional
SSLeay compatible formats. So if additional security is considered
important the keys should be converted.
The default encryption is only 56 bits because this is the encryption
that most current implementations of PKCS#8 will support.
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.
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.
=head1 PKCS#5 v1.5 and PKCS#12 algorithms.
Various algorithms can be used with the B<-v1> command line option,
including PKCS#5 v1.5 and PKCS#12. These are described in more detail
below.
=over 4
=item B<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.
=item B<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.
=item B<PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES 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.
=back
=head1 EXAMPLES
Convert a private from traditional to PKCS#5 v2.0 format using triple
DES:
openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
Convert a private from traditional to PKCS#5 v2.0 format using AES with
256 bits in CBC mode and B<hmacWithSHA256> PRF:
openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -out enckey.pem
Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
(DES):
openssl pkcs8 -in key.pem -topk8 -out enckey.pem
Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
(3DES):
openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
Read a DER unencrypted PKCS#8 format private key:
openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
Convert a private key from any PKCS#8 format to traditional format:
openssl pkcs8 -in pk8.pem -out key.pem
=head1 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.
The format of PKCS#8 DSA (and other) private keys is not well documented:
it is hidden away in PKCS#11 v2.01, section 11.9. OpenSSL's default DSA
PKCS#8 private key format complies with this standard.
=head1 BUGS
There should be an option that prints out the encryption algorithm
in use and other details such as the iteration count.
PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private
key format for OpenSSL: for compatibility several of the utilities use
the old format at present.
=head1 SEE ALSO
L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>,
L<gendsa(1)|gendsa(1)>
=cut

135
doc/apps/pkey.pod Normal file
View File

@@ -0,0 +1,135 @@
=pod
=head1 NAME
pkey - public or private key processing tool
=head1 SYNOPSIS
B<openssl> B<pkey>
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-cipher>]
[B<-text>]
[B<-text_pub>]
[B<-noout>]
[B<-pubin>]
[B<-pubout>]
[B<-engine id>]
=head1 DESCRIPTION
The B<pkey> command processes public or private keys. They can be converted
between various forms and their components printed out.
=head1 COMMAND OPTIONS
=over 4
=item B<-inform DER|PEM>
This specifies the input format DER or PEM.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
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.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-out filename>
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 B<not> be the same as the input
filename.
=item B<-passout password>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-cipher>
These options encrypt the private key with the supplied cipher. Any algorithm
name accepted by EVP_get_cipherbyname() is acceptable such as B<des3>.
=item B<-text>
prints out the various public or private key components in
plain text in addition to the encoded version.
=item B<-text_pub>
print out only public key components even if a private key is being processed.
=item B<-noout>
do not output the encoded version of the key.
=item B<-pubin>
by default a private key is read from the input file: with this
option a public key is read instead.
=item B<-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.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=back
=head1 EXAMPLES
To remove the pass phrase on an RSA private key:
openssl pkey -in key.pem -out keyout.pem
To encrypt a private key using triple DES:
openssl pkey -in key.pem -des3 -out keyout.pem
To convert a private key from PEM to DER format:
openssl pkey -in key.pem -outform DER -out keyout.der
To print out the components of a private key to standard output:
openssl pkey -in key.pem -text -noout
To print out the public components of a private key to standard output:
openssl pkey -in key.pem -text_pub -noout
To just output the public part of a private key:
openssl pkey -in key.pem -pubout -out pubkey.pem
=head1 SEE ALSO
L<genpkey(1)|genpkey(1)>, L<rsa(1)|rsa(1)>, L<pkcs8(1)|pkcs8(1)>,
L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, L<gendsa(1)|gendsa(1)>
=cut

69
doc/apps/pkeyparam.pod Normal file
View File

@@ -0,0 +1,69 @@
=pod
=head1 NAME
pkeyparam - public key algorithm parameter processing tool
=head1 SYNOPSIS
B<openssl> B<pkeyparam>
[B<-in filename>]
[B<-out filename>]
[B<-text>]
[B<-noout>]
[B<-engine id>]
=head1 DESCRIPTION
The B<pkey> command processes public or private keys. They can be converted
between various forms and their components printed out.
=head1 COMMAND OPTIONS
=over 4
=item B<-in filename>
This specifies the input filename to read parameters from or standard input if
this option is not specified.
=item B<-out filename>
This specifies the output filename to write parameters to or standard output if
this option is not specified.
=item B<-text>
prints out the parameters in plain text in addition to the encoded version.
=item B<-noout>
do not output the encoded version of the parameters.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=back
=head1 EXAMPLE
Print out text version of parameters:
openssl pkeyparam -in param.pem -text
=head1 NOTES
There are no B<-inform> or B<-outform> options for this command because only
PEM format is supported because the key type is determined by the PEM headers.
=head1 SEE ALSO
L<genpkey(1)|genpkey(1)>, L<rsa(1)|rsa(1)>, L<pkcs8(1)|pkcs8(1)>,
L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>, L<gendsa(1)|gendsa(1)>
=cut

235
doc/apps/pkeyutl.pod Normal file
View File

@@ -0,0 +1,235 @@
=pod
=head1 NAME
pkeyutl - public key algorithm utility
=head1 SYNOPSIS
B<openssl> B<pkeyutl>
[B<-in file>]
[B<-out file>]
[B<-sigfile file>]
[B<-inkey file>]
[B<-keyform PEM|DER>]
[B<-passin arg>]
[B<-peerkey file>]
[B<-peerform PEM|DER>]
[B<-pubin>]
[B<-certin>]
[B<-rev>]
[B<-sign>]
[B<-verify>]
[B<-verifyrecover>]
[B<-encrypt>]
[B<-decrypt>]
[B<-derive>]
[B<-pkeyopt opt:value>]
[B<-hexdump>]
[B<-asn1parse>]
[B<-engine id>]
=head1 DESCRIPTION
The B<pkeyutl> command can be used to perform public key operations using
any supported algorithm.
=head1 COMMAND OPTIONS
=over 4
=item B<-in filename>
This specifies the input filename to read data from or standard input
if this option is not specified.
=item B<-out filename>
specifies the output filename to write to or standard output by
default.
=item B<-inkey file>
the input key file, by default it should be a private key.
=item B<-keyform PEM|DER>
the key format PEM, DER or ENGINE.
=item B<-passin arg>
the input key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-peerkey file>
the peer key file, used by key derivation (agreement) operations.
=item B<-peerform PEM|DER>
the peer key format PEM, DER or ENGINE.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=item B<-pubin>
the input file is a public key.
=item B<-certin>
the input is a certificate containing a public key.
=item B<-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.
=item B<-sign>
sign the input data and output the signed result. This requires
a private key.
=item B<-verify>
verify the input data against the signature file and indicate if the
verification succeeded or failed.
=item B<-verifyrecover>
verify the input data and output the recovered data.
=item B<-encrypt>
encrypt the input data using a public key.
=item B<-decrypt>
decrypt the input data using a private key.
=item B<-derive>
derive a shared secret using the peer key.
=item B<-hexdump>
hex dump the output data.
=item B<-asn1parse>
asn1parse the output data, this is useful when combined with the
B<-verifyrecover> option when an ASN1 structure is signed.
=back
=head1 NOTES
The operations and options supported vary according to the key algorithm
and its implementation. The OpenSSL operations and options are indicated below.
Unless otherwise mentioned all algorithms support the B<digest:alg> option
which specifies the digest in use for sign, verify and verifyrecover operations.
The value B<alg> should represent a digest name as used in the
EVP_get_digestbyname() function for example B<sha1>.
This value is used only for sanity-checking the lengths of data passed in to
the B<pkeyutl> and for creating the structures that make up the signature
(e.g. B<DigestInfo> in RSASSA PKCS#1 v1.5 signatures).
In case of RSA, ECDSA and DSA signatures, this utility
will not perform hashing on input data but rather use the data directly as
input of signature algorithm. Depending on key type, signature type and mode
of padding, the maximum acceptable lengths of input data differ. In general,
with RSA the signed data can't be longer than the key modulus, in case of ECDSA
and DSA the data shouldn't be longer than field size, otherwise it will be
silently truncated to field size.
In other words, if the value of digest is B<sha1> the input should be 20 bytes
long binary encoding of SHA-1 hash function output.
=head1 RSA ALGORITHM
The RSA algorithm supports encrypt, decrypt, sign, verify and verifyrecover
operations in general. Some padding modes only support some of these
operations however.
=over 4
=item -B<rsa_padding_mode:mode>
This sets the RSA padding mode. Acceptable values for B<mode> are B<pkcs1> for
PKCS#1 padding, B<sslv23> for SSLv23 padding, B<none> for no padding, B<oaep>
for B<OAEP> mode, B<x931> for X9.31 mode and B<pss> for PSS.
In PKCS#1 padding if the message digest is not set then the supplied data is
signed or verified directly instead of using a B<DigestInfo> structure. If a
digest is set then the a B<DigestInfo> structure is used and its the length
must correspond to the digest type.
For B<oeap> mode only encryption and decryption is supported.
For B<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 are can be performed in this mode.
For B<pss> mode only sign and verify are supported and the digest type must be
specified.
=item B<rsa_pss_saltlen:len>
For B<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 B<PSS> block
structure.
=back
=head1 DSA ALGORITHM
The DSA algorithm supports signing and verification operations only. Currently
there are no additional options other than B<digest>. Only the SHA1
digest can be used and this digest is assumed by default.
=head1 DH ALGORITHM
The DH algorithm only supports the derivation operation and no additional
options.
=head1 EC ALGORITHM
The EC algorithm supports sign, verify and derive operations. The sign and
verify operations use ECDSA and derive uses ECDH. Currently there are no
additional options other than B<digest>. Only the SHA1 digest can be used and
this digest is assumed by default.
=head1 EXAMPLES
Sign some data using a private key:
openssl pkeyutl -sign -in file -inkey key.pem -out sig
Recover the signed data (e.g. if an RSA key is used):
openssl pkeyutl -verifyrecover -in sig -inkey key.pem
Verify the signature (e.g. a DSA key):
openssl pkeyutl -verify -in file -sigfile sig -inkey key.pem
Sign data using a message digest value (this is currently only valid for RSA):
openssl pkeyutl -sign -in file -inkey key.pem -out sig -pkeyopt digest:sha256
Derive a shared secret value:
openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret
=head1 SEE ALSO
L<genpkey(1)|genpkey(1)>, L<pkey(1)|pkey(1)>, L<rsautl(1)|rsautl(1)>
L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>

55
doc/apps/rand.pod Normal file
View File

@@ -0,0 +1,55 @@
=pod
=head1 NAME
rand - generate pseudo-random bytes
=head1 SYNOPSIS
B<openssl rand>
[B<-out> I<file>]
[B<-rand> I<file(s)>]
[B<-base64>]
[B<-hex>]
I<num>
=head1 DESCRIPTION
The B<rand> command outputs I<num> pseudo-random bytes after seeding
the random number generator once. As in other B<openssl> command
line tools, PRNG seeding uses the file I<$HOME/>B<.rnd> or B<.rnd>
in addition to the files given in the B<-rand> option. A new
I<$HOME>/B<.rnd> or B<.rnd> file will be written back if enough
seeding was obtained from these sources.
=head1 OPTIONS
=over 4
=item B<-out> I<file>
Write to I<file> instead of standard output.
=item B<-rand> I<file(s)>
Use specified file or files or EGD socket (see L<RAND_egd(3)|RAND_egd(3)>)
for seeding the random number generator.
Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-base64>
Perform base64 encoding on the output.
=item B<-hex>
Show the output as a hex string.
=back
=head1 SEE ALSO
L<RAND_bytes(3)|RAND_bytes(3)>
=cut

680
doc/apps/req.pod Normal file
View File

@@ -0,0 +1,680 @@
=pod
=head1 NAME
req - PKCS#10 certificate request and certificate generating utility.
=head1 SYNOPSIS
B<openssl> B<req>
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-text>]
[B<-pubkey>]
[B<-noout>]
[B<-verify>]
[B<-modulus>]
[B<-new>]
[B<-rand file(s)>]
[B<-newkey rsa:bits>]
[B<-newkey alg:file>]
[B<-nodes>]
[B<-key filename>]
[B<-keyform PEM|DER>]
[B<-keyout filename>]
[B<-keygen_engine id>]
[B<-[digest]>]
[B<-config filename>]
[B<-multivalue-rdn>]
[B<-x509>]
[B<-days n>]
[B<-set_serial n>]
[B<-asn1-kludge>]
[B<-no-asn1-kludge>]
[B<-newhdr>]
[B<-extensions section>]
[B<-reqexts section>]
[B<-utf8>]
[B<-nameopt>]
[B<-reqopt>]
[B<-subject>]
[B<-subj arg>]
[B<-batch>]
[B<-verbose>]
[B<-engine id>]
=head1 DESCRIPTION
The B<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.
=head1 COMMAND OPTIONS
=over 4
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
form compatible with the PKCS#10. The B<PEM> form is the default format: it
consists of the B<DER> format base64 encoded with additional header and
footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
This specifies the input filename to read a request from or standard input
if this option is not specified. A request is only read if the creation
options (B<-new> and B<-newkey>) are not specified.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-out filename>
This specifies the output filename to write to or standard output by
default.
=item B<-passout arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-text>
prints out the certificate request in text form.
=item B<-subject>
prints out the request subject (or certificate subject if B<-x509> is
specified)
=item B<-pubkey>
outputs the public key.
=item B<-noout>
this option prevents output of the encoded version of the request.
=item B<-modulus>
this option prints out the value of the modulus of the public key
contained in the request.
=item B<-verify>
verifies the signature on the request.
=item B<-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.
If the B<-key> option is not used it will generate a new RSA private
key using information specified in the configuration file.
=item B<-subj arg>
Replaces subject field of input request with specified data and outputs
modified request. The arg must be formatted as
I</type0=value0/type1=value1/type2=...>,
characters may be escaped by \ (backslash), no spaces are skipped.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-newkey arg>
this option creates a new certificate request and a new private
key. The argument takes one of several forms. B<rsa:nbits>, where
B<nbits> is the number of bits, generates an RSA key B<nbits>
in size. If B<nbits> is omitted, i.e. B<-newkey rsa> specified,
the default key size, specified in the configuration file is used.
All other algorithms support the B<-newkey alg:file> form, where file may be
an algorithm parameter file, created by the B<genpkey -genparam> command
or and X.509 certificate for a key with approriate algorithm.
B<param:file> generates a key using the parameter file or certificate B<file>,
the algorithm is determined by the parameters. B<algname:file> use algorithm
B<algname> and parameter file B<file>: the two algorithms must match or an
error occurs. B<algname> just uses algorithm B<algname>, and parameters,
if neccessary should be specified via B<-pkeyopt> parameter.
B<dsa:filename> generates a DSA key using the parameters
in the file B<filename>. B<ec:filename> generates EC key (usable both with
ECDSA or ECDH algorithms), B<gost2001:filename> generates GOST R
34.10-2001 key (requires B<ccgost> engine configured in the configuration
file). If just B<gost2001> is specified a parameter set should be
specified by B<-pkeyopt paramset:X>
=item B<-pkeyopt opt:value>
set the public key algorithm option B<opt> to B<value>. The precise set of
options supported depends on the public key algorithm used and its
implementation. See B<KEY GENERATION OPTIONS> in the B<genpkey> manual page
for more details.
=item B<-key filename>
This specifies the file to read the private key from. It also
accepts PKCS#8 format private keys for PEM format files.
=item B<-keyform PEM|DER>
the format of the private key file specified in the B<-key>
argument. PEM is the default.
=item B<-keyout filename>
this gives the filename to write the newly created private key to.
If this option is not specified then the filename present in the
configuration file is used.
=item B<-nodes>
if this option is specified then if a private key is created it
will not be encrypted.
=item B<-[digest]>
this specifies the message digest to sign the request with (such as
B<-md5>, B<-sha1>). This overrides the digest algorithm specified in
the configuration file.
Some public key algorithms may override this choice. For instance, DSA
signatures always use SHA1, GOST R 34.10 signatures always use
GOST R 34.11-94 (B<-md_gost94>).
=item B<-config filename>
this allows an alternative configuration file to be specified,
this overrides the compile time filename or any specified in
the B<OPENSSL_CONF> environment variable.
=item B<-subj arg>
sets subject name for new request or supersedes the subject name
when processing a request.
The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
characters may be escaped by \ (backslash), no spaces are skipped.
=item B<-multivalue-rdn>
this option causes the -subj argument to be interpreted with full
support for multivalued RDNs. Example:
I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
If -multi-rdn is not used then the UID value is I<123456+CN=John Doe>.
=item B<-x509>
this option outputs a self signed certificate instead of a certificate
request. This is typically used to generate a test certificate or
a self signed root CA. The extensions added to the certificate
(if any) are specified in the configuration file. Unless specified
using the B<set_serial> option, a large random number will be used for
the serial number.
=item B<-days n>
when the B<-x509> option is being used this specifies the number of
days to certify the certificate for. The default is 30 days.
=item B<-set_serial 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 B<0x>.
It is possible to use negative serial numbers but this is not recommended.
=item B<-extensions section>
=item B<-reqexts section>
these options specify alternative sections to include certificate
extensions (if the B<-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.
=item B<-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.
=item B<-nameopt option>
option which determines how the subject or issuer names are displayed. The
B<option> argument can be a single option or multiple options separated by
commas. Alternatively the B<-nameopt> switch may be used more than once to
set multiple options. See the L<x509(1)|x509(1)> manual page for details.
=item B<-reqopt>
customise the output format used with B<-text>. The B<option> argument can be
a single option or multiple options separated by commas.
See discission of the B<-certopt> parameter in the L<B<x509>|x509(1)>
command.
=item B<-asn1-kludge>
by default the B<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.
More precisely the B<Attributes> in a PKCS#10 certificate request
are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so
if no attributes are present then they should be encoded as an
empty B<SET OF>. The invalid form does not include the empty
B<SET OF> whereas the correct form does.
It should be noted that very few CAs still require the use of this option.
=item B<-no-asn1-kludge>
Reverses effect of B<-asn1-kludge>
=item B<-newhdr>
Adds the word B<NEW> to the PEM file header and footer lines on the outputted
request. Some software (Netscape certificate server) and some CAs need this.
=item B<-batch>
non-interactive mode.
=item B<-verbose>
print extra details about the operations being performed.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=item B<-keygen_engine id>
specifies an engine (by its unique B<id> string) which would be used
for key generation operations.
=back
=head1 CONFIGURATION FILE FORMAT
The configuration options are specified in the B<req> section of
the configuration file. As with all configuration files if no
value is specified in the specific section (i.e. B<req>) then
the initial unnamed or B<default> section is searched too.
The options available are described in detail below.
=over 4
=item B<input_password output_password>
The passwords for the input private key file (if present) and
the output private key file (if one will be created). The
command line options B<passin> and B<passout> override the
configuration file values.
=item B<default_bits>
Specifies the default key size in bits.
This option is used in conjunction with the B<-new> option to generate
a new key. It can be overridden by specifying an explicit key size in
the B<-newkey> option. The smallest accepted key size is 512 bits. If
no key size is specified then 2048 bits is used.
=item B<default_keyfile>
This is the default filename to write a private key to. If not
specified the key is written to standard output. This can be
overridden by the B<-keyout> option.
=item B<oid_file>
This specifies a file containing additional B<OBJECT IDENTIFIERS>.
Each line of the file should consist of the numerical form of the
object identifier followed by white space then the short name followed
by white space and finally the long name.
=item B<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 B<=> and the numerical form. The short
and long names are the same when this option is used.
=item B<RANDFILE>
This specifies a filename in which random number seed information is
placed and read from, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
It is used for private key generation.
=item B<encrypt_key>
If this is set to B<no> then if a private key is generated it is
B<not> encrypted. This is equivalent to the B<-nodes> command line
option. For compatibility B<encrypt_rsa_key> is an equivalent option.
=item B<default_md>
This option specifies the digest algorithm to use. Possible values
include B<md5 sha1 mdc2>. If not present then MD5 is used. This
option can be overridden on the command line.
=item B<string_mask>
This option masks out the use of certain string types in certain
fields. Most users will not need to change this option.
It can be set to several values B<default> which is also the default
option uses PrintableStrings, T61Strings and BMPStrings if the
B<pkix> value is used then only PrintableStrings and BMPStrings will
be used. This follows the PKIX recommendation in RFC2459. If the
B<utf8only> option is used then only UTF8Strings will be used: this
is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
option just uses PrintableStrings and T61Strings: certain software has
problems with BMPStrings and UTF8Strings: in particular Netscape.
=item B<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 B<-reqexts> command line switch. See the
L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
extension section format.
=item B<x509_extensions>
this specifies the configuration file section containing a list of
extensions to add to certificate generated when the B<-x509> switch
is used. It can be overridden by the B<-extensions> command line switch.
=item B<prompt>
if set to the value B<no> this disables prompting of certificate fields
and just takes values from the config file directly. It also changes the
expected format of the B<distinguished_name> and B<attributes> sections.
=item B<utf8>
if set to the value B<yes> then 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.
=item B<attributes>
this specifies the section containing any request attributes: its format
is the same as B<distinguished_name>. Typically these may contain the
challengePassword or unstructuredName types. They are currently ignored
by OpenSSL's request signing utilities but some CAs might want them.
=item B<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.
=back
=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
There are two separate formats for the distinguished name and attribute
sections. If the B<prompt> option is set to B<no> then these sections
just consist of field names and values: for example,
CN=My Name
OU=My Organization
emailAddress=someone@somewhere.org
This allows external programs (e.g. GUI based) to generate a template file
with all the field names and values and just pass it to B<req>. An example
of this kind of configuration file is contained in the B<EXAMPLES> section.
Alternatively if the B<prompt> option is absent or not set to B<no> then the
file contains field prompting information. It consists of lines of the form:
fieldName="prompt"
fieldName_default="default field value"
fieldName_min= 2
fieldName_max= 4
"fieldName" is the field name being used, for example commonName (or CN).
The "prompt" string is used to ask the user to enter the relevant
details. If the user enters nothing then the default value is used if no
default value is present then the field is omitted. A field can
still be omitted if a default value is present if the user just
enters the '.' character.
The number of characters entered must be between the fieldName_min and
fieldName_max limits: there may be additional restrictions based
on the field being used (for example countryName can only ever be
two characters long and must fit in a PrintableString).
Some fields (such as 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 fieldName contains some characters followed by a full stop
they will be ignored. So for example a second organizationName can
be input by calling it "1.organizationName".
The actual permitted field names are any object identifier short or
long names. These are compiled into OpenSSL and include the usual
values such as commonName, countryName, localityName, organizationName,
organizationalUnitName, stateOrProvinceName. Additionally emailAddress
is include as well as name, surname, givenName initials and dnQualifier.
Additional object identifiers can be defined with the B<oid_file> or
B<oid_section> options in the configuration file. Any additional fields
will be treated as though they were a DirectoryString.
=head1 EXAMPLES
Examine and verify certificate request:
openssl req -in req.pem -text -verify -noout
Create a private key and then generate a certificate request from it:
openssl genrsa -out key.pem 2048
openssl req -new -key key.pem -out req.pem
The same but just using req:
openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
Generate a self signed root certificate:
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
Example of a file pointed to by the B<oid_file> option:
1.2.3.4 shortName A longer Name
1.2.3.6 otherName Other longer Name
Example of a section pointed to by B<oid_section> making use of variable
expansion:
testoid1=1.2.3.5
testoid2=${testoid1}.6
Sample configuration file prompting for field values:
[ req ]
default_bits = 2048
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
Sample configuration containing all field values:
RANDFILE = $ENV::HOME/.rnd
[ req ]
default_bits = 2048
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
=head1 NOTES
The header and footer lines in the B<PEM> format are normally:
-----BEGIN CERTIFICATE REQUEST-----
-----END CERTIFICATE REQUEST-----
some software (some versions of Netscape certificate server) instead needs:
-----BEGIN NEW CERTIFICATE REQUEST-----
-----END NEW CERTIFICATE REQUEST-----
which is produced with the B<-newhdr> option but is otherwise compatible.
Either form is accepted transparently on input.
The certificate requests generated by B<Xenroll> with MSIE have extensions
added. It includes the B<keyUsage> extension which determines the type of
key (signature only or general purpose) and any additional OIDs entered
by the script in an extendedKeyUsage extension.
=head1 DIAGNOSTICS
The following messages are frequently asked about:
Using configuration from /some/path/openssl.cnf
Unable to load config info
This is followed some time later by...
unable to find 'distinguished_name' in config
problems making Certificate Request
The first error message is the clue: it can't find the configuration
file! Certain operations (like examining a certificate request) don't
need a configuration file so its use isn't enforced. Generation of
certificates or requests however does need a configuration file. This
could be regarded as a bug.
Another puzzling message is this:
Attributes:
a0:00
this is displayed when no attributes are present and the request includes
the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
0x00). If you just see:
Attributes:
then the B<SET OF> is missing and the encoding is technically invalid (but
it is tolerated). See the description of the command line option B<-asn1-kludge>
for more information.
=head1 ENVIRONMENT VARIABLES
The variable B<OPENSSL_CONF> if defined allows an alternative configuration
file location to be specified, it will be overridden by the B<-config> command
line switch if it is present. For compatibility reasons the B<SSLEAY_CONF>
environment variable serves the same purpose but its use is discouraged.
=head1 BUGS
OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
This can cause problems if you need characters that aren't available in
PrintableStrings and you don't want to or can't use BMPStrings.
As a consequence of the T61String handling the only correct way to represent
accented characters in OpenSSL is to use a 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.
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 subjectAltName should be input by the user.
=head1 SEE ALSO
L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)>,
L<x509v3_config(5)|x509v3_config(5)>
=cut

210
doc/apps/rsa.pod Normal file
View File

@@ -0,0 +1,210 @@
=pod
=head1 NAME
rsa - RSA key processing tool
=head1 SYNOPSIS
B<openssl> B<rsa>
[B<-inform PEM|NET|DER>]
[B<-outform PEM|NET|DER>]
[B<-in filename>]
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-sgckey>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
[B<-camellia128>]
[B<-camellia192>]
[B<-camellia256>]
[B<-des>]
[B<-des3>]
[B<-idea>]
[B<-text>]
[B<-noout>]
[B<-modulus>]
[B<-check>]
[B<-pubin>]
[B<-pubout>]
[B<-RSAPublicKey_in>]
[B<-RSAPublicKey_out>]
[B<-engine id>]
=head1 DESCRIPTION
The B<rsa> command processes RSA keys. They can be converted between various
forms and their components printed out. B<Note> this command uses the
traditional SSLeay compatible format for private key encryption: newer
applications should use the more secure PKCS#8 format using the B<pkcs8>
utility.
=head1 COMMAND OPTIONS
=over 4
=item B<-inform DER|NET|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
form compatible with the PKCS#1 RSAPrivateKey or SubjectPublicKeyInfo format.
The B<PEM> form is the default format: it consists of the B<DER> format base64
encoded with additional header and footer lines. On input PKCS#8 format private
keys are also accepted. The B<NET> form is a format is described in the B<NOTES>
section.
=item B<-outform DER|NET|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
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.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-out filename>
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 B<not> be the same as the input
filename.
=item B<-passout password>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-sgckey>
use the modified NET algorithm used with some versions of Microsoft IIS and SGC
keys.
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
These options encrypt the private key with the specified
cipher 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 B<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 use to add or change the pass phrase.
These options can only be used with PEM format output files.
=item B<-text>
prints out the various public or private key components in
plain text in addition to the encoded version.
=item B<-noout>
this option prevents output of the encoded version of the key.
=item B<-modulus>
this option prints out the value of the modulus of the key.
=item B<-check>
this option checks the consistency of an RSA private key.
=item B<-pubin>
by default a private key is read from the input file: with this
option a public key is read instead.
=item B<-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.
=item B<-RSAPublicKey_in>, B<-RSAPublicKey_out>
like B<-pubin> and B<-pubout> except B<RSAPublicKey> format is used instead.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=back
=head1 NOTES
The PEM private key format uses the header and footer lines:
-----BEGIN RSA PRIVATE KEY-----
-----END RSA PRIVATE KEY-----
The PEM public key format uses the header and footer lines:
-----BEGIN PUBLIC KEY-----
-----END PUBLIC KEY-----
The PEM B<RSAPublicKey> format uses the header and footer lines:
-----BEGIN RSA PUBLIC KEY-----
-----END RSA PUBLIC KEY-----
The B<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.
Some newer version of IIS have additional data in the exported .key
files. To use these with the utility, view the file with a binary editor
and look for the string "private-key", then trace back to the byte
sequence 0x30, 0x82 (this is an ASN1 SEQUENCE). Copy all the data
from this point onwards to another file and use that as the input
to the B<rsa> utility with the B<-inform NET> option. If you get
an error after entering the password try the B<-sgckey> option.
=head1 EXAMPLES
To remove the pass phrase on an RSA private key:
openssl rsa -in key.pem -out keyout.pem
To encrypt a private key using triple DES:
openssl rsa -in key.pem -des3 -out keyout.pem
To convert a private key from PEM to DER format:
openssl rsa -in key.pem -outform DER -out keyout.der
To print out the components of a private key to standard output:
openssl rsa -in key.pem -text -noout
To just output the public part of a private key:
openssl rsa -in key.pem -pubout -out pubkey.pem
Output the public part of a private key in B<RSAPublicKey> format:
openssl rsa -in key.pem -RSAPublicKey_out -out pubkey.pem
=head1 BUGS
The command line password arguments don't currently work with
B<NET> format.
There should be an option that automatically handles .key files,
without having to manually edit them.
=head1 SEE ALSO
L<pkcs8(1)|pkcs8(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>,
L<gendsa(1)|gendsa(1)>
=cut

183
doc/apps/rsautl.pod Normal file
View File

@@ -0,0 +1,183 @@
=pod
=head1 NAME
rsautl - RSA utility
=head1 SYNOPSIS
B<openssl> B<rsautl>
[B<-in file>]
[B<-out file>]
[B<-inkey file>]
[B<-pubin>]
[B<-certin>]
[B<-sign>]
[B<-verify>]
[B<-encrypt>]
[B<-decrypt>]
[B<-pkcs>]
[B<-ssl>]
[B<-raw>]
[B<-hexdump>]
[B<-asn1parse>]
=head1 DESCRIPTION
The B<rsautl> command can be used to sign, verify, encrypt and decrypt
data using the RSA algorithm.
=head1 COMMAND OPTIONS
=over 4
=item B<-in filename>
This specifies the input filename to read data from or standard input
if this option is not specified.
=item B<-out filename>
specifies the output filename to write to or standard output by
default.
=item B<-inkey file>
the input key file, by default it should be an RSA private key.
=item B<-pubin>
the input file is an RSA public key.
=item B<-certin>
the input is a certificate containing an RSA public key.
=item B<-sign>
sign the input data and output the signed result. This requires
and RSA private key.
=item B<-verify>
verify the input data and output the recovered data.
=item B<-encrypt>
encrypt the input data using an RSA public key.
=item B<-decrypt>
decrypt the input data using an RSA private key.
=item B<-pkcs, -oaep, -ssl, -raw>
the padding to use: PKCS#1 v1.5 (the default), PKCS#1 OAEP,
special padding used in SSL v2 backwards compatible handshakes,
or no padding, respectively.
For signatures, only B<-pkcs> and B<-raw> can be used.
=item B<-hexdump>
hex dump the output data.
=item B<-asn1parse>
asn1parse the output data, this is useful when combined with the
B<-verify> option.
=back
=head1 NOTES
B<rsautl> because it uses the RSA algorithm directly can only be
used to sign or verify small pieces of data.
=head1 EXAMPLES
Sign some data using a private key:
openssl rsautl -sign -in file -inkey key.pem -out sig
Recover the signed data
openssl rsautl -verify -in sig -inkey key.pem
Examine the raw signed data:
openssl rsautl -verify -in file -inkey key.pem -raw -hexdump
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
The PKCS#1 block formatting is evident from this. If this was done using
encrypt and decrypt the block would have been of type 2 (the second byte)
and random padding data visible instead of the 0xff bytes.
It is possible to analyse the signature of certificates using this
utility in conjunction with B<asn1parse>. Consider the self signed
example in certs/pca-cert.pem . Running B<asn1parse> as follows yields:
openssl asn1parse -in pca-cert.pem
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
The final BIT STRING contains the actual signature. It can be extracted with:
openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614
The certificate public key can be extracted with:
openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem
The signature can be analysed with:
openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin
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%..
This is the parsed version of an ASN1 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:
openssl asn1parse -in pca-cert.pem -out tbs -noout -strparse 4
and its digest computed with:
openssl md5 -c tbs
MD5(tbs)= f3:46:9e:aa:1a:4a:73:c9:37:ea:93:00:48:25:08:b5
which it can be seen agrees with the recovered value above.
=head1 SEE ALSO
L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>

370
doc/apps/s_client.pod Normal file
View File

@@ -0,0 +1,370 @@
=pod
=head1 NAME
s_client - SSL/TLS client program
=head1 SYNOPSIS
B<openssl> B<s_client>
[B<-connect host:port>]
[B<-servername name>]
[B<-verify depth>]
[B<-verify_return_error>]
[B<-cert filename>]
[B<-certform DER|PEM>]
[B<-key filename>]
[B<-keyform DER|PEM>]
[B<-pass arg>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-no_alt_chains>]
[B<-reconnect>]
[B<-pause>]
[B<-showcerts>]
[B<-debug>]
[B<-msg>]
[B<-nbio_test>]
[B<-state>]
[B<-nbio>]
[B<-crlf>]
[B<-ign_eof>]
[B<-no_ign_eof>]
[B<-quiet>]
[B<-ssl2>]
[B<-ssl3>]
[B<-tls1>]
[B<-no_ssl2>]
[B<-no_ssl3>]
[B<-no_tls1>]
[B<-no_tls1_1>]
[B<-no_tls1_2>]
[B<-fallback_scsv>]
[B<-bugs>]
[B<-cipher cipherlist>]
[B<-serverpref>]
[B<-starttls protocol>]
[B<-engine id>]
[B<-tlsextdebug>]
[B<-no_ticket>]
[B<-sess_out filename>]
[B<-sess_in filename>]
[B<-rand file(s)>]
[B<-serverinfo types>]
[B<-status>]
[B<-alpn protocols>]
[B<-nextprotoneg protocols>]
=head1 DESCRIPTION
The B<s_client> command implements a generic SSL/TLS client which connects
to a remote host using SSL/TLS. It is a I<very> useful diagnostic tool for
SSL servers.
=head1 OPTIONS
=over 4
=item B<-connect host:port>
This specifies the host and optional port to connect to. If not specified
then an attempt is made to connect to the local host on port 4433.
=item B<-servername name>
Set the TLS SNI (Server Name Indication) extension in the ClientHello message.
=item B<-cert certname>
The certificate to use, if one is requested by the server. The default is
not to use a certificate.
=item B<-certform format>
The certificate format to use: DER or PEM. PEM is the default.
=item B<-key keyfile>
The private key to use. If not specified then the certificate file will
be used.
=item B<-keyform format>
The private format to use: DER or PEM. PEM is the default.
=item B<-pass arg>
the private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-verify 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.
=item B<-verify_return_error>
Return verification errors instead of continuing. This will typically
abort the handshake with a fatal error.
=item B<-CApath directory>
The directory to use for server certificate verification. This directory
must be in "hash format", see B<verify> for more information. These are
also used when building the client certificate chain.
=item B<-CAfile file>
A file containing trusted certificates to use during server authentication
and to use when attempting to build the client certificate chain.
=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains>
Set various certificate chain valiadition option. See the
L<B<verify>|verify(1)> manual page for details.
=item B<-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.
=item B<-pause>
pauses 1 second between each read and write call.
=item B<-showcerts>
display the whole server certificate chain: normally only the server
certificate itself is displayed.
=item B<-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. Note: the output produced by this
option is not always accurate because a connection might never have been
established.
=item B<-state>
prints out the SSL session states.
=item B<-debug>
print extensive debugging information including a hex dump of all traffic.
=item B<-msg>
show all protocol messages with hex dump.
=item B<-nbio_test>
tests non-blocking I/O
=item B<-nbio>
turns on non-blocking I/O
=item B<-crlf>
this option translated a line feed from the terminal into CR+LF as required
by some servers.
=item B<-ign_eof>
inhibit shutting down the connection when end of file is reached in the
input.
=item B<-quiet>
inhibit printing of session and certificate information. This implicitly
turns on B<-ign_eof> as well.
=item B<-no_ign_eof>
shut down the connection when end of file is reached in the input.
Can be used to override the implicit B<-ign_eof> after B<-quiet>.
=item B<-psk_identity identity>
Use the PSK identity B<identity> when using a PSK cipher suite.
=item B<-psk key>
Use the PSK key B<key> when using a PSK cipher suite. The key is
given as a hexadecimal number without leading 0x, for example -psk
1a2b3c4d.
=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
These options require or disable the use of the specified SSL or TLS protocols.
By default the initial handshake uses a I<version-flexible> method which will
negotiate the highest mutually supported protocol version.
=item B<-fallback_scsv>
Send TLS_FALLBACK_SCSV in the ClientHello.
=item B<-bugs>
there are several known bug in SSL and TLS implementations. Adding this
option enables various workarounds.
=item B<-cipher 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 B<ciphers>
command for more information.
=item B<-serverpref>
use the server's cipher preferences; only used for SSLV2.
=item B<-starttls protocol>
send the protocol-specific message(s) to switch to TLS for communication.
B<protocol> is a keyword for the intended protocol. Currently, the only
supported keywords are "smtp", "pop3", "imap", and "ftp".
=item B<-tlsextdebug>
print out a hex dump of any TLS extensions received from the server.
=item B<-no_ticket>
disable RFC4507bis session ticket support.
=item B<-sess_out filename>
output SSL session to B<filename>
=item B<-sess_in sess.pem>
load SSL session from B<filename>. The client will attempt to resume a
connection from this session.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-serverinfo types>
a list of comma-separated TLS Extension Types (numbers between 0 and
65535). Each type will be sent as an empty ClientHello TLS Extension.
The server's response (if any) will be encoded and displayed as a PEM
file.
=item B<-status>
sends a certificate status request to the server (OCSP stapling). The server
response (if any) is printed out.
=item B<-alpn protocols>, B<-nextprotoneg protocols>
these flags enable the
Enable the Application-Layer Protocol Negotiation or Next Protocol
Negotiation extension, respectively. ALPN is the IETF standard and
replaces NPN.
The B<protocols> list is a
comma-separated protocol names that the client should advertise
support for. The list should contain most wanted protocols first.
Protocol names are printable ASCII strings, for example "http/1.1" or
"spdy/3".
Empty list of protocols is treated specially and will cause the client to
advertise support for the TLS extension but disconnect just after
reciving ServerHello with a list of server supported protocols.
=back
=head1 CONNECTED COMMANDS
If a connection is established with an SSL server then any data received
from the server is displayed and any key presses will be sent to the
server. When used interactively (which means neither B<-quiet> nor B<-ign_eof>
have been given), the session will be renegotiated if the line begins with an
B<R>, and if the line begins with a B<Q> or if end of file is reached, the
connection will be closed down.
=head1 NOTES
B<s_client> can be used to debug SSL servers. To connect to an SSL HTTP
server the command:
openssl s_client -connect servername:443
would typically be used (https uses port 443). If the connection succeeds
then an HTTP command can be given such as "GET /" to retrieve a web page.
If the handshake fails then there are several possible causes, if it is
nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>,
B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> options can be tried
in case it is a buggy server. In particular you should play with these
options B<before> submitting a bug report to an OpenSSL mailing list.
A frequent problem when attempting to get client certificates working
is that a web client complains it has no certificates or gives an empty
list to choose from. This is normally because the server is not sending
the clients certificate authority in its "acceptable CA list" when it
requests a certificate. By using B<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 B<-prexit> option and send an HTTP request
for an appropriate page.
If a certificate is specified on the command line using the B<-cert>
option it will not be used unless the server specifically requests
a client certificate. Therefor merely including a client certificate
on the command line is no guarantee that the certificate works.
If there are problems verifying a server certificate then the
B<-showcerts> option can be used to show the whole chain.
Since the SSLv23 client hello cannot include compression methods or extensions
these will only be supported if its use is disabled, for example by using the
B<-no_sslv2> option.
The B<s_client> utility is a test tool and is designed to continue the
handshake after any certificate verification errors. As a result it will
accept any certificate chain (trusted or not) sent by the peer. None test
applications should B<not> do this as it makes them vulnerable to a MITM
attack. This behaviour can be changed by with the B<-verify_return_error>
option: any verify errors are then returned aborting the handshake.
=head1 BUGS
Because this program has a lot of options and also because some of
the techniques used are rather old, the C source of 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.
The B<-prexit> option is a bit of a hack. We should really report
information whenever a session is renegotiated.
=head1 SEE ALSO
L<sess_id(1)|sess_id(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)>
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
=cut

423
doc/apps/s_server.pod Normal file
View File

@@ -0,0 +1,423 @@
=pod
=head1 NAME
s_server - SSL/TLS server program
=head1 SYNOPSIS
B<openssl> B<s_server>
[B<-accept port>]
[B<-context id>]
[B<-verify depth>]
[B<-Verify depth>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-cert filename>]
[B<-certform DER|PEM>]
[B<-key keyfile>]
[B<-keyform DER|PEM>]
[B<-pass arg>]
[B<-dcert filename>]
[B<-dcertform DER|PEM>]
[B<-dkey keyfile>]
[B<-dkeyform DER|PEM>]
[B<-dpass arg>]
[B<-dhparam filename>]
[B<-nbio>]
[B<-nbio_test>]
[B<-crlf>]
[B<-debug>]
[B<-msg>]
[B<-state>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-no_alt_chains>]
[B<-nocert>]
[B<-cipher cipherlist>]
[B<-serverpref>]
[B<-quiet>]
[B<-no_tmp_rsa>]
[B<-ssl2>]
[B<-ssl3>]
[B<-tls1>]
[B<-no_ssl2>]
[B<-no_ssl3>]
[B<-no_tls1>]
[B<-no_dhe>]
[B<-bugs>]
[B<-hack>]
[B<-www>]
[B<-WWW>]
[B<-HTTP>]
[B<-engine id>]
[B<-tlsextdebug>]
[B<-no_ticket>]
[B<-id_prefix arg>]
[B<-rand file(s)>]
[B<-serverinfo file>]
[B<-no_resumption_on_reneg>]
[B<-status>]
[B<-status_verbose>]
[B<-status_timeout nsec>]
[B<-status_url url>]
[B<-alpn protocols>]
[B<-nextprotoneg protocols>]
=head1 DESCRIPTION
The B<s_server> command implements a generic SSL/TLS server which listens
for connections on a given port using SSL/TLS.
=head1 OPTIONS
=over 4
=item B<-accept port>
the TCP port to listen on for connections. If not specified 4433 is used.
=item B<-context 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.
=item B<-cert certname>
The certificate to use, most servers cipher suites require the use of a
certificate and some require a certificate with a certain public key type:
for example the DSS cipher suites require a certificate containing a DSS
(DSA) key. If not specified then the filename "server.pem" will be used.
=item B<-certform format>
The certificate format to use: DER or PEM. PEM is the default.
=item B<-key keyfile>
The private key to use. If not specified then the certificate file will
be used.
=item B<-keyform format>
The private format to use: DER or PEM. PEM is the default.
=item B<-pass arg>
the private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-dcert filename>, B<-dkey keyname>
specify an additional certificate and private key, these behave in the
same manner as the B<-cert> and B<-key> options except there is no default
if they are not specified (no additional certificate and key is used). As
noted above some cipher suites require a certificate containing a key of
a certain type. Some cipher suites need a certificate carrying an RSA key
and some a DSS (DSA) key. By using RSA and DSS certificates and keys
a server can support clients which only support RSA or DSS cipher suites
by using an appropriate certificate.
=item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg>
additional certificate and private key format and passphrase respectively.
=item B<-nocert>
if this option is set then no certificate is used. This restricts the
cipher suites available to the anonymous ones (currently just anonymous
DH).
=item B<-dhparam filename>
the DH parameter file to use. The ephemeral DH cipher suites generate keys
using a set of DH parameters. If not specified then an attempt is made to
load the parameters from the server certificate file. If this fails then
a static set of parameters hard coded into the s_server program will be used.
=item B<-no_dhe>
if this option is set then no DH parameters will be loaded effectively
disabling the ephemeral DH cipher suites.
=item B<-no_tmp_rsa>
certain export cipher suites sometimes use a temporary RSA key, this option
disables temporary RSA key generation.
=item B<-verify depth>, B<-Verify depth>
The verify 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 B<-verify> option a certificate is requested but the
client does not have to send one, with the B<-Verify> option the client
must supply a certificate or an error occurs.
If the ciphersuite cannot request a client certificate (for example an
anonymous ciphersuite or PSK) this option has no effect.
=item B<-crl_check>, B<-crl_check_all>
Check the peer certificate has not been revoked by its CA.
The CRL(s) are appended to the certificate file. With the B<-crl_check_all>
option all CRLs of all CAs in the chain are checked.
=item B<-CApath directory>
The directory to use for client certificate verification. This directory
must be in "hash format", see B<verify> for more information. These are
also used when building the server certificate chain.
=item B<-CAfile 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.
=item B<-no_alt_chains>
See the L<B<verify>|verify(1)> manual page for details.
=item B<-state>
prints out the SSL session states.
=item B<-debug>
print extensive debugging information including a hex dump of all traffic.
=item B<-msg>
show all protocol messages with hex dump.
=item B<-nbio_test>
tests non blocking I/O
=item B<-nbio>
turns on non blocking I/O
=item B<-crlf>
this option translated a line feed from the terminal into CR+LF.
=item B<-quiet>
inhibit printing of session and certificate information.
=item B<-psk_hint hint>
Use the PSK identity hint B<hint> when using a PSK cipher suite.
=item B<-psk key>
Use the PSK key B<key> when using a PSK cipher suite. The key is
given as a hexadecimal number without leading 0x, for example -psk
1a2b3c4d.
=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
These options require or disable the use of the specified SSL or TLS protocols.
By default the initial handshake uses a I<version-flexible> method which will
negotiate the highest mutually supported protocol version.
=item B<-bugs>
there are several known bug in SSL and TLS implementations. Adding this
option enables various workarounds.
=item B<-hack>
this option enables a further workaround for some some early Netscape
SSL code (?).
=item B<-cipher cipherlist>
this allows the cipher list used by the server to be modified. When
the client sends a list of supported ciphers the first client cipher
also included in the server list is used. Because the client specifies
the preference order, the order of the server cipherlist irrelevant. See
the B<ciphers> command for more information.
=item B<-serverpref>
use the server's cipher preferences, rather than the client's preferences.
=item B<-tlsextdebug>
print out a hex dump of any TLS extensions received from the server.
=item B<-no_ticket>
disable RFC4507bis session ticket support.
=item B<-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.
=item B<-WWW>
emulates a simple web server. Pages will be resolved relative to the
current directory, for example if the URL https://myhost/page.html is
requested the file ./page.html will be loaded.
=item B<-HTTP>
emulates a simple web server. Pages will be resolved relative to the
current directory, for example if the URL https://myhost/page.html is
requested the file ./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).
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=item B<-id_prefix arg>
generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful
for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple
servers, when each of which might be generating a unique range of session
IDs (eg. with a certain prefix).
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-serverinfo file>
a file containing one or more blocks of PEM data. Each PEM block
must encode a TLS ServerHello extension (2 bytes type, 2 bytes length,
followed by "length" bytes of extension data). If the client sends
an empty TLS ClientHello extension matching the type, the corresponding
ServerHello extension will be returned.
=item B<-no_resumption_on_reneg>
set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag.
=item B<-status>
enables certificate status request support (aka OCSP stapling).
=item B<-status_verbose>
enables certificate status request support (aka OCSP stapling) and gives
a verbose printout of the OCSP response.
=item B<-status_timeout nsec>
sets the timeout for OCSP response to B<nsec> seconds.
=item B<-status_url url>
sets a fallback responder URL to use if no responder URL is present in the
server certificate. Without this option an error is returned if the server
certificate does not contain a responder address.
=item B<-alpn protocols>, B<-nextprotoneg protocols>
these flags enable the
Enable the Application-Layer Protocol Negotiation or Next Protocol
Negotiation extension, respectively. ALPN is the IETF standard and
replaces NPN.
The B<protocols> list is a
comma-separated list of supported protocol names.
The list should contain most wanted protocols first.
Protocol names are printable ASCII strings, for example "http/1.1" or
"spdy/3".
=back
=head1 CONNECTED COMMANDS
If a connection request is established with an SSL client and neither the
B<-www> nor the B<-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.
Certain single letter commands are also recognized which perform special
operations: these are listed below.
=over 4
=item B<q>
end the current SSL connection but still accept new connections.
=item B<Q>
end the current SSL connection and exit.
=item B<r>
renegotiate the SSL session.
=item B<R>
renegotiate the SSL session and request a client certificate.
=item B<P>
send some plain text down the underlying TCP connection: this should
cause the client to disconnect due to a protocol violation.
=item B<S>
print out some session cache status information.
=back
=head1 NOTES
B<s_server> can be used to debug SSL clients. To accept connections from
a web browser the command:
openssl s_server -accept 443 -www
can be used for example.
Most web browsers (in particular Netscape and MSIE) only support RSA cipher
suites, so they cannot connect to servers which don't use a certificate
carrying an RSA key or a version of OpenSSL with RSA disabled.
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.
The session parameters can printed out using the B<sess_id> program.
=head1 BUGS
Because this program has a lot of options and also because some of
the techniques used are rather old, the C source of 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.
The output of common ciphers is wrong: it just gives the list of ciphers that
OpenSSL recognizes and the client supports.
There should be a way for the B<s_server> program to print out details of any
unknown cipher suites a client says it supports.
=head1 SEE ALSO
L<sess_id(1)|sess_id(1)>, L<s_client(1)|s_client(1)>, L<ciphers(1)|ciphers(1)>
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
=cut

173
doc/apps/s_time.pod Normal file
View File

@@ -0,0 +1,173 @@
=pod
=head1 NAME
s_time - SSL/TLS performance timing program
=head1 SYNOPSIS
B<openssl> B<s_time>
[B<-connect host:port>]
[B<-www page>]
[B<-cert filename>]
[B<-key filename>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-reuse>]
[B<-new>]
[B<-verify depth>]
[B<-nbio>]
[B<-time seconds>]
[B<-ssl2>]
[B<-ssl3>]
[B<-bugs>]
[B<-cipher cipherlist>]
=head1 DESCRIPTION
The B<s_time> 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 (if any), and calculates the average time spent for one connection.
=head1 OPTIONS
=over 4
=item B<-connect host:port>
This specifies the host and optional port to connect to.
=item B<-www page>
This specifies the page to GET from the server. A value of '/' gets the
index.htm[l] page. If this parameter is not specified, then B<s_time> will only
perform the handshake to establish SSL connections but not transfer any
payload data.
=item B<-cert certname>
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.
=item B<-key keyfile>
The private key to use. If not specified then the certificate file will
be used. The file is in PEM format.
=item B<-verify 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.
=item B<-CApath directory>
The directory to use for server certificate verification. This directory
must be in "hash format", see B<verify> for more information. These are
also used when building the client certificate chain.
=item B<-CAfile file>
A file containing trusted certificates to use during server authentication
and to use when attempting to build the client certificate chain.
=item B<-new>
performs the timing test using a new session ID for each connection.
If neither B<-new> nor B<-reuse> are specified, they are both on by default
and executed in sequence.
=item B<-reuse>
performs the timing test using the same session ID; this can be used as a test
that session caching is working. If neither B<-new> nor B<-reuse> are
specified, they are both on by default and executed in sequence.
=item B<-nbio>
turns on non-blocking I/O.
=item B<-ssl2>, B<-ssl3>
these options disable the use of certain SSL or TLS protocols. By default
the initial handshake uses a method which should be compatible with all
servers and permit them to use SSL v3, SSL v2 or TLS as appropriate.
The timing program is not as rich in options to turn protocols on and off as
the L<s_client(1)|s_client(1)> program and may not connect to all servers.
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 B<-ssl3> option; others
will only support SSL v2 and may need the B<-ssl2> option.
=item B<-bugs>
there are several known bug in SSL and TLS implementations. Adding this
option enables various workarounds.
=item B<-cipher 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 L<ciphers(1)|ciphers(1)> command for more information.
=item B<-time length>
specifies how long (in seconds) B<s_time> should establish connections and
optionally transfer payload data from a server. Server and client performance
and the link speed determine how many connections B<s_time> can establish.
=back
=head1 NOTES
B<s_time> 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
openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3]
would typically be used (https uses port 443). 'commoncipher' is a cipher to
which both client and server can agree, see the L<ciphers(1)|ciphers(1)> command
for details.
If the handshake fails then there are several possible causes, if it is
nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>,
B<-ssl3> options can be tried
in case it is a buggy server. In particular you should play with these
options B<before> submitting a bug report to an OpenSSL mailing list.
A frequent problem when attempting to get client certificates working
is that a web client complains it has no certificates or gives an empty
list to choose from. This is normally because the server is not sending
the clients certificate authority in its "acceptable CA list" when it
requests a certificate. By using L<s_client(1)|s_client(1)> 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 B<-prexit> option of L<s_client(1)|s_client(1)> and
send an HTTP request for an appropriate page.
If a certificate is specified on the command line using the B<-cert>
option it will not be used unless the server specifically requests
a client certificate. Therefor merely including a client certificate
on the command line is no guarantee that the certificate works.
=head1 BUGS
Because this program does not have all the options of the
L<s_client(1)|s_client(1)> program to turn protocols on and off, you may not be
able to measure the performance of all protocols with all servers.
The B<-verify> option should really exit if the server verification
fails.
=head1 SEE ALSO
L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)>
=cut

151
doc/apps/sess_id.pod Normal file
View File

@@ -0,0 +1,151 @@
=pod
=head1 NAME
sess_id - SSL/TLS session handling utility
=head1 SYNOPSIS
B<openssl> B<sess_id>
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
[B<-out filename>]
[B<-text>]
[B<-noout>]
[B<-context ID>]
=head1 DESCRIPTION
The B<sess_id> process the encoded version of the SSL session structure
and optionally prints out SSL session details (for example the SSL session
master key) in human readable format. Since this is a diagnostic tool that
needs some knowledge of the SSL protocol to use properly, most users will
not need to use it.
=over 4
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
format containing session details. The precise format can vary from one version
to the next. The B<PEM> form is the default format: it consists of the B<DER>
format base64 encoded with additional header and footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
This specifies the input filename to read session information from or standard
input by default.
=item B<-out filename>
This specifies the output filename to write session information to or standard
output if this option is not specified.
=item B<-text>
prints out the various public or private key components in
plain text in addition to the encoded version.
=item B<-cert>
if a certificate is present in the session it will be output using this option,
if the B<-text> option is also present then it will be printed out in text form.
=item B<-noout>
this option prevents output of the encoded version of the session.
=item B<-context ID>
this option can set the session id so the output session information uses the
supplied ID. The ID can be any string of characters. This option wont normally
be used.
=back
=head1 OUTPUT
Typical output:
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)
Theses are described below in more detail.
=over 4
=item B<Protocol>
this is the protocol in use TLSv1, SSLv3 or SSLv2.
=item B<Cipher>
the cipher used this is the actual raw SSL or TLS cipher code, see the SSL
or TLS specifications for more information.
=item B<Session-ID>
the SSL session ID in hex format.
=item B<Session-ID-ctx>
the session ID context in hex format.
=item B<Master-Key>
this is the SSL session master key.
=item B<Key-Arg>
the key argument, this is only used in SSL v2.
=item B<Start Time>
this is the session start time represented as an integer in standard Unix format.
=item B<Timeout>
the timeout in seconds.
=item B<Verify return code>
this is the return code when an SSL client certificate is verified.
=back
=head1 NOTES
The PEM encoded session format uses the header and footer lines:
-----BEGIN SSL SESSION PARAMETERS-----
-----END SSL SESSION PARAMETERS-----
Since the SSL session output contains the master key it is possible to read the contents
of an encrypted session using this information. Therefore appropriate security precautions
should be taken if the information is being output by a "real" application. This is
however strongly discouraged and should only be used for debugging purposes.
=head1 BUGS
The cipher and start time should be printed out in human readable form.
=head1 SEE ALSO
L<ciphers(1)|ciphers(1)>, L<s_server(1)|s_server(1)>
=cut

450
doc/apps/smime.pod Normal file
View File

@@ -0,0 +1,450 @@
=pod
=head1 NAME
smime - S/MIME utility
=head1 SYNOPSIS
B<openssl> B<smime>
[B<-encrypt>]
[B<-decrypt>]
[B<-sign>]
[B<-resign>]
[B<-verify>]
[B<-pk7out>]
[B<-[cipher]>]
[B<-in file>]
[B<-no_alt_chains>]
[B<-certfile file>]
[B<-signer file>]
[B<-recip file>]
[B<-inform SMIME|PEM|DER>]
[B<-passin arg>]
[B<-inkey file>]
[B<-out file>]
[B<-outform SMIME|PEM|DER>]
[B<-content file>]
[B<-to addr>]
[B<-from ad>]
[B<-subject s>]
[B<-text>]
[B<-indef>]
[B<-noindef>]
[B<-stream>]
[B<-rand file(s)>]
[B<-md digest>]
[cert.pem]...
=head1 DESCRIPTION
The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and
verify S/MIME messages.
=head1 COMMAND OPTIONS
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.
=over 4
=item B<-encrypt>
encrypt mail for the given recipient certificates. Input file is the message
to be encrypted. The output file is the encrypted mail in MIME format.
Note that no revocation check is done for the recipient cert, so if that
key has been compromised, others may be able to decrypt the text.
=item B<-decrypt>
decrypt mail using the supplied certificate and private key. Expects an
encrypted mail message in MIME format for the input file. The decrypted mail
is written to the output file.
=item B<-sign>
sign mail using the supplied certificate and private key. Input file is
the message to be signed. The signed message in MIME format is written
to the output file.
=item B<-verify>
verify signed mail. Expects a signed mail message on input and outputs
the signed data. Both clear text and opaque signing is supported.
=item B<-pk7out>
takes an input message and writes out a PEM encoded PKCS#7 structure.
=item B<-resign>
resign a message: take an existing message and one or more new signers.
=item B<-in filename>
the input message to be encrypted or signed or the MIME message to
be decrypted or verified.
=item B<-inform SMIME|PEM|DER>
this specifies the input format for the PKCS#7 structure. The default
is B<SMIME> which reads an S/MIME format message. B<PEM> and B<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
B<-encrypt> or B<-sign>) this option has no effect.
=item B<-out filename>
the message text that has been decrypted or verified or the output MIME
format message that has been signed or verified.
=item B<-outform SMIME|PEM|DER>
this specifies the output format for the PKCS#7 structure. The default
is B<SMIME> which write an S/MIME format message. B<PEM> and B<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
B<-verify> or B<-decrypt>) this option has no effect.
=item B<-stream -indef -noindef>
the B<-stream> and B<-indef> options are equivalent and 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 B<SMIME> it is currently off by default for all
other operations.
=item B<-noindef>
disable streaming I/O where it would produce and indefinite length constructed
encoding. This option currently has no effect. In future streaming will be
enabled by default on all relevant operations and this option will disable it.
=item B<-content filename>
This specifies a file containing the detached content, this is only
useful with the B<-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 S/MIME and it uses the multipart/signed MIME content type.
=item B<-text>
this option adds plain text (text/plain) 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 MIME
type text/plain then an error occurs.
=item B<-CAfile file>
a file containing trusted CA certificates, only used with B<-verify>.
=item B<-CApath dir>
a directory containing trusted CA certificates, only used with
B<-verify>. This directory must be a standard certificate directory: that
is a hash of each subject name (using B<x509 -hash>) should be linked
to each certificate.
=item B<-md digest>
digest algorithm to use when signing or resigning. If not present then the
default digest algorithm for the signing key will be used (usually SHA1).
=item B<-[cipher]>
the encryption algorithm to use. For example DES (56 bits) - B<-des>,
triple DES (168 bits) - B<-des3>,
EVP_get_cipherbyname() function) can also be used preceded by a dash, for
example B<-aes_128_cbc>. See L<B<enc>|enc(1)> for list of ciphers
supported by your version of OpenSSL.
If not specified triple DES is used. Only used with B<-encrypt>.
=item B<-nointern>
when verifying a message normally certificates (if any) included in
the message are searched for the signing certificate. With this option
only the certificates specified in the B<-certfile> option are used.
The supplied certificates can still be used as untrusted CAs however.
=item B<-noverify>
do not verify the signers certificate of a signed message.
=item B<-nochain>
do not do chain verification of signers certificates: that is don't
use the certificates in the signed message as untrusted CAs.
=item B<-nosigs>
don't try to verify the signatures on the message.
=item B<-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 signers certificate
available locally (passed using the B<-certfile> option for example).
=item B<-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.
=item B<-binary>
normally the input message is converted to "canonical" format which is
effectively using CR and LF as end of line: as required by the S/MIME
specification. When this option is present no translation occurs. This
is useful when handling binary data which may not be in MIME format.
=item B<-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 S/MIME. Without this option cleartext signing with
the MIME type multipart/signed is used.
=item B<-certfile 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.
=item B<-signer 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 then the signers certificates will be written to this file if the
verification was successful.
=item B<-recip file>
the recipients certificate when decrypting a message. This certificate
must match one of the recipients of the message or an error occurs.
=item B<-inkey file>
the private key to use when signing or decrypting. This must match the
corresponding certificate. If this option is not specified then the
private key must be included in the certificate file specified with
the B<-recip> or B<-signer> file. When signing this option can be used
multiple times to specify successive keys.
=item B<-passin arg>
the private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<cert.pem...>
one or more certificates of message recipients: used when encrypting
a message.
=item B<-to, -from, -subject>
the relevant mail headers. These are included outside the signed
portion of a message so they may be included manually. If signing
then many S/MIME mail clients check the signers certificate's email
address matches that specified in the From: address.
=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains>
Set various options of certificate chain verification. See
L<B<verify>|verify(1)> manual page for details.
=back
=head1 NOTES
The 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.
The supplied message to be signed or encrypted must include the
necessary MIME headers or many S/MIME clients wont display it
properly (if at all). You can use the B<-text> option to automatically
add plain text headers.
A "signed and encrypted" message is one where a signed message is
then encrypted. This can be produced by encrypting an already signed
message: see the examples section.
This version of the program only allows one signer per message but it
will verify multiple signers on received messages. Some S/MIME clients
choke if a message contains multiple signers. It is possible to sign
messages "in parallel" by signing an already signed message.
The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7
encrypted data is used for other purposes.
The B<-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.
The B<-stream> and B<-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 B<-encrypt> operation and the
B<-sign> operation if the content is not detached.
Streaming is always used for the B<-sign> operation with detached data but
since the content is no longer part of the PKCS#7 structure the encoding
remains DER.
=head1 EXIT CODES
=over 4
=item Z<>0
the operation was completely successfully.
=item Z<>1
an error occurred parsing the command options.
=item Z<>2
one of the input files could not be read.
=item Z<>3
an error occurred creating the PKCS#7 file or when reading the MIME
message.
=item Z<>4
an error occurred decrypting or verifying the message.
=item Z<>5
the message was verified correctly but an error occurred writing out
the signers certificates.
=back
=head1 EXAMPLES
Create a cleartext signed message:
openssl smime -sign -in message.txt -text -out mail.msg \
-signer mycert.pem
Create an opaque signed message:
openssl smime -sign -in message.txt -text -out mail.msg -nodetach \
-signer mycert.pem
Create a signed message, include some additional certificates and
read the private key from another file:
openssl smime -sign -in in.txt -text -out mail.msg \
-signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
Create a signed message with two signers:
openssl smime -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -signer othercert.pem
Send a signed message under Unix directly to sendmail, including headers:
openssl smime -sign -in in.txt -text -signer mycert.pem \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed message" | sendmail someone@somewhere
Verify a message and extract the signer's certificate if successful:
openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt
Send encrypted mail using triple DES:
openssl smime -encrypt -in in.txt -from steve@openssl.org \
-to someone@somewhere -subject "Encrypted message" \
-des3 user.pem -out mail.msg
Sign and encrypt mail:
openssl smime -sign -in ml.txt -signer my.pem -text \
| openssl smime -encrypt -out mail.msg \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed and Encrypted message" -des3 user.pem
Note: the encryption command does not include the B<-text> option because the
message being encrypted already has MIME headers.
Decrypt mail:
openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
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:
-----BEGIN PKCS7-----
-----END PKCS7-----
and using the command:
openssl smime -verify -inform PEM -in signature.pem -content content.txt
Alternatively you can base64 decode the signature and use:
openssl smime -verify -inform DER -in signature.der -content content.txt
Create an encrypted message using 128 bit Camellia:
openssl smime -encrypt -in plain.txt -camellia128 -out mail.msg cert.pem
Add a signer to an existing message:
openssl smime -resign -in mail.msg -signer newsign.pem -out mail2.msg
=head1 BUGS
The MIME parser isn't very clever: it seems to handle most messages that I've
thrown at it but it may choke on others.
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.
Ideally a database should be maintained of a certificates for each email
address.
The code doesn't currently take note of the permitted symmetric encryption
algorithms as supplied in the 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.
No revocation checking is done on the signer's certificate.
The current code can only handle S/MIME v2 messages, the more complex S/MIME v3
structures may cause parsing errors.
=head1 HISTORY
The use of multiple B<-signer> options and the B<-resign> command were first
added in OpenSSL 1.0.0
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
=cut

59
doc/apps/speed.pod Normal file
View File

@@ -0,0 +1,59 @@
=pod
=head1 NAME
speed - test library performance
=head1 SYNOPSIS
B<openssl speed>
[B<-engine id>]
[B<md2>]
[B<mdc2>]
[B<md5>]
[B<hmac>]
[B<sha1>]
[B<rmd160>]
[B<idea-cbc>]
[B<rc2-cbc>]
[B<rc5-cbc>]
[B<bf-cbc>]
[B<des-cbc>]
[B<des-ede3>]
[B<rc4>]
[B<rsa512>]
[B<rsa1024>]
[B<rsa2048>]
[B<rsa4096>]
[B<dsa512>]
[B<dsa1024>]
[B<dsa2048>]
[B<idea>]
[B<rc2>]
[B<des>]
[B<rsa>]
[B<blowfish>]
=head1 DESCRIPTION
This command is used to test the performance of cryptographic algorithms.
=head1 OPTIONS
=over 4
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=item B<[zero or more test algorithms]>
If any options are given, B<speed> tests those algorithms, otherwise all of
the above are tested.
=back
=cut

133
doc/apps/spkac.pod Normal file
View File

@@ -0,0 +1,133 @@
=pod
=head1 NAME
spkac - SPKAC printing and generating utility
=head1 SYNOPSIS
B<openssl> B<spkac>
[B<-in filename>]
[B<-out filename>]
[B<-key keyfile>]
[B<-passin arg>]
[B<-challenge string>]
[B<-pubkey>]
[B<-spkac spkacname>]
[B<-spksect section>]
[B<-noout>]
[B<-verify>]
[B<-engine id>]
=head1 DESCRIPTION
The B<spkac> command processes Netscape signed public key and challenge
(SPKAC) files. It can print out their contents, verify the signature and
produce its own SPKACs from a supplied private key.
=head1 COMMAND OPTIONS
=over 4
=item B<-in filename>
This specifies the input filename to read from or standard input if this
option is not specified. Ignored if the B<-key> option is used.
=item B<-out filename>
specifies the output filename to write to or standard output by
default.
=item B<-key keyfile>
create an SPKAC file using the private key in B<keyfile>. The
B<-in>, B<-noout>, B<-spksect> and B<-verify> options are ignored if
present.
=item B<-passin password>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-challenge string>
specifies the challenge string if an SPKAC is being created.
=item B<-spkac spkacname>
allows an alternative name form the variable containing the
SPKAC. The default is "SPKAC". This option affects both
generated and input SPKAC files.
=item B<-spksect section>
allows an alternative name form the section containing the
SPKAC. The default is the default section.
=item B<-noout>
don't output the text version of the SPKAC (not used if an
SPKAC is being created).
=item B<-pubkey>
output the public key of an SPKAC (not used if an SPKAC is
being created).
=item B<-verify>
verifies the digital signature on the supplied SPKAC.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=back
=head1 EXAMPLES
Print out the contents of an SPKAC:
openssl spkac -in spkac.cnf
Verify the signature of an SPKAC:
openssl spkac -in spkac.cnf -noout -verify
Create an SPKAC using the challenge string "hello":
openssl spkac -key key.pem -challenge hello -out spkac.cnf
Example of an SPKAC, (long lines split up for clarity):
SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA1cCoq2Wa3Ixs47uI7F\
PVwHVIPDx5yso105Y6zpozam135a8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03u\
PFoQIDAQABFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJh1bEIYuc\
2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnDdq+NQ3F+X4deMx9AaEglZtULwV\
4=
=head1 NOTES
A created SPKAC with suitable DN components appended can be fed into
the B<ca> utility.
SPKACs are typically generated by Netscape when a form is submitted
containing the B<KEYGEN> tag as part of the certificate enrollment
process.
The challenge string permits a primitive form of proof of possession
of private key. By checking the SPKAC signature and a random challenge
string some guarantee is given that the user knows the private key
corresponding to the public key being certified. This is important in
some applications. Without this it is possible for a previous SPKAC
to be used in a "replay attack".
=head1 SEE ALSO
L<ca(1)|ca(1)>
=cut

594
doc/apps/ts.pod Normal file
View File

@@ -0,0 +1,594 @@
=pod
=head1 NAME
ts - Time Stamping Authority tool (client/server)
=head1 SYNOPSIS
B<openssl> B<ts>
B<-query>
[B<-rand> file:file...]
[B<-config> configfile]
[B<-data> file_to_hash]
[B<-digest> digest_bytes]
[B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...>]
[B<-policy> object_id]
[B<-no_nonce>]
[B<-cert>]
[B<-in> request.tsq]
[B<-out> request.tsq]
[B<-text>]
B<openssl> B<ts>
B<-reply>
[B<-config> configfile]
[B<-section> tsa_section]
[B<-queryfile> request.tsq]
[B<-passin> password_src]
[B<-signer> tsa_cert.pem]
[B<-inkey> private.pem]
[B<-chain> certs_file.pem]
[B<-policy> object_id]
[B<-in> response.tsr]
[B<-token_in>]
[B<-out> response.tsr]
[B<-token_out>]
[B<-text>]
[B<-engine> id]
B<openssl> B<ts>
B<-verify>
[B<-data> file_to_hash]
[B<-digest> digest_bytes]
[B<-queryfile> request.tsq]
[B<-in> response.tsr]
[B<-token_in>]
[B<-CApath> trusted_cert_path]
[B<-CAfile> trusted_certs.pem]
[B<-untrusted> cert_file.pem]
=head1 DESCRIPTION
The B<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:
=over 4
=item 1.
The TSA client computes a one-way hash value for a data file and sends
the hash to the TSA.
=item 2.
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.
=item 3.
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.
=back
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 B<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, verifying if a
response corresponds to a particular request or a data file.
There is no support for sending the requests/responses automatically
over HTTP or TCP yet as suggested in RFC 3161. The users must send the
requests either by ftp or e-mail.
=head1 OPTIONS
=head2 Time Stamp Request generation
The B<-query> switch can be used for creating and printing a time stamp
request with the following options:
=over 4
=item B<-rand> file:file...
The files containing random data for seeding the random number
generator. Multiple files can be specified, the separator is B<;> for
MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional)
=item B<-config> configfile
The configuration file to use, this option overrides the
B<OPENSSL_CONF> environment variable. Only the OID section
of the config file is used with the B<-query> command. (Optional)
=item B<-data> file_to_hash
The data file for which the time stamp request needs to be
created. stdin is the default if neither the B<-data> nor the B<-digest>
parameter is specified. (Optional)
=item B<-digest> 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. (Optional)
=item B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...>
The message digest to apply to the data file, it supports all the message
digest algorithms that are supported by the openssl B<dgst> command.
The default is SHA-1. (Optional)
=item B<-policy> 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. (Optional)
=item B<-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. (Optional)
=item B<-cert>
The TSA is expected to include its signing certificate in the
response. (Optional)
=item B<-in> 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. (Optional)
=item B<-out> request.tsq
Name of the output file to which the request will be written. Default
is stdout. (Optional)
=item B<-text>
If this option is specified the output is human-readable text format
instead of DER. (Optional)
=back
=head2 Time Stamp Response generation
A time stamp response (TimeStampResp) consists of a response status
and the time stamp token itself (ContentInfo), if the token generation was
successful. The B<-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 B<-token_out> is not
specified the output is always a time stamp response (TimeStampResp),
otherwise it is a time stamp token (ContentInfo).
=over 4
=item B<-config> configfile
The configuration file to use, this option overrides the
B<OPENSSL_CONF> environment variable. See B<CONFIGURATION FILE
OPTIONS> for configurable variables. (Optional)
=item B<-section> tsa_section
The name of the config file section conatining the settings for the
response generation. If not specified the default TSA section is
used, see B<CONFIGURATION FILE OPTIONS> for details. (Optional)
=item B<-queryfile> request.tsq
The name of the file containing a DER encoded time stamp request. (Optional)
=item B<-passin> password_src
Specifies the password source for the private key of the TSA. See
B<PASS PHRASE ARGUMENTS> in L<openssl(1)|openssl(1)>. (Optional)
=item B<-signer> 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 B<signer_cert>
variable of the config file. (Optional)
=item B<-inkey> private.pem
The signer private key of the TSA in PEM format. Overrides the
B<signer_key> config file option. (Optional)
=item B<-chain> certs_file.pem
The collection of certificates in PEM format that will all
be included in the response in addition to the signer certificate if
the B<-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 B<-reply> command does not build a certificate
chain automatically. (Optional)
=item B<-policy> 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
B<default_policy> config file option. (Optional)
=item B<-in> response.tsr
Specifies a previously created time stamp response or time stamp token
(if B<-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 e.g. 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
'granted' status info is added to the token. (Optional)
=item B<-token_in>
This flag can be used together with the B<-in> option and indicates
that the input is a DER encoded time stamp token (ContentInfo) instead
of a time stamp response (TimeStampResp). (Optional)
=item B<-out> response.tsr
The response is written to this file. The format and content of the
file depends on other options (see B<-text>, B<-token_out>). The default is
stdout. (Optional)
=item B<-token_out>
The output is a time stamp token (ContentInfo) instead of time stamp
response (TimeStampResp). (Optional)
=item B<-text>
If this option is specified the output is human-readable text format
instead of DER. (Optional)
=item B<-engine> id
Specifying an engine (by its unique B<id> string) will cause B<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. Default is builtin. (Optional)
=back
=head2 Time Stamp Response verification
The B<-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 B<-verify> command does not use the configuration file.
=over 4
=item B<-data> file_to_hash
The response or token must be verified against file_to_hash. The file
is hashed with the message digest algorithm specified in the token.
The B<-digest> and B<-queryfile> options must not be specified with this one.
(Optional)
=item B<-digest> 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 B<-data> and B<-queryfile> options must not be
specified with this one. (Optional)
=item B<-queryfile> request.tsq
The original time stamp request in DER format. The B<-data> and B<-digest>
options must not be specified with this one. (Optional)
=item B<-in> response.tsr
The time stamp response that needs to be verified in DER format. (Mandatory)
=item B<-token_in>
This flag can be used together with the B<-in> option and indicates
that the input is a DER encoded time stamp token (ContentInfo) instead
of a time stamp response (TimeStampResp). (Optional)
=item B<-CApath> trusted_cert_path
The name of the directory containing the trused CA certificates of the
client. See the similar option of L<verify(1)|verify(1)> for additional
details. Either this option or B<-CAfile> must be specified. (Optional)
=item B<-CAfile> 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
L<verify(1)|verify(1)> for additional details. Either this option
or B<-CApath> must be specified.
(Optional)
=item B<-untrusted> 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.
(Optional)
=back
=head1 CONFIGURATION FILE OPTIONS
The B<-query> and B<-reply> commands make use of a configuration file
defined by the B<OPENSSL_CONF> environment variable. See L<config(5)|config(5)>
for a general description of the syntax of the config file. The
B<-query> command uses only the symbolic OID names section
and it can work without it. However, the B<-reply> command needs the
config file for its operation.
When there is a command line switch equivalent of a variable the
switch always overrides the settings in the config file.
=over 4
=item B<tsa> section, B<default_tsa>
This is the main section and it specifies the name of another section
that contains all the options for the B<-reply> command. This default
section can be overridden with the B<-section> command line switch. (Optional)
=item B<oid_file>
See L<ca(1)|ca(1)> for description. (Optional)
=item B<oid_section>
See L<ca(1)|ca(1)> for description. (Optional)
=item B<RANDFILE>
See L<ca(1)|ca(1)> for description. (Optional)
=item B<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. (Mandatory)
=item B<crypto_device>
Specifies the OpenSSL engine that will be set as the default for
all available algorithms. The default value is builtin, you can specify
any other engines supported by OpenSSL (e.g. use chil for the NCipher HSM).
(Optional)
=item B<signer_cert>
TSA signing certificate in PEM format. The same as the B<-signer>
command line option. (Optional)
=item B<certs>
A file containing a set of PEM encoded certificates that need to be
included in the response. The same as the B<-chain> command line
option. (Optional)
=item B<signer_key>
The private key of the TSA in PEM format. The same as the B<-inkey>
command line option. (Optional)
=item B<default_policy>
The default policy to use when the request does not mandate any
policy. The same as the B<-policy> command line option. (Optional)
=item B<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. (Optional)
=item B<digests>
The list of message digest algorithms that the TSA accepts. At least
one algorithm must be specified. (Mandatory)
=item B<accuracy>
The accuracy of the time source of the TSA in seconds, milliseconds
and microseconds. E.g. secs:1, millisecs:500, microsecs:100. If any of
the components is missing zero is assumed for that field. (Optional)
=item B<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. Supported only on UNIX platforms.
The maximum value is 6, default is 0.
(Optional)
=item B<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. Default is no. (Optional)
=item B<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. Default is no. (Optional)
=item B<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 B<certs> variable or the B<-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. Default is no. (Optional)
=back
=head1 ENVIRONMENT VARIABLES
B<OPENSSL_CONF> contains the path of the configuration file and can be
overridden by the B<-config> command line option.
=head1 EXAMPLES
All the examples below presume that B<OPENSSL_CONF> is set to a proper
configuration file, e.g. the example configuration file
openssl/apps/openssl.cnf will do.
=head2 Time Stamp Request
To create a time stamp request for design1.txt with SHA-1
without nonce and policy and no certificate is required in the response:
openssl ts -query -data design1.txt -no_nonce \
-out design1.tsq
To create a similar time stamp request with specifying the message imprint
explicitly:
openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
-no_nonce -out design1.tsq
To print the content of the previous request in human readable format:
openssl ts -query -in design1.tsq -text
To create a time stamp request which includes the MD-5 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):
openssl ts -query -data design2.txt -md5 \
-policy tsa_policy1 -cert -out design2.tsq
=head2 Time Stamp Response
Before generating a response a signing certificate must be created for
the TSA that contains the B<timeStamping> critical extended key usage extension
without any other key usage extensions. You can add the
'extendedKeyUsage = critical,timeStamping' line to the user certificate section
of the config file to generate a proper certificate. See L<req(1)|req(1)>,
L<ca(1)|ca(1)>, L<x509(1)|x509(1)> 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.
To create a time stamp response for a request:
openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \
-signer tsacert.pem -out design1.tsr
If you want to use the settings in the config file you could just write:
openssl ts -reply -queryfile design1.tsq -out design1.tsr
To print a time stamp reply to stdout in human readable format:
openssl ts -reply -in design1.tsr -text
To create a time stamp token instead of time stamp response:
openssl ts -reply -queryfile design1.tsq -out design1_token.der -token_out
To print a time stamp token to stdout in human readable format:
openssl ts -reply -in design1_token.der -token_in -text -token_out
To extract the time stamp token from a response:
openssl ts -reply -in design1.tsr -out design1_token.der -token_out
To add 'granted' status info to a time stamp token thereby creating a
valid response:
openssl ts -reply -in design1_token.der -token_in -out design1.tsr
=head2 Time Stamp Verification
To verify a time stamp reply against a request:
openssl ts -verify -queryfile design1.tsq -in design1.tsr \
-CAfile cacert.pem -untrusted tsacert.pem
To verify a time stamp reply that includes the certificate chain:
openssl ts -verify -queryfile design2.tsq -in design2.tsr \
-CAfile cacert.pem
To verify a time stamp token against the original data file:
openssl ts -verify -data design2.txt -in design2.tsr \
-CAfile cacert.pem
To verify a time stamp token against a message imprint:
openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
-in design2.tsr -CAfile cacert.pem
You could also look at the 'test' directory for more examples.
=head1 BUGS
If you find any bugs or you have suggestions please write to
Zoltan Glozik <zglozik@opentsa.org>. Known issues:
=over 4
=item * No support for time stamps over SMTP, though it is quite easy
to implement an automatic e-mail based TSA with L<procmail(1)|procmail(1)>
and L<perl(1)|perl(1)>. HTTP server support is provided in the form of
a separate apache module. HTTP client support is provided by
L<tsget(1)|tsget(1)>. Pure TCP/IP protocol is not supported.
=item * 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 L<openssl(1)|openssl(1)> is trying to create a time stamp
response at the same time. This is not an issue when using the apache
server module, it does proper locking.
=item * Look for the FIXME word in the source files.
=item * The source code should really be reviewed by somebody else, too.
=item * More testing is needed, I have done only some basic tests (see
test/testtsa).
=back
=cut
=head1 AUTHOR
Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org)
=head1 SEE ALSO
L<tsget(1)|tsget(1)>, L<openssl(1)|openssl(1)>, L<req(1)|req(1)>,
L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
L<config(5)|config(5)>
=cut

194
doc/apps/tsget.pod Normal file
View File

@@ -0,0 +1,194 @@
=pod
=head1 NAME
tsget - Time Stamping HTTP/HTTPS client
=head1 SYNOPSIS
B<tsget>
B<-h> server_url
[B<-e> extension]
[B<-o> output]
[B<-v>]
[B<-d>]
[B<-k> private_key.pem]
[B<-p> key_password]
[B<-c> client_cert.pem]
[B<-C> CA_certs.pem]
[B<-P> CA_path]
[B<-r> file:file...]
[B<-g> EGD_socket]
[request]...
=head1 DESCRIPTION
The B<tsget> command can be used for sending a time stamp request, as
specified in B<RFC 3161>, to a time stamp server over HTTP or HTTPS and storing
the time stamp response in a file. This tool cannot be used for creating the
requests and verifying responses, you can use the OpenSSL B<ts(1)> command to
do that. B<tsget> can send several requests to the server without closing
the TCP connection if more than one requests are specified on the command
line.
The tool sends the following HTTP request for each time stamp request:
POST url HTTP/1.1
User-Agent: OpenTSA tsget.pl/<version>
Host: <host>:<port>
Pragma: no-cache
Content-Type: application/timestamp-query
Accept: application/timestamp-reply
Content-Length: length of body
...binary request specified by the user...
B<tsget> expects a response of type application/timestamp-reply, which is
written to a file without any interpretation.
=head1 OPTIONS
=over 4
=item B<-h> server_url
The URL of the HTTP/HTTPS server listening for time stamp requests.
=item B<-e> extension
If the B<-o> option is not given this argument specifies the extension of the
output files. The base name of the output file will be the same as those of
the input files. Default extension is '.tsr'. (Optional)
=item B<-o> output
This option can be specified only when just one request is sent to the
server. The time stamp response will be written to the given output file. '-'
means standard output. In case of multiple time stamp requests or the absence
of this argument the names of the output files will be derived from the names
of the input files and the default or specified extension argument. (Optional)
=item B<-v>
The name of the currently processed request is printed on standard
error. (Optional)
=item B<-d>
Switches on verbose mode for the underlying B<curl> library. You can see
detailed debug messages for the connection. (Optional)
=item B<-k> private_key.pem
(HTTPS) In case of certificate-based client authentication over HTTPS
<private_key.pem> must contain the private key of the user. The private key
file can optionally be protected by a passphrase. The B<-c> option must also
be specified. (Optional)
=item B<-p> key_password
(HTTPS) Specifies the passphrase for the private key specified by the B<-k>
argument. If this option is omitted and the key is passphrase protected B<tsget>
will ask for it. (Optional)
=item B<-c> client_cert.pem
(HTTPS) In case of certificate-based client authentication over HTTPS
<client_cert.pem> must contain the X.509 certificate of the user. The B<-k>
option must also be specified. If this option is not specified no
certificate-based client authentication will take place. (Optional)
=item B<-C> CA_certs.pem
(HTTPS) The trusted CA certificate store. The certificate chain of the peer's
certificate must include one of the CA certificates specified in this file.
Either option B<-C> or option B<-P> must be given in case of HTTPS. (Optional)
=item B<-P> CA_path
(HTTPS) The path containing the trusted CA certificates to verify the peer's
certificate. The directory must be prepared with the B<c_rehash>
OpenSSL utility. Either option B<-C> or option B<-P> must be given in case of
HTTPS. (Optional)
=item B<-rand> file:file...
The files containing random data for seeding the random number
generator. Multiple files can be specified, the separator is B<;> for
MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional)
=item B<-g> EGD_socket
The name of an EGD socket to get random data from. (Optional)
=item [request]...
List of files containing B<RFC 3161> DER-encoded time stamp requests. If no
requests are specified only one request will be sent to the server and it will be
read from the standard input. (Optional)
=back
=head1 ENVIRONMENT VARIABLES
The B<TSGET> environment variable can optionally contain default
arguments. The content of this variable is added to the list of command line
arguments.
=head1 EXAMPLES
The examples below presume that B<file1.tsq> and B<file2.tsq> contain valid
time stamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests
and at port 8443 for HTTPS requests, the TSA service is available at the /tsa
absolute path.
Get a time stamp response for file1.tsq over HTTP, output is written to
file1.tsr:
tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq
Get a time stamp response for file1.tsq and file2.tsq over HTTP showing
progress, output is written to file1.reply and file2.reply respectively:
tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \
file1.tsq file2.tsq
Create a time stamp request, write it to file3.tsq, send it to the server and
write the response to file3.tsr:
openssl ts -query -data file3.txt -cert | tee file3.tsq \
| tsget -h http://tsa.opentsa.org:8080/tsa \
-o file3.tsr
Get a time stamp response for file1.tsq over HTTPS without client
authentication:
tsget -h https://tsa.opentsa.org:8443/tsa \
-C cacerts.pem file1.tsq
Get a time stamp response for file1.tsq over HTTPS with certificate-based
client authentication (it will ask for the passphrase if client_key.pem is
protected):
tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \
-k client_key.pem -c client_cert.pem file1.tsq
You can shorten the previous command line if you make use of the B<TSGET>
environment variable. The following commands do the same as the previous
example:
TSGET='-h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \
-k client_key.pem -c client_cert.pem'
export TSGET
tsget file1.tsq
=head1 AUTHOR
Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org)
=head1 SEE ALSO
L<openssl(1)|openssl(1)>, L<ts(1)|ts(1)>, L<curl(1)|curl(1)>,
B<RFC 3161>
=cut

457
doc/apps/verify.pod Normal file
View File

@@ -0,0 +1,457 @@
=pod
=head1 NAME
verify - Utility to verify certificates.
=head1 SYNOPSIS
B<openssl> B<verify>
[B<-CApath directory>]
[B<-CAfile file>]
[B<-purpose purpose>]
[B<-policy arg>]
[B<-ignore_critical>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crlfile file>]
[B<-crl_download>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-policy_check>]
[B<-explicit_policy>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-x509_strict>]
[B<-extended_crl>]
[B<-use_deltas>]
[B<-policy_print>]
[B<-no_alt_chains>]
[B<-allow_proxy_certs>]
[B<-untrusted file>]
[B<-help>]
[B<-issuer_checks>]
[B<-trusted file>]
[B<-verbose>]
[B<->]
[certificates]
=head1 DESCRIPTION
The B<verify> command verifies certificate chains.
=head1 COMMAND OPTIONS
=over 4
=item B<-CApath directory>
A directory of trusted certificates. The certificates should have names
of the form: hash.0 or have symbolic links to them of this
form ("hash" is the hashed certificate subject name: see the B<-hash> option
of the B<x509> utility). Under Unix the B<c_rehash> script will automatically
create symbolic links to a directory of certificates.
=item B<-CAfile file>
A file of trusted certificates. The file should contain multiple certificates
in PEM format concatenated together.
=item B<-attime timestamp>
Perform validation checks using time specified by B<timestamp> and not
current system time. B<timestamp> is the number of seconds since
01.01.1970 (UNIX time).
=item B<-check_ss_sig>
Verify the signature on the self-signed root CA. This is disabled by default
because it doesn't add any security.
=item B<-crlfile file>
File containing one or more CRL's (in PEM format) to load.
=item B<-crl_download>
Attempt to download CRL information for this certificate.
=item B<-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.
=item B<-untrusted file>
A file of untrusted certificates. The file should contain multiple certificates
in PEM format concatenated together.
=item B<-purpose purpose>
The intended use for the certificate. If this option is not specified,
B<verify> will not consider certificate purpose during chain verification.
Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> section for more
information.
=item B<-help>
Print out a usage message.
=item B<-verbose>
Print extra information about the operations being performed.
=item B<-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. The presence of rejection messages does not itself imply that
anything is wrong; during the normal verification process, several
rejections may take place.
=item B<-policy arg>
Enable policy processing and add B<arg> to the user-initial-policy-set (see
RFC5280). The policy B<arg> can be an object name an OID in numeric form.
This argument can appear more than once.
=item B<-policy_check>
Enables certificate policy processing.
=item B<-explicit_policy>
Set policy variable require-explicit-policy (see RFC5280).
=item B<-inhibit_any>
Set policy variable inhibit-any-policy (see RFC5280).
=item B<-inhibit_map>
Set policy variable inhibit-policy-mapping (see RFC5280).
=item B<-no_alt_chains>
When building a certificate chain, if the first certificate chain found is not
trusted, then OpenSSL will continue to check to see if an alternative chain can
be found that is trusted. With this option that behaviour is suppressed so that
only the first chain found is ever used. Using this option will force the
behaviour to match that of previous OpenSSL versions.
=item B<-allow_proxy_certs>
Allow the verification of proxy certificates.
=item B<-trusted file>
A file of additional trusted certificates. The file should contain multiple
certificates in PEM format concatenated together.
=item B<-policy_print>
Print out diagnostics related to policy processing.
=item B<-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.
=item B<-crl_check_all>
Checks the validity of B<all> certificates in the chain by attempting
to look up valid CRLs.
=item B<-ignore_critical>
Normally if an unhandled critical extension is present which is not
supported by OpenSSL the certificate is rejected (as required by RFC5280).
If this option is set critical extensions are ignored.
=item B<-x509_strict>
For strict X.509 compliance, disable non-compliant workarounds for broken
certificates.
=item B<-extended_crl>
Enable extended CRL features such as indirect CRLs and alternate CRL
signing keys.
=item B<-use_deltas>
Enable support for delta CRLs.
=item B<-check_ss_sig>
Verify the signature on the self-signed root CA. This is disabled by default
because it doesn't add any security.
=item B<->
Indicates the last option. All arguments following this are assumed to be
certificate files. This is useful if the first certificate filename begins
with a B<->.
=item B<certificates>
One or more certificates to verify. If no certificates are given, B<verify>
will attempt to read a certificate from standard input. Certificates must be
in PEM format.
=back
=head1 VERIFY OPERATION
The B<verify> program uses the same functions as the internal SSL and S/MIME
verification, therefore this description applies to these verify operations
too.
There is one crucial difference between the verify operations performed
by the B<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.
The verify operation consists of a number of separate steps.
Firstly a certificate chain is built up starting from the supplied certificate
and ending in the root CA. It is an error if the whole chain cannot be built
up. The chain is built up by looking up the issuers certificate of the current
certificate. If a certificate is found which is its own issuer it is assumed
to be the root CA.
The process of 'looking up the issuers certificate' itself involves a number
of steps. In versions of OpenSSL before 0.9.5a the first certificate whose
subject name matched the issuer of the current certificate was assumed to be
the issuers certificate. In OpenSSL 0.9.6 and later all certificates
whose subject name matches the issuer name of the current certificate are
subject to further tests. The relevant authority key identifier components
of the current certificate (if present) must match the subject key identifier
(if present) and issuer and serial number of the candidate issuer, in addition
the keyUsage extension of the candidate issuer (if present) must permit
certificate signing.
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.
The second operation is to check every untrusted certificate's extensions for
consistency with the supplied purpose. If the B<-purpose> option is not included
then no checks are done. The supplied or "leaf" certificate must have extensions
compatible with the supplied purpose and all other certificates must also be valid
CA certificates. The precise extensions required are described in more detail in
the B<CERTIFICATE EXTENSIONS> section of the B<x509> utility.
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 SSLeay and OpenSSL a certificate with no trust settings is considered
to be valid for all purposes.
The final operation is to check the validity of the certificate chain. The validity
period is checked against the current system time and the notBefore and notAfter
dates in the certificate. The certificate signatures are also checked at this
point.
If all operations complete successfully then certificate is considered valid. If
any operation fails then the certificate is not valid.
=head1 DIAGNOSTICS
When a verify operation fails the output messages can be somewhat cryptic. The
general form of the error message is:
server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit)
error 24 at 1 depth lookup:invalid CA certificate
The first line contains the name of the certificate being verified followed by
the subject name of the certificate. The second line contains the error number
and the depth. The depth is number of the certificate being verified when a
problem was detected starting with zero for the certificate being verified itself
then 1 for the CA that signed the certificate and so on. Finally a text version
of the error number is presented.
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 x509_vfy.h
Some of the error codes are defined but never returned: these are described
as "unused".
=over 4
=item B<0 X509_V_OK: ok>
the operation was successful.
=item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
the issuer certificate of a looked up certificate could not be found. This
normally means the list of trusted certificates is not complete.
=item B<3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
the CRL of a certificate could not be found.
=item B<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.
=item B<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.
=item B<6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key>
the public key in the certificate SubjectPublicKeyInfo could not be read.
=item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
the signature of the certificate is invalid.
=item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
the signature of the certificate is invalid.
=item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
the certificate is not yet valid: the notBefore date is after the current time.
=item B<10 X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired>
the certificate has expired: that is the notAfter date is before the current time.
=item B<11 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
the CRL is not yet valid.
=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
the CRL has expired.
=item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
the certificate notBefore field contains an invalid time.
=item B<14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field>
the certificate notAfter field contains an invalid time.
=item B<15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field>
the CRL lastUpdate field contains an invalid time.
=item B<16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field>
the CRL nextUpdate field contains an invalid time.
=item B<17 X509_V_ERR_OUT_OF_MEM: out of memory>
an error occurred trying to allocate memory. This should never happen.
=item B<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.
=item B<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.
=item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
the issuer certificate could not be found: this occurs if the issuer
certificate of an untrusted certificate cannot be found.
=item B<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.
=item B<22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
the certificate chain length is greater than the supplied maximum depth. Unused.
=item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked>
the certificate has been revoked.
=item B<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.
=item B<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
the basicConstraints pathlength parameter has been exceeded.
=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
the supplied certificate cannot be used for the specified purpose.
=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
the root CA is not marked as trusted for the specified purpose.
=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected>
the root CA is marked to reject the specified purpose.
=item B<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 B<-issuer_checks> option is set.
=item B<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 B<-issuer_checks> option is set.
=item B<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 was present and did not match the authority key identifier
of the current certificate. Only displayed when the B<-issuer_checks> option is set.
=item B<32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing>
the current candidate issuer certificate was rejected because its keyUsage extension
does not permit certificate signing.
=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
an application specific error. Unused.
=back
=head1 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
B<-CAfile> option) or a directory (as specified by B<-CApath>. If they occur in both then only
the certificates in the file will be recognised.
Previous versions of OpenSSL assume certificates with matching subject name are identical and
mishandled them.
Previous versions of this documentation swapped the meaning of the
B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
=head1 SEE ALSO
L<x509(1)|x509(1)>
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
=cut

65
doc/apps/version.pod Normal file
View File

@@ -0,0 +1,65 @@
=pod
=head1 NAME
version - print OpenSSL version information
=head1 SYNOPSIS
B<openssl version>
[B<-a>]
[B<-v>]
[B<-b>]
[B<-o>]
[B<-f>]
[B<-p>]
[B<-d>]
=head1 DESCRIPTION
This command is used to print out version information about OpenSSL.
=head1 OPTIONS
=over 4
=item B<-a>
all information, this is the same as setting all the other flags.
=item B<-v>
the current OpenSSL version.
=item B<-b>
the date the current version of OpenSSL was built.
=item B<-o>
option information: various options set when the library was built.
=item B<-f>
compilation flags.
=item B<-p>
platform setting.
=item B<-d>
OPENSSLDIR setting.
=back
=head1 NOTES
The output of B<openssl version -a> would typically be used when sending
in a bug report.
=head1 HISTORY
The B<-d> option was added in OpenSSL 0.9.7.
=cut

890
doc/apps/x509.pod Normal file
View File

@@ -0,0 +1,890 @@
=pod
=head1 NAME
x509 - Certificate display and signing utility
=head1 SYNOPSIS
B<openssl> B<x509>
[B<-inform DER|PEM|NET>]
[B<-outform DER|PEM|NET>]
[B<-keyform DER|PEM>]
[B<-CAform DER|PEM>]
[B<-CAkeyform DER|PEM>]
[B<-in filename>]
[B<-out filename>]
[B<-serial>]
[B<-hash>]
[B<-subject_hash>]
[B<-issuer_hash>]
[B<-ocspid>]
[B<-subject>]
[B<-issuer>]
[B<-nameopt option>]
[B<-email>]
[B<-ocsp_uri>]
[B<-startdate>]
[B<-enddate>]
[B<-purpose>]
[B<-dates>]
[B<-checkend num>]
[B<-modulus>]
[B<-pubkey>]
[B<-fingerprint>]
[B<-alias>]
[B<-noout>]
[B<-trustout>]
[B<-clrtrust>]
[B<-clrreject>]
[B<-addtrust arg>]
[B<-addreject arg>]
[B<-setalias arg>]
[B<-days arg>]
[B<-set_serial n>]
[B<-signkey filename>]
[B<-passin arg>]
[B<-x509toreq>]
[B<-req>]
[B<-CA filename>]
[B<-CAkey filename>]
[B<-CAcreateserial>]
[B<-CAserial filename>]
[B<-force_pubkey key>]
[B<-text>]
[B<-certopt option>]
[B<-C>]
[B<-md2|-md5|-sha1|-mdc2>]
[B<-clrext>]
[B<-extfile filename>]
[B<-extensions section>]
[B<-engine id>]
=head1 DESCRIPTION
The B<x509> command is a multi purpose certificate utility. It can be
used to display certificate information, convert certificates to
various forms, sign certificate requests like a "mini CA" or edit
certificate trust settings.
Since there are a large number of options they will split up into
various sections.
=head1 OPTIONS
=head2 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
=over 4
=item B<-inform DER|PEM|NET>
This specifies the input format normally the command will expect an X509
certificate but this can change if other options such as B<-req> are
present. The DER format is the DER encoding of the certificate and PEM
is the base64 encoding of the DER encoding with header and footer lines
added. The NET option is an obscure Netscape server format that is now
obsolete.
=item B<-outform DER|PEM|NET>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
This specifies the input filename to read a certificate from or standard input
if this option is not specified.
=item B<-out filename>
This specifies the output filename to write to or standard output by
default.
=item B<-md2|-md5|-sha1|-mdc2>
the digest to use. This affects any signing or display option that uses a message
digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. If not
specified then SHA1 is used. If the key being used to sign with is a DSA key
then this option has no effect: SHA1 is always used with DSA keys.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<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.
=back
=head2 DISPLAY OPTIONS
Note: the B<-alias> and B<-purpose> options are also display options
but are described in the B<TRUST SETTINGS> section.
=over 4
=item B<-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.
=item B<-certopt option>
customise the output format used with B<-text>. The B<option> argument can be
a single option or multiple options separated by commas. The B<-certopt> switch
may be also be used more than once to set multiple options. See the B<TEXT OPTIONS>
section for more information.
=item B<-noout>
this option prevents output of the encoded version of the request.
=item B<-pubkey>
outputs the the certificate's SubjectPublicKeyInfo block in PEM format.
=item B<-modulus>
this option prints out the value of the modulus of the public key
contained in the certificate.
=item B<-serial>
outputs the certificate serial number.
=item B<-subject_hash>
outputs the "hash" of the certificate subject name. This is used in OpenSSL to
form an index to allow certificates in a directory to be looked up by subject
name.
=item B<-issuer_hash>
outputs the "hash" of the certificate issuer name.
=item B<-ocspid>
outputs the OCSP hash values for the subject name and public key.
=item B<-hash>
synonym for "-subject_hash" for backward compatibility reasons.
=item B<-subject_hash_old>
outputs the "hash" of the certificate subject name using the older algorithm
as used by OpenSSL versions before 1.0.0.
=item B<-issuer_hash_old>
outputs the "hash" of the certificate issuer name using the older algorithm
as used by OpenSSL versions before 1.0.0.
=item B<-subject>
outputs the subject name.
=item B<-issuer>
outputs the issuer name.
=item B<-nameopt option>
option which determines how the subject or issuer names are displayed. The
B<option> argument can be a single option or multiple options separated by
commas. Alternatively the B<-nameopt> switch may be used more than once to
set multiple options. See the B<NAME OPTIONS> section for more information.
=item B<-email>
outputs the email address(es) if any.
=item B<-ocsp_uri>
outputs the OCSP responder address(es) if any.
=item B<-startdate>
prints out the start date of the certificate, that is the notBefore date.
=item B<-enddate>
prints out the expiry date of the certificate, that is the notAfter date.
=item B<-dates>
prints out the start and expiry dates of a certificate.
=item B<-checkend arg>
checks if the certificate expires within the next B<arg> seconds and exits
non-zero if yes it will expire or zero if not.
=item B<-fingerprint>
prints out the digest of the DER encoded version of the whole certificate
(see digest options).
=item B<-C>
this outputs the certificate in the form of a C source file.
=back
=head2 TRUST SETTINGS
Please note these options are currently experimental and may well change.
A B<trusted certificate> is an ordinary certificate which has several
additional pieces of information attached to it such as the permitted
and prohibited uses of the certificate and an "alias".
Normally when a certificate is being verified at least one certificate
must be "trusted". By default a trusted certificate must be stored
locally and must be a root CA: any certificate chain ending in this CA
is then usable for any purpose.
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 SSL client but not SSL server use.
See the description of the B<verify> utility for more information on the
meaning of trust settings.
Future versions of OpenSSL will recognize trust settings on any
certificate: not just root CAs.
=over 4
=item B<-trustout>
this causes B<x509> to output a B<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
B<-trustout> option a trusted certificate is output. A trusted
certificate is automatically output if any trust settings are modified.
=item B<-setalias arg>
sets the alias of the certificate. This will allow the certificate
to be referred to using a nickname for example "Steve's Certificate".
=item B<-alias>
outputs the certificate alias, if any.
=item B<-clrtrust>
clears all the permitted or trusted uses of the certificate.
=item B<-clrreject>
clears all the prohibited or rejected uses of the certificate.
=item B<-addtrust arg>
adds a trusted certificate use. Any object name can be used here
but currently only B<clientAuth> (SSL client use), B<serverAuth>
(SSL server use) and B<emailProtection> (S/MIME email) are used.
Other OpenSSL applications may define additional uses.
=item B<-addreject arg>
adds a prohibited use. It accepts the same values as the B<-addtrust>
option.
=item B<-purpose>
this option performs tests on the certificate extensions and outputs
the results. For a more complete description see the B<CERTIFICATE
EXTENSIONS> section.
=back
=head2 SIGNING OPTIONS
The B<x509> utility can be used to sign certificates and requests: it
can thus behave like a "mini CA".
=over 4
=item B<-signkey filename>
this option causes the input file to be self signed using the supplied
private key.
If the input file is a certificate it sets the issuer name to the
subject name (i.e. makes it self signed) changes the public key to the
supplied value and changes the start and end dates. The start date is
set to the current time and the end date is set to a value determined
by the B<-days> option. Any certificate extensions are retained unless
the B<-clrext> option is supplied.
If the input is a certificate request then a self signed certificate
is created using the supplied private key using the subject name in
the request.
=item B<-passin arg>
the key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-clrext>
delete any extensions from a certificate. This option is used when a
certificate is being created from another certificate (for example with
the B<-signkey> or the B<-CA> options). Normally all extensions are
retained.
=item B<-keyform PEM|DER>
specifies the format (DER or PEM) of the private key file used in the
B<-signkey> option.
=item B<-days arg>
specifies the number of days to make a certificate valid for. The default
is 30 days.
=item B<-x509toreq>
converts a certificate into a certificate request. The B<-signkey> option
is used to pass the required private key.
=item B<-req>
by default a certificate is expected on input. With this option a
certificate request is expected instead.
=item B<-set_serial n>
specifies the serial number to use. This option can be used with either
the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA>
option the serial number file (as specified by the B<-CAserial> or
B<-CAcreateserial> options) is not used.
The serial number can be decimal or hex (if preceded by B<0x>). Negative
serial numbers can also be specified but their use is not recommended.
=item B<-CA filename>
specifies the CA certificate to be used for signing. When this option is
present B<x509> behaves like a "mini CA". The input file is signed by this
CA using this option: that is its issuer name is set to the subject name
of the CA and it is digitally signed using the CAs private key.
This option is normally combined with the B<-req> option. Without the
B<-req> option the input is a certificate which must be self signed.
=item B<-CAkey filename>
sets the CA private key to sign a certificate with. If this option is
not specified then it is assumed that the CA private key is present in
the CA certificate file.
=item B<-CAserial filename>
sets the CA serial number file to use.
When the B<-CA> option is used to sign a certificate it uses a serial
number specified in a file. This file consist of one line containing
an even number of hex digits with the serial number to use. After each
use the serial number is incremented and written out to the file again.
The default filename consists of the CA certificate file base name with
".srl" appended. For example if the CA certificate file is called
"mycacert.pem" it expects to find a serial number file called "mycacert.srl".
=item B<-CAcreateserial>
with this option the CA serial number file is created if it does not exist:
it will contain the serial number "02" and the certificate being signed will
have the 1 as its serial number. Normally if the B<-CA> option is specified
and the serial number file does not exist it is an error.
=item B<-extfile filename>
file containing certificate extensions to use. If not specified then
no extensions are added to the certificate.
=item B<-extensions section>
the section to add certificate extensions from. If this option is not
specified then the extensions should either be contained in the unnamed
(default) section or the default section should contain a variable called
"extensions" which contains the section to use. See the
L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
extension section format.
=item B<-force_pubkey key>
when a certificate is created set its public key to B<key> instead of the
key in the certificate or certificate request. This option is useful for
creating certificates where the algorithm can't normally sign requests, for
example DH.
The format or B<key> can be specified using the B<-keyform> option.
=back
=head2 NAME OPTIONS
The B<nameopt> command line switch determines how the subject and issuer
names are displayed. If no B<nameopt> switch is present the default "oneline"
format is used which is compatible with previous versions of OpenSSL.
Each option is described in detail below, all options can be preceded by
a B<-> to turn the option off. Only the first four will normally be used.
=over 4
=item B<compat>
use the old format. This is equivalent to specifying no name options at all.
=item B<RFC2253>
displays names compatible with RFC2253 equivalent to B<esc_2253>, B<esc_ctrl>,
B<esc_msb>, B<utf8>, B<dump_nostr>, B<dump_unknown>, B<dump_der>,
B<sep_comma_plus>, B<dn_rev> and B<sname>.
=item B<oneline>
a oneline format which is more readable than RFC2253. It is equivalent to
specifying the B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>,
B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, B<space_eq> and B<sname>
options.
=item B<multiline>
a multiline format. It is equivalent B<esc_ctrl>, B<esc_msb>, B<sep_multiline>,
B<space_eq>, B<lname> and B<align>.
=item B<esc_2253>
escape the "special" characters required by RFC2253 in a field That is
B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginning of a string
and a space character at the beginning or end of a string.
=item B<esc_ctrl>
escape control characters. That is those with ASCII values less than
0x20 (space) and the delete (0x7f) character. They are escaped using the
RFC2253 \XX notation (where XX are two hex digits representing the
character value).
=item B<esc_msb>
escape characters with the MSB set, that is with ASCII values larger than
127.
=item B<use_quote>
escapes some characters by surrounding the whole string with B<"> characters,
without the option all escaping is done with the B<\> character.
=item B<utf8>
convert all strings to UTF8 format first. This is required by RFC2253. If
you are lucky enough to have a UTF8 compatible terminal then the use
of this option (and B<not> setting B<esc_msb>) may result in the correct
display of multibyte (international) characters. Is this option is not
present then multibyte characters larger than 0xff will be represented
using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits.
Also if this option is off any UTF8Strings will be converted to their
character form first.
=item B<ignore_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.
=item B<show_type>
show the type of the ASN1 character string. The type precedes the
field contents. For example "BMPSTRING: Hello World".
=item B<dump_der>
when this option is set any fields that need to be hexdumped will
be dumped using the DER encoding of the field. Otherwise just the
content octets will be displayed. Both options use the RFC2253
B<#XXXX...> format.
=item B<dump_nostr>
dump non character string types (for example OCTET STRING) if this
option is not set then non character string types will be displayed
as though each content octet represents a single character.
=item B<dump_all>
dump all fields. This option when used with B<dump_der> allows the
DER encoding of the structure to be unambiguously determined.
=item B<dump_unknown>
dump any field whose OID is not recognised by OpenSSL.
=item B<sep_comma_plus>, B<sep_comma_plus_space>, B<sep_semi_plus_space>,
B<sep_multiline>
these options determine the field separators. The first character is
between RDNs and the second between multiple AVAs (multiple AVAs are
very rare and their use is discouraged). The options ending in
"space" additionally place a space after the separator to make it
more readable. The B<sep_multiline> uses a linefeed character for
the RDN separator and a spaced B<+> for the AVA separator. It also
indents the fields by four characters. If no field separator is specified
then B<sep_comma_plus_space> is used by default.
=item B<dn_rev>
reverse the fields of the DN. This is required by RFC2253. As a side
effect this also reverses the order of multiple AVAs but this is
permissible.
=item B<nofname>, B<sname>, B<lname>, B<oid>
these options alter how the field name is displayed. B<nofname> does
not display the field at all. B<sname> uses the "short name" form
(CN for commonName for example). B<lname> uses the long form.
B<oid> represents the OID in numerical form and is useful for
diagnostic purpose.
=item B<align>
align field values for a more readable output. Only usable with
B<sep_multiline>.
=item B<space_eq>
places spaces round the B<=> character which follows the field
name.
=back
=head2 TEXT OPTIONS
As well as customising the name output format, it is also possible to
customise the actual fields printed using the B<certopt> options when
the B<text> option is present. The default behaviour is to print all fields.
=over 4
=item B<compatible>
use the old format. This is equivalent to specifying no output options at all.
=item B<no_header>
don't print header information: that is the lines saying "Certificate" and "Data".
=item B<no_version>
don't print out the version number.
=item B<no_serial>
don't print out the serial number.
=item B<no_signame>
don't print out the signature algorithm used.
=item B<no_validity>
don't print the validity, that is the B<notBefore> and B<notAfter> fields.
=item B<no_subject>
don't print out the subject name.
=item B<no_issuer>
don't print out the issuer name.
=item B<no_pubkey>
don't print out the public key.
=item B<no_sigdump>
don't give a hexadecimal dump of the certificate signature.
=item B<no_aux>
don't print out certificate trust information.
=item B<no_extensions>
don't print out any X509V3 extensions.
=item B<ext_default>
retain default extension behaviour: attempt to print out unsupported certificate extensions.
=item B<ext_error>
print an error message for unsupported certificate extensions.
=item B<ext_parse>
ASN1 parse unsupported extensions.
=item B<ext_dump>
hex dump unsupported extensions.
=item B<ca_default>
the value used by the B<ca> utility, equivalent to B<no_issuer>, B<no_pubkey>,
B<no_header>, and B<no_version>.
=back
=head1 EXAMPLES
Note: in these examples the '\' means the example should be all on one
line.
Display the contents of a certificate:
openssl x509 -in cert.pem -noout -text
Display the certificate serial number:
openssl x509 -in cert.pem -noout -serial
Display the certificate subject name:
openssl x509 -in cert.pem -noout -subject
Display the certificate subject name in RFC2253 form:
openssl x509 -in cert.pem -noout -subject -nameopt RFC2253
Display the certificate subject name in oneline form on a terminal
supporting UTF8:
openssl x509 -in cert.pem -noout -subject -nameopt oneline,-esc_msb
Display the certificate MD5 fingerprint:
openssl x509 -in cert.pem -noout -fingerprint
Display the certificate SHA1 fingerprint:
openssl x509 -sha1 -in cert.pem -noout -fingerprint
Convert a certificate from PEM to DER format:
openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
Convert a certificate to a certificate request:
openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
Convert a certificate request into a self signed certificate using
extensions for a CA:
openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
-signkey key.pem -out cacert.pem
Sign a certificate request using the CA certificate above and add user
certificate extensions:
openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
-CA cacert.pem -CAkey key.pem -CAcreateserial
Set a certificate to be trusted for SSL client use and change set its alias to
"Steve's Class 1 CA"
openssl x509 -in cert.pem -addtrust clientAuth \
-setalias "Steve's Class 1 CA" -out trust.pem
=head1 NOTES
The PEM format uses the header and footer lines:
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
it will also handle files containing:
-----BEGIN X509 CERTIFICATE-----
-----END X509 CERTIFICATE-----
Trusted certificates have the lines
-----BEGIN TRUSTED CERTIFICATE-----
-----END TRUSTED CERTIFICATE-----
The conversion to UTF8 format used with the name options assumes that
T61Strings use the ISO8859-1 character set. This is wrong but Netscape
and MSIE do this as do many certificates. So although this is incorrect
it is more likely to display the majority of certificates correctly.
The B<-fingerprint> option takes the digest of the DER encoded certificate.
This is commonly called a "fingerprint". Because of the nature of message
digests the fingerprint of a certificate is unique to that certificate and
two certificates with the same fingerprint can be considered to be the same.
The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
The B<-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.
=head1 CERTIFICATE EXTENSIONS
The B<-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.
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.
The basicConstraints extension CA flag is used to determine whether the
certificate can be used as a CA. If the CA flag is true then it is a CA,
if the CA flag is false then it is not a CA. B<All> CAs should have the
CA flag set to true.
If the basicConstraints extension is absent then the certificate is
considered to be a "possible CA" other extensions are checked according
to the intended use of the certificate. A warning is given in this case
because the certificate should really not be regarded as a CA: however
it is allowed to be a CA to work around some broken software.
If the certificate is a V1 certificate (and thus has no extensions) and
it is self signed it is also assumed to be a CA but a warning is again
given: this is to work around the problem of Verisign roots which are V1
self signed certificates.
If the keyUsage extension is present then additional restraints are
made on the uses of the certificate. A CA certificate B<must> have the
keyCertSign bit set if the keyUsage extension is present.
The extended key usage extension places additional restrictions on the
certificate uses. If this extension is present (whether critical or not)
the key can only be used for the purposes specified.
A complete description of each test is given below. The comments about
basicConstraints and keyUsage and V1 certificates above apply to B<all>
CA certificates.
=over 4
=item B<SSL Client>
The extended key usage extension must be absent or include the "web client
authentication" OID. keyUsage must be absent or it must have the
digitalSignature bit set. Netscape certificate type must be absent or it must
have the SSL client bit set.
=item B<SSL Client CA>
The extended key usage extension must be absent or include the "web client
authentication" OID. Netscape certificate type must be absent or it must have
the SSL CA bit set: this is used as a work around if the basicConstraints
extension is absent.
=item B<SSL Server>
The extended key usage extension must be absent or include the "web server
authentication" and/or one of the SGC OIDs. keyUsage must be absent or it
must have the digitalSignature, the keyEncipherment set or both bits set.
Netscape certificate type must be absent or have the SSL server bit set.
=item B<SSL Server CA>
The extended key usage extension must be absent or include the "web server
authentication" and/or one of the SGC OIDs. Netscape certificate type must
be absent or the SSL CA bit must be set: this is used as a work around if the
basicConstraints extension is absent.
=item B<Netscape SSL Server>
For Netscape SSL clients to connect to an SSL server it must have the
keyEncipherment bit set if the 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.
=item B<Common S/MIME Client Tests>
The extended key usage extension must be absent or include the "email
protection" OID. Netscape certificate type must be absent or should have the
S/MIME bit set. If the 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 S/MIME bit.
=item B<S/MIME Signing>
In addition to the common S/MIME client tests the digitalSignature bit must
be set if the keyUsage extension is present.
=item B<S/MIME Encryption>
In addition to the common S/MIME tests the keyEncipherment bit must be set
if the keyUsage extension is present.
=item B<S/MIME CA>
The extended key usage extension must be absent or include the "email
protection" OID. Netscape certificate type must be absent or must have the
S/MIME CA bit set: this is used as a work around if the basicConstraints
extension is absent.
=item B<CRL Signing>
The keyUsage extension must be absent or it must have the CRL signing bit
set.
=item B<CRL Signing CA>
The normal CA tests apply. Except in this case the basicConstraints extension
must be present.
=back
=head1 BUGS
Extensions in certificates are not transferred to certificate requests and
vice versa.
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.
There should be options to explicitly set such things as start and end
dates rather than an offset from the current time.
The code to implement the verify behaviour described in the B<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
OpenSSL 0.9.5 and later.
=head1 SEE ALSO
L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
L<gendsa(1)|gendsa(1)>, L<verify(1)|verify(1)>,
L<x509v3_config(5)|x509v3_config(5)>
=head1 HISTORY
Before OpenSSL 0.9.8, the default digest for RSA keys was MD5.
The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options
before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding
of the distinguished name. In 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 B<c_rehash> or similar.
=cut

529
doc/apps/x509v3_config.pod Normal file
View File

@@ -0,0 +1,529 @@
=pod
=for comment openssl_manual_section:5
=head1 NAME
x509v3_config - X509 V3 certificate extension configuration format
=head1 DESCRIPTION
Several of the OpenSSL utilities can add extensions to a certificate or
certificate request based on the contents of a configuration file.
Typically the application will contain an option to point to an extension
section. Each line of the extension section takes the form:
extension_name=[critical,] extension_options
If B<critical> is present then the extension will be critical.
The format of B<extension_options> depends on the value of B<extension_name>.
There are four main types of extension: I<string> extensions, I<multi-valued>
extensions, I<raw> and I<arbitrary> extensions.
String extensions simply have a string which contains either the value itself
or how it is obtained.
For example:
nsComment="This is a Comment"
Multi-valued extensions have a short form and a long form. The short form
is a list of names and values:
basicConstraints=critical,CA:true,pathlen:1
The long form allows the values to be placed in a separate section:
basicConstraints=critical,@bs_section
[bs_section]
CA=true
pathlen=1
Both forms are equivalent.
The syntax of raw extensions is governed by the extension code: it can
for example contain data in multiple sections. The correct syntax to
use is defined by the extension code itself: check out the certificate
policies extension for an example.
If an extension type is unsupported then the I<arbitrary> extension syntax
must be used, see the L<ARBITRARY EXTENSIONS|/"ARBITRARY EXTENSIONS"> section for more details.
=head1 STANDARD EXTENSIONS
The following sections describe each supported extension in detail.
=head2 Basic Constraints.
This is a multi valued extension which indicates whether a certificate is
a CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or
B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by an
non-negative value can be included.
For example:
basicConstraints=CA:TRUE
basicConstraints=CA:FALSE
basicConstraints=critical,CA:TRUE, pathlen:0
A CA certificate B<must> include the basicConstraints value with the CA field
set to TRUE. An end user certificate must either set CA to FALSE or exclude the
extension entirely. Some software may require the inclusion of basicConstraints
with CA set to FALSE for end entity certificates.
The pathlen parameter indicates the maximum number of CAs that can appear
below this one in a chain. So if you have a CA with a pathlen of zero it can
only be used to sign end user certificates and not further CAs.
=head2 Key Usage.
Key usage is a multi valued extension consisting of a list of names of the
permitted key usages.
The supporte names are: digitalSignature, nonRepudiation, keyEncipherment,
dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly
and decipherOnly.
Examples:
keyUsage=digitalSignature, nonRepudiation
keyUsage=critical, keyCertSign
=head2 Extended Key Usage.
This extensions consists of a list of usages indicating purposes for which
the certificate public key can be used for,
These can either be object short names or the dotted numerical form of OIDs.
While any OID can be used only certain values make sense. In particular the
following PKIX, NS and MS values are meaningful:
Value Meaning
----- -------
serverAuth SSL/TLS Web Server Authentication.
clientAuth SSL/TLS Web Client Authentication.
codeSigning Code signing.
emailProtection E-mail Protection (S/MIME).
timeStamping Trusted Timestamping
msCodeInd Microsoft Individual Code Signing (authenticode)
msCodeCom Microsoft Commercial Code Signing (authenticode)
msCTLSign Microsoft Trust List Signing
msSGC Microsoft Server Gated Crypto
msEFS Microsoft Encrypted File System
nsSGC Netscape Server Gated Crypto
Examples:
extendedKeyUsage=critical,codeSigning,1.2.3.4
extendedKeyUsage=nsSGC,msSGC
=head2 Subject Key Identifier.
This is really a string extension and can take two possible values. Either
the word B<hash> which will automatically follow the guidelines in RFC3280
or a hex string giving the extension value to include. The use of the hex
string is strongly discouraged.
Example:
subjectKeyIdentifier=hash
=head2 Authority Key Identifier.
The authority key identifier extension permits two options. keyid and issuer:
both can take the optional value "always".
If the keyid option is present an attempt is made to copy the subject key
identifier from the parent certificate. If the value "always" is present
then an error is returned if the option fails.
The issuer option copies the issuer and serial number from the issuer
certificate. This will only be done if the keyid option fails or
is not included unless the "always" flag will always include the value.
Example:
authorityKeyIdentifier=keyid,issuer
=head2 Subject Alternative Name.
The subject alternative name extension allows various literal values to be
included in the configuration file. These include B<email> (an email address)
B<URI> a uniform resource indicator, B<DNS> (a DNS domain name), B<RID> (a
registered ID: OBJECT IDENTIFIER), B<IP> (an IP address), B<dirName>
(a distinguished name) and otherName.
The email option include a special 'copy' value. This will automatically
include and email addresses contained in the certificate subject name in
the extension.
The IP address used in the B<IP> options can be in either IPv4 or IPv6 format.
The value of B<dirName> should point to a section containing the distinguished
name to use as a set of name value pairs. Multi values AVAs can be formed by
prefacing the name with a B<+> character.
otherName can include arbitrary data associated with an OID: the value
should be the OID followed by a semicolon and the content in standard
L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format.
Examples:
subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/
subjectAltName=IP:192.168.7.1
subjectAltName=IP:13::17
subjectAltName=email:my@other.address,RID:1.2.3.4
subjectAltName=otherName:1.2.3.4;UTF8:some other identifier
subjectAltName=dirName:dir_sect
[dir_sect]
C=UK
O=My Organization
OU=My Unit
CN=My Name
=head2 Issuer Alternative Name.
The issuer alternative name option supports all the literal options of
subject alternative name. It does B<not> support the email:copy option because
that would not make sense. It does support an additional issuer:copy option
that will copy all the subject alternative name values from the issuer
certificate (if possible).
Example:
issuserAltName = issuer:copy
=head2 Authority Info Access.
The authority information access extension gives details about how to access
certain information relating to the CA. Its syntax is accessOID;location
where I<location> has the same syntax as subject alternative name (except
that email:copy is not supported). accessOID can be any valid OID but only
certain values are meaningful, for example OCSP and caIssuers.
Example:
authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
=head2 CRL distribution points.
This is a multi-valued extension whose options can be either in name:value pair
using the same form as subject alternative name or a single value representing
a section name containing all the distribution point fields.
For a name:value pair a new DistributionPoint with the fullName field set to
the given value both the cRLissuer and reasons fields are omitted in this case.
In the single option case the section indicated contains values for each
field. In this section:
If the name is "fullname" the value field should contain the full name
of the distribution point in the same format as subject alternative name.
If the name is "relativename" then the value field should contain a section
name whose contents represent a DN fragment to be placed in this field.
The name "CRLIssuer" if present should contain a value for this field in
subject alternative name format.
If the name is "reasons" the value field should consist of a comma
separated field containing the reasons. Valid reasons are: "keyCompromise",
"CACompromise", "affiliationChanged", "superseded", "cessationOfOperation",
"certificateHold", "privilegeWithdrawn" and "AACompromise".
Simple examples:
crlDistributionPoints=URI:http://myhost.com/myca.crl
crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
Full distribution point example:
crlDistributionPoints=crldp1_section
[crldp1_section]
fullname=URI:http://myhost.com/myca.crl
CRLissuer=dirName:issuer_sect
reasons=keyCompromise, CACompromise
[issuer_sect]
C=UK
O=Organisation
CN=Some Name
=head2 Issuing Distribution Point
This extension should only appear in CRLs. It is a multi valued extension
whose syntax is similar to the "section" pointed to by the CRL distribution
points extension with a few differences.
The names "reasons" and "CRLissuer" are not recognized.
The name "onlysomereasons" is accepted which sets this field. The value is
in the same format as the CRL distribution point "reasons" field.
The names "onlyuser", "onlyCA", "onlyAA" and "indirectCRL" are also accepted
the values should be a boolean value (TRUE or FALSE) to indicate the value of
the corresponding field.
Example:
issuingDistributionPoint=critical, @idp_section
[idp_section]
fullname=URI:http://myhost.com/myca.crl
indirectCRL=TRUE
onlysomereasons=keyCompromise, CACompromise
[issuer_sect]
C=UK
O=Organisation
CN=Some Name
=head2 Certificate Policies.
This is a I<raw> extension. All the fields of this extension can be set by
using the appropriate syntax.
If you follow the PKIX recommendations and just using one OID then you just
include the value of that OID. Multiple OIDs can be set separated by commas,
for example:
certificatePolicies= 1.2.4.5, 1.1.3.4
If you wish to include qualifiers then the policy OID and qualifiers need to
be specified in a separate section: this is done by using the @section syntax
instead of a literal OID value.
The section referred to must include the policy OID using the name
policyIdentifier, cPSuri qualifiers can be included using the syntax:
CPS.nnn=value
userNotice qualifiers can be set using the syntax:
userNotice.nnn=@notice
The value of the userNotice qualifier is specified in the relevant section.
This section can include explicitText, organization and noticeNumbers
options. explicitText and organization are text strings, noticeNumbers is a
comma separated list of numbers. The organization and noticeNumbers options
(if included) must BOTH be present. If you use the userNotice option with IE5
then you need the 'ia5org' option at the top level to modify the encoding:
otherwise it will not be interpreted properly.
Example:
certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
[polsect]
policyIdentifier = 1.3.5.8
CPS.1="http://my.host.name/"
CPS.2="http://my.your.name/"
userNotice.1=@notice
[notice]
explicitText="Explicit Text Here"
organization="Organisation Name"
noticeNumbers=1,2,3,4
The B<ia5org> option changes the type of the I<organization> field. In RFC2459
it can only be of type DisplayText. In RFC3280 IA5Strring is also permissible.
Some software (for example some versions of MSIE) may require ia5org.
=head2 Policy Constraints
This is a multi-valued extension which consisting of the names
B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative intger
value. At least one component must be present.
Example:
policyConstraints = requireExplicitPolicy:3
=head2 Inhibit Any Policy
This is a string extension whose value must be a non negative integer.
Example:
inhibitAnyPolicy = 2
=head2 Name Constraints
The name constraints extension is a multi-valued extension. The name should
begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of
the name and the value follows the syntax of subjectAltName except email:copy
is not supported and the B<IP> form should consist of an IP addresses and
subnet mask separated by a B</>.
Examples:
nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
nameConstraints=permitted;email:.somedomain.com
nameConstraints=excluded;email:.com
=head2 OCSP No Check
The OCSP No Check extension is a string extension but its value is ignored.
Example:
noCheck = ignored
=head1 DEPRECATED EXTENSIONS
The following extensions are non standard, Netscape specific and largely
obsolete. Their use in new applications is discouraged.
=head2 Netscape String extensions.
Netscape Comment (B<nsComment>) is a string extension containing a comment
which will be displayed when the certificate is viewed in some browsers.
Example:
nsComment = "Some Random Comment"
Other supported extensions in this category are: B<nsBaseUrl>,
B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl>
and B<nsSslServerName>.
=head2 Netscape Certificate Type
This is a multi-valued extensions which consists of a list of flags to be
included. It was used to indicate the purposes for which a certificate could
be used. The basicConstraints, keyUsage and extended key usage extensions are
now used instead.
Acceptable values for nsCertType are: B<client>, B<server>, B<email>,
B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>.
=head1 ARBITRARY EXTENSIONS
If an extension is not supported by the OpenSSL code then it must be encoded
using the arbitrary extension format. It is also possible to use the arbitrary
format for supported extensions. Extreme care should be taken to ensure that
the data is formatted correctly for the given extension type.
There are two ways to encode arbitrary extensions.
The first way is to use the word ASN1 followed by the extension content
using the same syntax as L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>.
For example:
1.2.3.4=critical,ASN1:UTF8String:Some random data
1.2.3.4=ASN1:SEQUENCE:seq_sect
[seq_sect]
field1 = UTF8:field1
field2 = UTF8:field2
It is also possible to use the word DER to include the raw encoded data in any
extension.
1.2.3.4=critical,DER:01:02:03:04
1.2.3.4=DER:01020304
The value following DER is a hex dump of the DER encoding of the extension
Any extension can be placed in this form to override the default behaviour.
For example:
basicConstraints=critical,DER:00:01:02:03
=head1 WARNING
There is no guarantee that a specific implementation will process a given
extension. It may therefore be sometimes possible to use certificates for
purposes prohibited by their extensions because a specific application does
not recognize or honour the values of the relevant extensions.
The DER and ASN1 options should be used with caution. It is possible to create
totally invalid extensions if they are not used carefully.
=head1 NOTES
If an extension is multi-value and a field value must contain a comma the long
form must be used otherwise the comma would be misinterpreted as a field
separator. For example:
subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
will produce an error but the equivalent form:
subjectAltName=@subject_alt_section
[subject_alt_section]
subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
is valid.
Due to the behaviour of the OpenSSL B<conf> library the same field name
can only occur once in a section. This means that:
subjectAltName=@alt_section
[alt_section]
email=steve@here
email=steve@there
will only recognize the last value. This can be worked around by using the form:
[alt_section]
email.1=steve@here
email.2=steve@there
=head1 HISTORY
The X509v3 extension code was first added to OpenSSL 0.9.2.
Policy mappings, inhibit any policy and name constraints support was added in
OpenSSL 0.9.8
The B<directoryName> and B<otherName> option as well as the B<ASN1> option
for arbitrary extensions was added in OpenSSL 0.9.8
=head1 SEE ALSO
L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>,
L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>
=cut