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

Import OpenSSL 1.1.0f

Browse Source
This commit is contained in:
Steve Dower
2017-09-07 16:27:43 -07:00
committed by Steve Dower
parent ccd3ab4aff
commit f4b81cb7c9
3340 changed files with 325158 additions and 557542 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
doc/apps/CA.pl.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,19 +7,27 @@ 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>]
B<-?> |
B<-h> |
B<-help>
B<CA.pl>
B<-newcert> |
B<-newreq> |
B<-newreq-nodes> |
B<-xsign> |
B<-sign> |
B<-signCA> |
B<-signcert> |
B<-crl> |
B<-newca>
[B<-extra-cmd> extra-params]
B<CA.pl> B<-pkcs12> [B<-extra-pkcs12> extra-params] [B<certname>]
B<CA.pl> B<-verify> [B<-extra-verify> extra-params] B<certfile>...
B<CA.pl> B<-revoke> [B<-extra-ca> extra-params] B<certfile> [B<reason>]
=head1 DESCRIPTION
@@ -29,7 +36,7 @@ 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
=head1 OPTIONS
=over 4
@@ -41,15 +48,18 @@ prints a usage message.
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".
This argument invokes B<openssl req> command.
=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".
Executes B<openssl req> command below the hood.
=item B<-newreq-nodes>
is like B<-newreq> except that the private key will not be encrypted.
Uses B<openssl req> command.
=item B<-newca>
@@ -58,6 +68,7 @@ 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.
B<openssl req> and B<openssl ca> commands are get invoked.
=item B<-pkcs12>
@@ -69,34 +80,55 @@ 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.
Delegates work to B<openssl pkcs12> command.
=item B<-sign>, B<-signreq>, B<-xsign>
=item B<-sign>, B<-signcert>, 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.
to standard output. Leverages B<openssl ca> command.
=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.
Extra params are passed on to B<openssl ca> command.
=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".
Extra params are passed on to B<openssl x509> and B<openssl ca> commands.
=item B<-crl>
generate a CRL. Executes B<openssl ca> command.
=item B<-revoke certfile [reason]>
revoke the certificate contained in the specified B<certfile>. An optional
reason may be specified, and must be one of: B<unspecified>,
B<keyCompromise>, B<CACompromise>, B<affiliationChanged>, B<superseded>,
B<cessationOfOperation>, B<certificateHold>, or B<removeFromCRL>.
Leverages B<openssl ca> command.
=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".
are specified on the command line it tries to verify the file "newcert.pem".
Invokes B<openssl verify> command.
=item B<files>
=item B<-extra-req> | B<-extra-ca> | B<-extra-pkcs12> | B<-extra-x509> | B<-extra-verify> <extra-params>
one or more optional certificate file names for use with the B<-verify> command.
The purpose of these parameters is to allow optional parameters to be supplied
to B<openssl> that this command executes. The B<-extra-cmd> are specific to the
option being used and the B<openssl> command getting invoked. For example
when this command invokes B<openssl req> extra parameters can be passed on
with the B<-extra-req> parameter. The
B<openssl> commands being invoked per option are documented below.
Users should consult B<openssl> command documentation for more information.
=back
@@ -117,7 +149,7 @@ the request and finally create a PKCS#12 file containing it.
=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
use it with DSA certificates and requests using the L<req(1)> command
directly. The following example shows the steps that would typically be taken.
Create some DSA parameters:
@@ -137,7 +169,7 @@ 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
openssl req -out newreq.pem -newkey dsa:dsap.pem
Sign the request:
@@ -158,22 +190,25 @@ 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".
can be used and the B<OPENSSL_CONF> environment variable changed to point to
the correct path of the configuration file.
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)>
L<x509(1)>, L<ca(1)>, L<req(1)>, L<pkcs12(1)>,
L<config(5)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

59
doc/apps/asn1parse.pod
View File

@@ -7,6 +7,7 @@ asn1parse - ASN.1 parsing tool
=head1 SYNOPSIS
B<openssl> B<asn1parse>
[B<-help>]
[B<-inform PEM|DER>]
[B<-in filename>]
[B<-out filename>]
@@ -20,6 +21,7 @@ B<openssl> B<asn1parse>
[B<-strparse offset>]
[B<-genstr string>]
[B<-genconf file>]
[B<-strictpem>]
=head1 DESCRIPTION
@@ -30,6 +32,10 @@ structures. It can also be used to extract data from ASN.1 formatted data.
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform> B<DER|PEM>
the input format. B<DER> is binary format and B<PEM> (the default) is base64
@@ -82,36 +88,44 @@ 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
L<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.
file using the B<out> option.
=item B<-strictpem>
If this option is used then B<-inform> will be ignored. Without this option any
data in a PEM format input file will be treated as being base64 encoded and
processed whether it has the normal PEM BEGIN and END markers or not. This
option will ignore any data prior to the start of the BEGIN marker, or after an
END marker in a PEM file.
=back
=head2 OUTPUT
=head2 Output
The output will typically contain lines like this:
0:d=0 hl=4 l= 681 cons: SEQUENCE
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
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
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
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
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
@@ -119,27 +133,27 @@ 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.
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
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
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>
C<1.2.3.4 shortName A long name>
=head1 EXAMPLES
@@ -180,6 +194,15 @@ ASN.1 types is not well handled (if at all).
=head1 SEE ALSO
L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>
L<ASN1_generate_nconf(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

109
doc/apps/ca.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,11 +7,13 @@ ca - sample minimal CA application
=head1 SYNOPSIS
B<openssl> B<ca>
[B<-help>]
[B<-verbose>]
[B<-config filename>]
[B<-name section>]
[B<-gencrl>]
[B<-revoke file>]
[B<-valid file>]
[B<-status serial>]
[B<-updatedb>]
[B<-crl_reason reason>]
@@ -49,6 +50,7 @@ B<openssl> B<ca>
[B<-engine id>]
[B<-subj arg>]
[B<-utf8>]
[B<-create_serial>]
[B<-multivalue-rdn>]
=head1 DESCRIPTION
@@ -60,13 +62,23 @@ and their status.
The options descriptions will be divided into each purpose.
=head1 CA OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-verbose>
this prints extra details about the operations being performed.
=item B<-config filename>
specifies the configuration file to use.
Optional; for a description of the default value,
see L<openssl(1)/COMMAND SUMMARY>.
=item B<-name section>
@@ -80,7 +92,7 @@ signed by the CA.
=item B<-ss_cert filename>
a single self signed certificate to be signed by the CA.
a single self-signed certificate to be signed by the CA.
=item B<-spkac filename>
@@ -91,7 +103,7 @@ 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.
are taken as the names of files containing certificate requests.
=item B<-out filename>
@@ -128,7 +140,7 @@ the 'ps' utility) this option should be used with caution.
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
Certificate requests signed with a different key are ignored. If
B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is
ignored.
@@ -141,11 +153,7 @@ 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.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-notext>
@@ -167,7 +175,8 @@ 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.
the message digest to use.
Any digest supported by the OpenSSL B<dgst> command can be used.
This option also applies to CRLs.
=item B<-policy arg>
@@ -188,7 +197,7 @@ 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
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.
@@ -214,7 +223,7 @@ 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
L<x509v3_config(5)> manual page for details of the
extension section format.
=item B<-extfile file>
@@ -238,14 +247,20 @@ 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
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<-create_serial>
if reading serial from the text file as specified in the configuration
fails, specifying this option creates a new random serial to be used as next
serial number.
=item B<-multivalue-rdn>
this option causes the -subj argument to be interpretedt with full
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>
@@ -275,6 +290,10 @@ the number of hours before the next CRL is due.
a filename containing a certificate to revoke.
=item B<-valid filename>
a filename containing a certificate to add a Valid certificate entry.
=item B<-status serial>
displays the revocation status of the certificate with the specified
@@ -291,7 +310,7 @@ 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 practice B<removeFromCRL> is not particularly useful because it is only used
in delta CRLs which are not currently implemented.
=item B<-crl_hold instruction>
@@ -319,7 +338,7 @@ 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
L<x509v3_config(5)> manual page for details of the
extension section format.
=back
@@ -353,7 +372,7 @@ any) used.
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.
by white space and finally the long name.
=item B<oid_section>
@@ -380,12 +399,12 @@ 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)>).
an EGD socket (see L<RAND_egd(3)>).
=item B<default_days>
the same as the B<-days> option. The number of days to certify
a certificate for.
a certificate for.
=item B<default_startdate>
@@ -406,7 +425,7 @@ 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.
the same as the B<-md> option. Mandatory.
=item B<database>
@@ -508,7 +527,7 @@ this can be regarded more of a quirk than intended behaviour.
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.
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
@@ -568,18 +587,18 @@ 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
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
@@ -587,9 +606,9 @@ A sample configuration file with the relevant sections for B<ca>:
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
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
@@ -616,14 +635,9 @@ The values below reflect the default values.
./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
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.
@@ -631,18 +645,18 @@ 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.
possible to include one SPKAC or self-signed certificate.
=head1 BUGS
The use of an in memory text database can cause problems when large
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.
(perl script or GUI) can handle things properly. The script
B<CA.pl> helps 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
@@ -651,7 +665,7 @@ 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
Canceling some commands by refusing to certify a certificate can
create an empty file.
=head1 WARNINGS
@@ -670,7 +684,7 @@ 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
this when the certificate is displayed then this will hand the requester
a valid CA certificate.
This situation can be avoided by setting B<copy_extensions> to B<copy>
@@ -690,7 +704,16 @@ 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)>
L<req(1)>, L<spkac(1)>, L<x509(1)>, L<CA.pl(1)>,
L<config(5)>, L<x509v3_config(5)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

493
doc/apps/ciphers.pod
View File

@@ -2,16 +2,23 @@
=head1 NAME
ciphers - SSL cipher display and cipher list tool.
ciphers - SSL cipher display and cipher list tool
=head1 SYNOPSIS
B<openssl> B<ciphers>
[B<-help>]
[B<-s>]
[B<-v>]
[B<-V>]
[B<-ssl2>]
[B<-ssl3>]
[B<-tls1>]
[B<-tls1_1>]
[B<-tls1_2>]
[B<-s>]
[B<-psk>]
[B<-srp>]
[B<-stdname>]
[B<cipherlist>]
=head1 DESCRIPTION
@@ -20,39 +27,76 @@ 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
=head1 OPTIONS
=over 4
=item B<-help>
Print a usage message.
=item B<-s>
Only list supported ciphers: those consistent with the security level, and
minimum and maximum protocol version. This is closer to the actual cipher list
an application will support.
PSK and SRP ciphers are not enabled by default: they require B<-psk> or B<-srp>
to enable them.
It also does not change the default list of supported signature algorithms.
On a server the list of supported ciphers might also exclude other ciphers
depending on the configured certificates and presence of DH parameters.
If this option is not used then all ciphers that match the cipherlist will be
listed.
=item B<-psk>
When combined with B<-s> includes cipher suites which require PSK.
=item B<-srp>
When combined with B<-s> includes cipher suites which require SRP.
=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.
Verbose output: For each ciphersuite, list details as provided by
L<SSL_CIPHER_description(3)>.
=item B<-V>
Like B<-v>, but include cipher suite codes in output (hex format).
Like B<-v>, but include the official cipher suite values in hex.
=item B<-ssl3>, B<-tls1>
=item B<-tls1_2>
This lists ciphers compatible with any of SSLv3, TLSv1, TLSv1.1 or TLSv1.2.
In combination with the B<-s> option, list the ciphers which would be used if
TLSv1.2 were negotiated.
=item B<-ssl2>
=item B<-ssl3>
Only include SSLv2 ciphers.
In combination with the B<-s> option, list the ciphers which would be used if
SSLv3 were negotiated.
=item B<-h>, B<-?>
=item B<-tls1>
Print a brief usage message.
In combination with the B<-s> option, list the ciphers which would be used if
TLSv1 were negotiated.
=item B<-tls1_1>
In combination with the B<-s> option, list the ciphers which would be used if
TLSv1.1 were negotiated.
=item B<-stdname>
precede each ciphersuite by its standard name: only available is OpenSSL
is built with tracing enabled (B<enable-ssl-trace> argument to Configure).
=item B<cipherlist>
A cipher list to convert to a cipher preference list. If it is not included
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
@@ -94,8 +138,11 @@ 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.
The cipher string B<@STRENGTH> can be used at any point to sort the current
cipher list in order of encryption algorithm key length.
The cipher string B<@SECLEVEL=n> can be used at any point to set the security
level to B<n>.
=head1 CIPHER STRINGS
@@ -107,55 +154,42 @@ The following is a list of all permitted cipher strings and their meanings.
The default cipher list.
This is determined at compile time and is normally
B<ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2>.
B<ALL:!COMPLEMENTOFDEFAULT:!eNULL>.
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).
The ciphers included in B<ALL>, but not enabled by default. Currently
this includes all RC4 and anonymous ciphers. Note that this rule does
not cover B<eNULL>, which is not included by B<ALL> (use B<COMPLEMENTOFALL> if
necessary). Note that RC4 based ciphersuites are not built into OpenSSL by
default (see the enable-weak-ssl-ciphers option to Configure).
=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
All cipher suites except the B<eNULL> ciphers (which must be explicitly enabled
if needed).
As of OpenSSL 1.0.0, the B<ALL> cipher suites are sensibly ordered by default.
=item B<COMPLEMENTOFALL>
the cipher suites not enabled by B<ALL>, currently being B<eNULL>.
The cipher suites not enabled by B<ALL>, currently 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.
"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.
"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.
"low" encryption cipher suites, currently those using 64 or 56 bit
encryption algorithms but excluding export cipher suites. All these
ciphersuites have been removed as of OpenSSL 1.1.0.
=item B<eNULL>, B<NULL>
@@ -163,102 +197,83 @@ 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.
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.
to "man in the middle" attacks and so their use is 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>
=item B<kRSA>, B<aRSA>, B<RSA>
cipher suites using RSA key exchange.
Cipher suites using RSA key exchange or authentication. B<RSA> is an alias for
B<kRSA>.
=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.
Cipher suites using static DH key agreement and DH certificates signed by CAs
with RSA and DSS keys or either respectively.
All these cipher suites have been removed in OpenSSL 1.1.0.
=item B<kDHE>, B<kEDH>
=item B<kDHE>, B<kEDH>, B<DH>
cipher suites using ephemeral DH key agreement, including anonymous cipher
Cipher suites using ephemeral DH key agreement, including anonymous cipher
suites.
=item B<DHE>, B<EDH>
cipher suites using authenticated ephemeral DH key agreement.
Cipher suites using authenticated ephemeral DH key agreement.
=item B<ADH>
anonymous DH cipher suites, note that this does not include anonymous Elliptic
Anonymous DH cipher suites, note that this does not include anonymous Elliptic
Curve DH (ECDH) cipher suites.
=item B<DH>
=item B<kEECDH>, B<kECDHE>, B<ECDH>
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 using ephemeral ECDH key agreement, including anonymous
cipher suites.
=item B<ECDHE>, B<EECDH>
cipher suites using authenticated ephemeral ECDH key agreement.
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.
Anonymous Elliptic Curve Diffie-Hellman cipher suites.
=item B<aDSS>, B<DSS>
cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
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
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.
All these cipher suites have been removed in OpenSSL 1.1.0.
=item B<aECDSA>, B<ECDSA>
cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA
Cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA
keys.
=item B<kFZA>, B<aFZA>, B<eFZA>, B<FZA>
=item B<TLSv1.2>, B<TLSv1.0>, B<SSLv3>
ciphers suites using FORTEZZA key exchange, authentication, encryption or all
FORTEZZA algorithms. Not implemented.
Lists ciphersuites which are only supported in at least TLS v1.2, TLS v1.0 or
SSL v3.0 respectively.
Note: there are no ciphersuites specific to TLS v1.1.
Since this is only the minimum version, if, for example, TLSv1.0 is negotiated
then both TLSv1.0 and SSLv3.0 ciphersuites are available.
=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.
Note: these cipher strings B<do not> change the negotiated version of SSL or
TLS, they only affect the list of available cipher suites.
=item B<AES128>, B<AES256>, B<AES>
@@ -269,88 +284,107 @@ cipher suites using 128 bit AES, 256 bit AES or either 128 or 256 bit AES.
AES in Galois Counter Mode (GCM): these ciphersuites are only supported
in TLS v1.2.
=item B<AESCCM>, B<AESCCM8>
AES in Cipher Block Chaining - Message Authentication Mode (CCM): these
ciphersuites are only supported in TLS v1.2. B<AESCCM> references CCM
cipher suites using both 16 and 8 octet Integrity Check Value (ICV)
while B<AESCCM8> only references 8 octet ICV.
=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<CHACHA20>
cipher suites using ChaCha20.
=item B<3DES>
cipher suites using triple DES.
=item B<DES>
cipher suites using DES (not triple DES).
Cipher suites using DES (not triple DES).
All these cipher suites have been removed in OpenSSL 1.1.0.
=item B<RC4>
cipher suites using RC4.
Cipher suites using RC4.
=item B<RC2>
cipher suites using RC2.
Cipher suites using RC2.
=item B<IDEA>
cipher suites using IDEA.
Cipher suites using IDEA.
=item B<SEED>
cipher suites using SEED.
Cipher suites using SEED.
=item B<MD5>
cipher suites using MD5.
Cipher suites using MD5.
=item B<SHA1>, B<SHA>
cipher suites using SHA1.
Cipher suites using SHA1.
=item B<SHA256>, B<SHA384>
ciphersuites using SHA256 or SHA384.
Ciphersuites using SHA256 or SHA384.
=item B<aGOST>
=item B<aGOST>
cipher suites using GOST R 34.10 (either 2001 or 94) for authenticaction
(needs an engine supporting GOST algorithms).
Cipher suites using GOST R 34.10 (either 2001 or 94) for authentication
(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)
Cipher suites using GOST R 34.10-2001 authentication.
=item B<kGOST>
cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357.
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.
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.
Cipher suites using GOST 28147-89 MAC B<instead of> HMAC.
=item B<PSK>
cipher suites using pre-shared keys (PSK).
All cipher suites using pre-shared keys (PSK).
=item B<kPSK>, B<kECDHEPSK>, B<kDHEPSK>, B<kRSAPSK>
Cipher suites using PSK key exchange, ECDHE_PSK, DHE_PSK or RSA_PSK.
=item B<aPSK>
Cipher suites using PSK authentication (currently all PSK modes apart from
RSA_PSK).
=item B<SUITEB128>, B<SUITEB128ONLY>, B<SUITEB192>
enables suite B mode operation using 128 (permitting 192 bit mode by peer)
Enables suite B mode of 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.
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
@@ -361,70 +395,42 @@ 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.
=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_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE-DSS-DES-CBC3-SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE-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.
=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_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE-DSS-DES-CBC3-SHA
TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE-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
@@ -489,26 +495,10 @@ algorithms, such as the B<ccgost> engine, included in the OpenSSL distribution.
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
@@ -556,16 +546,6 @@ Note: these ciphers can also be used in SSL v3.
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
@@ -581,22 +561,116 @@ Note: these ciphers can also be used in SSL v3.
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
RSA_WITH_AES_128_CCM AES128-CCM
RSA_WITH_AES_256_CCM AES256-CCM
DHE_RSA_WITH_AES_128_CCM DHE-RSA-AES128-CCM
DHE_RSA_WITH_AES_256_CCM DHE-RSA-AES256-CCM
RSA_WITH_AES_128_CCM_8 AES128-CCM8
RSA_WITH_AES_256_CCM_8 AES256-CCM8
DHE_RSA_WITH_AES_128_CCM_8 DHE-RSA-AES128-CCM8
DHE_RSA_WITH_AES_256_CCM_8 DHE-RSA-AES256-CCM8
ECDHE_ECDSA_WITH_AES_128_CCM ECDHE-ECDSA-AES128-CCM
ECDHE_ECDSA_WITH_AES_256_CCM ECDHE-ECDSA-AES256-CCM
ECDHE_ECDSA_WITH_AES_128_CCM_8 ECDHE-ECDSA-AES128-CCM8
ECDHE_ECDSA_WITH_AES_256_CCM_8 ECDHE-ECDSA-AES256-CCM8
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 Camellia HMAC-Based ciphersuites from RFC6367, extending TLS v1.2
=head2 Deprecated SSL v2.0 cipher suites.
TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-ECDSA-CAMELLIA128-SHA256
TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-ECDSA-CAMELLIA256-SHA384
TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-RSA-CAMELLIA128-SHA256
TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-RSA-CAMELLIA256-SHA384
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
=head2 Pre-shared keying (PSK) ciphersuites
PSK_WITH_NULL_SHA PSK-NULL-SHA
DHE_PSK_WITH_NULL_SHA DHE-PSK-NULL-SHA
RSA_PSK_WITH_NULL_SHA RSA-PSK-NULL-SHA
PSK_WITH_RC4_128_SHA PSK-RC4-SHA
PSK_WITH_3DES_EDE_CBC_SHA PSK-3DES-EDE-CBC-SHA
PSK_WITH_AES_128_CBC_SHA PSK-AES128-CBC-SHA
PSK_WITH_AES_256_CBC_SHA PSK-AES256-CBC-SHA
DHE_PSK_WITH_RC4_128_SHA DHE-PSK-RC4-SHA
DHE_PSK_WITH_3DES_EDE_CBC_SHA DHE-PSK-3DES-EDE-CBC-SHA
DHE_PSK_WITH_AES_128_CBC_SHA DHE-PSK-AES128-CBC-SHA
DHE_PSK_WITH_AES_256_CBC_SHA DHE-PSK-AES256-CBC-SHA
RSA_PSK_WITH_RC4_128_SHA RSA-PSK-RC4-SHA
RSA_PSK_WITH_3DES_EDE_CBC_SHA RSA-PSK-3DES-EDE-CBC-SHA
RSA_PSK_WITH_AES_128_CBC_SHA RSA-PSK-AES128-CBC-SHA
RSA_PSK_WITH_AES_256_CBC_SHA RSA-PSK-AES256-CBC-SHA
PSK_WITH_AES_128_GCM_SHA256 PSK-AES128-GCM-SHA256
PSK_WITH_AES_256_GCM_SHA384 PSK-AES256-GCM-SHA384
DHE_PSK_WITH_AES_128_GCM_SHA256 DHE-PSK-AES128-GCM-SHA256
DHE_PSK_WITH_AES_256_GCM_SHA384 DHE-PSK-AES256-GCM-SHA384
RSA_PSK_WITH_AES_128_GCM_SHA256 RSA-PSK-AES128-GCM-SHA256
RSA_PSK_WITH_AES_256_GCM_SHA384 RSA-PSK-AES256-GCM-SHA384
PSK_WITH_AES_128_CBC_SHA256 PSK-AES128-CBC-SHA256
PSK_WITH_AES_256_CBC_SHA384 PSK-AES256-CBC-SHA384
PSK_WITH_NULL_SHA256 PSK-NULL-SHA256
PSK_WITH_NULL_SHA384 PSK-NULL-SHA384
DHE_PSK_WITH_AES_128_CBC_SHA256 DHE-PSK-AES128-CBC-SHA256
DHE_PSK_WITH_AES_256_CBC_SHA384 DHE-PSK-AES256-CBC-SHA384
DHE_PSK_WITH_NULL_SHA256 DHE-PSK-NULL-SHA256
DHE_PSK_WITH_NULL_SHA384 DHE-PSK-NULL-SHA384
RSA_PSK_WITH_AES_128_CBC_SHA256 RSA-PSK-AES128-CBC-SHA256
RSA_PSK_WITH_AES_256_CBC_SHA384 RSA-PSK-AES256-CBC-SHA384
RSA_PSK_WITH_NULL_SHA256 RSA-PSK-NULL-SHA256
RSA_PSK_WITH_NULL_SHA384 RSA-PSK-NULL-SHA384
PSK_WITH_AES_128_GCM_SHA256 PSK-AES128-GCM-SHA256
PSK_WITH_AES_256_GCM_SHA384 PSK-AES256-GCM-SHA384
ECDHE_PSK_WITH_RC4_128_SHA ECDHE-PSK-RC4-SHA
ECDHE_PSK_WITH_3DES_EDE_CBC_SHA ECDHE-PSK-3DES-EDE-CBC-SHA
ECDHE_PSK_WITH_AES_128_CBC_SHA ECDHE-PSK-AES128-CBC-SHA
ECDHE_PSK_WITH_AES_256_CBC_SHA ECDHE-PSK-AES256-CBC-SHA
ECDHE_PSK_WITH_AES_128_CBC_SHA256 ECDHE-PSK-AES128-CBC-SHA256
ECDHE_PSK_WITH_AES_256_CBC_SHA384 ECDHE-PSK-AES256-CBC-SHA384
ECDHE_PSK_WITH_NULL_SHA ECDHE-PSK-NULL-SHA
ECDHE_PSK_WITH_NULL_SHA256 ECDHE-PSK-NULL-SHA256
ECDHE_PSK_WITH_NULL_SHA384 ECDHE-PSK-NULL-SHA384
PSK_WITH_CAMELLIA_128_CBC_SHA256 PSK-CAMELLIA128-SHA256
PSK_WITH_CAMELLIA_256_CBC_SHA384 PSK-CAMELLIA256-SHA384
DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 DHE-PSK-CAMELLIA128-SHA256
DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 DHE-PSK-CAMELLIA256-SHA384
RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 RSA-PSK-CAMELLIA128-SHA256
RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 RSA-PSK-CAMELLIA256-SHA384
ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-PSK-CAMELLIA128-SHA256
ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-PSK-CAMELLIA256-SHA384
PSK_WITH_AES_128_CCM PSK-AES128-CCM
PSK_WITH_AES_256_CCM PSK-AES256-CCM
DHE_PSK_WITH_AES_128_CCM DHE-PSK-AES128-CCM
DHE_PSK_WITH_AES_256_CCM DHE-PSK-AES256-CCM
PSK_WITH_AES_128_CCM_8 PSK-AES128-CCM8
PSK_WITH_AES_256_CCM_8 PSK-AES256-CCM8
DHE_PSK_WITH_AES_128_CCM_8 DHE-PSK-AES128-CCM8
DHE_PSK_WITH_AES_256_CCM_8 DHE-PSK-AES256-CCM8
=head2 ChaCha20-Poly1305 cipher suites, extending TLS v1.2
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 ECDHE-RSA-CHACHA20-POLY1305
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 ECDHE-ECDSA-CHACHA20-POLY1305
TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 DHE-RSA-CHACHA20-POLY1305
TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 PSK-CHACHA20-POLY1305
TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 ECDHE-PSK-CHACHA20-POLY1305
TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 DHE-PSK-CHACHA20-POLY1305
TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256 RSA-PSK-CHACHA20-POLY1305
=head2 Older names used by OpenSSL
The following names are accepted by older releases:
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA (DHE-RSA-DES-CBC3-SHA)
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA (DHE-DSS-DES-CBC3-SHA)
=head1 NOTES
@@ -627,19 +701,30 @@ 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
Include all ciphers with RSA authentication but leave out ciphers without
encryption.
openssl ciphers -v 'RSA:!COMPLEMENTOFALL'
Set security level to 2 and display all ciphers consistent with level 2:
openssl ciphers -s -v 'ALL:@SECLEVEL=2'
=head1 SEE ALSO
L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ssl(3)|ssl(3)>
L<s_client(1)>, L<s_server(1)>, L<ssl(7)>
=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.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

151
doc/apps/cms.pod
View File

@@ -7,6 +7,7 @@ cms - CMS utility
=head1 SYNOPSIS
B<openssl> B<cms>
[B<-help>]
[B<-encrypt>]
[B<-decrypt>]
[B<-sign>]
@@ -35,7 +36,36 @@ B<openssl> B<cms>
[B<-print>]
[B<-CAfile file>]
[B<-CApath dir>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-md digest>]
[B<-[cipher]>]
[B<-nointern>]
@@ -44,6 +74,8 @@ B<openssl> B<cms>
[B<-noattr>]
[B<-nosmimecap>]
[B<-binary>]
[B<-crlfeol>]
[B<-asciicrlf>]
[B<-nodetach>]
[B<-certfile file>]
[B<-certsout file>]
@@ -72,7 +104,7 @@ B<openssl> B<cms>
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
=head1 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
@@ -80,6 +112,10 @@ type.
=over 4
=item B<-help>
Print out a usage message.
=item B<-encrypt>
encrypt mail for the given recipient certificates. Input file is the message
@@ -153,13 +189,13 @@ B<EncrytedData> type and output the content.
=item B<-sign_receipt>
Generate and output a signed receipt for the supplied message. The input
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>
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.
@@ -223,7 +259,7 @@ is S/MIME and it uses the multipart/signed MIME content type.
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
off text headers: if the decrypted or verified message is not of MIME
type text/plain then an error occurs.
=item B<-noout>
@@ -248,6 +284,14 @@ 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<-no-CAfile>
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-md digest>
digest algorithm to use when signing or resigning. If not present then the
@@ -257,11 +301,11 @@ default digest algorithm for the signing key will be used (usually SHA1).
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
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
If not specified triple DES is used. Only used with B<-encrypt> and
B<-EncryptedData_create> commands.
=item B<-nointern>
@@ -300,6 +344,20 @@ 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<-crlfeol>
normally the output file uses a single B<LF> as end of line. When this
option is present B<CRLF> is used instead.
=item B<-asciicrlf>
when signing use ASCII CRLF format canonicalisation. This strips trailing
whitespace from all lines, deletes trailing blank lines at EOF and sets
the encapsulated content type. This option is normally used with detached
content and an output signature format of DER. This option is not normally
needed when verifying as it is enabled automatically if the encapsulated
content format is detected.
=item B<-nodetach>
when signing a message use opaque signing: this form is more resistant
@@ -343,7 +401,7 @@ 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
be provided by all recipient 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>
@@ -353,7 +411,7 @@ 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
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>
@@ -365,7 +423,7 @@ requests.
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
B<-EncryptedData_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.
@@ -381,7 +439,7 @@ B<KEKRecipientInfo> structures.
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.
numerical format.
=item B<-inkey file>
@@ -401,20 +459,20 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<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.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an 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.
a message.
=item B<-to, -from, -subject>
@@ -423,10 +481,16 @@ 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>
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set various certificate chain valiadition option. See the
L<B<verify>|verify(1)> manual page for details.
Set various certificate chain validation options. See the
L<verify(1)> manual page for details.
=back
@@ -438,7 +502,7 @@ 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
necessary MIME headers or many S/MIME clients won't display it
properly (if at all). You can use the B<-text> option to automatically
add plain text headers.
@@ -459,7 +523,7 @@ 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.
The B<-stream> and B<-indef> options enable 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.
@@ -473,10 +537,10 @@ 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.
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)>).
with caution. For a fuller description see L<CMS_decrypt(3)>).
=head1 EXIT CODES
@@ -537,29 +601,29 @@ be processed by the older B<smime> command.
Create a cleartext signed message:
openssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem
-signer mycert.pem
Create an opaque signed message
openssl cms -sign -in message.txt -text -out mail.msg -nodetach \
-signer mycert.pem
-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
-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
-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
-from steve@openssl.org -to someone@somewhere \
-subject "Signed message" | sendmail someone@somewhere
Verify a message and extract the signer's certificate if successful:
@@ -568,15 +632,15 @@ Verify a message and extract the signer's certificate if successful:
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
-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
| 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.
@@ -593,7 +657,7 @@ it with:
-----BEGIN PKCS7-----
-----END PKCS7-----
and using the command,
and using the command,
openssl cms -verify -inform PEM -in signature.pem -content content.txt
@@ -612,17 +676,17 @@ Add a signer to an existing message:
Sign mail using RSA-PSS:
openssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -keyopt rsa_padding_mode:pss
-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
-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
-recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
=head1 BUGS
@@ -654,11 +718,20 @@ 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.
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.
The -no_alt_chains options was first added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

73
doc/apps/config.pod
View File

@@ -1,4 +1,3 @@
=pod
=for comment openssl_manual_section:5
@@ -47,7 +46,8 @@ 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.
instead of calling getenv() directly. The value string must not exceed 64k in
length after variable expansion. Otherwise an error will occur.
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<\>
@@ -56,21 +56,21 @@ 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
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
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
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.
@@ -91,7 +91,7 @@ section containing configuration module specific information. E.g.
The features of each configuration module are described below.
=head2 ASN1 OBJECT CONFIGURATION MODULE
=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
@@ -102,16 +102,16 @@ 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
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
=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
@@ -141,7 +141,7 @@ For example:
[bar_section]
... "bar" ENGINE specific commands ...
The command B<engine_id> is used to give the ENGINE name. If used this
The command B<engine_id> is used to give the ENGINE name. If used this
command must be first. For example:
[engine_section]
@@ -165,10 +165,10 @@ 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()>
supply using the functions 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
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.
@@ -190,7 +190,7 @@ For example:
# Supply all default algorithms
default_algorithms = ALL
=head2 EVP CONFIGURATION MODULE
=head2 EVP Configuration Module
This modules has the name B<alg_section> which points to a section containing
algorithm commands.
@@ -208,6 +208,34 @@ For example:
fips_mode = on
=head2 SSL Configuration Module
This module has the name B<ssl_conf> which points to a section containing
SSL configurations.
Each line in the SSL configuration section contains the name of the
configuration and the section containing it.
Each configuration section consists of command value pairs for B<SSL_CONF>.
Each pair will be passed to a B<SSL_CTX> or B<SSL> structure if it calls
SSL_CTX_config() or SSL_config() with the appropriate configuration name.
Note: any characters before an initial dot in the configuration section are
ignored so the same command can be used multiple times.
For example:
ssl_conf = ssl_sect
[ssl_sect]
server = server_section
[server_section]
RSA.Certificate = server-rsa.pem
ECDSA.Certificate = server-ecdsa.pem
Ciphers = ALL:!RC4
=head1 NOTES
@@ -238,7 +266,7 @@ 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
@@ -264,11 +292,11 @@ 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
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
default section both values can be looked up with B<TEMP> taking
priority and B</tmp> used if neither is defined:
TMP=/tmp
@@ -316,7 +344,7 @@ More complex OpenSSL library configuration. Add OID and don't enter FIPS mode:
# 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
The above examples can be used 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
@@ -345,6 +373,15 @@ file.
=head1 SEE ALSO
L<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)>
L<x509(1)>, L<req(1)>, L<ca(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

22
doc/apps/crl.pod
View File

@@ -7,6 +7,7 @@ crl - CRL utility
=head1 SYNOPSIS
B<openssl> B<crl>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-text>]
@@ -25,10 +26,14 @@ B<openssl> B<crl>
The B<crl> command processes CRL files in DER or PEM format.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. B<DER> format is DER encoded CRL
@@ -37,7 +42,7 @@ 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
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -57,7 +62,7 @@ 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)>.
the description of B<-nameopt> in L<x509(1)>.
=item B<-noout>
@@ -123,6 +128,15 @@ and files too.
=head1 SEE ALSO
L<crl2pkcs7(1)|crl2pkcs7(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>
L<crl2pkcs7(1)>, L<ca(1)>, L<x509(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

24
doc/apps/crl2pkcs7.pod
View File

@@ -2,11 +2,12 @@
=head1 NAME
crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates.
crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates
=head1 SYNOPSIS
B<openssl> B<crl2pkcs7>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
@@ -20,10 +21,14 @@ 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
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the CRL input format. B<DER> format is DER encoded CRL
@@ -69,8 +74,8 @@ Create a PKCS#7 structure from a certificate and CRL:
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
openssl crl2pkcs7 -nocrl -certfile newcert.pem
-certfile demoCA/cacert.pem -outform DER -out p7.der
=head1 NOTES
@@ -86,6 +91,15 @@ install user certificates and CAs in MSIE using the Xenroll control.
=head1 SEE ALSO
L<pkcs7(1)|pkcs7(1)>
L<pkcs7(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

122
doc/apps/dgst.pod
View File

@@ -2,18 +2,18 @@
=head1 NAME
dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md2, md4, md5, dss1 - message digests
dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md4, md5, blake2b, blake2s - message digests
=head1 SYNOPSIS
B<openssl> B<dgst>
[B<-sha|-sha1|-mdc2|-ripemd160|-sha224|-sha256|-sha384|-sha512|-md2|-md4|-md5|-dss1>]
B<openssl> B<dgst>
[B<-help>]
[B<-I<digest>>]
[B<-c>]
[B<-d>]
[B<-hex>]
[B<-binary>]
[B<-r>]
[B<-non-fips-allow>]
[B<-out filename>]
[B<-sign filename>]
[B<-keyform arg>]
@@ -22,8 +22,9 @@ B<openssl> B<dgst>
[B<-prverify filename>]
[B<-signature filename>]
[B<-hmac key>]
[B<-non-fips-allow>]
[B<-fips-fingerprint>]
[B<-engine id>]
[B<-engine_impl>]
[B<file...>]
B<openssl>
@@ -36,88 +37,92 @@ 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.
The generic name, B<dgst>, may be used with an option specifying the
algorithm to be used.
The default digest is I<sha256>.
A supported I<digest> name may also be used as the command name.
To see the list of supported algorithms, use the I<list --digest-commands>
command.
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-I<digest>>
Specifies name of a supported digest to be used. To see the list of
supported digests, use the command I<list --digest-commands>.
=item B<-c>
print out the digest in two digit groups separated by colons, only relevant if
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.
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 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.
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.
Output the digest in the "coreutils" format used by programs like B<sha1sum>.
=item B<-out filename>
filename to output to, or standard output by default.
Filename to output to, or standard output by default.
=item B<-sign filename>
digitally sign the digest using the private key in "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)>.
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)>.
=item B<-verify filename>
verify the signature using the the public key in "filename".
Verify the signature using 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".
Verify the signature using the private key in "filename".
=item B<-signature filename>
the actual signature to verify.
The actual signature to verify.
=item B<-hmac key>
create a hashed MAC using "key".
Create a hashed MAC using "key".
=item B<-mac alg>
create MAC (keyed Message Authentication Code). The most popular MAC
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
@@ -128,11 +133,11 @@ via B<-macopt> parameter.
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
=over 4
=item B<key:string>
Specifies MAC key as alphnumeric string (use if key contain printable
Specifies MAC key as alphanumeric 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.
@@ -146,24 +151,31 @@ for example exactly 32 chars for gost-mac.
=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.
A file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an 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.
all others.
=item B<-fips-fingerprint>
compute HMAC using a specific key
for certain OpenSSL-FIPS operations.
Compute HMAC using a specific key for certain OpenSSL-FIPS operations.
=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 or B<-engine_impl> is also
specified.
=item B<-engine_impl>
When used with the B<-engine> option, it specifies to also use
engine B<id> for digest operations.
=item B<file...>
file or files to digest. If no files are specified then standard input is
File or files to digest. If no files are specified then standard input is
used.
=back
@@ -185,8 +197,13 @@ To verify a signature:
=head1 NOTES
The digest of choice for all new applications is SHA1. Other digests are
however still widely used.
The digest mechanisms that are available will depend on the options
used when building OpenSSL.
The B<list digest-commands> command can be used to list them.
New or agile applications should use probably use SHA-256. Other digests,
particularly SHA-1 and MD5, are still widely used for interoperating
with existing formats and protocols.
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.
@@ -204,5 +221,18 @@ 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.
=head1 HISTORY
The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0
The FIPS-related options were removed in OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

32
doc/apps/dhparam.pod
View File

@@ -7,6 +7,7 @@ dhparam - DH parameter manipulation and generation
=head1 SYNOPSIS
B<openssl dhparam>
[B<-help>]
[B<-inform DER|PEM>]
[B<-outform DER|PEM>]
[B<-in> I<filename>]
@@ -30,6 +31,10 @@ This command is used to manipulate DH parameter files.
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -39,7 +44,7 @@ additional header and footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in> I<filename>
@@ -67,7 +72,8 @@ avoid small-subgroup attacks that may be possible otherwise.
=item B<-check>
check if the parameters are valid primes and generator.
Performs numerous checks to see if the supplied parameters are valid and
displays a warning if not.
=item B<-2>, B<-5>
@@ -79,8 +85,8 @@ 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.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -103,7 +109,7 @@ 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.
be loaded by calling the get_dhNNNN() function.
=item B<-engine id>
@@ -117,8 +123,8 @@ for all available algorithms.
=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
B<gendh> in previous versions of OpenSSL. The B<dh> and B<gendh>
programs are retained for now but may have different purposes in future
versions of OpenSSL.
=head1 NOTES
@@ -139,11 +145,15 @@ There should be a way to generate and manipulate DH keys.
=head1 SEE ALSO
L<dsaparam(1)|dsaparam(1)>
L<dsaparam(1)>
=head1 HISTORY
=head1 COPYRIGHT
The B<dhparam> command was added in OpenSSL 0.9.5.
The B<-dsaparam> option was added in OpenSSL 0.9.6.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

28
doc/apps/dsa.pod
View File

@@ -7,6 +7,7 @@ dsa - DSA key processing
=head1 SYNOPSIS
B<openssl> B<dsa>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
@@ -36,10 +37,14 @@ 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
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option with a private key uses
@@ -54,7 +59,7 @@ PKCS#8 format is also accepted.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -66,7 +71,7 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-out filename>
@@ -78,7 +83,7 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
@@ -144,7 +149,7 @@ 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:
To convert a private key from PEM to DER format:
openssl dsa -in key.pem -outform DER -out keyout.der
@@ -158,7 +163,16 @@ To just output the public part of a private key:
=head1 SEE ALSO
L<dsaparam(1)|dsaparam(1)>, L<gendsa(1)|gendsa(1)>, L<rsa(1)|rsa(1)>,
L<genrsa(1)|genrsa(1)>
L<dsaparam(1)>, L<gendsa(1)>, L<rsa(1)>,
L<genrsa(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

26
doc/apps/dsaparam.pod
View File

@@ -7,6 +7,7 @@ dsaparam - DSA parameter manipulation and generation
=head1 SYNOPSIS
B<openssl dsaparam>
[B<-help>]
[B<-inform DER|PEM>]
[B<-outform DER|PEM>]
[B<-in filename>]
@@ -27,6 +28,10 @@ This command is used to manipulate or generate DSA parameter files.
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -36,7 +41,7 @@ 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
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -62,7 +67,7 @@ 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.
be loaded by calling the get_dsaXXX() function.
=item B<-genkey>
@@ -72,8 +77,8 @@ 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.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -104,7 +109,16 @@ 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)>
L<gendsa(1)>, L<dsa(1)>, L<genrsa(1)>,
L<rsa(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

50
doc/apps/ec.pod
View File

@@ -7,6 +7,7 @@ ec - EC key processing
=head1 SYNOPSIS
B<openssl> B<ec>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
@@ -23,20 +24,26 @@ B<openssl> B<ec>
[B<-pubout>]
[B<-conv_form arg>]
[B<-param_enc arg>]
[B<-no_public>]
[B<-check>]
[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
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
(http://www.secg.org/). To convert an OpenSSL EC private key into the
PKCS#8 private key format use the B<pkcs8> command.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option with a private key uses
@@ -48,7 +55,7 @@ PKCS#8 format is also accepted.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -60,7 +67,7 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-out filename>
@@ -72,11 +79,11 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-des|-des3|-idea>
These options encrypt the private key with the DES, triple DES, IDEA or
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
@@ -122,12 +129,20 @@ the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
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
specified by an 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,
B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279,
is currently not implemented in OpenSSL.
=item B<-no_public>
This option omits the public key components from the private key output.
=item B<-check>
this option checks the consistency of an EC private or public key.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<ec>
@@ -155,7 +170,7 @@ 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:
To convert a private key from PEM to DER format:
openssl ec -in key.pem -outform DER -out keyout.der
@@ -177,14 +192,15 @@ To change the point conversion form to B<compressed>:
=head1 SEE ALSO
L<ecparam(1)|ecparam(1)>, L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>
L<ecparam(1)>, L<dsa(1)>, L<rsa(1)>
=head1 HISTORY
=head1 COPYRIGHT
The ec command was first introduced in OpenSSL 0.9.8.
Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
=head1 AUTHOR
Nils Larsch for the OpenSSL project (http://www.openssl.org).
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

38
doc/apps/ecparam.pod
View File

@@ -7,6 +7,7 @@ ecparam - EC parameter manipulation and generation
=head1 SYNOPSIS
B<openssl ecparam>
[B<-help>]
[B<-inform DER|PEM>]
[B<-outform DER|PEM>]
[B<-in filename>]
@@ -32,16 +33,20 @@ This command is used to manipulate or generate EC parameter files.
=over 4
=item B<-help>
Print out a usage message.
=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
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
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -66,7 +71,7 @@ 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.
be loaded by calling the get_ec_group_XXX() function.
=item B<-check>
@@ -96,10 +101,10 @@ the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
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
specified by an 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,
B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279,
is currently not implemented in OpenSSL.
=item B<-no_seed>
@@ -109,13 +114,13 @@ is included in the ECParameters structure (see RFC 3279).
=item B<-genkey>
This option will generate a EC private key using the specified parameters.
This option will generate an 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.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -136,7 +141,7 @@ PEM format EC parameters use the header and footer lines:
-----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.
B<ecparam> can only create EC parameters from known (named) curves.
=head1 EXAMPLES
@@ -166,14 +171,15 @@ To print out the EC parameters to standard output:
=head1 SEE ALSO
L<ec(1)|ec(1)>, L<dsaparam(1)|dsaparam(1)>
L<ec(1)>, L<dsaparam(1)>
=head1 HISTORY
=head1 COPYRIGHT
The ecparam command was first introduced in OpenSSL 0.9.8.
Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
=head1 AUTHOR
Nils Larsch for the OpenSSL project (http://www.openssl.org)
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

72
doc/apps/enc.pod
View File

@@ -7,6 +7,8 @@ enc - symmetric cipher routines
=head1 SYNOPSIS
B<openssl enc -ciphername>
[B<-help>]
[B<-ciphers>]
[B<-in filename>]
[B<-out filename>]
[B<-pass arg>]
@@ -22,7 +24,7 @@ B<openssl enc -ciphername>
[B<-salt>]
[B<-nosalt>]
[B<-z>]
[B<-md>]
[B<-md digest>]
[B<-p>]
[B<-P>]
[B<-bufsize number>]
@@ -42,6 +44,14 @@ either by itself or in addition to the encryption or decryption.
=over 4
=item B<-help>
Print out a usage message.
=item B<-ciphers>
List all supported ciphers.
=item B<-in filename>
the input filename, standard input by default.
@@ -53,17 +63,7 @@ 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.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-e>
@@ -98,9 +98,16 @@ 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<-md digest>
Use the specified digest to create the key from the passphrase.
The default algorithm is sha-256.
=item B<-nosalt>
do not use a salt
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.
=item B<-salt>
@@ -170,7 +177,7 @@ 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
options can only be used for hardware-assisted implementations of
ciphers, which are supported by OpenSSL core or other engine, specified
in the configuration file.
@@ -181,7 +188,7 @@ 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.
OpenSSL.
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
@@ -212,7 +219,7 @@ 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
list of ciphers, supported by your version of OpenSSL, including
ones provided by configured engines.
The B<enc> program does not support authenticated encryption modes
@@ -255,7 +262,7 @@ authentication tag.
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)
gost89-cnt `GOST 28147-89 in CNT mode (provided by ccgost engine)
idea-cbc IDEA algorithm in CBC mode
idea same as idea-cbc
@@ -281,13 +288,13 @@ authentication tag.
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
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
@@ -297,11 +304,11 @@ Just base64 encode a binary file:
Decode the same file
openssl base64 -d -in file.b64 -out file.bin
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
openssl des3 -salt -in file.txt -out file.des3
Decrypt a file using a supplied password:
@@ -330,4 +337,17 @@ 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.
=head1 HISTORY
The default digest was changed from MD5 to SHA256 in Openssl 1.1.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

104
doc/apps/engine.pod Normal file
View File

@@ -0,0 +1,104 @@
=pod
=head1 NAME
engine - load and query engines
=head1 SYNOPSIS
B<openssl engine>
[ I<engine...> ]
[B<-v>]
[B<-vv>]
[B<-vvv>]
[B<-vvv>]
[B<-vvv>]
[B<-c>]
[B<-t>]
[B<-tt>]
[B<-pre> I<command>]
[B<-post> I<command>]
[ I<engine...> ]
=head1 DESCRIPTION
The B<engine> command is used to query the status and capabilities
of the specified B<engine>'s.
Engines may be specified before and after all other command-line flags.
Only those specified are queried.
=head1 OPTIONS
=over 4
=item B<-v> B<-vv> B<-vvv> B<-vvvv>
Provides information about each specified engine. The first flag lists
all the possible run-time control commands; the second adds a
description of each command; the third adds the input flags, and the
final option adds the internal input flags.
=item B<-c>
Lists the capabilities of each engine.
=item B<-t>
Tests if each specified engine is available, and displays the answer.
=item B<-tt>
Displays an error trace for any unavailable engine.
=item B<-pre> I<command>
=item B<-post> I<command>
Command-line configuration of engines.
The B<-pre> command is given to the engine before it is loaded and
the B<-post> command is given after the engine is loaded.
The I<command> is of the form I<cmd:val> where I<cmd> is the command,
and I<val> is the value for the command.
See the example below.
=back
=head1 EXAMPLE
To list all the commands available to a dynamic engine:
% openssl engine -t -tt -vvvv dynamic
(dynamic) Dynamic engine loading support
[ unavailable ]
SO_PATH: Specifies the path to the new ENGINE shared library
(input flags): STRING
NO_VCHECK: Specifies to continue even if version checking fails (boolean)
(input flags): NUMERIC
ID: Specifies an ENGINE id name for loading
(input flags): STRING
LIST_ADD: Whether to add a loaded ENGINE to the internal list (0=no,1=yes,2=mandatory)
(input flags): NUMERIC
DIR_LOAD: Specifies whether to load from 'DIR_ADD' directories (0=no,1=yes,2=mandatory)
(input flags): NUMERIC
DIR_ADD: Adds a directory from which ENGINEs can be loaded
(input flags): STRING
LOAD: Load up the ENGINE specified by other settings
(input flags): NO_INPUT
To list the capabilities of the I<rsax> engine:
% openssl engine -c
(rsax) RSAX engine support
[RSA]
(dynamic) Dynamic engine loading support
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

18
doc/apps/errstr.pod
View File

@@ -11,10 +11,14 @@ 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
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 OPTIONS
None.
=head1 EXAMPLE
The error code:
@@ -22,18 +26,20 @@ 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
=head1 COPYRIGHT
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)>
Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

27
doc/apps/gendsa.pod
View File

@@ -7,6 +7,7 @@ gendsa - generate a DSA private key from a set of parameters
=head1 SYNOPSIS
B<openssl> B<gendsa>
[B<-help>]
[B<-out filename>]
[B<-aes128>]
[B<-aes192>]
@@ -30,6 +31,15 @@ The B<gendsa> command generates a DSA private key from a DSA parameter file
=over 4
=item B<-help>
Print out a usage message.
=item B<-out filename>
Output the key to the specified file. If this argument is not specified then
standard output is used.
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
These options encrypt the private key with specified
@@ -39,8 +49,8 @@ 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.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -66,7 +76,16 @@ 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)>
L<dsaparam(1)>, L<dsa(1)>, L<genrsa(1)>,
L<rsa(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

79
doc/apps/genpkey.pod
View File

@@ -7,6 +7,7 @@ genpkey - generate a private key
=head1 SYNOPSIS
B<openssl> B<genpkey>
[B<-help>]
[B<-out filename>]
[B<-outform PEM|DER>]
[B<-pass arg>]
@@ -26,10 +27,14 @@ The B<genpkey> command generates a private key.
=over 4
=item B<-help>
Print out a usage message.
=item B<-out filename>
the output filename. If this argument is not specified then standard output is
used.
Output the key to the specified file. If this argument is not specified then
standard output is used.
=item B<-outform DER|PEM>
@@ -38,7 +43,7 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-cipher>
@@ -68,14 +73,14 @@ 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.
precede any 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>
precede any B<-pkeyopt> options. The options B<-paramfile> and B<-algorithm>
are mutually exclusive.
=item B<-text>
@@ -87,7 +92,7 @@ parameters along with the PEM or DER structure.
=head1 KEY GENERATION OPTIONS
The options supported by each algorith and indeed each implementation of an
The options supported by each algorithm and indeed each implementation of an
algorithm can vary. The options for the OpenSSL implementations are detailed
below.
@@ -141,11 +146,20 @@ and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections
=head1 EC PARAMETER GENERATION OPTIONS
The EC parameter generation options below can also
be supplied as EC key generation options. This can (for example) generate a
key from a named curve without the need to use an explicit parameter file.
=over 4
=item B<ec_paramgen_curve:curve>
the EC curve to use.
the EC curve to use. OpenSSL supports NIST curve names such as "P-256".
=item B<ec_param_enc:encoding>
the encoding to use for parameters. The "encoding" parameter must be either
"named_curve" or "explicit".
=back
@@ -153,7 +167,7 @@ the EC curve to use.
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
See README.gost file in the engines/ccgost directory of the source
distribution for more details.
Use of a parameter file for the GOST R 34.10 algorithm is optional.
@@ -178,6 +192,9 @@ numeric OID. Following parameter sets are supported:
=back
=head1 X25519 KEY GENERATION OPTIONS
The X25519 algorithm does not currently support any key generation options.
=head1 NOTES
@@ -190,7 +207,7 @@ can be used.
Generate an RSA private key using default parameters:
openssl genpkey -algorithm RSA -out key.pem
openssl genpkey -algorithm RSA -out key.pem
Encrypt output private key using 128 bit AES and the passphrase "hello":
@@ -199,21 +216,21 @@ Encrypt output private key using 128 bit AES and the passphrase "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
-pkeyopt rsa_keygen_pubexp:3
Generate 1024 bit DSA parameters:
openssl genpkey -genparam -algorithm DSA -out dsap.pem \
-pkeyopt dsa_paramgen_bits:1024
-pkeyopt dsa_paramgen_bits:1024
Generate DSA key from parameters:
openssl genpkey -paramfile dsap.pem -out dsakey.pem
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
-pkeyopt dh_paramgen_prime_len:1024
Output RFC5114 2048 bit DH parameters with 224 bit subgroup:
@@ -221,8 +238,40 @@ Output RFC5114 2048 bit DH parameters with 224 bit subgroup:
Generate DH key from parameters:
openssl genpkey -paramfile dhp.pem -out dhkey.pem
openssl genpkey -paramfile dhp.pem -out dhkey.pem
Generate EC parameters:
openssl genpkey -genparam -algorithm EC -out ecp.pem \
-pkeyopt ec_paramgen_curve:secp384r1 \
-pkeyopt ec_param_enc:named_curve
Generate EC key from parameters:
openssl genpkey -paramfile ecp.pem -out eckey.pem
Generate EC key directly:
openssl genpkey -algorithm EC -out eckey.pem \
-pkeyopt ec_paramgen_curve:P-384 \
-pkeyopt ec_param_enc:named_curve
Generate an X25519 private key:
openssl genpkey -algorithm X25519 -out xkey.pem
=head1 HISTORY
The ability to use NIST curve names, and to generate an EC key directly,
were added in OpenSSL 1.0.2.
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

34
doc/apps/genrsa.pod
View File

@@ -7,11 +7,15 @@ genrsa - generate an RSA private key
=head1 SYNOPSIS
B<openssl> B<genrsa>
[B<-help>]
[B<-out filename>]
[B<-passout arg>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
[B<-aria128>]
[B<-aria192>]
[B<-aria256>]
[B<-camellia128>]
[B<-camellia192>]
[B<-camellia256>]
@@ -32,17 +36,21 @@ The B<genrsa> command generates an RSA private key.
=over 4
=item B<-help>
Print out a usage message.
=item B<-out filename>
the output filename. If this argument is not specified then standard output is
used.
Output the key to the specified file. 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
=item B<-aes128|-aes192|-aes256|-aria128|-aria192|-aria256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
These options encrypt the private key with specified
cipher before outputting it. If none of these options is
@@ -56,8 +64,8 @@ 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.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -71,7 +79,7 @@ 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.
specified. The default is 2048.
=back
@@ -96,7 +104,15 @@ be much larger (typically 1024 bits).
=head1 SEE ALSO
L<gendsa(1)|gendsa(1)>
L<gendsa(1)>
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

81
doc/apps/list.pod Normal file
View File

@@ -0,0 +1,81 @@
=pod
=head1 NAME
list - list algorithms and features
=head1 SYNOPSIS
B<openssl list>
[B<-help>]
[B<-commands>]
[B<-digest-commands>]
[B<-digest-algorithms>]
[B<-cipher-commands>]
[B<-cipher-algorithms>]
[B<-public-key-algorithms>]
[B<-disabled>]
=head1 DESCRIPTION
This command is used to generate list of algorithms or disabled
features.
=head1 OPTIONS
=over 4
=item B<-help>
Display out a usage message.
=item B<-commands>
Display a list of standard commands.
=item B<-digest-commands>
Display a list of message digest commands, which are typically used
as input to the L<dgst(1)> or L<speed(1)> commands.
=item B<-digest-algorithms>
Display a list of message digest algorithms.
If a line is of the form
foo => bar
then B<foo> is an alias for the official algorithm name, B<bar>.
=item B<-cipher-commands>
Display a list of cipher commands, which are typically used as input
to the L<dgst(1)> or L<speed(1)> commands.
=item B<-cipher-algorithms>
Display a list of cipher algorithms.
If a line is of the form
foo => bar
then B<foo> is an alias for the official algorithm name, B<bar>.
=item B<-public-key-algorithms>
Display a list of public key algorithms, with each algorithm as
a block of multiple lines, all but the first are indented.
=item B<-disabled>
Display a list of disabled features, those that were compiled out
of the installation.
=back
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

18
doc/apps/nseq.pod
View File

@@ -2,11 +2,12 @@
=head1 NAME
nseq - create or examine a netscape certificate sequence
nseq - create or examine a Netscape certificate sequence
=head1 SYNOPSIS
B<openssl> B<nseq>
[B<-help>]
[B<-in filename>]
[B<-out filename>]
[B<-toseq>]
@@ -18,10 +19,14 @@ 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
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies the input filename to read or standard input if this
@@ -67,4 +72,13 @@ It is used by Netscape certificate server for example.
This program needs a few more options: like allowing DER or PEM input and
output files and allowing multiple certificate files to be used.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

145
doc/apps/ocsp.pod
View File

@@ -7,6 +7,7 @@ ocsp - Online Certificate Status Protocol utility
=head1 SYNOPSIS
B<openssl> B<ocsp>
[B<-help>]
[B<-out file>]
[B<-issuer file>]
[B<-cert file>]
@@ -25,12 +26,41 @@ B<openssl> B<ocsp>
[B<-nonce>]
[B<-no_nonce>]
[B<-url URL>]
[B<-host host:n>]
[B<-header name value>]
[B<-host host:port>]
[B<-header>]
[B<-path>]
[B<-CApath dir>]
[B<-CAfile file>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-VAfile file>]
[B<-validity_period n>]
[B<-status_age n>]
@@ -65,10 +95,19 @@ 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
=head1 OPTIONS
This command operates as either a client or a server.
The options are described below, divided into those two modes.
=head2 OCSP Client Options
=over 4
=item B<-help>
Print out a usage message.
=item B<-out filename>
specify output filename, default is standard output.
@@ -107,7 +146,7 @@ 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
Normally if an OCSP request is input using the B<reqin> 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.
@@ -134,15 +173,14 @@ specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified.
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.
or "/" by default. This is equivalent to specifying B<-url> with scheme
http:// and the given hostname, port, and pathname.
=item B<-header name value>
=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.
Adds the header B<name> with the specified B<value> to the OCSP request
that is sent to the responder.
This may be repeated.
=item B<-timeout seconds>
@@ -153,9 +191,24 @@ connection timeout to the OCSP responder in seconds
file or pathname containing trusted CA certificates. These are used to verify
the signature on the OCSP response.
=item B<-no_alt_chains>
=item B<-no-CAfile>
See L<B<verify>|verify(1)> manual page for details.
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set different certificate verification options.
See L<verify(1)> manual page for details.
=item B<-verify_other file>
@@ -218,26 +271,29 @@ 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.
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.
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|...>
=item B<-[digest]>
this option sets digest algorithm to use for certificate identification
in the OCSP request. By default SHA-1 is used.
this option sets digest algorithm to use for certificate identification in the
OCSP request. Any digest supported by the OpenSSL B<dgst> command can be used.
The default is SHA-1. This option may be used multiple times to specify the
digest used by subsequent certificate identifiers.
=back
=head1 OCSP SERVER OPTIONS
=head2 OCSP Server Options
=over 4
@@ -249,7 +305,7 @@ 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).
B<reqin> 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.
@@ -286,13 +342,13 @@ option.
=item B<-nrequest number>
The OCSP server will exit after receiving B<number> requests, default unlimited.
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.
B<nextUpdate> field. If neither option is present then the B<nextUpdate> field
is omitted meaning fresh revocation information is immediately available.
=back
@@ -354,7 +410,7 @@ 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.
script using the B<reqin> and B<respout> options.
=head1 EXAMPLES
@@ -362,40 +418,49 @@ 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
Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the
response to a file, print it out in text form, and verify the response:
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
openssl ocsp -respin resp.der -text -noverify
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
-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:
Query status information using an 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.
Query status information using request read from a file, and write the 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.
The -no_alt_chains options was first added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

148
doc/apps/openssl.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -12,7 +11,7 @@ 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<list> [ B<standard-commands> | B<digest-commands> | B<cipher-commands> | B<cipher-algorithms> | B<digest-algorithms> | B<public-key-algorithms>]
B<openssl> B<no->I<XXX> [ I<arbitrary options> ]
@@ -23,12 +22,12 @@ 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
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 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
@@ -41,20 +40,29 @@ 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
Many commands use an external configuration file for some or all of their
arguments and have a B<-config> option to specify that file.
The environment variable B<OPENSSL_CONF> can be used to specify
the location of the file.
If the environment variable is not specified, then the file is named
B<openssl.cnf> in the default certificate storage area, whose value
depends on the configuration flags specified when the OpenSSL
was built.
The list parameters B<standard-commands>, B<digest-commands>,
and B<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:
The list parameters B<cipher-algorithms> and
B<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
The list parameter B<public-key-algorithms> lists all supported public
key algorithms.
The pseudo-command B<no->I<XXX> tests whether a command of the
The 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
@@ -63,11 +71,11 @@ 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.)
B<list>, or B<no->I<XXX> itself.)
=head2 STANDARD COMMANDS
=head2 Standard Commands
=over 10
=over 4
=item L<B<asn1parse>|asn1parse(1)>
@@ -75,7 +83,7 @@ Parse an ASN.1 sequence.
=item L<B<ca>|ca(1)>
Certificate Authority (CA) Management.
Certificate Authority (CA) Management.
=item L<B<ciphers>|ciphers(1)>
@@ -83,7 +91,7 @@ Cipher Suite Description Determination.
=item L<B<cms>|cms(1)>
CMS (Cryptographic Message Syntax) utility
CMS (Cryptographic Message Syntax) utility.
=item L<B<crl>|crl(1)>
@@ -104,9 +112,8 @@ 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)>
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)>
@@ -114,16 +121,16 @@ 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)>
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
EC (Elliptic curve) key processing.
=item L<B<ecparam>|ecparam(1)>
EC parameter manipulation and generation
EC parameter manipulation and generation.
=item L<B<enc>|enc(1)>
@@ -131,7 +138,7 @@ Encoding with Ciphers.
=item L<B<engine>|engine(1)>
Engine (loadble module) information and manipulation.
Engine (loadable module) information and manipulation.
=item L<B<errstr>|errstr(1)>
@@ -144,8 +151,8 @@ 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)>
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)>
@@ -153,11 +160,11 @@ Generation of Private Key or Parameters.
=item L<B<genrsa>|genrsa(1)>
Generation of RSA Private Key. Superceded by L<B<genpkey>|genpkey(1)>.
Generation of RSA Private Key. Superseded by L<B<genpkey>|genpkey(1)>.
=item L<B<nseq>|nseq(1)>
Create or examine a netscape certificate sequence
Create or examine a Netscape certificate sequence.
=item L<B<ocsp>|ocsp(1)>
@@ -203,7 +210,7 @@ RSA key management.
=item L<B<rsautl>|rsautl(1)>
RSA utility for signing, verification, encryption, and decryption. Superseded
by L<B<pkeyutl>|pkeyutl(1)>
by L<B<pkeyutl>|pkeyutl(1)>.
=item L<B<s_client>|s_client(1)>
@@ -239,11 +246,11 @@ Algorithm Speed Measurement.
=item L<B<spkac>|spkac(1)>
SPKAC printing and generating utility
SPKAC printing and generating utility.
=item L<B<ts>|ts(1)>
Time Stamping Authority tool (client/server)
Time Stamping Authority tool (client/server).
=item L<B<verify>|verify(1)>
@@ -259,9 +266,9 @@ X.509 Certificate Data Management.
=back
=head2 MESSAGE DIGEST COMMANDS
=head2 Message Digest Commands
=over 10
=over 4
=item B<md2>
@@ -279,11 +286,11 @@ MDC2 Digest
RMD-160 Digest
=item B<sha>
=item B<sha>
SHA Digest
=item B<sha1>
=item B<sha1>
SHA-1 Digest
@@ -305,9 +312,9 @@ SHA-512 Digest
=back
=head2 ENCODING AND CIPHER COMMANDS
=head2 Encoding and Cipher Commands
=over 10
=over 4
=item B<base64>
@@ -351,7 +358,22 @@ RC5 Cipher
=back
=head1 PASS PHRASE ARGUMENTS
=head1 OPTIONS
Details of which options are available depend on the specific command.
This section describes some common options with common behavior.
=head2 Common Options
=over 4
=item B<-help>
Provides a terse summary of all options.
=back
=head2 Pass Phrase Options
Several commands accept password arguments, typically using B<-passin>
and B<-passout> for input and output passwords respectively. These allow
@@ -361,23 +383,23 @@ 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
=over 4
=item B<pass:password>
the actual password is B<password>. Since the password is visible
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
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>
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
@@ -385,38 +407,44 @@ 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
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.
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)>
L<asn1parse(1)>, L<ca(1)>, L<config(5)>,
L<crl(1)>, L<crl2pkcs7(1)>, L<dgst(1)>,
L<dhparam(1)>, L<dsa(1)>, L<dsaparam(1)>,
L<enc(1)>, L<engine(1)>, L<gendsa(1)>, L<genpkey(1)>,
L<genrsa(1)>, L<nseq(1)>, L<openssl(1)>,
L<passwd(1)>,
L<pkcs12(1)>, L<pkcs7(1)>, L<pkcs8(1)>,
L<rand(1)>, L<req(1)>, L<rsa(1)>,
L<rsautl(1)>, L<s_client(1)>,
L<s_server(1)>, L<s_time(1)>,
L<smime(1)>, L<spkac(1)>,
L<verify(1)>, L<version(1)>, L<x509(1)>,
L<crypto(7)>, L<ssl(7)>, L<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.
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

14
doc/apps/passwd.pod
View File

@@ -7,6 +7,7 @@ passwd - compute password hashes
=head1 SYNOPSIS
B<openssl passwd>
[B<-help>]
[B<-crypt>]
[B<-1>]
[B<-apr1>]
@@ -31,6 +32,10 @@ algorithm B<1> and its Apache variant B<apr1> are available.
=over 4
=item B<-help>
Print out a usage message.
=item B<-crypt>
Use the B<crypt> algorithm (default).
@@ -79,4 +84,13 @@ B<openssl passwd -1 -salt xxxxxxxx password> prints B<$1$xxxxxxxx$UYCIxa628.9qXj
B<openssl passwd -apr1 -salt xxxxxxxx password> prints B<$apr1$xxxxxxxx$dxHfLAsjHkDRmG83UXe8K0>.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

84
doc/apps/pkcs12.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,9 +7,10 @@ pkcs12 - PKCS#12 file utility
=head1 SYNOPSIS
B<openssl> B<pkcs12>
[B<-help>]
[B<-export>]
[B<-chain>]
[B<-inkey filename>]
[B<-inkey file_or_id>]
[B<-certfile filename>]
[B<-name name>]
[B<-caname name>]
@@ -39,6 +39,8 @@ B<openssl> B<pkcs12>
[B<-rand file(s)>]
[B<-CAfile file>]
[B<-CApath dir>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-CSP name>]
=head1 DESCRIPTION
@@ -47,7 +49,7 @@ 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
=head1 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
@@ -57,6 +59,10 @@ file can be created by using the B<-export> option (see below).
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies filename of the PKCS#12 file to be parsed. Standard input is used
@@ -71,13 +77,13 @@ default. They are all written in PEM format.
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)>.
L<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)>.
in L<openssl(1)>.
=item B<-password arg>
@@ -167,10 +173,12 @@ 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>
=item B<-inkey file_or_id>
file to read private key from. If not present then a private key must be present
in the input file.
If no engine is used, the argument is taken as a file; if an engine is
specified, the argument is given to the engine as a key identifier.
=item B<-name friendlyname>
@@ -192,13 +200,13 @@ displays them.
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)>.
L<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)>.
L<openssl(1)>.
=item B<-chain>
@@ -266,8 +274,8 @@ 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.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -281,6 +289,14 @@ 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<-no-CAfile>
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-CSP name>
write B<name> as a Microsoft CSP name.
@@ -311,6 +327,16 @@ 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.
Prior 1.1 release passwords containing non-ASCII characters were encoded
in non-compliant manner, which limited interoperability, in first hand
with Windows. But switching to standard-compliant password encoding
poses problem accessing old data protected with broken encoding. For
this reason even legacy encodings is attempted when reading the
data. If you use PKCS#12 files in production application you are advised
to convert the data, because implemented heuristic approach is not
MT-safe, its sole goal is to facilitate the data upgrade with this
utility.
=head1 EXAMPLES
Parse a PKCS#12 file and output it to a file:
@@ -322,7 +348,7 @@ 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:
@@ -338,31 +364,17 @@ 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)>
L<pkcs8(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

22
doc/apps/pkcs7.pod
View File

@@ -7,6 +7,7 @@ pkcs7 - PKCS#7 utility
=head1 SYNOPSIS
B<openssl> B<pkcs7>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
@@ -20,10 +21,14 @@ B<openssl> B<pkcs7>
The B<pkcs7> command processes PKCS#7 files in DER or PEM format.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. B<DER> format is DER encoded PKCS#7
@@ -32,7 +37,7 @@ 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
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -95,11 +100,20 @@ For compatibility with some CAs it will also accept:
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
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)>
L<crl2pkcs7(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

186
doc/apps/pkcs8.pod
View File

@@ -7,6 +7,7 @@ pkcs8 - PKCS#8 format private key conversion tool
=head1 SYNOPSIS
B<openssl> B<pkcs8>
[B<-help>]
[B<-topk8>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
@@ -14,15 +15,18 @@ B<openssl> B<pkcs8>
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-iter count>]
[B<-noiter>]
[B<-nocrypt>]
[B<-nooct>]
[B<-embed>]
[B<-nsdb>]
[B<-traditional>]
[B<-v2 alg>]
[B<-v2prf alg>]
[B<-v1 alg>]
[B<-engine id>]
[B<-scrypt>]
[B<-scrypt_N N>]
[B<-scrypt_r r>]
[B<-scrypt_p p>]
=head1 DESCRIPTION
@@ -30,28 +34,32 @@ 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
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=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.
Normally a PKCS#8 private key is expected on input and a private key will be
written to the output file. With the B<-topk8> option the situation is
reversed: it reads a 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.
This specifies the input format: see L<KEY FORMATS> for more details.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
This specifies the output format: see L<KEY FORMATS> for more details.
=item B<-traditional>
When this option is present and B<-topk8> is not a traditional format private
key is written.
=item B<-in filename>
@@ -62,7 +70,7 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-out filename>
@@ -74,7 +82,13 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-iter count>
When creating new PKCS#8 containers, use a given number of iterations on
the password in deriving the encryption key for the PKCS#8 output.
High values increase the time required to brute-force a PKCS#8 container.
=item B<-nocrypt>
@@ -85,50 +99,28 @@ 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.
This option sets the PKCS#5 v2.0 algorithm.
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.
B<aes128>, B<aes256> and B<des3>. If this option isn't specified then B<aes256>
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.
value would be B<hmacWithSHA256>. If this option isn't set then the default
for the cipher is used or B<hmacWithSHA256> if there is no default.
Some implementations may not support custom PRF algorithms and may require
the B<hmacWithSHA1> option to work.
=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.
This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used. Some
older implementations may not support PKCS#5 v2.0 and may require this option.
If not specified PKCS#5 v2.0 form is used.
=item B<-engine id>
@@ -137,10 +129,49 @@ 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<-scrypt>
uses the B<scrypt> algorithm for private key encryption using default
parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with a 256 bit
key. These parameters can be modified using the B<-scrypt_N>, B<-scrypt_r>,
B<-scrypt_p> and B<-v2> options.
B<-scrypt_N N> B<-scrypt_r r> B<-scrypt_p p>
sets the scrypt B<N>, B<r> or B<p> parameters.
=back
=head1 KEY FORMATS
Various different formats are used by the pkcs8 utility. These are detailed
below.
If a key is being converted from PKCS#8 form (i.e. the B<-topk8> option is
not used) then the input file must be in PKCS#8 format. An encrypted
key is expected unless B<-nocrypt> is included.
If B<-topk8> is not used and B<PEM> mode is set the output file will be an
unencrypted private key in PKCS#8 format. If the B<-traditional> option is
used then a traditional format private key is written instead.
If B<-topk8> is not used and B<DER> mode is set the output file will be an
unencrypted private key in traditional DER format.
If B<-topk8> is used then any supported private key can be used for the input
file in a format specified by B<-inform>. The output file will be encrypted
PKCS#8 format using the specified encryption parameters unless B<-nocrypt>
is included.
=head1 NOTES
By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit
AES with HMAC and SHA256 is used.
Some older implementations do not support PKCS#5 v2.0 format and require
the older PKCS#5 v1.5 form instead, possibly also requiring insecure weak
encryption algorithms such as 56 bit DES.
The encrypted form of a PEM encode PKCS#8 files uses the following
headers and footers:
@@ -157,13 +188,6 @@ 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.
@@ -197,20 +221,28 @@ allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.
=head1 EXAMPLES
Convert a private from traditional to PKCS#5 v2.0 format using triple
DES:
Convert a private key to PKCS#8 format using default parameters (AES with
256 bit key and B<hmacWithSHA256>):
openssl pkcs8 -in key.pem -topk8 -out enckey.pem
Convert a private key to PKCS#8 unencrypted format:
openssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem
Convert a private key 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:
Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC
mode and B<hmacWithSHA512> PRF:
openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -out enckey.pem
openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -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
openssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem
Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
(3DES):
@@ -221,9 +253,14 @@ 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:
Convert a private key from any PKCS#8 encrypted format to traditional format:
openssl pkcs8 -in pk8.pem -out key.pem
openssl pkcs8 -in pk8.pem -traditional -out key.pem
Convert a private key to PKCS#8 format, encrypting with AES-256 and with
one million iterations of the password:
openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem
=head1 STANDARDS
@@ -243,13 +280,22 @@ PKCS#8 private key format complies with this standard.
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)>
L<dsa(1)>, L<rsa(1)>, L<genrsa(1)>,
L<gendsa(1)>
=head1 HISTORY
The B<-iter> option was added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

38
doc/apps/pkey.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,12 +7,14 @@ pkey - public or private key processing tool
=head1 SYNOPSIS
B<openssl> B<pkey>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-traditional>]
[B<-cipher>]
[B<-text>]
[B<-text_pub>]
@@ -27,17 +28,21 @@ B<openssl> B<pkey>
The B<pkey> command processes public or private keys. They can be converted
between various forms and their components printed out.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=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
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -49,7 +54,7 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-out filename>
@@ -61,7 +66,13 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-traditional>
normally a private key is written using standard format: this is PKCS#8 form
with the appropriate encryption algorithm (if any). If the B<-traditional>
option is specified then the older "traditional" format is used instead.
=item B<-cipher>
@@ -71,7 +82,7 @@ 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.
plain text in addition to the encoded version.
=item B<-text_pub>
@@ -111,7 +122,7 @@ 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:
To convert a private key from PEM to DER format:
openssl pkey -in key.pem -outform DER -out keyout.der
@@ -129,7 +140,16 @@ To just output the public part of a private key:
=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)>
L<genpkey(1)>, L<rsa(1)>, L<pkcs8(1)>,
L<dsa(1)>, L<genrsa(1)>, L<gendsa(1)>
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

23
doc/apps/pkeyparam.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,6 +7,7 @@ pkeyparam - public key algorithm parameter processing tool
=head1 SYNOPSIS
B<openssl> B<pkeyparam>
[B<-help>]
[B<-in filename>]
[B<-out filename>]
[B<-text>]
@@ -19,10 +19,14 @@ B<openssl> B<pkeyparam>
The B<pkey> command processes public or private keys. They can be converted
between various forms and their components printed out.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies the input filename to read parameters from or standard input if
@@ -35,7 +39,7 @@ this option is not specified.
=item B<-text>
prints out the parameters in plain text in addition to the encoded version.
prints out the parameters in plain text in addition to the encoded version.
=item B<-noout>
@@ -63,7 +67,16 @@ 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)>
L<genpkey(1)>, L<rsa(1)>, L<pkcs8(1)>,
L<dsa(1)>, L<genrsa(1)>, L<gendsa(1)>
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

109
doc/apps/pkeyutl.pod
View File

@@ -7,14 +7,15 @@ pkeyutl - public key algorithm utility
=head1 SYNOPSIS
B<openssl> B<pkeyutl>
[B<-help>]
[B<-in file>]
[B<-out file>]
[B<-sigfile file>]
[B<-inkey file>]
[B<-keyform PEM|DER>]
[B<-keyform PEM|DER|ENGINE>]
[B<-passin arg>]
[B<-peerkey file>]
[B<-peerform PEM|DER>]
[B<-peerform PEM|DER|ENGINE>]
[B<-pubin>]
[B<-certin>]
[B<-rev>]
@@ -24,20 +25,27 @@ B<openssl> B<pkeyutl>
[B<-encrypt>]
[B<-decrypt>]
[B<-derive>]
[B<-kdf algorithm>]
[B<-kdflen length>]
[B<-pkeyopt opt:value>]
[B<-hexdump>]
[B<-asn1parse>]
[B<-engine id>]
[B<-engine_impl>]
=head1 DESCRIPTION
The B<pkeyutl> command can be used to perform public key operations using
any supported algorithm.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies the input filename to read data from or standard input
@@ -48,43 +56,39 @@ if this option is not specified.
specifies the output filename to write to or standard output by
default.
=item B<-sigfile file>
Signature file, required for B<verify> operations only
=item B<-inkey file>
the input key file, by default it should be a private key.
=item B<-keyform PEM|DER>
=item B<-keyform PEM|DER|ENGINE>
the key format PEM, DER or ENGINE.
the key format PEM, DER or ENGINE. Default is PEM.
=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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<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<-peerform PEM|DER|ENGINE>
the peer key format PEM, DER or ENGINE. Default is PEM.
=item B<-pubin>
the input file is a public key.
the input file is a public key.
=item B<-certin>
the input is a certificate containing a public key.
the input is a certificate containing a public key.
=item B<-rev>
@@ -117,6 +121,23 @@ decrypt the input data using a private key.
derive a shared secret using the peer key.
=item B<-kdf algorithm>
Use key derivation function B<algorithm>. The supported algorithms are
at present B<TLS1-PRF> and B<HKDF>.
Note: additional parameters and the KDF output length will normally have to be
set for this to work.
See L<EVP_PKEY_CTX_set_hkdf_md(3)> and L<EVP_PKEY_CTX_set_tls1_prf_md(3)>
for the supported string parameters of each algorithm.
=item B<-kdflen length>
Set the output length for KDF.
=item B<-pkeyopt opt:value>
Public key options specified as opt:value. See NOTES below for more details.
=item B<-hexdump>
hex dump the output data.
@@ -126,6 +147,18 @@ hex dump the output data.
asn1parse the output data, this is useful when combined with the
B<-verifyrecover> option when an ASN1 structure is signed.
=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<-engine_impl>
When used with the B<-engine> option, it specifies to also use
engine B<id> for crypto operations.
=back
=head1 NOTES
@@ -153,24 +186,25 @@ 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.
The RSA algorithm generally supports the encrypt, decrypt, sign,
verify and verifyrecover operations. However, some padding modes
support only a subset of these operations. The following additional
B<pkeyopt> values are supported:
=over 4
=item -B<rsa_padding_mode:mode>
=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
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<oaep> 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,
@@ -207,6 +241,11 @@ 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 X25519 ALGORITHM
The X25519 algorithm supports key derivation only. Currently there are no
additional options.
=head1 EXAMPLES
Sign some data using a private key:
@@ -229,7 +268,25 @@ Derive a shared secret value:
openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret
Hexdump 48 bytes of TLS1 PRF using digest B<SHA256> and shared secret and
seed consisting of the single byte 0xFF:
openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \
-pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump
=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)>
L<genpkey(1)>, L<pkey(1)>, L<rsautl(1)>
L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>,
L<EVP_PKEY_CTX_set_hkdf_md(3)>, L<EVP_PKEY_CTX_set_tls1_prf_md(3)>
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

20
doc/apps/rand.pod
View File

@@ -7,6 +7,7 @@ rand - generate pseudo-random bytes
=head1 SYNOPSIS
B<openssl rand>
[B<-help>]
[B<-out> I<file>]
[B<-rand> I<file(s)>]
[B<-base64>]
@@ -26,15 +27,19 @@ seeding was obtained from these sources.
=over 4
=item B<-help>
Print out a usage message.
=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)>)
Use specified file or files or EGD socket (see L<RAND_egd(3)>)
for seeding the random number generator.
Multiple files can be specified separated by a OS-dependent character.
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -50,6 +55,15 @@ Show the output as a hex string.
=head1 SEE ALSO
L<RAND_bytes(3)|RAND_bytes(3)>
L<RAND_bytes(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

69
doc/apps/c_rehash.pod → doc/apps/rehash.pod
View File

@@ -5,20 +5,29 @@ Original text by James Westby, contributed under the OpenSSL license.
=head1 NAME
c_rehash - Create symbolic links to files named by the hash values
c_rehash, rehash - Create symbolic links to files named by the hash values
=head1 SYNOPSIS
B<c_rehash>
B<[-old]>
B<openssl>
B<rehash>
B<[-h]>
B<[-help]>
B<[-old]>
B<[-n]>
B<[-v]>
[ I<directory>...]
B<c_rehash>
I<flags...>
=head1 DESCRIPTION
B<c_rehash> scans directories and calculates a hash value of each
On some platforms, the OpenSSL B<rehash> command is available as
an external script called B<c_rehash>. They are functionally equivalent,
except for minor differences noted below.
B<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.
@@ -28,18 +37,19 @@ 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,
is consulted; this should 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.
permissions on that directory, otherwise an error will be generated.
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.
When processing a directory, B<rehash> will first remove all links
that have a name in that syntax, even if they are being used for some
other purpose.
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>.
@@ -50,9 +60,13 @@ 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.
cannot be parsed as either a certificate or a CRL or if
more than one such object appears in the file.
The program uses the B<openssl> program to compute the hashes and
=head2 Script Configuration
The B<c_rehash> script
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
@@ -69,15 +83,15 @@ optionally prefixed with some text and an equals sign.
=over 4
=item B<-help> B<-h>
Display a brief usage message.
=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.
links to be used for releases before 1.0.0.
Note that current versions will not use the old style.
=item B<-n>
@@ -87,13 +101,13 @@ 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.
By default, B<rehash> only lists each directory as it is processed.
=back
=head1 ENVIRONMENT
=over
=over 4
=item B<OPENSSL>
@@ -109,6 +123,17 @@ Ignored if directories are listed on the command line.
=head1 SEE ALSO
L<openssl(1)|openssl(1)>,
L<crl(1)|crl(1)>.
L<x509(1)|x509(1)>.
L<openssl(1)>,
L<crl(1)>.
L<x509(1)>.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

195
doc/apps/req.pod
View File

@@ -1,13 +1,13 @@
=pod
=head1 NAME
req - PKCS#10 certificate request and certificate generating utility.
req - PKCS#10 certificate request and certificate generating utility
=head1 SYNOPSIS
B<openssl> B<req>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
@@ -34,8 +34,6 @@ B<openssl> B<req>
[B<-x509>]
[B<-days n>]
[B<-set_serial n>]
[B<-asn1-kludge>]
[B<-no-asn1-kludge>]
[B<-newhdr>]
[B<-extensions section>]
[B<-reqexts section>]
@@ -54,10 +52,14 @@ 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
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -67,7 +69,7 @@ footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -79,7 +81,7 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-out filename>
@@ -89,7 +91,7 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-text>
@@ -127,18 +129,11 @@ 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.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -152,13 +147,13 @@ 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.
or and X.509 certificate for a key with appropriate 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.
if necessary 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
@@ -198,8 +193,9 @@ 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
this specifies the message digest to sign the request.
Any digest supported by the OpenSSL B<dgst> command can be used.
This overrides the digest algorithm specified in
the configuration file.
Some public key algorithms may override this choice. For instance, DSA
@@ -208,9 +204,9 @@ 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.
this allows an alternative configuration file to be specified.
Optional; for a description of the default value,
see L<openssl(1)/COMMAND SUMMARY>.
=item B<-subj arg>
@@ -237,6 +233,9 @@ a self signed root CA. The extensions added to the certificate
using the B<set_serial> option, a large random number will be used for
the serial number.
If existing request is specified with the B<-in> option, it is converted
to the self signed certificate otherwise new request is created.
=item B<-days n>
when the B<-x509> option is being used this specifies the number of
@@ -246,7 +245,6 @@ days to certify the certificate for. The default is 30 days.
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>
@@ -260,7 +258,7 @@ a variety of purposes.
=item B<-utf8>
this option causes field values to be interpreted as UTF8 strings, by
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.
@@ -270,36 +268,16 @@ configuration file, must be valid UTF8 strings.
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.
set multiple options. See the L<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.
a single option or multiple options separated by commas.
See discission of the B<-certopt> parameter in the L<B<x509>|x509(1)>
See discussion of the B<-certopt> parameter in the L<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
@@ -365,7 +343,7 @@ overridden by the B<-keyout> option.
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.
by white space and finally the long name.
=item B<oid_section>
@@ -377,7 +355,7 @@ 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)>).
placed and read from, or an EGD socket (see L<RAND_egd(3)>).
It is used for private key generation.
=item B<encrypt_key>
@@ -388,9 +366,10 @@ 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.
This option specifies the digest algorithm to use.
Any digest supported by the OpenSSL B<dgst> command can be used.
If not present then MD5 is used.
This option can be overridden on the command line.
=item B<string_mask>
@@ -398,7 +377,7 @@ 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
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
@@ -410,8 +389,8 @@ problems with BMPStrings and UTF8Strings: in particular Netscape.
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
by the B<-reqexts> command line switch. See the
L<x509v3_config(5)> manual page for details of the
extension section format.
=item B<x509_extensions>
@@ -521,8 +500,8 @@ Generate a self signed root certificate:
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
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:
@@ -533,65 +512,65 @@ expansion:
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
default_bits = 2048
default_keyfile = privkey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
req_extensions = v3_ca
dirstring_type = nobmp
[ req_distinguished_name ]
countryName = Country Name (2 letter code)
countryName_default = AU
countryName_min = 2
countryName_max = 2
countryName = Country Name (2 letter code)
countryName_default = AU
countryName_min = 2
countryName_max = 2
localityName = Locality Name (eg, city)
localityName = Locality Name (eg, city)
organizationalUnitName = Organizational Unit Name (eg, section)
organizationalUnitName = Organizational Unit Name (eg, section)
commonName = Common Name (eg, YOUR name)
commonName_max = 64
commonName = Common Name (eg, YOUR name)
commonName_max = 64
emailAddress = Email Address
emailAddress_max = 40
emailAddress = Email Address
emailAddress_max = 40
[ req_attributes ]
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20
[ v3_ca ]
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer:always
basicConstraints = CA:true
basicConstraints = critical, CA:true
Sample configuration containing all field values:
RANDFILE = $ENV::HOME/.rnd
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
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
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
challengePassword = A challenge password
=head1 NOTES
@@ -618,13 +597,13 @@ by the script in an extendedKeyUsage extension.
The following messages are frequently asked about:
Using configuration from /some/path/openssl.cnf
Unable to load config info
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
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
@@ -647,13 +626,6 @@ 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
@@ -673,8 +645,17 @@ 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)>
L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
L<gendsa(1)>, L<config(5)>,
L<x509v3_config(5)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

40
doc/apps/rsa.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,13 +7,13 @@ rsa - RSA key processing tool
=head1 SYNOPSIS
B<openssl> B<rsa>
[B<-help>]
[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>]
@@ -42,10 +41,14 @@ 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
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|NET|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -57,7 +60,7 @@ section.
=item B<-outform DER|NET|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -69,7 +72,7 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-out filename>
@@ -81,12 +84,7 @@ 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.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
@@ -101,7 +99,7 @@ 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.
plain text in addition to the encoded version.
=item B<-noout>
@@ -165,8 +163,7 @@ 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.
to the B<rsa> utility with the B<-inform NET> option.
=head1 EXAMPLES
@@ -178,7 +175,7 @@ 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:
To convert a private key from PEM to DER format:
openssl rsa -in key.pem -outform DER -out keyout.der
@@ -204,7 +201,16 @@ 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)>
L<pkcs8(1)>, L<dsa(1)>, L<genrsa(1)>,
L<gendsa(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

63
doc/apps/rsautl.pod
View File

@@ -7,9 +7,11 @@ rsautl - RSA utility
=head1 SYNOPSIS
B<openssl> B<rsautl>
[B<-help>]
[B<-in file>]
[B<-out file>]
[B<-inkey file>]
[B<-keyform PEM|DER|ENGINE>]
[B<-pubin>]
[B<-certin>]
[B<-sign>]
@@ -27,10 +29,14 @@ B<openssl> B<rsautl>
The B<rsautl> command can be used to sign, verify, encrypt and decrypt
data using the RSA algorithm.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies the input filename to read data from or standard input
@@ -45,18 +51,22 @@ default.
the input key file, by default it should be an RSA private key.
=item B<-keyform PEM|DER|ENGINE>
the key format PEM, DER or ENGINE.
=item B<-pubin>
the input file is an RSA public key.
the input file is an RSA public key.
=item B<-certin>
the input is a certificate containing an RSA public key.
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.
an RSA private key.
=item B<-verify>
@@ -126,24 +136,24 @@ 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 ]
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
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
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
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
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:
@@ -151,18 +161,18 @@ 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
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
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
@@ -180,4 +190,15 @@ 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)>
L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

320
doc/apps/s_client.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,7 +7,12 @@ s_client - SSL/TLS client program
=head1 SYNOPSIS
B<openssl> B<s_client>
[B<-help>]
[B<-connect host:port>]
[B<-proxy host:port>]
[B<-unix path>]
[B<-4>]
[B<-6>]
[B<-servername name>]
[B<-verify depth>]
[B<-verify_return_error>]
@@ -19,9 +23,40 @@ B<openssl> B<s_client>
[B<-pass arg>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-dane_tlsa_domain domain>]
[B<-dane_tlsa_rrdata rrdata>]
[B<-dane_ee_no_namechecks>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-reconnect>]
[B<-pause>]
[B<-showcerts>]
[B<-debug>]
[B<-msg>]
@@ -32,19 +67,31 @@ B<openssl> B<s_client>
[B<-ign_eof>]
[B<-no_ign_eof>]
[B<-quiet>]
[B<-ssl2>]
[B<-ssl3>]
[B<-tls1>]
[B<-no_ssl2>]
[B<-tls1_1>]
[B<-tls1_2>]
[B<-no_ssl3>]
[B<-no_tls1>]
[B<-no_tls1_1>]
[B<-no_tls1_2>]
[B<-dtls>]
[B<-dtls1>]
[B<-dtls1_2>]
[B<-fallback_scsv>]
[B<-async>]
[B<-split_send_frag>]
[B<-max_pipelines>]
[B<-read_buf>]
[B<-bugs>]
[B<-comp>]
[B<-no_comp>]
[B<-sigalgs sigalglist>]
[B<-curves curvelist>]
[B<-cipher cipherlist>]
[B<-serverpref>]
[B<-starttls protocol>]
[B<-xmpphost hostname>]
[B<-engine id>]
[B<-tlsextdebug>]
[B<-no_ticket>]
@@ -55,6 +102,8 @@ B<openssl> B<s_client>
[B<-status>]
[B<-alpn protocols>]
[B<-nextprotoneg protocols>]
[B<-ct|noct>]
[B<-ctlogfile>]
=head1 DESCRIPTION
@@ -64,13 +113,40 @@ SSL servers.
=head1 OPTIONS
In addition to the options below the B<s_client> utility also supports the
common and client only options documented in the
in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)>
manual page.
=over 4
=item B<-help>
Print out a usage message.
=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<-proxy host:port>
When used with the B<-connect> flag, the program uses the host and port
specified with this flag and issues an HTTP CONNECT command to connect
to the desired server.
=item B<-unix path>
Connect over the specified Unix-domain socket.
=item B<-4>
Use IPv4 only.
=item B<-6>
Use IPv6 only.
=item B<-servername name>
Set the TLS SNI (Server Name Indication) extension in the ClientHello message.
@@ -96,7 +172,7 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-verify depth>
@@ -122,20 +198,86 @@ also used when building the client certificate chain.
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>
=item B<-no-CAfile>
Set various certificate chain valiadition option. See the
L<B<verify>|verify(1)> manual page for details.
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-dane_tlsa_domain domain>
Enable RFC6698/RFC7671 DANE TLSA authentication and specify the
TLSA base domain which becomes the default SNI hint and the primary
reference identifier for hostname checks. This must be used in
combination with at least one instance of the B<-dane_tlsa_rrdata>
option below.
When DANE authentication succeeds, the diagnostic output will include
the lowest (closest to 0) depth at which a TLSA record authenticated
a chain certificate. When that TLSA record is a "2 1 0" trust
anchor public key that signed (rather than matched) the top-most
certificate of the chain, the result is reported as "TA public key
verified". Otherwise, either the TLSA record "matched TA certificate"
at a positive depth or else "matched EE certificate" at depth 0.
=item B<-dane_tlsa_rrdata rrdata>
Use one or more times to specify the RRDATA fields of the DANE TLSA
RRset associated with the target service. The B<rrdata> value is
specied in "presentation form", that is four whitespace separated
fields that specify the usage, selector, matching type and associated
data, with the last of these encoded in hexadecimal. Optional
whitespace is ignored in the associated data field. For example:
$ openssl s_client -brief -starttls smtp \
-connect smtp.example.com:25 \
-dane_tlsa_domain smtp.example.com \
-dane_tlsa_rrdata "2 1 1
B111DD8A1C2091A89BD4FD60C57F0716CCE50FEEFF8137CDBEE0326E 02CF362B" \
-dane_tlsa_rrdata "2 1 1
60B87575447DCBA2A36B7D11AC09FB24A9DB406FEE12D2CC90180517 616E8A18"
...
Verification: OK
Verified peername: smtp.example.com
DANE TLSA 2 1 1 ...ee12d2cc90180517616e8a18 matched TA certificate at depth 1
...
=item B<-dane_ee_no_namechecks>
This disables server name checks when authenticating via DANE-EE(3) TLSA
records.
For some applications, primarily web browsers, it is not safe to disable name
checks due to "unknown key share" attacks, in which a malicious server can
convince a client that a connection to a victim server is instead a secure
connection to the malicious server.
The malicious server may then be able to violate cross-origin scripting
restrictions.
Thus, despite the text of RFC7671, name checks are by default enabled for
DANE-EE(3) TLSA records, and can be disabled in applications where it is safe
to do so.
In particular, SMTP and XMPP clients should set this option as SRV and MX
records already make it possible for a remote domain to redirect client
connections to any server of its choice, and in any case SMTP and XMPP clients
do not execute scripts downloaded from remote servers.
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set various certificate chain validation options. See the
L<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
@@ -164,6 +306,15 @@ print extensive debugging information including a hex dump of all traffic.
show all protocol messages with hex dump.
=item B<-trace>
show verbose trace output of protocol messages. OpenSSL needs to be compiled
with B<enable-ssl-trace> for this option to work.
=item B<-msgfile>
file to send output of B<-msg> or B<-trace> to, default standard output.
=item B<-nbio_test>
tests non-blocking I/O
@@ -202,21 +353,91 @@ 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>
=item B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, 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.
By default B<s_client> will negotiate the highest mutually supported protocol
version.
When a specific TLS version is required, only that version will be offered to
and accepted from the server.
=item B<-dtls>, B<-dtls1>, B<-dtls1_2>
These options make B<s_client> use DTLS protocols instead of TLS.
With B<-dtls>, B<s_client> will negotiate any supported DTLS protocol version,
whilst B<-dtls1> and B<-dtls1_2> will only support DTLS1.0 and DTLS1.2
respectively.
=item B<-fallback_scsv>
Send TLS_FALLBACK_SCSV in the ClientHello.
=item B<-async>
switch on asynchronous mode. Cryptographic operations will be performed
asynchronously. This will only have an effect if an asynchronous capable engine
is also used via the B<-engine> option. For test purposes the dummy async engine
(dasync) can be used (if available).
=item B<-split_send_frag int>
The size used to split data for encrypt pipelines. If more data is written in
one go than this value then it will be split into multiple pipelines, up to the
maximum number of pipelines defined by max_pipelines. This only has an effect if
a suitable ciphersuite has been negotiated, an engine that supports pipelining
has been loaded, and max_pipelines is greater than 1. See
L<SSL_CTX_set_split_send_fragment(3)> for further information.
=item B<-max_pipelines int>
The maximum number of encrypt/decrypt pipelines to be used. This will only have
an effect if an engine has been loaded that supports pipelining (e.g. the dasync
engine) and a suitable ciphersuite has been negotiated. The default value is 1.
See L<SSL_CTX_set_max_pipelines(3)> for further information.
=item B<-read_buf int>
The default read buffer size to be used for connections. This will only have an
effect if the buffer size is larger than the size that would otherwise be used
and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for
further information).
=item B<-bugs>
there are several known bug in SSL and TLS implementations. Adding this
option enables various workarounds.
=item B<-comp>
Enables support for SSL/TLS compression.
This option was introduced in OpenSSL 1.1.0.
TLS compression is not recommended and is off by default as of
OpenSSL 1.1.0.
=item B<-no_comp>
Disables support for SSL/TLS compression.
TLS compression is not recommended and is off by default as of
OpenSSL 1.1.0.
=item B<-brief>
only provide a brief summary of connection parameters instead of the
normal verbose output.
=item B<-sigalgs sigalglist>
Specifies the list of signature algorithms that are sent by the client.
The server selects one entry in the list based on its preferences.
For example strings, see L<SSL_CTX_set1_sigalgs(3)>
=item B<-curves curvelist>
Specifies the list of supported curves to be sent by the client. The curve is
is ultimately selected by the server. For a list of all curves, use:
$ openssl ecparam -list_curves
=item B<-cipher cipherlist>
this allows the cipher list sent by the client to be modified. Although
@@ -224,15 +445,19 @@ 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".
supported keywords are "smtp", "pop3", "imap", "ftp", "xmpp", "xmpp-server",
and "irc."
=item B<-xmpphost hostname>
This option, when used with "-starttls xmpp" or "-starttls xmpp-server",
specifies the host for the "to" attribute of the stream element.
If this option is not specified, then the host specified with "-connect"
will be used.
=item B<-tlsextdebug>
@@ -240,7 +465,7 @@ print out a hex dump of any TLS extensions received from the server.
=item B<-no_ticket>
disable RFC4507bis session ticket support.
disable RFC4507bis session ticket support.
=item B<-sess_out filename>
@@ -261,14 +486,14 @@ 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.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an 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
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.
@@ -291,7 +516,22 @@ 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.
receiving ServerHello with a list of server supported protocols.
=item B<-ct|noct>
Use one of these two options to control whether Certificate Transparency (CT)
is enabled (B<-ct>) or disabled (B<-noct>).
If CT is enabled, signed certificate timestamps (SCTs) will be requested from
the server and reported at handshake completion.
Enabling CT also enables OCSP stapling, as this is one possible delivery method
for SCTs.
=item B<-ctlogfile>
A file containing a list of known Certificate Transparency logs. See
L<SSL_CTX_set_ctlog_list_file(3)> for the expected file format.
=back
@@ -315,8 +555,8 @@ 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
nothing obvious like no client certificate then the B<-bugs>,
B<-ssl3>, B<-tls1>, 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.
@@ -338,10 +578,6 @@ 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
@@ -351,20 +587,30 @@ 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.
Because this program has a lot of options and also because some of the
techniques used are rather old, the C source of B<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)>
L<SSL_CONF_cmd(3)>,
L<sess_id(1)>, L<s_server(1)>, L<ciphers(1)>
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
The -no_alt_chains options was first added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

345
doc/apps/s_server.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,7 +7,14 @@ s_server - SSL/TLS server program
=head1 SYNOPSIS
B<openssl> B<s_server>
[B<-accept port>]
[B<-help>]
[B<-port port>]
[B<-accept val>]
[B<-naccept count>]
[B<-unix val>]
[B<-unlink>]
[B<-4>]
[B<-6>]
[B<-context id>]
[B<-verify depth>]
[B<-Verify depth>]
@@ -33,21 +39,62 @@ B<openssl> B<s_server>
[B<-state>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_return_error>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-nocert>]
[B<-client_sigalgs sigalglist>]
[B<-named_curve curve>]
[B<-cipher cipherlist>]
[B<-serverpref>]
[B<-quiet>]
[B<-no_tmp_rsa>]
[B<-ssl2>]
[B<-ssl3>]
[B<-tls1>]
[B<-no_ssl2>]
[B<-tls1_1>]
[B<-tls1_2>]
[B<-dtls>]
[B<-dtls1>]
[B<-dtls1_2>]
[B<-listen>]
[B<-async>]
[B<-split_send_frag>]
[B<-max_pipelines>]
[B<-read_buf>]
[B<-no_ssl3>]
[B<-no_tls1>]
[B<-no_tls1_1>]
[B<-no_tls1_2>]
[B<-no_dhe>]
[B<-bugs>]
[B<-hack>]
[B<-comp>]
[B<-no_comp>]
[B<-brief>]
[B<-www>]
[B<-WWW>]
[B<-HTTP>]
@@ -72,15 +119,48 @@ for connections on a given port using SSL/TLS.
=head1 OPTIONS
In addition to the options below the B<s_server> utility also supports the
common and server only options documented in the
in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)>
manual page.
=over 4
=item B<-accept port>
=item B<-help>
the TCP port to listen on for connections. If not specified 4433 is used.
Print out a usage message.
=item B<-port port>
The TCP port to listen on for connections. If not specified 4433 is used.
=item B<-accept val>
The optional TCP host and port to listen on for connections. If not specified, *:4433 is used.
=item B<-naccept count>
The server will exit after receiving B<number> connections, default unlimited.
=item B<-unix val>
Unix domain socket to accept on.
=item B<-unlink>
For -unix, unlink existing socket first.
=item B<-4>
Use IPv4 only.
=item B<-6>
Use IPv6 only.
=item B<-context id>
sets the SSL context id. It can be given any string value. If this option
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>
@@ -105,12 +185,12 @@ 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)>.
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)>.
=item B<-dcert filename>, B<-dkey keyname>
specify an additional certificate and private key, these behave in the
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
@@ -121,42 +201,27 @@ by using an appropriate certificate.
=item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg>
additional certificate and private key format and passphrase respectively.
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
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
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.
load the parameters from the server certificate file.
If this fails then a static set of parameters hard coded into the B<s_server>
program will be used.
=item B<-no_dhe>
if this option is set then no DH parameters will be loaded effectively
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.
@@ -176,37 +241,78 @@ 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>
=item B<-no-CAfile>
See the L<B<verify>|verify(1)> manual page for details.
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=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<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set different peer certificate verification options.
See the L<verify(1)> manual page for details.
=item B<-verify_return_error>
Verification errors normally just print a message but allow the
connection to continue, for debugging purposes.
If this option is used, then verification errors close the connection.
=item B<-state>
prints out the SSL session states.
Prints the SSL session states.
=item B<-debug>
print extensive debugging information including a hex dump of all traffic.
Print extensive debugging information including a hex dump of all traffic.
=item B<-msg>
show all protocol messages with hex dump.
Show all protocol messages with hex dump.
=item B<-trace>
Show verbose trace output of protocol messages. OpenSSL needs to be compiled
with B<enable-ssl-trace> for this option to work.
=item B<-msgfile>
File to send output of B<-msg> or B<-trace> to, default standard output.
=item B<-nbio_test>
tests non blocking I/O
Tests non blocking I/O
=item B<-nbio>
turns on non blocking I/O
Turns on non blocking I/O
=item B<-crlf>
this option translated a line feed from the terminal into CR+LF.
This option translated a line feed from the terminal into CR+LF.
=item B<-quiet>
inhibit printing of session and certificate information.
Inhibit printing of session and certificate information.
=item B<-psk_hint hint>
@@ -221,22 +327,96 @@ given as a hexadecimal number without leading 0x, for example -psk
=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.
By default B<s_server> will negotiate the highest mutually supported protocol
version.
When a specific TLS version is required, only that version will be accepted
from the client.
=item B<-dtls>, B<-dtls1>, B<-dtls1_2>
These options make B<s_server> use DTLS protocols instead of TLS.
With B<-dtls>, B<s_server> will negotiate any supported DTLS protocol version,
whilst B<-dtls1> and B<-dtls1_2> will only support DTLSv1.0 and DTLSv1.2
respectively.
=item B<-listen>
This option can only be used in conjunction with one of the DTLS options above.
With this option B<s_server> will listen on a UDP port for incoming connections.
Any ClientHellos that arrive will be checked to see if they have a cookie in
them or not.
Any without a cookie will be responded to with a HelloVerifyRequest.
If a ClientHello with a cookie is received then B<s_server> will connect to
that peer and complete the handshake.
=item B<-async>
Switch on asynchronous mode. Cryptographic operations will be performed
asynchronously. This will only have an effect if an asynchronous capable engine
is also used via the B<-engine> option. For test purposes the dummy async engine
(dasync) can be used (if available).
=item B<-split_send_frag int>
The size used to split data for encrypt pipelines. If more data is written in
one go than this value then it will be split into multiple pipelines, up to the
maximum number of pipelines defined by max_pipelines. This only has an effect if
a suitable ciphersuite has been negotiated, an engine that supports pipelining
has been loaded, and max_pipelines is greater than 1. See
L<SSL_CTX_set_split_send_fragment(3)> for further information.
=item B<-max_pipelines int>
The maximum number of encrypt/decrypt pipelines to be used. This will only have
an effect if an engine has been loaded that supports pipelining (e.g. the dasync
engine) and a suitable ciphersuite has been negotiated. The default value is 1.
See L<SSL_CTX_set_max_pipelines(3)> for further information.
=item B<-read_buf int>
The default read buffer size to be used for connections. This will only have an
effect if the buffer size is larger than the size that would otherwise be used
and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for
further information).
=item B<-bugs>
there are several known bug in SSL and TLS implementations. Adding this
There are several known bug in SSL and TLS implementations. Adding this
option enables various workarounds.
=item B<-hack>
=item B<-comp>
this option enables a further workaround for some some early Netscape
SSL code (?).
Enable negotiation of TLS compression.
This option was introduced in OpenSSL 1.1.0.
TLS compression is not recommended and is off by default as of
OpenSSL 1.1.0.
=item B<-no_comp>
Disable negotiation of TLS compression.
TLS compression is not recommended and is off by default as of
OpenSSL 1.1.0.
=item B<-brief>
Provide a brief summary of connection parameters instead of the normal verbose
output.
=item B<-client_sigalgs sigalglist>
Signature algorithms to support for client certificate authentication
(colon-separated list)
=item B<-named_curve curve>
Specifies the elliptic curve to use. NOTE: this is single curve, not a list.
For a list of all possible curves, use:
$ openssl ecparam -list_curves
=item B<-cipher cipherlist>
this allows the cipher list used by the server to be modified. When
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
@@ -244,62 +424,67 @@ the B<ciphers> command for more information.
=item B<-serverpref>
use the server's cipher preferences, rather than the client's preferences.
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.
Print a hex dump of any TLS extensions received from the server.
=item B<-no_ticket>
disable RFC4507bis session ticket support.
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.
Sends a status message back to the client when it connects. This includes
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
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
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<-rev>
Simple test server which just reverses the text received from the client
and sends it back to the server. Also sets B<-brief>.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<s_server>
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
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.
A file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an 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
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
@@ -307,24 +492,24 @@ ServerHello extension will be returned.
=item B<-no_resumption_on_reneg>
set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag.
Set the B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> option.
=item B<-status>
enables certificate status request support (aka OCSP stapling).
Enables certificate status request support (aka OCSP stapling).
=item B<-status_verbose>
enables certificate status request support (aka OCSP stapling) and gives
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.
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
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.
@@ -346,7 +531,7 @@ Protocol names are printable ASCII strings, for example "http/1.1" or
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.
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.
@@ -401,10 +586,10 @@ 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.
Because this program has a lot of options and also because some of the
techniques used are rather old, the C source of B<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.
@@ -414,10 +599,20 @@ 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)>
L<SSL_CONF_cmd(3)>,
L<sess_id(1)>, L<s_client(1)>, L<ciphers(1)>
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
The -no_alt_chains options was first added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

49
doc/apps/s_time.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,18 +7,20 @@ s_time - SSL/TLS performance timing program
=head1 SYNOPSIS
B<openssl> B<s_time>
[B<-help>]
[B<-connect host:port>]
[B<-www page>]
[B<-cert filename>]
[B<-key filename>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-reuse>]
[B<-new>]
[B<-verify depth>]
[B<-nbio>]
[B<-time seconds>]
[B<-ssl2>]
[B<-ssl3>]
[B<-bugs>]
[B<-cipher cipherlist>]
@@ -36,6 +37,10 @@ transferred (if any), and calculates the average time spent for one connection.
=over 4
=item B<-help>
Print out a usage message.
=item B<-connect host:port>
This specifies the host and optional port to connect to.
@@ -76,6 +81,14 @@ also used when building the client certificate chain.
A file containing trusted certificates to use during server authentication
and to use when attempting to build the client certificate chain.
=item B<-no-CAfile>
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-new>
performs the timing test using a new session ID for each connection.
@@ -92,18 +105,17 @@ specified, they are both on by default and executed in sequence.
turns on non-blocking I/O.
=item B<-ssl2>, B<-ssl3>
=item 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.
servers and permit them to use SSL v3 or TLS as appropriate.
The timing program is not as rich in options to turn protocols on and off as
the L<s_client(1)|s_client(1)> program and may not connect to all servers.
the L<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.
work if TLS is turned off with the B<-ssl3> option.
=item B<-bugs>
@@ -115,7 +127,7 @@ option enables various workarounds.
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.
See the L<ciphers(1)> command for more information.
=item B<-time length>
@@ -133,11 +145,11 @@ 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
which both client and server can agree, see the L<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>,
nothing obvious like no client certificate then the B<-bugs> and
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.
@@ -146,10 +158,10 @@ 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
requests a certificate. By using L<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
is necessary to use the B<-prexit> option of L<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>
@@ -160,7 +172,7 @@ 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
L<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
@@ -168,6 +180,15 @@ fails.
=head1 SEE ALSO
L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)>
L<s_client(1)>, L<s_server(1)>, L<ciphers(1)>
=head1 COPYRIGHT
Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

38
doc/apps/sess_id.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,8 +7,9 @@ sess_id - SSL/TLS session handling utility
=head1 SYNOPSIS
B<openssl> B<sess_id>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-outform PEM|DER|NSS>]
[B<-in filename>]
[B<-out filename>]
[B<-text>]
@@ -24,8 +24,14 @@ 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.
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -33,10 +39,11 @@ 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>
=item B<-outform DER|PEM|NSS>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
This specifies the output format. The B<PEM> and B<DER> options have the same meaning
as the B<-inform> option. The B<NSS> option outputs the session id and the master key
in NSS keylog format.
=item B<-in filename>
@@ -51,7 +58,7 @@ 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.
plain text in addition to the encoded version.
=item B<-cert>
@@ -65,7 +72,7 @@ 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
supplied ID. The ID can be any string of characters. This option won't normally
be used.
=back
@@ -91,7 +98,7 @@ Theses are described below in more detail.
=item B<Protocol>
this is the protocol in use TLSv1, SSLv3 or SSLv2.
this is the protocol in use TLSv1.2, TLSv1.1, TLSv1 or SSLv3.
=item B<Cipher>
@@ -110,10 +117,6 @@ the session ID context in hex format.
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.
@@ -146,6 +149,15 @@ 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)>
L<ciphers(1)>, L<s_server(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

121
doc/apps/smime.pod
View File

@@ -7,21 +7,54 @@ smime - S/MIME utility
=head1 SYNOPSIS
B<openssl> B<smime>
[B<-help>]
[B<-encrypt>]
[B<-decrypt>]
[B<-sign>]
[B<-resign>]
[B<-verify>]
[B<-pk7out>]
[B<-binary>]
[B<-crlfeol>]
[B<-[cipher]>]
[B<-in file>]
[B<-CAfile file>]
[B<-CApath dir>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-certfile file>]
[B<-signer file>]
[B<-recip file>]
[B<-inform SMIME|PEM|DER>]
[B<-passin arg>]
[B<-inkey file>]
[B<-inkey file_or_id>]
[B<-out file>]
[B<-outform SMIME|PEM|DER>]
[B<-content file>]
@@ -41,13 +74,17 @@ B<openssl> B<smime>
The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and
verify S/MIME messages.
=head1 COMMAND OPTIONS
=head1 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<-help>
Print out a usage message.
=item B<-encrypt>
encrypt mail for the given recipient certificates. Input file is the message
@@ -136,7 +173,7 @@ is S/MIME and it uses the multipart/signed MIME content type.
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
off text headers: if the decrypted or verified message is not of MIME
type text/plain then an error occurs.
=item B<-CAfile file>
@@ -150,6 +187,14 @@ 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<-no-CAfile>
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-md digest>
digest algorithm to use when signing or resigning. If not present then the
@@ -159,8 +204,8 @@ default digest algorithm for the signing key will be used (usually SHA1).
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
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>.
@@ -205,6 +250,11 @@ 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<-crlfeol>
normally the output file uses a single B<LF> as end of line. When this
option is present B<CRLF> is used instead.
=item B<-nodetach>
when signing a message use opaque signing: this form is more resistant
@@ -230,31 +280,33 @@ verification was successful.
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>
=item B<-inkey file_or_id>
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.
If no engine is used, the argument is taken as a file; if an engine is
specified, the argument is given to the engine as a key identifier.
=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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<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.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an 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.
a message.
=item B<-to, -from, -subject>
@@ -263,10 +315,16 @@ 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>
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set various options of certificate chain verification. See
L<B<verify>|verify(1)> manual page for details.
L<verify(1)> manual page for details.
=back
@@ -278,7 +336,7 @@ 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
necessary MIME headers or many S/MIME clients won't display it
properly (if at all). You can use the B<-text> option to automatically
add plain text headers.
@@ -299,7 +357,7 @@ 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.
The B<-stream> and B<-indef> options enable 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.
@@ -345,29 +403,29 @@ the signers certificates.
Create a cleartext signed message:
openssl smime -sign -in message.txt -text -out mail.msg \
-signer mycert.pem
-signer mycert.pem
Create an opaque signed message:
openssl smime -sign -in message.txt -text -out mail.msg -nodetach \
-signer mycert.pem
-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
-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
-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
-from steve@openssl.org -to someone@somewhere \
-subject "Signed message" | sendmail someone@somewhere
Verify a message and extract the signer's certificate if successful:
@@ -376,15 +434,15 @@ Verify a message and extract the signer's certificate if successful:
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
-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
| 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.
@@ -401,7 +459,7 @@ it with:
-----BEGIN PKCS7-----
-----END PKCS7-----
and using the command:
and using the command:
openssl smime -verify -inform PEM -in signature.pem -content content.txt
@@ -445,6 +503,15 @@ structures may cause parsing errors.
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.
The -no_alt_chains options was first added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

58
doc/apps/speed.pod
View File

@@ -7,41 +7,27 @@ speed - test library performance
=head1 SYNOPSIS
B<openssl speed>
[B<-help>]
[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>]
[B<-elapsed>]
[B<-evp algo>]
[B<-decrypt>]
[B<algorithm...>]
=head1 DESCRIPTION
This command is used to test the performance of cryptographic algorithms.
To see the list of supported algorithms, use the I<list --digest-commands>
or I<list --cipher-commands> command.
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<speed>
@@ -49,6 +35,19 @@ 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<-elapsed>
Measure time in real time instead of CPU time. It can be useful when testing
speed of hardware engines.
=item B<-evp algo>
Use the specified cipher or message digest algorithm via the EVP interface.
=item B<-decrypt>
Time the decryption instead of encryption. Affects only the EVP testing.
=item B<[zero or more test algorithms]>
If any options are given, B<speed> tests those algorithms, otherwise all of
@@ -56,4 +55,13 @@ the above are tested.
=back
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

20
doc/apps/spkac.pod
View File

@@ -7,6 +7,7 @@ spkac - SPKAC printing and generating utility
=head1 SYNOPSIS
B<openssl> B<spkac>
[B<-help>]
[B<-in filename>]
[B<-out filename>]
[B<-key keyfile>]
@@ -25,10 +26,14 @@ 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
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies the input filename to read from or standard input if this
@@ -48,7 +53,7 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-challenge string>
@@ -128,6 +133,15 @@ to be used in a "replay attack".
=head1 SEE ALSO
L<ca(1)|ca(1)>
L<ca(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

213
doc/apps/ts.pod
View File

@@ -12,8 +12,8 @@ B<-query>
[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<-[digest]>]
[B<-tspolicy> object_id]
[B<-no_nonce>]
[B<-cert>]
[B<-in> request.tsq]
@@ -27,9 +27,10 @@ B<-reply>
[B<-queryfile> request.tsq]
[B<-passin> password_src]
[B<-signer> tsa_cert.pem]
[B<-inkey> private.pem]
[B<-inkey> file_or_id]
[B<-sha1|-sha224|-sha256|-sha384|-sha512>]
[B<-chain> certs_file.pem]
[B<-policy> object_id]
[B<-tspolicy> object_id]
[B<-in> response.tsr]
[B<-token_in>]
[B<-out> response.tsr]
@@ -47,6 +48,38 @@ B<-verify>
[B<-CApath> trusted_cert_path]
[B<-CAfile> trusted_certs.pem]
[B<-untrusted> cert_file.pem]
[I<verify options>]
I<verify options:>
[-attime timestamp]
[-check_ss_sig]
[-crl_check]
[-crl_check_all]
[-explicit_policy]
[-extended_crl]
[-ignore_critical]
[-inhibit_any]
[-inhibit_map]
[-issuer_checks]
[-no_alt_chains]
[-no_check_time]
[-partial_chain]
[-policy arg]
[-policy_check]
[-policy_print]
[-purpose purpose]
[-suiteB_128]
[-suiteB_128_only]
[-suiteB_192]
[-trusted_first]
[-use_deltas]
[-auth_level num]
[-verify_depth num]
[-verify_email email]
[-verify_hostname hostname]
[-verify_ip ip]
[-verify_name name]
[-x509_strict]
=head1 DESCRIPTION
@@ -106,9 +139,9 @@ 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)
The configuration file to use.
Optional; for a description of the default value,
see L<openssl(1)/COMMAND SUMMARY>.
=item B<-data> file_to_hash
@@ -121,16 +154,16 @@ parameter is specified. (Optional)
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
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<...>
=item B<-[digest]>
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 message digest to apply to the data file.
Any digest supported by the OpenSSL B<dgst> command can be used.
The default is SHA-1. (Optional)
=item B<-policy> object_id
=item B<-tspolicy> 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
@@ -154,7 +187,6 @@ response. (Optional)
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
@@ -183,13 +215,14 @@ otherwise it is a time stamp token (ContentInfo).
=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)
The configuration file to use.
Optional; for a description of the default value,
see L<openssl(1)/COMMAND SUMMARY>.
See B<CONFIGURATION FILE OPTIONS> for configurable variables.
=item B<-section> tsa_section
The name of the config file section conatining the settings for the
The name of the config file section containing the settings for the
response generation. If not specified the default TSA section is
used, see B<CONFIGURATION FILE OPTIONS> for details. (Optional)
@@ -200,7 +233,7 @@ 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)
B<PASS PHRASE ARGUMENTS> in L<openssl(1)>. (Optional)
=item B<-signer> tsa_cert.pem
@@ -210,10 +243,17 @@ 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
=item B<-inkey> file_or_id
The signer private key of the TSA in PEM format. Overrides the
B<signer_key> config file option. (Optional)
If no engine is used, the argument is taken as a file; if an engine is
specified, the argument is given to the engine as a key identifier.
=item B<-sha1|-sha224|-sha256|-sha384|-sha512>
Signing digest to use. Overrides the B<signer_digest> config file
option. (Optional)
=item B<-chain> certs_file.pem
@@ -224,7 +264,7 @@ 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
=item B<-tspolicy> object_id
The default policy to use for the response unless the client
explicitly requires a particular TSA policy. The OID can be specified
@@ -283,7 +323,7 @@ data file. The B<-verify> command does not use the configuration file.
=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.
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)
@@ -311,16 +351,16 @@ 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
The name of the directory containing the trusted CA certificates of the
client. See the similar option of L<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
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)> for additional details. Either this option
or B<-CApath> must be specified.
(Optional)
@@ -332,12 +372,24 @@ certificate. This file must contain the TSA signing certificate and
all intermediate CA certificates unless the response includes them.
(Optional)
=item I<verify options>
The options B<-attime timestamp>, B<-check_ss_sig>, B<-crl_check>,
B<-crl_check_all>, B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>,
B<-inhibit_any>, B<-inhibit_map>, B<-issuer_checks>, B<-no_alt_chains>,
B<-no_check_time>, B<-partial_chain>, B<-policy>, B<-policy_check>,
B<-policy_print>, B<-purpose>, B<-suiteB_128>, B<-suiteB_128_only>,
B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, B<-auth_level>,
B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, B<-verify_ip>,
B<-verify_name>, and B<-x509_strict> can be used to control timestamp
verification. See L<verify(1)>.
=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)>
The B<-query> and B<-reply> commands make use of a configuration file.
See L<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
@@ -348,7 +400,7 @@ switch always overrides the settings in the config file.
=over 4
=item B<tsa> section, B<default_tsa>
=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
@@ -356,15 +408,15 @@ 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)
See L<ca(1)> for description. (Optional)
=item B<oid_section>
See L<ca(1)|ca(1)> for description. (Optional)
See L<ca(1)> for description. (Optional)
=item B<RANDFILE>
See L<ca(1)|ca(1)> for description. (Optional)
See L<ca(1)> for description. (Optional)
=item B<serial>
@@ -375,8 +427,8 @@ 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
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)
@@ -396,10 +448,15 @@ option. (Optional)
The private key of the TSA in PEM format. The same as the B<-inkey>
command line option. (Optional)
=item B<signer_digest>
Signing digest to use. The same as the
B<-sha1|-sha224|-sha256|-sha384|-sha512> 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)
policy. The same as the B<-tspolicy> command line option. (Optional)
=item B<other_policies>
@@ -419,7 +476,7 @@ 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
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.
@@ -450,42 +507,37 @@ 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
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
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
-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
-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
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
-tspolicy tsa_policy1 -cert -out design2.tsq
=head2 Time Stamp Response
@@ -493,8 +545,8 @@ 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
of the config file to generate a proper certificate. See L<req(1)>,
L<ca(1)>, L<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.
@@ -502,7 +554,7 @@ 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
-signer tsacert.pem -out design1.tsr
If you want to use the settings in the config file you could just write:
@@ -534,61 +586,76 @@ valid response:
To verify a time stamp reply against a request:
openssl ts -verify -queryfile design1.tsq -in design1.tsr \
-CAfile cacert.pem -untrusted tsacert.pem
-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
-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
-CAfile cacert.pem
To verify a time stamp token against a message imprint:
openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
-in design2.tsr -CAfile cacert.pem
-in design2.tsr -CAfile cacert.pem
You could also look at the 'test' directory for more examples.
=head1 BUGS
=for comment foreign manuals: procmail(1), perl(1)
If you find any bugs or you have suggestions please write to
Zoltan Glozik <zglozik@opentsa.org>. Known issues:
=over 4
=over 2
=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
=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)>
and L<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.
L<tsget(1)>. Pure TCP/IP protocol is not supported.
=item * The file containing the last serial number of the TSA is not
=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
instance of L<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 *
=item * The source code should really be reviewed by somebody else, too.
Look for the FIXME word in the source files.
=item * More testing is needed, I have done only some basic tests (see
=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)>
L<tsget(1)>, L<openssl(1)>, L<req(1)>,
L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
L<config(5)>
=head1 COPYRIGHT
Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

45
doc/apps/tsget.pod
View File

@@ -33,15 +33,15 @@ 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
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...
...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.
@@ -142,7 +142,7 @@ 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
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
@@ -151,44 +151,49 @@ 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
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
| 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
-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
-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'
-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)>,
L<openssl(1)>, L<ts(1)>, L<curl(1)>,
B<RFC 3161>
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

637
doc/apps/verify.pod
View File

@@ -2,49 +2,72 @@
=head1 NAME
verify - Utility to verify certificates.
verify - Utility to verify certificates
=head1 SYNOPSIS
B<openssl> B<verify>
[B<-CApath directory>]
[B<-help>]
[B<-CAfile file>]
[B<-purpose purpose>]
[B<-policy arg>]
[B<-ignore_critical>]
[B<-CApath directory>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-allow_proxy_certs>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crlfile file>]
[B<-CRLfile file>]
[B<-crl_download>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-policy_check>]
[B<-engine id>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-x509_strict>]
[B<-extended_crl>]
[B<-use_deltas>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-allow_proxy_certs>]
[B<-untrusted file>]
[B<-help>]
[B<-issuer_checks>]
[B<-trusted file>]
[B<-use_deltas>]
[B<-verbose>]
[B<-auth_level level>]
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-show_chain>]
[B<->]
[certificates]
=head1 DESCRIPTION
The B<verify> command verifies certificate chains.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-CAfile file>
A B<file> of trusted certificates.
The file should contain one or more certificates in PEM format.
=item B<-CApath directory>
A directory of trusted certificates. The certificates should have names
@@ -53,9 +76,17 @@ 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<-no-CAfile>
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-allow_proxy_certs>
Allow the verification of proxy certificates
=item B<-attime timestamp>
@@ -68,9 +99,11 @@ current system time. B<timestamp> is the number of seconds since
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>
=item B<-CRLfile file>
File containing one or more CRL's (in PEM format) to load.
The B<file> should contain one or more CRLs in PEM format.
This option can be specified more than once to include CRLs from multiple
B<files>.
=item B<-crl_download>
@@ -81,34 +114,54 @@ Attempt to download CRL information for this certificate.
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>
=item B<-crl_check_all>
A file of untrusted certificates. The file should contain multiple certificates
in PEM format concatenated together.
Checks the validity of B<all> certificates in the chain by attempting
to look up valid CRLs.
=item B<-purpose purpose>
=item B<-engine id>
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.
Specifying an engine B<id> will cause L<verify(1)> to attempt to load the
specified engine.
The engine will then be set as the default for all its supported algorithms.
If you want to load certificates or CRLs that require engine support via any of
the B<-trusted>, B<-untrusted> or B<-CRLfile> options, the B<-engine> option
must be specified before those options.
=item B<-help>
=item B<-explicit_policy>
Print out a usage message.
Set policy variable require-explicit-policy (see RFC5280).
=item B<-verbose>
=item B<-extended_crl>
Print extra information about the operations being performed.
Enable extended CRL features such as indirect CRLs and alternate CRL
signing keys.
=item B<-issuer_checks>
=item B<-ignore_critical>
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.
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<-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_check_time>
This option suppresses checking the validity period of certificates and CRLs
against the current time. If option B<-attime timestamp> is used to specify
a verification time, the check is not suppressed.
=item B<-partial_chain>
Allow verification to succeed even if a I<complete> chain cannot be built to a
self-signed trust-anchor, provided it is possible to construct a chain to a
trusted certificate that might not be self-signed.
=item B<-policy arg>
@@ -120,73 +173,139 @@ This argument can appear more than once.
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>
=item B<-purpose purpose>
Checks end entity certificate validity by attempting to look up a valid CRL.
If a valid CRL cannot be found an error occurs.
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<-crl_check_all>
=item B<-suiteB_128_only>, B<-suiteB_128>, B<-suiteB_192>
Checks the validity of B<all> certificates in the chain by attempting
to look up valid CRLs.
enable the Suite B mode operation at 128 bit Level of Security, 128 bit or
192 bit, or only 192 bit Level of Security respectively.
See RFC6460 for details. In particular the supported signature algorithms are
reduced to support only ECDSA and SHA256 or SHA384 and only the elliptic curves
P-256 and P-384.
=item B<-ignore_critical>
=item B<-trusted_first>
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.
When constructing the certificate chain, use the trusted certificates specified
via B<-CAfile>, B<-CApath> or B<-trusted> before any certificates specified via
B<-untrusted>.
This can be useful in environments with Bridge or Cross-Certified CAs.
As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
=item B<-no_alt_chains>
By default, unless B<-trusted_first> is specified, when building a certificate
chain, if the first certificate chain found is not trusted, then OpenSSL will
attempt to replace untrusted issuer certificates with certificates from the
trust store to see if an alternative chain can be found that is trusted.
As of OpenSSL 1.1.0, with B<-trusted_first> always on, this option has no
effect.
=item B<-untrusted file>
A B<file> of additional untrusted certificates (intermediate issuer CAs) used
to construct a certificate chain from the subject certificate to a trust-anchor.
The B<file> should contain one or more certificates in PEM format.
This option can be specified more than once to include untrusted certificates
from multiple B<files>.
=item B<-trusted file>
A B<file> of trusted certificates, which must be self-signed, unless the
B<-partial_chain> option is specified.
The B<file> contains one or more certificates in PEM format.
With this option, no additional (e.g., default) certificate lists are
consulted.
That is, the only trust-anchors are those listed in B<file>.
This option can be specified more than once to include trusted certificates
from multiple B<files>.
This option implies the B<-no-CAfile> and B<-no-CApath> options.
This option cannot be used in combination with either of the B<-CAfile> or
B<-CApath> options.
=item B<-use_deltas>
Enable support for delta CRLs.
=item B<-verbose>
Print extra information about the operations being performed.
=item B<-auth_level level>
Set the certificate chain authentication security level to B<level>.
The authentication security level determines the acceptable signature and
public key strength when verifying certificate chains.
For a certificate chain to validate, the public keys of all the certificates
must meet the specified security B<level>.
The signature algorithm security level is enforced for all the certificates in
the chain except for the chain's I<trust anchor>, which is either directly
trusted or validated by means other than its signature.
See L<SSL_CTX_set_security_level(3)> for the definitions of the available
levels.
The default security level is -1, or "not set".
At security level 0 or lower all algorithms are acceptable.
Security level 1 requires at least 80-bit-equivalent security and is broadly
interoperable, though it will, for example, reject MD5 signatures or RSA keys
shorter than 1024 bits.
=item B<-verify_depth num>
Limit the certificate chain to B<num> intermediate CA certificates.
A maximal depth chain can have up to B<num+2> certificates, since neither the
end-entity certificate nor the trust-anchor certificate count against the
B<-verify_depth> limit.
=item B<-verify_email email>
Verify if the B<email> matches the email address in Subject Alternative Name or
the email in the subject Distinguished Name.
=item B<-verify_hostname hostname>
Verify if the B<hostname> matches DNS name in Subject Alternative Name or
Common Name in the subject certificate.
=item B<-verify_ip ip>
Verify if the B<ip> matches the IP address in Subject Alternative Name of
the subject certificate.
=item B<-verify_name name>
Use default verification policies like trust model and required certificate
policies identified by B<name>.
The trust model determines which auxiliary trust or reject OIDs are applicable
to verifying the given certificate chain.
See the B<-addtrust> and B<-addreject> options of the L<x509(1)> command-line
utility.
Supported policy names include: B<default>, B<pkcs7>, B<smime_sign>,
B<ssl_client>, B<ssl_server>.
These mimics the combinations of purpose and trust settings used in SSL, CMS
and S/MIME.
As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not
specified, so the B<-verify_name> options are functionally equivalent to the
corresponding B<-purpose> settings.
=item B<-x509_strict>
For strict X.509 compliance, disable non-compliant workarounds for broken
certificates.
=item B<-extended_crl>
=item B<-show_chain>
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.
Display information about the certificate chain that has been built (if
successful). Certificates in the chain that came from the untrusted list will be
flagged as "untrusted".
=item B<->
@@ -217,21 +336,21 @@ 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.
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 process of 'looking up the issuers certificate' itself involves a number of
steps.
After 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
@@ -246,10 +365,10 @@ compatible with the supplied purpose and all other certificates must also be val
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 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 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
@@ -274,160 +393,296 @@ problem was detected starting with zero for the certificate being verified itsel
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
A partial 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>
=item B<X509_V_OK>
the operation was successful.
The operation was successful.
=item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
=item B<X509_V_ERR_UNSPECIFIED>
the issuer certificate of a looked up certificate could not be found. This
Unspecified error; should not happen.
=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT>
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>
=item B<X509_V_ERR_UNABLE_TO_GET_CRL>
the CRL of a certificate could not be found.
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>
=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE>
the certificate signature could not be decrypted. This means that the actual signature value
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>
=item B<X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE>
the CRL signature could not be decrypted: this means that the actual signature value
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>
=item B<X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY>
the public key in the certificate SubjectPublicKeyInfo could not be read.
The public key in the certificate SubjectPublicKeyInfo could not be read.
=item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
=item B<X509_V_ERR_CERT_SIGNATURE_FAILURE>
the signature of the certificate is invalid.
The signature of the certificate is invalid.
=item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
=item B<X509_V_ERR_CRL_SIGNATURE_FAILURE>
the signature of the certificate is invalid.
The signature of the certificate is invalid.
=item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
=item B<X509_V_ERR_CERT_NOT_YET_VALID>
the certificate is not yet valid: the notBefore date is after the current time.
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>
=item B<X509_V_ERR_CERT_HAS_EXPIRED>
the certificate has expired: that is the notAfter date is before the current time.
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>
=item B<X509_V_ERR_CRL_NOT_YET_VALID>
the CRL is not yet valid.
The CRL is not yet valid.
=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
=item B<X509_V_ERR_CRL_HAS_EXPIRED>
the 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>
=item B<X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD>
the certificate notBefore field contains an invalid time.
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>
=item B<X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD>
the certificate notAfter field contains an invalid time.
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>
=item B<X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD>
the CRL lastUpdate field contains an invalid time.
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>
=item B<X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD>
the CRL nextUpdate field contains an invalid time.
The CRL nextUpdate field contains an invalid time.
=item B<17 X509_V_ERR_OUT_OF_MEM: out of memory>
=item B<X509_V_ERR_OUT_OF_MEM>
an error occurred trying to allocate memory. This should never happen.
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>
=item B<X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT>
the passed certificate is self signed and the same certificate cannot be found in the list of
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>
=item B<X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN>
the certificate chain could be built up using the untrusted certificates but the root could not
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>
=item B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY>
the issuer certificate could not be found: this occurs if the issuer
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>
=item B<X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE>
no signatures could be verified because the chain contains only one certificate and it is not
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>
=item B<X509_V_ERR_CERT_CHAIN_TOO_LONG>
the certificate chain length is greater than the supplied maximum depth. Unused.
The certificate chain length is greater than the supplied maximum depth. Unused.
=item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked>
=item B<X509_V_ERR_CERT_REVOKED>
the certificate has been revoked.
The certificate has been revoked.
=item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate>
=item B<X509_V_ERR_INVALID_CA>
a CA certificate is invalid. Either it is not a CA or its extensions are not consistent
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>
=item B<X509_V_ERR_PATH_LENGTH_EXCEEDED>
the basicConstraints pathlength parameter has been exceeded.
The basicConstraints pathlength parameter has been exceeded.
=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
=item B<X509_V_ERR_INVALID_PURPOSE>
the supplied certificate cannot be used for the specified purpose.
The supplied certificate cannot be used for the specified purpose.
=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
=item B<X509_V_ERR_CERT_UNTRUSTED>
the root CA is not marked as trusted for the specified purpose.
=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected>
=item B<X509_V_ERR_CERT_REJECTED>
the root CA is marked to reject the specified purpose.
The root CA is marked to reject the specified purpose.
=item B<29 X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch>
=item B<X509_V_ERR_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.
not used as of OpenSSL 1.1.0 as a result of the deprecation of the
B<-issuer_checks> option.
=item B<30 X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch>
=item B<X509_V_ERR_AKID_SKID_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.
Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
B<-issuer_checks> option.
=item B<31 X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch>
=item B<X509_V_ERR_AKID_ISSUER_SERIAL_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.
Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
B<-issuer_checks> option.
=item B<32 X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing>
=item B<X509_V_ERR_KEYUSAGE_NO_CERTSIGN>
the current candidate issuer certificate was rejected because its keyUsage extension
does not permit certificate signing.
Not used as of OpenSSL 1.1.0 as a result of the deprecation of the
B<-issuer_checks> option.
=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
=item B<X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER>
an application specific error. Unused.
Unable to get CRL issuer certificate.
=item B<X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION>
Unhandled critical extension.
=item B<X509_V_ERR_KEYUSAGE_NO_CRL_SIGN>
Key usage does not include CRL signing.
=item B<X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION>
Unhandled critical CRL extension.
=item B<X509_V_ERR_INVALID_NON_CA>
Invalid non-CA certificate has CA markings.
=item B<X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED>
Proxy path length constraint exceeded.
=item B<X509_V_ERR_PROXY_SUBJECT_INVALID>
Proxy certificate subject is invalid. It MUST be the same as the issuer
with a single CN component added.
=item B<X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE>
Key usage does not include digital signature.
=item B<X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED>
Proxy certificates not allowed, please use B<-allow_proxy_certs>.
=item B<X509_V_ERR_INVALID_EXTENSION>
Invalid or inconsistent certificate extension.
=item B<X509_V_ERR_INVALID_POLICY_EXTENSION>
Invalid or inconsistent certificate policy extension.
=item B<X509_V_ERR_NO_EXPLICIT_POLICY>
No explicit policy.
=item B<X509_V_ERR_DIFFERENT_CRL_SCOPE>
Different CRL scope.
=item B<X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE>
Unsupported extension feature.
=item B<X509_V_ERR_UNNESTED_RESOURCE>
RFC 3779 resource not subset of parent's resources.
=item B<X509_V_ERR_PERMITTED_VIOLATION>
Permitted subtree violation.
=item B<X509_V_ERR_EXCLUDED_VIOLATION>
Excluded subtree violation.
=item B<X509_V_ERR_SUBTREE_MINMAX>
Name constraints minimum and maximum not supported.
=item B<X509_V_ERR_APPLICATION_VERIFICATION>
Application verification failure. Unused.
=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE>
Unsupported name constraint type.
=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX>
Unsupported or invalid name constraint syntax.
=item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX>
Unsupported or invalid name syntax.
=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR>
CRL path validation error.
=item B<X509_V_ERR_PATH_LOOP>
Path loop.
=item B<X509_V_ERR_SUITE_B_INVALID_VERSION>
Suite B: certificate version invalid.
=item B<X509_V_ERR_SUITE_B_INVALID_ALGORITHM>
Suite B: invalid public key algorithm.
=item B<X509_V_ERR_SUITE_B_INVALID_CURVE>
Suite B: invalid ECC curve.
=item B<X509_V_ERR_SUITE_B_INVALID_SIGNATURE_ALGORITHM>
Suite B: invalid signature algorithm.
=item B<X509_V_ERR_SUITE_B_LOS_NOT_ALLOWED>
Suite B: curve not allowed for this LOS.
=item B<X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256>
Suite B: cannot sign P-384 with P-256.
=item B<X509_V_ERR_HOSTNAME_MISMATCH>
Hostname mismatch.
=item B<X509_V_ERR_EMAIL_MISMATCH>
Email address mismatch.
=item B<X509_V_ERR_IP_ADDRESS_MISMATCH>
IP address mismatch.
=item B<X509_V_ERR_DANE_NO_MATCH>
DANE TLSA authentication is enabled, but no TLSA records matched the
certificate chain.
This error is only possible in L<s_client(1)>.
=back
@@ -436,7 +691,7 @@ an application specific error. Unused.
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
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
@@ -444,14 +699,26 @@ 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.
B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
=head1 SEE ALSO
L<x509(1)|x509(1)>
L<x509(1)>
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
The B<-show_chain> option was first added to OpenSSL 1.1.0.
The B<-issuer_checks> option is deprecated as of OpenSSL 1.1.0 and
is silently ignored.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

19
doc/apps/version.pod
View File

@@ -7,6 +7,7 @@ version - print OpenSSL version information
=head1 SYNOPSIS
B<openssl version>
[B<-help>]
[B<-a>]
[B<-v>]
[B<-b>]
@@ -14,6 +15,7 @@ B<openssl version>
[B<-f>]
[B<-p>]
[B<-d>]
[B<-e>]
=head1 DESCRIPTION
@@ -23,6 +25,10 @@ This command is used to print out version information about OpenSSL.
=over 4
=item B<-help>
Print out a usage message.
=item B<-a>
all information, this is the same as setting all the other flags.
@@ -51,6 +57,10 @@ platform setting.
OPENSSLDIR setting.
=item B<-e>
ENGINESDIR setting.
=back
=head1 NOTES
@@ -58,8 +68,13 @@ OPENSSLDIR setting.
The output of B<openssl version -a> would typically be used when sending
in a bug report.
=head1 HISTORY
=head1 COPYRIGHT
The B<-d> option was added in OpenSSL 0.9.7.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

111
doc/apps/x509.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,6 +7,7 @@ x509 - Certificate display and signing utility
=head1 SYNOPSIS
B<openssl> B<x509>
[B<-help>]
[B<-inform DER|PEM|NET>]
[B<-outform DER|PEM|NET>]
[B<-keyform DER|PEM>]
@@ -55,7 +55,7 @@ B<openssl> B<x509>
[B<-text>]
[B<-certopt option>]
[B<-C>]
[B<-md2|-md5|-sha1|-mdc2>]
[B<-[digest]>]
[B<-clrext>]
[B<-extfile filename>]
[B<-extensions section>]
@@ -73,10 +73,14 @@ various sections.
=head1 OPTIONS
=head2 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
=head2 Input, Output, and General Purpose Options
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM|NET>
This specifies the input format normally the command will expect an X509
@@ -88,7 +92,7 @@ obsolete.
=item B<-outform DER|PEM|NET>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -101,12 +105,14 @@ if this option is not specified.
This specifies the output filename to write to or standard output by
default.
=item B<-md2|-md5|-sha1|-mdc2>
=item B<-[digest]>
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.
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.
Any digest supported by the OpenSSL B<dgst> command can be used.
If not specified then SHA1 is used with B<-fingerprint> or
the default digest for the signing algorithm is used, typically SHA256.
=item B<-engine id>
@@ -117,7 +123,7 @@ for all available algorithms.
=back
=head2 DISPLAY OPTIONS
=head2 Display Options
Note: the B<-alias> and B<-purpose> options are also display options
but are described in the B<TRUST SETTINGS> section.
@@ -143,7 +149,7 @@ this option prevents output of the encoded version of the request.
=item B<-pubkey>
outputs the the certificate's SubjectPublicKeyInfo block in PEM format.
outputs the certificate's SubjectPublicKeyInfo block in PEM format.
=item B<-modulus>
@@ -233,9 +239,7 @@ 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.
=head2 Trust Settings
A B<trusted certificate> is an ordinary certificate which has several
additional pieces of information attached to it such as the permitted
@@ -286,9 +290,12 @@ 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.
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), B<emailProtection> (S/MIME email) and
B<anyExtendedKeyUsage> are used.
As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or
enables all purposes when trusted.
Other OpenSSL applications may define additional uses.
=item B<-addreject arg>
@@ -304,7 +311,7 @@ EXTENSIONS> section.
=back
=head2 SIGNING OPTIONS
=head2 Signing Options
The B<x509> utility can be used to sign certificates and requests: it
can thus behave like a "mini CA".
@@ -314,14 +321,15 @@ can thus behave like a "mini CA".
=item B<-signkey filename>
this option causes the input file to be self signed using the supplied
private key.
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.
the B<-clrext> option is supplied; this includes, for example, any existing
key identifier extensions.
If the input is a certificate request then a self signed certificate
is created using the supplied private key using the subject name in
@@ -330,7 +338,7 @@ 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)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-clrext>
@@ -366,8 +374,7 @@ 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.
The serial number can be decimal or hex (if preceded by B<0x>).
=item B<-CA filename>
@@ -395,15 +402,16 @@ 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
".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.
have the 1 as its serial number. If the B<-CA> option is specified
and the serial number file does not exist a random number is generated;
this is the recommended practice.
=item B<-extfile filename>
@@ -416,7 +424,7 @@ 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
L<x509v3_config(5)> manual page for details of the
extension section format.
=item B<-force_pubkey key>
@@ -430,7 +438,7 @@ The format or B<key> can be specified using the B<-keyform> option.
=back
=head2 NAME OPTIONS
=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"
@@ -442,7 +450,7 @@ a B<-> to turn the option off. Only the first four will normally be used.
=item B<compat>
use the old format. This is equivalent to specifying no name options at all.
use the old format.
=item B<RFC2253>
@@ -455,7 +463,7 @@ B<sep_comma_plus>, B<dn_rev> and B<sname>.
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.
options. This is the I<default> of no name options are given explicitly.
=item B<multiline>
@@ -464,10 +472,15 @@ B<space_eq>, B<lname> and B<align>.
=item B<esc_2253>
escape the "special" characters required by RFC2253 in a field That is
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_2254>
escape the "special" characters required by RFC2254 in a field. That is
the B<NUL> character as well as and B<()*>.
=item B<esc_ctrl>
escape control characters. That is those with ASCII values less than
@@ -568,7 +581,7 @@ name.
=back
=head2 TEXT OPTIONS
=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
@@ -693,20 +706,20 @@ 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
-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
-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
-setalias "Steve's Class 1 CA" -out trust.pem
=head1 NOTES
@@ -821,7 +834,7 @@ Otherwise it is the same as a normal SSL server.
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
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.
@@ -840,7 +853,7 @@ if the keyUsage extension is present.
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.
extension is absent.
=item B<CRL Signing>
@@ -866,25 +879,27 @@ 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)>
L<req(1)>, L<ca(1)>, L<genrsa(1)>,
L<gendsa(1)>, L<verify(1)>,
L<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.
the old form must have their links rebuilt using B<c_rehash> or similar.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

82
doc/apps/x509v3_config.pod
View File

@@ -88,7 +88,7 @@ only be used to sign end user certificates and not further CAs.
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,
The supported names are: digitalSignature, nonRepudiation, keyEncipherment,
dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly
and decipherOnly.
@@ -108,24 +108,24 @@ 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
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
OCSPSigning OCSP Signing
ipsecIKE ipsec Internet Key Exchange
msCodeInd Microsoft Individual Code Signing (authenticode)
msCodeCom Microsoft Commercial Code Signing (authenticode)
msCTLSign Microsoft Trust List Signing
msEFS Microsoft Encrypted File System
Examples:
extendedKeyUsage=critical,codeSigning,1.2.3.4
extendedKeyUsage=nsSGC,msSGC
extendedKeyUsage=serverAuth,clientAuth
=head2 Subject Key Identifier.
@@ -167,7 +167,7 @@ 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
include any 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.
@@ -178,7 +178,7 @@ 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.
L<ASN1_generate_nconf(3)> format.
Examples:
@@ -202,7 +202,7 @@ Examples:
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
that will copy all the subject alternative name values from the issuer
certificate (if possible).
Example:
@@ -224,7 +224,7 @@ Example:
authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
=head2 CRL distribution points.
=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
@@ -358,7 +358,7 @@ 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
B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative integer
value. At least one component must be present.
Example:
@@ -380,7 +380,7 @@ Example:
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
is not supported and the B<IP> form should consist of an IP addresses and
subnet mask separated by a B</>.
Examples:
@@ -401,6 +401,20 @@ Example:
noCheck = ignored
=head2 TLS Feature (aka Must Staple)
This is a multi-valued extension consisting of a list of TLS extension
identifiers. Each identifier may be a number (0..65535) or a supported name.
When a TLS client sends a listed extension, the TLS server is expected to
include that extension in its reply.
The supported names are: B<status_request> and B<status_request_v2>.
Example:
tlsfeature = status_request
=head1 DEPRECATED EXTENSIONS
The following extensions are non standard, Netscape specific and largely
@@ -441,7 +455,7 @@ 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)>.
using the same syntax as L<ASN1_generate_nconf(3)>.
For example:
1.2.3.4=critical,ASN1:UTF8String:Some random data
@@ -491,7 +505,7 @@ will produce an error but the equivalent form:
[subject_alt_section]
subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
is valid.
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:
@@ -510,20 +524,18 @@ will only recognize the last value. This can be worked around by using the form:
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)>
L<req(1)>, L<ca(1)>, L<x509(1)>,
L<ASN1_generate_nconf(3)>
=head1 COPYRIGHT
Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut