abc/GmSSL
1
0
Fork 0
mirror of https://github.com/guanzhi/GmSSL.git synced 2026-05-17 13:56:25 +08:00
Code Issues Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
Zhi Guan
2015-08-15 15:02:15 +08:00
parent 06df2fab54
commit 3bdc0ea895
2536 changed files with 417052 additions and 271997 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
doc/HOWTO/certificates.txt
View File

@@ -3,22 +3,22 @@
1. Introduction
How you handle certificates depend a great deal on what your role is.
How you handle certificates depends a great deal on what your role is.
Your role can be one or several of:
- User of some client software
- User of some server software
- User of some client application
- User of some server application
- Certificate authority
This file is for users who wish to get a certificate of their own.
Certificate authorities should read ca.txt.
Certificate authorities should read https://www.openssl.org/docs/apps/ca.html.
In all the cases shown below, the standard configuration file, as
compiled into openssl, will be used. You may find it in /etc/,
/usr/local/ssl/ or somewhere else. The name is openssl.cnf, and
is better described in another HOWTO <config.txt?>. If you want to
use a different configuration file, use the argument '-config {file}'
with the command shown below.
/usr/local/ssl/ or somewhere else. By default the file is named
openssl.cnf and is described at https://www.openssl.org/docs/apps/config.html.
You can specify a different configuration file using the
'-config {file}' argument with the commands shown below.
2. Relationship with keys
@@ -29,24 +29,26 @@ somewhere. With OpenSSL, public keys are easily derived from private
keys, so before you create a certificate or a certificate request, you
need to create a private key.
Private keys are generated with 'openssl genrsa' if you want a RSA
private key, or 'openssl gendsa' if you want a DSA private key.
Further information on how to create private keys can be found in
another HOWTO <keys.txt?>. The rest of this text assumes you have
a private key in the file privkey.pem.
Private keys are generated with 'openssl genrsa -out privkey.pem' if
you want a RSA private key, or if you want a DSA private key:
'openssl dsaparam -out dsaparam.pem 2048; openssl gendsa -out privkey.pem dsaparam.pem'.
The private keys created by these commands are not passphrase protected;
it might or might not be the desirable thing. Further information on how to
create private keys can be found at https://www.openssl.org/docs/HOWTO/keys.txt.
The rest of this text assumes you have a private key in the file privkey.pem.
3. Creating a certificate request
To create a certificate, you need to start with a certificate
request (or, as some certificate authorities like to put
it, "certificate signing request", since that's exactly what they do,
they sign it and give you the result back, thus making it authentic
according to their policies). A certificate request can then be sent
to a certificate authority to get it signed into a certificate, or if
you have your own certificate authority, you may sign it yourself, or
if you need a self-signed certificate (because you just want a test
certificate or because you are setting up your own CA).
To create a certificate, you need to start with a certificate request
(or, as some certificate authorities like to put it, "certificate
signing request", since that's exactly what they do, they sign it and
give you the result back, thus making it authentic according to their
policies). A certificate request is sent to a certificate authority
to get it signed into a certificate. You can also sign the certificate
yourself if you have your own certificate authority or create a
self-signed certificate (typically for testing purpose).
The certificate request is created like this:
@@ -55,12 +57,14 @@ The certificate request is created like this:
Now, cert.csr can be sent to the certificate authority, if they can
handle files in PEM format. If not, use the extra argument '-outform'
followed by the keyword for the format to use (see another HOWTO
<formats.txt?>). In some cases, that isn't sufficient and you will
have to be more creative.
<formats.txt?>). In some cases, -outform does not let you output the
certificate request in the right format and you will have to use one
of the various other commands that are exposed by openssl (or get
creative and use a combination of tools).
When the certificate authority has then done the checks the need to
do (and probably gotten payment from you), they will hand over your
new certificate to you.
The certificate authority performs various checks (according to their
policies) and usually waits for payment from you. Once that is
complete, they send you your new certificate.
Section 5 will tell you more on how to handle the certificate you
received.
@@ -68,11 +72,12 @@ received.
4. Creating a self-signed test certificate
If you don't want to deal with another certificate authority, or just
want to create a test certificate for yourself. This is similar to
creating a certificate request, but creates a certificate instead of
a certificate request. This is NOT the recommended way to create a
CA certificate, see ca.txt.
You can create a self-signed certificate if you don't want to deal
with a certificate authority, or if you just want to create a test
certificate for yourself. This is similar to creating a certificate
request, but creates a certificate instead of a certificate request.
This is NOT the recommended way to create a CA certificate, see
https://www.openssl.org/docs/apps/ca.html.
openssl req -new -x509 -key privkey.pem -out cacert.pem -days 1095
@@ -93,13 +98,13 @@ certificate and your key to various formats, most often also putting
them together into one file. The ways to do this is described in
another HOWTO <formats.txt?>, I will just mention the simplest case.
In the case of a raw DER thing in PEM format, and assuming that's all
right for yor applications, simply concatenating the certificate and
right for your applications, simply concatenating the certificate and
the key into a new file and using that one should be enough. With
some applications, you don't even have to do that.
By now, you have your cetificate and your private key and can start
using the software that depend on it.
By now, you have your certificate and your private key and can start
using applications that depend on it.
--
Richard Levitte

206
doc/HOWTO/proxy_certificates.txt
View File

@@ -1,74 +1,69 @@
<DRAFT!>
HOWTO proxy certificates
0. WARNING
NONE OF THE CODE PRESENTED HERE HAVE BEEN CHECKED! They are just an
example to show you how things can be done. There may be typos or
type conflicts, and you will have to resolve them.
NONE OF THE CODE PRESENTED HERE HAS BEEN CHECKED! The code is just examples to
show you how things could be done. There might be typos or type conflicts, and
you will have to resolve them.
1. Introduction
Proxy certificates are defined in RFC 3820. They are really usual
certificates with the mandatory extension proxyCertInfo.
Proxy certificates are defined in RFC 3820. They are really usual certificates
with the mandatory extension proxyCertInfo.
Proxy certificates are issued by an End Entity (typically a user),
either directly with the EE certificate as issuing certificate, or by
extension through an already issued proxy certificate.. They are used
to extend rights to some other entity (a computer process, typically,
or sometimes to the user itself), so it can perform operations in the
name of the owner of the EE certificate.
Proxy certificates are issued by an End Entity (typically a user), either
directly with the EE certificate as issuing certificate, or by extension through
an already issued proxy certificate. Proxy certificates are used to extend
rights to some other entity (a computer process, typically, or sometimes to the
user itself). This allows the entity to perform operations on behalf of the
owner of the EE certificate.
See http://www.ietf.org/rfc/rfc3820.txt for more information.
2. A warning about proxy certificates
Noone seems to have tested proxy certificates with security in mind.
Basically, to this date, it seems that proxy certificates have only
been used in a world that's highly aware of them. What would happen
if an unsuspecting application is to validate a chain of certificates
that contains proxy certificates? It would usually consider the leaf
to be the certificate to check for authorisation data, and since proxy
certificates are controlled by the EE certificate owner alone, it's
would be normal to consider what the EE certificate owner could do
with them.
No one seems to have tested proxy certificates with security in mind. To this
date, it seems that proxy certificates have only been used in a context highly
aware of them.
subjectAltName and issuerAltName are forbidden in proxy certificates,
and this is enforced in OpenSSL. The subject must be the same as the
issuer, with one commonName added on.
Existing applications might misbehave when trying to validate a chain of
certificates which use a proxy certificate. They might incorrectly consider the
leaf to be the certificate to check for authorisation data, which is controlled
by the EE certificate owner.
Possible threats are, as far as has been imagined so far:
subjectAltName and issuerAltName are forbidden in proxy certificates, and this
is enforced in OpenSSL. The subject must be the same as the issuer, with one
commonName added on.
Possible threats we can think of at this time include:
- impersonation through commonName (think server certificates).
- use of additional extensions, possibly non-standard ones used in
certain environments, that would grant extra or different
authorisation rights.
- use of additional extensions, possibly non-standard ones used in certain
environments, that would grant extra or different authorisation rights.
For this reason, OpenSSL requires that the use of proxy certificates
be explicitely allowed. Currently, this can be done using the
following methods:
For these reasons, OpenSSL requires that the use of proxy certificates be
explicitly allowed. Currently, this can be done using the following methods:
- if the application calls X509_verify_cert() itself, it can do the
following prior to that call (ctx is the pointer passed in the call
to X509_verify_cert()):
- if the application directly calls X509_verify_cert(), it can first call:
X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
- in all other cases, proxy certificate validation can be enabled
before starting the application by setting the envirnoment variable
OPENSSL_ALLOW_PROXY with some non-empty value.
Where ctx is the pointer which then gets passed to X509_verify_cert().
There are thoughts to allow proxy certificates with a line in the
default openssl.cnf, but that's still in the future.
- proxy certificate validation can be enabled before starting the application
by setting the environment variable OPENSSL_ALLOW_PROXY_CERTS.
In the future, it might be possible to enable proxy certificates by editing
openssl.cnf.
3. How to create proxy cerificates
3. How to create proxy certificates
It's quite easy to create proxy certificates, by taking advantage of
the lack of checks of the 'openssl x509' application (*ahem*). But
first, you need to create a configuration section that contains a
definition of the proxyCertInfo extension, a little like this:
Creating proxy certificates is quite easy, by taking advantage of a lack of
checks in the 'openssl x509' application (*ahem*). You must first create a
configuration section that contains a definition of the proxyCertInfo extension,
for example:
[ v3_proxy ]
# A proxy certificate MUST NEVER be a CA certificate.
@@ -77,10 +72,10 @@ definition of the proxyCertInfo extension, a little like this:
# Usual authority key ID
authorityKeyIdentifier=keyid,issuer:always
# Now, for the extension that marks this certificate as a proxy one
# The extension which marks this certificate as a proxy
proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:1,policy:text:AB
It's also possible to give the proxy extension in a separate section:
It's also possible to specify the proxy extension in a separate section:
proxyCertInfo=critical,@proxy_ext
@@ -89,96 +84,85 @@ It's also possible to give the proxy extension in a separate section:
pathlen=0
policy=text:BC
The policy value has a specific syntax, {syntag}:{string}, where the
syntag determines what will be done with the string. The recognised
syntags are as follows:
The policy value has a specific syntax, {syntag}:{string}, where the syntag
determines what will be done with the string. The following syntags are
recognised:
text indicates that the string is simply the bytes, not
encoded in any kind of way:
text indicates that the string is simply bytes, without any encoding:
policy=text:räksmörgås
policy=text:räksmörgås
Previous versions of this design had a specific tag
for UTF-8 text. However, since the bytes are copied
as-is anyway, there's no need for it. Instead, use
the text: tag, like this:
Previous versions of this design had a specific tag for UTF-8 text.
However, since the bytes are copied as-is anyway, there is no need for
such a specific tag.
policy=text:räksmörgås
hex indicates the string is encoded in hex, with colons between each byte
(every second hex digit):
hex indicates the string is encoded in hex, with colons
between each byte (every second hex digit):
policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73
policy=hex:72:E4:6B:73:6D:F6:72:67:E5:73
Previous versions of this design had a tag to insert a complete DER
blob. However, the only legal use for this would be to surround the
bytes that would go with the hex: tag with whatever is needed to
construct a correct OCTET STRING. The DER tag therefore felt
superfluous, and was removed.
Previous versions of this design had a tag to insert a
complete DER blob. However, the only legal use for
this would be to surround the bytes that would go with
the hex: tag with what's needed to construct a correct
OCTET STRING. Since hex: does that, the DER tag felt
superfluous, and was therefore removed.
file indicates that the text of the policy should really be
taken from a file. The string is then really a file
name. This is useful for policies that are large
(more than a few of lines) XML documents, for example.
file indicates that the text of the policy should really be taken from a
file. The string is then really a file name. This is useful for
policies that are large (more than a few lines, e.g. XML documents).
The 'policy' setting can be split up in multiple lines like this:
0.policy=This is
1.polisy= a multi-
1.policy= a multi-
2.policy=line policy.
NOTE: the proxy policy value is the part that determines the rights
granted to the process using the proxy certificate. The value is
completely dependent on the application reading and interpretting it!
NOTE: the proxy policy value is the part which determines the rights granted to
the process using the proxy certificate. The value is completely dependent on
the application reading and interpreting it!
Now that you have created an extension section for your proxy
certificate, you can now easily create a proxy certificate like this:
Now that you have created an extension section for your proxy certificate, you
can easily create a proxy certificate by doing:
openssl req -new -config openssl.cnf \
-out proxy.req -keyout proxy.key
openssl x509 -req -CAcreateserial -in proxy.req -days 7 \
-out proxy.crt -CA user.crt -CAkey user.key \
-extfile openssl.cnf -extensions v3_proxy
openssl req -new -config openssl.cnf -out proxy.req -keyout proxy.key
openssl x509 -req -CAcreateserial -in proxy.req -days 7 -out proxy.crt \
-CA user.crt -CAkey user.key -extfile openssl.cnf -extensions v3_proxy
It's just as easy to create a proxy certificate using another proxy
certificate as issuer (note that I'm using a different configuration
section for it):
You can also create a proxy certificate using another proxy certificate as
issuer (note: I'm using a different configuration section for it):
openssl req -new -config openssl.cnf \
-out proxy2.req -keyout proxy2.key
openssl x509 -req -CAcreateserial -in proxy2.req -days 7 \
-out proxy2.crt -CA proxy.crt -CAkey proxy.key \
-extfile openssl.cnf -extensions v3_proxy2
openssl req -new -config openssl.cnf -out proxy2.req -keyout proxy2.key
openssl x509 -req -CAcreateserial -in proxy2.req -days 7 -out proxy2.crt \
-CA proxy.crt -CAkey proxy.key -extfile openssl.cnf -extensions v3_proxy2
4. How to have your application interpret the policy?
The basic way to interpret proxy policies is to prepare some default
rights, then do a check of the proxy certificate against the a chain
of proxy certificates, user certificate and CA certificates, and see
what rights came out by the end. Sounds easy, huh? It almost is.
The basic way to interpret proxy policies is to start with some default rights,
then compute the resulting rights by checking the proxy certificate against
the chain of proxy certificates, user certificate and CA certificates. You then
use the final computed rights. Sounds easy, huh? It almost is.
The slightly complicated part is how to pass data between your
The slightly complicated part is figuring out how to pass data between your
application and the certificate validation procedure.
You need the following ingredients:
- a callback routing that will be called for every certificate that's
validated. It will be called several times for each certificates,
so you must be attentive to when it's a good time to do the proxy
policy interpretation and check, as well as to fill in the defaults
when the EE certificate is checked.
- a callback function that will be called for every certificate being
validated. The callback be called several times for each certificate,
so you must be careful to do the proxy policy interpretation at the right
time. You also need to fill in the defaults when the EE certificate is
checked.
- a structure of data that's shared between your application code and
the callback.
- a data structure that is shared between your application code and the
callback.
- a wrapper function that sets it all up.
- an ex_data index function that creates an index into the generic
ex_data store that's attached to an X509 validation context.
- an ex_data index function that creates an index into the generic ex_data
store that is attached to an X509 validation context.
This is some cookbook code for you to fill in:
Here is some skeleton code you can fill in:
/* In this example, I will use a view of granted rights as a bit
array, one bit for each possible right. */
@@ -210,7 +194,7 @@ This is some cookbook code for you to fill in:
static int verify_callback(int ok, X509_STORE_CTX *ctx)
{
if (ok == 1) /* It's REALLY important you keep the proxy policy
check within this secion. It's important to know
check within this section. It's important to know
that when ok is 1, the certificates are checked
from top to bottom. You get the CA root first,
followed by the possible chain of intermediate
@@ -221,7 +205,7 @@ This is some cookbook code for you to fill in:
if (xs->ex_flags & EXFLAG_PROXY)
{
YOUR_RIGHTS *rights =
YOUR_RIGHTS *rights =
(YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
get_proxy_auth_ex_data_idx());
PROXY_CERT_INFO_EXTENSION *pci =
@@ -250,12 +234,12 @@ This is some cookbook code for you to fill in:
bit array and fill it with the rights granted by
the current proxy certificate, then use it as a
mask on the accumulated rights bit array, and
voilà, you now have a new accumulated rights bit
voilà, you now have a new accumulated rights bit
array. */
{
int i;
YOUR_RIGHTS tmp_rights;
memset(tmp_rights.rights, 0, sizeof(tmp_rights.rights));
memset(tmp_rights.rights, 0, sizeof(tmp_rights.rights));
/* process_rights() is supposed to be a procedure
that takes a string and it's length, interprets
@@ -276,7 +260,7 @@ This is some cookbook code for you to fill in:
{
/* We have a EE certificate, let's use it to set default!
*/
YOUR_RIGHTS *rights =
YOUR_RIGHTS *rights =
(YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
get_proxy_auth_ex_data_idx());

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

@@ -39,13 +39,13 @@ prints a usage message.
=item B<-newcert>
creates a new self signed certificate. The private key and certificate are
written to the file "newreq.pem".
creates a new self signed certificate. The private key is written to the file
"newkey.pem" and the request written to the file "newreq.pem".
=item B<-newreq>
creates a new certificate request. The private key and request are
written to the file "newreq.pem".
creates a new certificate request. The private key is written to the file
"newkey.pem" and the request written to the file "newreq.pem".
=item B<-newreq-nodes>

10
doc/apps/asn1parse.pod
View File

@@ -15,6 +15,8 @@ B<openssl> B<asn1parse>
[B<-length number>]
[B<-i>]
[B<-oid filename>]
[B<-dump>]
[B<-dlimit num>]
[B<-strparse offset>]
[B<-genstr string>]
[B<-genconf file>]
@@ -64,6 +66,14 @@ indents the output according to the "depth" of the structures.
a file containing additional OBJECT IDENTIFIERs (OIDs). The format of this
file is described in the NOTES section below.
=item B<-dump>
dump unknown data in hex format.
=item B<-dlimit num>
like B<-dump>, but only the first B<num> bytes are output.
=item B<-strparse offset>
parse the contents octets of the ASN.1 object starting at B<offset>. This

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

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

25
doc/apps/ca.pod
View File

@@ -13,6 +13,8 @@ B<openssl> B<ca>
[B<-name section>]
[B<-gencrl>]
[B<-revoke file>]
[B<-status serial>]
[B<-updatedb>]
[B<-crl_reason reason>]
[B<-crl_hold instruction>]
[B<-crl_compromise time>]
@@ -26,6 +28,7 @@ B<openssl> B<ca>
[B<-md arg>]
[B<-policy arg>]
[B<-keyfile arg>]
[B<-keyform PEM|DER>]
[B<-key arg>]
[B<-passin arg>]
[B<-cert file>]
@@ -83,7 +86,7 @@ a single self signed certificate to be signed by the CA.
a file containing a single Netscape signed public key and challenge
and additional field values to be signed by the CA. See the B<SPKAC FORMAT>
section for information on the required format.
section for information on the required input and output format.
=item B<-infiles>
@@ -94,7 +97,7 @@ are assumed to the the names of files containing certificate requests.
the output file to output certificates to. The default is standard
output. The certificate details will also be printed out to this
file.
file in PEM format (except that B<-spkac> outputs DER format).
=item B<-outdir directory>
@@ -110,6 +113,11 @@ the CA certificate file.
the private key to sign requests with.
=item B<-keyform PEM|DER>
the format of the data in the private key file.
The default is PEM.
=item B<-key password>
the password used to encrypt the private key. Since on some
@@ -267,6 +275,15 @@ the number of hours before the next CRL is due.
a filename containing a certificate to revoke.
=item B<-status serial>
displays the revocation status of the certificate with the specified
serial number and exits.
=item B<-updatedb>
Updates the database index to purge expired certificates.
=item B<-crl_reason reason>
revocation reason, where B<reason> is one of: B<unspecified>, B<keyCompromise>,
@@ -499,6 +516,10 @@ the SPKAC and also the required DN components as name value pairs.
If you need to include the same component twice then it can be
preceded by a number and a '.'.
When processing SPKAC format, the output is DER if the B<-out>
flag is used, but PEM format if sending to stdout or the B<-outdir>
flag is used.
=head1 EXAMPLES
Note: these examples assume that the B<ca> directory structure is

250
doc/apps/ciphers.pod
View File

@@ -36,7 +36,7 @@ SSL v2 and for SSL v3/TLS v1.
=item B<-V>
Like B<-V>, but include cipher suite codes in output (hex format).
Like B<-v>, but include cipher suite codes in output (hex format).
=item B<-ssl3>
@@ -109,15 +109,15 @@ The following is a list of all permitted cipher strings and their meanings.
=item B<DEFAULT>
the default cipher list. This is determined at compile time and, as of OpenSSL
1.0.0, is normally B<ALL:!aNULL:!eNULL>. This must be the first cipher string
the default cipher list. This is determined at compile time and
is normally B<ALL:!EXPORT:!aNULL:!eNULL:!SSLv2>. This must be the firstcipher string
specified.
=item B<COMPLEMENTOFDEFAULT>
the ciphers included in B<ALL>, but not enabled by default. Currently
this is B<ADH>. Note that this rule does not cover B<eNULL>, which is
not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary).
this is B<ADH> and B<AECDH>. Note that this rule does not cover B<eNULL>,
which is not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary).
=item B<ALL>
@@ -165,21 +165,58 @@ included.
=item B<aNULL>
the cipher suites offering no authentication. This is currently the anonymous
DH algorithms. These cipher suites are vulnerable to a "man in the middle"
attack and so their use is normally discouraged.
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.
=item B<kRSA>, B<RSA>
cipher suites using RSA key exchange.
=item B<kEDH>
cipher suites using ephemeral DH key agreement.
=item B<kDHr>, B<kDHd>
=item B<kDHr>, B<kDHd>, B<kDH>
cipher suites using DH key agreement and DH certificates signed by CAs with RSA
and DSS keys respectively. Not implemented.
and DSS keys or either respectively.
=item B<kDHE>, B<kEDH>
cipher suites using ephemeral DH key agreement, including anonymous cipher
suites.
=item B<DHE>, B<EDH>
cipher suites using authenticated ephemeral DH key agreement.
=item B<ADH>
anonymous DH cipher suites, note that this does not include anonymous Elliptic
Curve DH (ECDH) cipher suites.
=item B<DH>
cipher suites using DH, including anonymous DH, ephemeral DH and fixed DH.
=item B<kECDHr>, B<kECDHe>, B<kECDH>
cipher suites using fixed ECDH key agreement signed by CAs with RSA and ECDSA
keys or either respectively.
=item B<kECDHE>, B<kEECDH>
cipher suites using ephemeral ECDH key agreement, including anonymous
cipher suites.
=item B<ECDHE>, B<EECDH>
cipher suites using authenticated ephemeral ECDH key agreement.
=item B<AECDH>
anonymous Elliptic Curve Diffie Hellman cipher suites.
=item B<ECDH>
cipher suites using ECDH key exchange, including anonymous, ephemeral and
fixed ECDH.
=item B<aRSA>
@@ -192,32 +229,41 @@ cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
=item B<aDH>
cipher suites effectively using DH authentication, i.e. the certificates carry
DH keys. Not implemented.
DH keys.
=item B<aECDH>
cipher suites effectively using ECDH authentication, i.e. the certificates
carry ECDH keys.
=item B<aECDSA>, B<ECDSA>
cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA
keys.
=item B<kFZA>, B<aFZA>, B<eFZA>, B<FZA>
ciphers suites using FORTEZZA key exchange, authentication, encryption or all
FORTEZZA algorithms. Not implemented.
=item B<TLSv1>, B<SSLv3>, B<SSLv2>
=item B<TLSv1.2>, B<TLSv1>, B<SSLv3>, B<SSLv2>
TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites respectively.
TLS v1.2, TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites respectively. Note:
there are no ciphersuites specific to TLS v1.1.
=item B<DH>
=item B<AES128>, B<AES256>, B<AES>
cipher suites using DH, including anonymous DH.
cipher suites using 128 bit AES, 256 bit AES or either 128 or 256 bit AES.
=item B<ADH>
=item B<AESGCM>
anonymous DH cipher suites.
AES in Galois Counter Mode (GCM): these ciphersuites are only supported
in TLS v1.2.
=item B<AES>
=item B<CAMELLIA128>, B<CAMELLIA256>, B<CAMELLIA>
cipher suites using AES.
=item B<CAMELLIA>
cipher suites using Camellia.
cipher suites using 128 bit CAMELLIA, 256 bit CAMELLIA or either 128 or 256 bit
CAMELLIA.
=item B<3DES>
@@ -251,6 +297,10 @@ cipher suites using MD5.
cipher suites using SHA1.
=item B<SHA256>, B<SHA384>
ciphersuites using SHA256 or SHA384.
=item B<aGOST>
cipher suites using GOST R 34.10 (either 2001 or 94) for authenticaction
@@ -277,6 +327,21 @@ cipher suites, using HMAC based on GOST R 34.11-94.
cipher suites using GOST 28147-89 MAC B<instead of> HMAC.
=item B<PSK>
cipher suites using pre-shared keys (PSK).
=item B<SUITEB128>, B<SUITEB128ONLY>, B<SUITEB192>
enables suite B mode operation using 128 (permitting 192 bit mode by peer)
128 bit (not permitting 192 bit by peer) or 192 bit level of security
respectively. If used these cipherstrings should appear first in the cipher
list and anything after them is ignored. Setting Suite B mode has additional
consequences required to comply with RFC6460. In particular the supported
signature algorithms is reduced to support only ECDSA and SHA256 or SHA384,
only the elliptic curves P-256 and P-384 can be used and only the two suite B
compliant ciphersuites (ECDHE-ECDSA-AES128-GCM-SHA256 and
ECDHE-ECDSA-AES256-GCM-SHA384) are permissible.
=back
@@ -300,12 +365,10 @@ e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
SSL_RSA_WITH_DES_CBC_SHA DES-CBC-SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
SSL_DH_DSS_EXPORT_WITH_DES40_CBC_SHA Not implemented.
SSL_DH_DSS_WITH_DES_CBC_SHA Not implemented.
SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA Not implemented.
SSL_DH_RSA_EXPORT_WITH_DES40_CBC_SHA Not implemented.
SSL_DH_RSA_WITH_DES_CBC_SHA Not implemented.
SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA Not implemented.
SSL_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
@@ -360,10 +423,10 @@ e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
TLS_RSA_WITH_AES_128_CBC_SHA AES128-SHA
TLS_RSA_WITH_AES_256_CBC_SHA AES256-SHA
TLS_DH_DSS_WITH_AES_128_CBC_SHA Not implemented.
TLS_DH_DSS_WITH_AES_256_CBC_SHA Not implemented.
TLS_DH_RSA_WITH_AES_128_CBC_SHA Not implemented.
TLS_DH_RSA_WITH_AES_256_CBC_SHA Not implemented.
TLS_DH_DSS_WITH_AES_128_CBC_SHA DH-DSS-AES128-SHA
TLS_DH_DSS_WITH_AES_256_CBC_SHA DH-DSS-AES256-SHA
TLS_DH_RSA_WITH_AES_128_CBC_SHA DH-RSA-AES128-SHA
TLS_DH_RSA_WITH_AES_256_CBC_SHA DH-RSA-AES256-SHA
TLS_DHE_DSS_WITH_AES_128_CBC_SHA DHE-DSS-AES128-SHA
TLS_DHE_DSS_WITH_AES_256_CBC_SHA DHE-DSS-AES256-SHA
@@ -378,10 +441,10 @@ e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
TLS_RSA_WITH_CAMELLIA_128_CBC_SHA CAMELLIA128-SHA
TLS_RSA_WITH_CAMELLIA_256_CBC_SHA CAMELLIA256-SHA
TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA Not implemented.
TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA Not implemented.
TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA Not implemented.
TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA Not implemented.
TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA DH-DSS-CAMELLIA128-SHA
TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA DH-DSS-CAMELLIA256-SHA
TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA DH-RSA-CAMELLIA128-SHA
TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA DH-RSA-CAMELLIA256-SHA
TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA DHE-DSS-CAMELLIA128-SHA
TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA DHE-DSS-CAMELLIA256-SHA
@@ -395,8 +458,8 @@ e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
TLS_RSA_WITH_SEED_CBC_SHA SEED-SHA
TLS_DH_DSS_WITH_SEED_CBC_SHA Not implemented.
TLS_DH_RSA_WITH_SEED_CBC_SHA Not implemented.
TLS_DH_DSS_WITH_SEED_CBC_SHA DH-DSS-SEED-SHA
TLS_DH_RSA_WITH_SEED_CBC_SHA DH-RSA-SEED-SHA
TLS_DHE_DSS_WITH_SEED_CBC_SHA DHE-DSS-SEED-SHA
TLS_DHE_RSA_WITH_SEED_CBC_SHA DHE-RSA-SEED-SHA
@@ -423,7 +486,100 @@ Note: these ciphers can also be used in SSL v3.
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 SSL v2.0 cipher suites.
=head2 Elliptic curve cipher suites.
TLS_ECDH_RSA_WITH_NULL_SHA ECDH-RSA-NULL-SHA
TLS_ECDH_RSA_WITH_RC4_128_SHA ECDH-RSA-RC4-SHA
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA ECDH-RSA-DES-CBC3-SHA
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA ECDH-RSA-AES128-SHA
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA ECDH-RSA-AES256-SHA
TLS_ECDH_ECDSA_WITH_NULL_SHA ECDH-ECDSA-NULL-SHA
TLS_ECDH_ECDSA_WITH_RC4_128_SHA ECDH-ECDSA-RC4-SHA
TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA ECDH-ECDSA-DES-CBC3-SHA
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA ECDH-ECDSA-AES128-SHA
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA ECDH-ECDSA-AES256-SHA
TLS_ECDHE_RSA_WITH_NULL_SHA ECDHE-RSA-NULL-SHA
TLS_ECDHE_RSA_WITH_RC4_128_SHA ECDHE-RSA-RC4-SHA
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ECDHE-RSA-DES-CBC3-SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA ECDHE-RSA-AES128-SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA ECDHE-RSA-AES256-SHA
TLS_ECDHE_ECDSA_WITH_NULL_SHA ECDHE-ECDSA-NULL-SHA
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA ECDHE-ECDSA-RC4-SHA
TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA ECDHE-ECDSA-DES-CBC3-SHA
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA ECDHE-ECDSA-AES128-SHA
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA ECDHE-ECDSA-AES256-SHA
TLS_ECDH_anon_WITH_NULL_SHA AECDH-NULL-SHA
TLS_ECDH_anon_WITH_RC4_128_SHA AECDH-RC4-SHA
TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA AECDH-DES-CBC3-SHA
TLS_ECDH_anon_WITH_AES_128_CBC_SHA AECDH-AES128-SHA
TLS_ECDH_anon_WITH_AES_256_CBC_SHA AECDH-AES256-SHA
=head2 TLS v1.2 cipher suites
TLS_RSA_WITH_NULL_SHA256 NULL-SHA256
TLS_RSA_WITH_AES_128_CBC_SHA256 AES128-SHA256
TLS_RSA_WITH_AES_256_CBC_SHA256 AES256-SHA256
TLS_RSA_WITH_AES_128_GCM_SHA256 AES128-GCM-SHA256
TLS_RSA_WITH_AES_256_GCM_SHA384 AES256-GCM-SHA384
TLS_DH_RSA_WITH_AES_128_CBC_SHA256 DH-RSA-AES128-SHA256
TLS_DH_RSA_WITH_AES_256_CBC_SHA256 DH-RSA-AES256-SHA256
TLS_DH_RSA_WITH_AES_128_GCM_SHA256 DH-RSA-AES128-GCM-SHA256
TLS_DH_RSA_WITH_AES_256_GCM_SHA384 DH-RSA-AES256-GCM-SHA384
TLS_DH_DSS_WITH_AES_128_CBC_SHA256 DH-DSS-AES128-SHA256
TLS_DH_DSS_WITH_AES_256_CBC_SHA256 DH-DSS-AES256-SHA256
TLS_DH_DSS_WITH_AES_128_GCM_SHA256 DH-DSS-AES128-GCM-SHA256
TLS_DH_DSS_WITH_AES_256_GCM_SHA384 DH-DSS-AES256-GCM-SHA384
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 DHE-RSA-AES128-SHA256
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 DHE-RSA-AES256-SHA256
TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 DHE-RSA-AES128-GCM-SHA256
TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 DHE-RSA-AES256-GCM-SHA384
TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 DHE-DSS-AES128-SHA256
TLS_DHE_DSS_WITH_AES_256_CBC_SHA256 DHE-DSS-AES256-SHA256
TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 DHE-DSS-AES128-GCM-SHA256
TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 DHE-DSS-AES256-GCM-SHA384
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 ECDH-RSA-AES128-SHA256
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 ECDH-RSA-AES256-SHA384
TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 ECDH-RSA-AES128-GCM-SHA256
TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 ECDH-RSA-AES256-GCM-SHA384
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 ECDH-ECDSA-AES128-SHA256
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 ECDH-ECDSA-AES256-SHA384
TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 ECDH-ECDSA-AES128-GCM-SHA256
TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 ECDH-ECDSA-AES256-GCM-SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 ECDHE-RSA-AES128-SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 ECDHE-RSA-AES256-SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ECDHE-RSA-AES128-GCM-SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 ECDHE-RSA-AES256-GCM-SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 ECDHE-ECDSA-AES128-SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 ECDHE-ECDSA-AES256-SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 ECDHE-ECDSA-AES128-GCM-SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 ECDHE-ECDSA-AES256-GCM-SHA384
TLS_DH_anon_WITH_AES_128_CBC_SHA256 ADH-AES128-SHA256
TLS_DH_anon_WITH_AES_256_CBC_SHA256 ADH-AES256-SHA256
TLS_DH_anon_WITH_AES_128_GCM_SHA256 ADH-AES128-GCM-SHA256
TLS_DH_anon_WITH_AES_256_GCM_SHA384 ADH-AES256-GCM-SHA384
=head2 Pre shared keying (PSK) cipheruites
TLS_PSK_WITH_RC4_128_SHA PSK-RC4-SHA
TLS_PSK_WITH_3DES_EDE_CBC_SHA PSK-3DES-EDE-CBC-SHA
TLS_PSK_WITH_AES_128_CBC_SHA PSK-AES128-CBC-SHA
TLS_PSK_WITH_AES_256_CBC_SHA PSK-AES256-CBC-SHA
=head2 Deprecated SSL v2.0 cipher suites.
SSL_CK_RC4_128_WITH_MD5 RC4-MD5
SSL_CK_RC4_128_EXPORT40_WITH_MD5 EXP-RC4-MD5
@@ -435,9 +591,6 @@ Note: these ciphers can also be used in SSL v3.
=head1 NOTES
The non-ephemeral DH modes are currently unimplemented in OpenSSL
because there is no support for DH certificates.
Some compiled versions of OpenSSL may not include all the ciphers
listed here because some ciphers were excluded at compile time.
@@ -452,6 +605,11 @@ strength:
openssl ciphers -v 'ALL:!ADH:@STRENGTH'
Include all ciphers except ones with no encryption (eNULL) or no
authentication (aNULL):
openssl ciphers -v 'ALL:!aNULL'
Include only 3DES ciphers and then place RSA ciphers last:
openssl ciphers -v '3DES:+RSA'

79
doc/apps/cms.pod
View File

@@ -35,6 +35,7 @@ B<openssl> B<cms>
[B<-print>]
[B<-CAfile file>]
[B<-CApath dir>]
[B<-no_alt_chains>]
[B<-md digest>]
[B<-[cipher]>]
[B<-nointern>]
@@ -57,6 +58,7 @@ B<openssl> B<cms>
[B<-secretkeyid id>]
[B<-econtent_type type>]
[B<-inkey file>]
[B<-keyopt name:parameter>]
[B<-passin arg>]
[B<-rand file(s)>]
[B<cert.pem...>]
@@ -90,6 +92,11 @@ decrypt mail using the supplied certificate and private key. Expects an
encrypted mail message in MIME format for the input file. The decrypted mail
is written to the output file.
=item B<-debug_decrypt>
this option sets the B<CMS_DEBUG_DECRYPT> flag. This option should be used
with caution: see the notes section below.
=item B<-sign>
sign mail using the supplied certificate and private key. Input file is
@@ -138,7 +145,7 @@ output an error.
=item B<-EncryptedData_encrypt>
Encrypt suppled content using supplied symmetric key and algorithm using a CMS
Encrypt content using supplied symmetric key and algorithm using a CMS
B<EncrytedData> type and output the content.
=item B<-sign_receipt>
@@ -316,8 +323,13 @@ verification was successful.
=item B<-recip file>
the recipients certificate when decrypting a message. This certificate
must match one of the recipients of the message or an error occurs.
when decrypting a message this specifies the recipients certificate. The
certificate must match one of the recipients of the message or an error
occurs.
When encrypting a message this option may be used multiple times to specify
each recipient. This form B<must> be used if customised parameters are
required (for example to specify RSA-OAEP).
=item B<-keyid>
@@ -376,6 +388,13 @@ private key must be included in the certificate file specified with
the B<-recip> or B<-signer> file. When signing this option can be used
multiple times to specify successive keys.
=item B<-keyopt name:opt>
for signing and encryption this option can be used multiple times to
set customised parameters for the preceding key or certificate. It can
currently be used to set RSA-PSS for signing, RSA-OAEP for encryption
or to modify default parameters for ECDH.
=item B<-passin arg>
the private key password source. For more information about the format of B<arg>
@@ -401,7 +420,7 @@ 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>
=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains>
Set various certificate chain valiadition option. See the
L<B<verify>|verify(1)> manual page for details.
@@ -446,32 +465,42 @@ Streaming is always used for the B<-sign> operation with detached data but
since the content is no longer part of the CMS structure the encoding
remains DER.
If the B<-decrypt> option is used without a recipient certificate then an
attempt is made to locate the recipient by trying each potential recipient
in turn using the supplied private key. To thwart the MMA attack
(Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are
tried whether they succeed or not and if no recipients match the message
is "decrypted" using a random key which will typically output garbage.
The B<-debug_decrypt> option can be used to disable the MMA attack protection
and return an error if no recipient can be found: this option should be used
with caution. For a fuller description see L<CMS_decrypt(3)|CMS_decrypt(3)>).
=head1 EXIT CODES
=over 4
=item 0
=item Z<>0
the operation was completely successfully.
=item 1
=item Z<>1
an error occurred parsing the command options.
=item 2
=item Z<>2
one of the input files could not be read.
=item 3
=item Z<>3
an error occurred creating the CMS file or when reading the MIME
message.
=item 4
=item Z<>4
an error occurred decrypting or verifying the message.
=item 5
=item Z<>5
the message was verified correctly but an error occurred writing out
the signers certificates.
@@ -493,6 +522,10 @@ The B<-compress> option.
The B<-secretkey> option when used with B<-encrypt>.
The use of PSS with B<-sign>.
The use of OAEP or non-RSA keys with B<-encrypt>.
Additionally the B<-EncryptedData_create> and B<-data_create> type cannot
be processed by the older B<smime> command.
@@ -573,6 +606,21 @@ Add a signer to an existing message:
openssl cms -resign -in mail.msg -signer newsign.pem -out mail2.msg
Sign mail using RSA-PSS:
openssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -keyopt rsa_padding_mode:pss
Create encrypted mail using RSA-OAEP:
openssl cms -encrypt -in plain.txt -out mail.msg \
-recip cert.pem -keyopt rsa_padding_mode:oaep
Use SHA256 KDF with an ECDH certificate:
openssl cms -encrypt -in plain.txt -out mail.msg \
-recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
=head1 BUGS
The MIME parser isn't very clever: it seems to handle most messages that I've
@@ -598,5 +646,16 @@ No revocation checking is done on the signer's certificate.
The use of multiple B<-signer> options and the B<-resign> command were first
added in OpenSSL 1.0.0
The B<keyopt> option was first added in OpenSSL 1.1.0
The use of B<-recip> to specify the recipient when encrypting mail was first
added to OpenSSL 1.1.0
Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0.
The use of non-RSA keys with B<-encrypt> and B<-decrypt> was first added
to OpenSSL 1.1.0.
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
=cut

77
doc/apps/config.pod
View File

@@ -89,8 +89,7 @@ section containing configuration module specific information. E.g.
... engine stuff here ...
Currently there are two configuration modules. One for ASN1 objects another
for ENGINE configuration.
The features of each configuration module are described below.
=head2 ASN1 OBJECT CONFIGURATION MODULE
@@ -119,7 +118,7 @@ variable points to a section containing further ENGINE configuration
information.
The section pointed to by B<engines> is a table of engine names (though see
B<engine_id> below) and further sections containing configuration informations
B<engine_id> below) and further sections containing configuration information
specific to each ENGINE.
Each ENGINE specific section is used to set default algorithms, load
@@ -191,6 +190,25 @@ For example:
# Supply all default algorithms
default_algorithms = ALL
=head2 EVP CONFIGURATION MODULE
This modules has the name B<alg_section> which points to a section containing
algorithm commands.
Currently the only algorithm command supported is B<fips_mode> whose
value should be a boolean string such as B<on> or B<off>. If the value is
B<on> this attempt to enter FIPS mode. If the call fails or the library is
not FIPS capable then an error occurs.
For example:
alg_section = evp_settings
[evp_settings]
fips_mode = on
=head1 NOTES
If a configuration file attempts to expand a variable that doesn't exist
@@ -259,6 +277,59 @@ priority and B</tmp> used if neither is defined:
# The above value is used if TEMP isn't in the environment
tmpfile=${ENV::TEMP}/tmp.filename
Simple OpenSSL library configuration example to enter FIPS mode:
# Default appname: should match "appname" parameter (if any)
# supplied to CONF_modules_load_file et al.
openssl_conf = openssl_conf_section
[openssl_conf_section]
# Configuration module list
alg_section = evp_sect
[evp_sect]
# Set to "yes" to enter FIPS mode if supported
fips_mode = yes
Note: in the above example you will get an error in non FIPS capable versions
of OpenSSL.
More complex OpenSSL library configuration. Add OID and don't enter FIPS mode:
# Default appname: should match "appname" parameter (if any)
# supplied to CONF_modules_load_file et al.
openssl_conf = openssl_conf_section
[openssl_conf_section]
# Configuration module list
alg_section = evp_sect
oid_section = new_oids
[evp_sect]
# This will have no effect as FIPS mode is off by default.
# Set to "yes" to enter FIPS mode, if supported
fips_mode = no
[new_oids]
# New OID, just short name
newoid1 = 1.2.3.4.1
# New OID shortname and long name
newoid2 = New OID 2 long name, 1.2.3.4.2
The above examples can be used with with any application supporting library
configuration if "openssl_conf" is modified to match the appropriate "appname".
For example if the second sample file above is saved to "example.cnf" then
the command line:
OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1
will output:
0:d=0 hl=2 l= 4 prim: OBJECT :newoid1
showing that the OID "newoid1" has been added as "1.2.3.4.1".
=head1 BUGS
Currently there is no way to include characters using the octal B<\nnn>

11
doc/apps/crl.pod
View File

@@ -12,6 +12,7 @@ B<openssl> B<crl>
[B<-text>]
[B<-in filename>]
[B<-out filename>]
[B<-nameopt option>]
[B<-noout>]
[B<-hash>]
[B<-issuer>]
@@ -53,6 +54,11 @@ default.
print out the CRL in text form.
=item B<-nameopt option>
option which determines how the subject or issuer names are displayed. See
the description of B<-nameopt> in L<x509(1)|x509(1)>.
=item B<-noout>
don't output the encoded version of the CRL.
@@ -62,6 +68,11 @@ don't output the encoded version of the CRL.
output a hash of the issuer name. This can be use to lookup CRLs in
a directory by issuer name.
=item B<-hash_old>
outputs the "hash" of the CRL issuer name using the older algorithm
as used by OpenSSL versions before 1.0.0.
=item B<-issuer>
output the issuer name.

79
doc/apps/dgst.pod
View File

@@ -2,16 +2,19 @@
=head1 NAME
dgst, md5, md4, md2, sha1, sha, mdc2, ripemd160 - message digests
dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md2, md4, md5, dss1 - message digests
=head1 SYNOPSIS
B<openssl> B<dgst>
[B<-md5|-md4|-md2|-sha1|-sha|-mdc2|-ripemd160|-dss1>]
[B<-sha|-sha1|-mdc2|-ripemd160|-sha224|-sha256|-sha384|-sha512|-md2|-md4|-md5|-dss1>]
[B<-c>]
[B<-d>]
[B<-hex>]
[B<-binary>]
[B<-r>]
[B<-hmac arg>]
[B<-non-fips-allow>]
[B<-out filename>]
[B<-sign filename>]
[B<-keyform arg>]
@@ -20,17 +23,19 @@ B<openssl> B<dgst>
[B<-prverify filename>]
[B<-signature filename>]
[B<-hmac key>]
[B<-non-fips-allow>]
[B<-fips-fingerprint>]
[B<file...>]
[B<md5|md4|md2|sha1|sha|mdc2|ripemd160>]
[B<-c>]
[B<-d>]
[B<file...>]
B<openssl>
[I<digest>]
[B<...>]
=head1 DESCRIPTION
The digest functions output the message digest of a supplied file or files
in hexadecimal form. They can also be used for digital signing and verification.
in hexadecimal. The digest functions also generate and verify digital
signatures using message digests.
=head1 OPTIONS
@@ -48,12 +53,26 @@ print out BIO debugging information.
=item B<-hex>
digest is to be output as a hex dump. This is the default case for a "normal"
digest as opposed to a digital signature.
digest as opposed to a digital signature. See NOTES below for digital
signatures using B<-hex>.
=item B<-binary>
output the digest or signature in binary form.
=item B<-r>
output the digest in the "coreutils" format used by programs like B<sha1sum>.
=item B<-hmac arg>
set the HMAC key to "arg".
=item B<-non-fips-allow>
Allow use of non FIPS digest when in FIPS mode. This has no effect when not in
FIPS mode.
=item B<-out filename>
filename to output to, or standard output by default.
@@ -64,8 +83,8 @@ digitally sign the digest using the private key in "filename".
=item B<-keyform arg>
Specifies the key format to sign digest with. Only PEM and ENGINE
formats are supported by the B<dgst> command.
Specifies the key format to sign digest with. The DER, PEM, P12,
and ENGINE formats are supported.
=item B<-engine id>
@@ -117,7 +136,7 @@ Following options are supported by both by B<HMAC> and B<gost-mac>:
=over 8
=item B<key:string>
Specifies MAC key as alphnumeric string (use if key contain printable
characters only). String length must conform to any restrictions of
the MAC algorithm for example exactly 32 chars for gost-mac.
@@ -138,6 +157,15 @@ Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-non-fips-allow>
enable use of non-FIPS algorithms such as MD5 even in FIPS mode.
=item B<-fips-fingerprint>
compute HMAC using a specific key
for certain OpenSSL-FIPS operations.
=item B<file...>
file or files to digest. If no files are specified then standard input is
@@ -145,18 +173,41 @@ used.
=back
=head1 EXAMPLES
To create a hex-encoded message digest of a file:
openssl dgst -md5 -hex file.txt
To sign a file using SHA-256 with binary file output:
openssl dgst -sha256 -sign privatekey.pem -out signature.sign file.txt
To verify a signature:
openssl dgst -sha256 -verify publickey.pem \
-signature signature.sign \
file.txt
=head1 NOTES
The digest of choice for all new applications is SHA1. Other digests are
however still widely used.
If you wish to sign or verify data using the DSA algorithm then the dss1
digest must be used.
When signing a file, B<dgst> will automatically determine the algorithm
(RSA, ECC, etc) to use for signing based on the private key's ASN.1 info.
When verifying signatures, it only handles the RSA, DSA, or ECDSA signature
itself, not the related data to identify the signer and algorithm used in
formats such as x.509, CMS, and S/MIME.
A source of random numbers is required for certain signing algorithms, in
particular DSA.
particular ECDSA and DSA.
The signing and verify options should only be used if a single file is
being signed or verified.
Hex signatures cannot be verified using B<openssl>. Instead, use "xxd -r"
or similar program to transform the hex signature into a binary signature
prior to verification.
=cut

18
doc/apps/dhparam.pod
View File

@@ -12,6 +12,7 @@ B<openssl dhparam>
[B<-in> I<filename>]
[B<-out> I<filename>]
[B<-dsaparam>]
[B<-check>]
[B<-noout>]
[B<-text>]
[B<-C>]
@@ -64,10 +65,16 @@ exchange more efficient. Beware that with such DSA-style DH
parameters, a fresh DH key should be created for each use to
avoid small-subgroup attacks that may be possible otherwise.
=item B<-check>
check if the parameters are valid primes and generator.
=item B<-2>, B<-5>
The generator to use, either 2 or 5. 2 is the default. If present then the
input file is ignored and parameters are generated instead.
The generator to use, either 2 or 5. If present then the
input file is ignored and parameters are generated instead. If not
present but B<numbits> is present, parameters are generated with the
default generator 2.
=item B<-rand> I<file(s)>
@@ -80,9 +87,10 @@ all others.
=item I<numbits>
this option specifies that a parameter set should be generated of size
I<numbits>. It must be the last option. If not present then a value of 512
is used. If this option is present then the input file is ignored and
parameters are generated instead.
I<numbits>. It must be the last option. If this option is present then
the input file is ignored and parameters are generated instead. If
this option is not present but a generator (B<-2> or B<-5>) is
present, parameters are generated with a default length of 2048 bits.
=item B<-noout>

12
doc/apps/dsa.pod
View File

@@ -13,6 +13,12 @@ B<openssl> B<dsa>
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
[B<-camellia128>]
[B<-camellia192>]
[B<-camellia256>]
[B<-des>]
[B<-des3>]
[B<-idea>]
@@ -74,10 +80,10 @@ filename.
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-des|-des3|-idea>
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
These options encrypt the private key with the DES, triple DES, or the
IDEA ciphers respectively before outputting it. A pass phrase is prompted for.
These options encrypt the private key with the specified
cipher before outputting it. A pass phrase is prompted for.
If none of these options is specified the key is written in plain text. This
means that using the B<dsa> utility to read in an encrypted key with no
encryption option can be used to remove the pass phrase from a key, or by

2
doc/apps/ec.pod
View File

@@ -41,7 +41,7 @@ PKCS#8 private key format use the B<pkcs8> command.
This specifies the input format. The B<DER> option with a private key uses
an ASN.1 DER encoded SEC1 private key. When used with a public key it
uses the SubjectPublicKeyInfo structur as specified in RFC 3280.
uses the SubjectPublicKeyInfo structure as specified in RFC 3280.
The B<PEM> form is the default format: it consists of the B<DER> format base64
encoded with additional header and footer lines. In the case of a private key
PKCS#8 format is also accepted.

2
doc/apps/ecparam.pod
View File

@@ -16,7 +16,7 @@ B<openssl ecparam>
[B<-C>]
[B<-check>]
[B<-name arg>]
[B<-list_curve>]
[B<-list_curves>]
[B<-conv_form arg>]
[B<-param_enc arg>]
[B<-no_seed>]

4
doc/apps/enc.pod
View File

@@ -215,6 +215,10 @@ unsupported options (for example B<openssl enc -help>) includes a
list of ciphers, supported by your versesion of OpenSSL, including
ones provided by configured engines.
The B<enc> program does not support authenticated encryption modes
like CCM and GCM. The utility does not store or retrieve the
authentication tag.
base64 Base 64

12
doc/apps/gendsa.pod
View File

@@ -8,6 +8,12 @@ gendsa - generate a DSA private key from a set of parameters
B<openssl> B<gendsa>
[B<-out filename>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
[B<-camellia128>]
[B<-camellia192>]
[B<-camellia256>]
[B<-des>]
[B<-des3>]
[B<-idea>]
@@ -24,10 +30,10 @@ The B<gendsa> command generates a DSA private key from a DSA parameter file
=over 4
=item B<-des|-des3|-idea>
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
These options encrypt the private key with the DES, triple DES, or the
IDEA ciphers respectively before outputting it. A pass phrase is prompted for.
These options encrypt the private key with specified
cipher before outputting it. A pass phrase is prompted for.
If none of these options is specified no encryption is used.
=item B<-rand file(s)>

15
doc/apps/genpkey.pod
View File

@@ -114,6 +114,8 @@ hexadecimal value if preceded by B<0x>. Default value is 65537.
The number of bits in the generated parameters. If not specified 1024 is used.
=back
=head1 DH PARAMETER GENERATION OPTIONS
=over 4
@@ -126,6 +128,15 @@ The number of bits in the prime parameter B<p>.
The value to use for the generator B<g>.
=item B<dh_rfc5114:num>
If this option is set then the appropriate RFC5114 parameters are used
instead of generating new parameters. The value B<num> can take the
values 1, 2 or 3 corresponding to RFC5114 DH parameters consisting of
1024 bit group with 160 bit subgroup, 2048 bit group with 224 bit subgroup
and 2048 bit group with 256 bit subgroup as mentioned in RFC5114 sections
2.1, 2.2 and 2.3 respectively.
=back
=head1 EC PARAMETER GENERATION OPTIONS
@@ -204,6 +215,10 @@ Generate 1024 bit DH parameters:
openssl genpkey -genparam -algorithm DH -out dhp.pem \
-pkeyopt dh_paramgen_prime_len:1024
Output RFC5114 2048 bit DH parameters with 224 bit subgroup:
openssl genpkey -genparam -algorithm DH -out dhp.pem -pkeyopt dh_rfc5114:2
Generate DH key from parameters:
openssl genpkey -paramfile dhp.pem -out dhkey.pem

18
doc/apps/genrsa.pod
View File

@@ -9,6 +9,18 @@ genrsa - generate an RSA private key
B<openssl> B<genrsa>
[B<-out filename>]
[B<-passout arg>]
[B<-aes128>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
[B<-camellia128>]
[B<-camellia192>]
[B<-camellia256>]
[B<-aes192>]
[B<-aes256>]
[B<-camellia128>]
[B<-camellia192>]
[B<-camellia256>]
[B<-des>]
[B<-des3>]
[B<-idea>]
@@ -36,10 +48,10 @@ used.
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-des|-des3|-idea>
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
These options encrypt the private key with the DES, triple DES, or the
IDEA ciphers respectively before outputting it. If none of these options is
These options encrypt the private key with specified
cipher before outputting it. If none of these options is
specified no encryption is used. If encryption is used a pass phrase is prompted
for if it is not supplied via the B<-passout> argument.

25
doc/apps/ocsp.pod
View File

@@ -29,6 +29,7 @@ B<openssl> B<ocsp>
[B<-path>]
[B<-CApath dir>]
[B<-CAfile file>]
[B<-no_alt_chains>]]
[B<-VAfile file>]
[B<-validity_period n>]
[B<-status_age n>]
@@ -40,6 +41,7 @@ B<openssl> B<ocsp>
[B<-no_cert_verify>]
[B<-no_chain>]
[B<-no_cert_checks>]
[B<-no_explicit>]
[B<-port num>]
[B<-index file>]
[B<-CA file>]
@@ -133,11 +135,19 @@ if the B<host> option is present then the OCSP request is sent to the host
B<hostname> on port B<port>. B<path> specifies the HTTP path name to use
or "/" by default.
=item B<-timeout seconds>
connection timeout to the OCSP responder in seconds
=item B<-CAfile file>, B<-CApath pathname>
file or pathname containing trusted CA certificates. These are used to verify
the signature on the OCSP response.
=item B<-no_alt_chains>
See L<B<verify>|verify(1)> manual page for details.
=item B<-verify_other file>
file containing additional certificates to search when attempting to locate
@@ -185,6 +195,10 @@ testing purposes.
do not use certificates in the response as additional untrusted CA
certificates.
=item B<-no_explicit>
do not explicitly trust the root CA if it is set to be trusted for OCSP signing.
=item B<-no_cert_checks>
don't perform any additional checks on the OCSP response signers certificate.
@@ -297,8 +311,9 @@ CA certificate in the request. If there is a match and the OCSPSigning
extended key usage is present in the OCSP responder certificate then the
OCSP verify succeeds.
Otherwise the root CA of the OCSP responders CA is checked to see if it
is trusted for OCSP signing. If it is the OCSP verify succeeds.
Otherwise, if B<-no_explicit> is B<not> set the root CA of the OCSP responders
CA is checked to see if it is trusted for OCSP signing. If it is the OCSP
verify succeeds.
If none of these checks is successful then the OCSP verify fails.
@@ -369,3 +384,9 @@ second file.
openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
-reqin req.der -respout resp.der
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
=cut

4
doc/apps/openssl.pod
View File

@@ -287,8 +287,6 @@ SHA Digest
SHA-1 Digest
=back
=item B<sha224>
SHA-224 Digest
@@ -305,6 +303,8 @@ SHA-384 Digest
SHA-512 Digest
=back
=head2 ENCODING AND CIPHER COMMANDS
=over 10

9
doc/apps/pkcs12.pod
View File

@@ -67,7 +67,7 @@ by default.
The filename to write certificates and private keys to, standard output by
default. They are all written in PEM format.
=item B<-pass arg>, B<-passin arg>
=item B<-passin arg>
the PKCS#12 file (i.e. input file) password source. For more information about
the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
@@ -75,10 +75,15 @@ L<openssl(1)|openssl(1)>.
=item B<-passout arg>
pass phrase source to encrypt any outputed private keys with. For more
pass phrase source to encrypt any outputted private keys with. For more
information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section
in L<openssl(1)|openssl(1)>.
=item B<-password arg>
With -export, -password is equivalent to -passout.
Otherwise, -password is equivalent to -passin.
=item B<-noout>
this option inhibits output of the keys and certificates to the output file

12
doc/apps/pkcs8.pod
View File

@@ -20,6 +20,7 @@ B<openssl> B<pkcs8>
[B<-embed>]
[B<-nsdb>]
[B<-v2 alg>]
[B<-v2prf alg>]
[B<-v1 alg>]
[B<-engine id>]
@@ -118,6 +119,12 @@ private keys with OpenSSL then this doesn't matter.
The B<alg> argument is the encryption algorithm to use, valid values include
B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used.
=item B<-v2prf alg>
This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value
values would be B<hmacWithSHA256>. If this option isn't set then the default
for the cipher is used or B<hmacWithSHA1> if there is no default.
=item B<-v1 alg>
This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete
@@ -195,6 +202,11 @@ DES:
openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
Convert a private from traditional to PKCS#5 v2.0 format using AES with
256 bits in CBC mode and B<hmacWithSHA256> PRF:
openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -out enckey.pem
Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
(DES):

6
doc/apps/req.pod
View File

@@ -235,8 +235,8 @@ this option outputs a self signed certificate instead of a certificate
request. This is typically used to generate a test certificate or
a self signed root CA. The extensions added to the certificate
(if any) are specified in the configuration file. Unless specified
using the B<set_serial> option B<0> will be used for the serial
number.
using the B<set_serial> option, a large random number will be used for
the serial number.
=item B<-days n>
@@ -303,7 +303,7 @@ Reverses effect of B<-asn1-kludge>
=item B<-newhdr>
Adds the word B<NEW> to the PEM file header and footer lines on the outputed
Adds the word B<NEW> to the PEM file header and footer lines on the outputted
request. Some software (Netscape certificate server) and some CAs need this.
=item B<-batch>

27
doc/apps/rsa.pod
View File

@@ -15,6 +15,12 @@ B<openssl> B<rsa>
[B<-out filename>]
[B<-passout arg>]
[B<-sgckey>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
[B<-camellia128>]
[B<-camellia192>]
[B<-camellia256>]
[B<-des>]
[B<-des3>]
[B<-idea>]
@@ -24,6 +30,8 @@ B<openssl> B<rsa>
[B<-check>]
[B<-pubin>]
[B<-pubout>]
[B<-RSAPublicKey_in>]
[B<-RSAPublicKey_out>]
[B<-engine id>]
=head1 DESCRIPTION
@@ -80,10 +88,10 @@ see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
use the modified NET algorithm used with some versions of Microsoft IIS and SGC
keys.
=item B<-des|-des3|-idea>
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
These options encrypt the private key with the DES, triple DES, or the
IDEA ciphers respectively before outputting it. A pass phrase is prompted for.
These options encrypt the private key with the specified
cipher before outputting it. A pass phrase is prompted for.
If none of these options is specified the key is written in plain text. This
means that using the B<rsa> utility to read in an encrypted key with no
encryption option can be used to remove the pass phrase from a key, or by
@@ -118,6 +126,10 @@ by default a private key is output: with this option a public
key will be output instead. This option is automatically set if
the input is a public key.
=item B<-RSAPublicKey_in>, B<-RSAPublicKey_out>
like B<-pubin> and B<-pubout> except B<RSAPublicKey> format is used instead.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<rsa>
@@ -139,6 +151,11 @@ The PEM public key format uses the header and footer lines:
-----BEGIN PUBLIC KEY-----
-----END PUBLIC KEY-----
The PEM B<RSAPublicKey> format uses the header and footer lines:
-----BEGIN RSA PUBLIC KEY-----
-----END RSA PUBLIC KEY-----
The B<NET> form is a format compatible with older Netscape servers
and Microsoft IIS .key files, this uses unsalted RC4 for its encryption.
It is not very secure and so should only be used when necessary.
@@ -173,6 +190,10 @@ To just output the public part of a private key:
openssl rsa -in key.pem -pubout -out pubkey.pem
Output the public part of a private key in B<RSAPublicKey> format:
openssl rsa -in key.pem -RSAPublicKey_out -out pubkey.pem
=head1 BUGS
The command line password arguments don't currently work with

79
doc/apps/s_client.pod
View File

@@ -9,7 +9,9 @@ s_client - SSL/TLS client program
B<openssl> B<s_client>
[B<-connect host:port>]
[B<-servername name>]
[B<-verify depth>]
[B<-verify_return_error>]
[B<-cert filename>]
[B<-certform DER|PEM>]
[B<-key filename>]
@@ -17,6 +19,7 @@ B<openssl> B<s_client>
[B<-pass arg>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-no_alt_chains>]
[B<-reconnect>]
[B<-pause>]
[B<-showcerts>]
@@ -27,6 +30,7 @@ B<openssl> B<s_client>
[B<-nbio>]
[B<-crlf>]
[B<-ign_eof>]
[B<-no_ign_eof>]
[B<-quiet>]
[B<-ssl2>]
[B<-ssl3>]
@@ -34,8 +38,12 @@ B<openssl> B<s_client>
[B<-no_ssl2>]
[B<-no_ssl3>]
[B<-no_tls1>]
[B<-no_tls1_1>]
[B<-no_tls1_2>]
[B<-fallback_scsv>]
[B<-bugs>]
[B<-cipher cipherlist>]
[B<-serverpref>]
[B<-starttls protocol>]
[B<-engine id>]
[B<-tlsextdebug>]
@@ -43,6 +51,9 @@ B<openssl> B<s_client>
[B<-sess_out filename>]
[B<-sess_in filename>]
[B<-rand file(s)>]
[B<-serverinfo types>]
[B<-status>]
[B<-nextprotoneg protocols>]
=head1 DESCRIPTION
@@ -59,6 +70,10 @@ SSL servers.
This specifies the host and optional port to connect to. If not specified
then an attempt is made to connect to the local host on port 4433.
=item B<-servername name>
Set the TLS SNI (Server Name Indication) extension in the ClientHello message.
=item B<-cert certname>
The certificate to use, if one is requested by the server. The default is
@@ -90,6 +105,11 @@ Currently the verify operation continues after errors so all the problems
with a certificate chain can be seen. As a side effect the connection
will never fail due to a server certificate verify failure.
=item B<-verify_return_error>
Return verification errors instead of continuing. This will typically
abort the handshake with a fatal error.
=item B<-CApath directory>
The directory to use for server certificate verification. This directory
@@ -101,7 +121,7 @@ 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>
=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains>
Set various certificate chain valiadition option. See the
L<B<verify>|verify(1)> manual page for details.
@@ -166,6 +186,11 @@ input.
inhibit printing of session and certificate information. This implicitly
turns on B<-ign_eof> as well.
=item B<-no_ign_eof>
shut down the connection when end of file is reached in the input.
Can be used to override the implicit B<-ign_eof> after B<-quiet>.
=item B<-psk_identity identity>
Use the PSK identity B<identity> when using a PSK cipher suite.
@@ -176,16 +201,19 @@ 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<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>
=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
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.
Unfortunately there are a lot of ancient and broken servers in use which
Unfortunately there are still 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<-no_tls> option others will only
support SSL v2 and may need the B<-ssl2> option.
work if TLS is turned off.
=item B<-fallback_scsv>
Send TLS_FALLBACK_SCSV in the ClientHello.
=item B<-bugs>
@@ -199,6 +227,10 @@ 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.
@@ -237,6 +269,29 @@ Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-serverinfo types>
a list of comma-separated TLS Extension Types (numbers between 0 and
65535). Each type will be sent as an empty ClientHello TLS Extension.
The server's response (if any) will be encoded and displayed as a PEM
file.
=item B<-status>
sends a certificate status request to the server (OCSP stapling). The server
response (if any) is printed out.
=item B<-nextprotoneg protocols>
enable Next Protocol Negotiation TLS extension and provide a list of
comma-separated protocol names that the client should advertise
support for. The list should contain most wanted protocols first.
Protocol names are printable ASCII strings, for example "http/1.1" or
"spdy/3".
Empty list of protocols is treated specially and will cause the client to
advertise support for the TLS extension but disconnect just after
reciving ServerHello with a list of server supported protocols.
=back
=head1 CONNECTED COMMANDS
@@ -286,6 +341,13 @@ Since the SSLv23 client hello cannot include compression methods or extensions
these will only be supported if its use is disabled, for example by using the
B<-no_sslv2> option.
The B<s_client> utility is a test tool and is designed to continue the
handshake after any certificate verification errors. As a result it will
accept any certificate chain (trusted or not) sent by the peer. None test
applications should B<not> do this as it makes them vulnerable to a MITM
attack. This behaviour can be changed by with the B<-verify_return_error>
option: any verify errors are then returned aborting the handshake.
=head1 BUGS
Because this program has a lot of options and also because some of
@@ -293,9 +355,6 @@ the techniques used are rather old, the C source of s_client is rather
hard to read and not a model of how things should be done. A typical
SSL client program would be much simpler.
The B<-verify> option should really exit if the server verification
fails.
The B<-prexit> option is a bit of a hack. We should really report
information whenever a session is renegotiated.
@@ -303,4 +362,8 @@ information whenever a session is renegotiated.
L<sess_id(1)|sess_id(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)>
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
=cut

65
doc/apps/s_server.pod
View File

@@ -33,8 +33,10 @@ B<openssl> B<s_server>
[B<-state>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-no_alt_chains>]
[B<-nocert>]
[B<-cipher cipherlist>]
[B<-serverpref>]
[B<-quiet>]
[B<-no_tmp_rsa>]
[B<-ssl2>]
@@ -54,6 +56,13 @@ B<openssl> B<s_server>
[B<-no_ticket>]
[B<-id_prefix arg>]
[B<-rand file(s)>]
[B<-serverinfo file>]
[B<-no_resumption_on_reneg>]
[B<-status>]
[B<-status_verbose>]
[B<-status_timeout nsec>]
[B<-status_url url>]
[B<-nextprotoneg protocols>]
=head1 DESCRIPTION
@@ -111,7 +120,7 @@ by using an appropriate certificate.
=item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg>
addtional certificate and private key format and passphrase respectively.
additional certificate and private key format and passphrase respectively.
=item B<-nocert>
@@ -144,6 +153,9 @@ 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.
@@ -163,6 +175,10 @@ and to use when attempting to build the server certificate chain. The list
is also used in the list of acceptable client CAs passed to the client when
a certificate is requested.
=item B<-no_alt_chains>
See the L<B<verify>|verify(1)> manual page for details.
=item B<-state>
prints out the SSL session states.
@@ -225,6 +241,10 @@ also included in the server list is used. Because the client specifies
the preference order, the order of the server cipherlist irrelevant. See
the B<ciphers> command for more information.
=item B<-serverpref>
use the server's cipher preferences, rather than the client's preferences.
=item B<-tlsextdebug>
print out a hex dump of any TLS extensions received from the server.
@@ -276,6 +296,45 @@ Multiple files can be specified separated by a OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-serverinfo file>
a file containing one or more blocks of PEM data. Each PEM block
must encode a TLS ServerHello extension (2 bytes type, 2 bytes length,
followed by "length" bytes of extension data). If the client sends
an empty TLS ClientHello extension matching the type, the corresponding
ServerHello extension will be returned.
=item B<-no_resumption_on_reneg>
set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag.
=item B<-status>
enables certificate status request support (aka OCSP stapling).
=item B<-status_verbose>
enables certificate status request support (aka OCSP stapling) and gives
a verbose printout of the OCSP response.
=item B<-status_timeout nsec>
sets the timeout for OCSP response to B<nsec> seconds.
=item B<-status_url url>
sets a fallback responder URL to use if no responder URL is present in the
server certificate. Without this option an error is returned if the server
certificate does not contain a responder address.
=item B<-nextprotoneg protocols>
enable Next Protocol Negotiation TLS extension and provide a
comma-separated list of supported protocol names.
The list should contain most wanted protocols first.
Protocol names are printable ASCII strings, for example "http/1.1" or
"spdy/3".
=back
=head1 CONNECTED COMMANDS
@@ -352,4 +411,8 @@ unknown cipher suites a client says it supports.
L<sess_id(1)|sess_id(1)>, L<s_client(1)|s_client(1)>, L<ciphers(1)|ciphers(1)>
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
=cut

18
doc/apps/smime.pod
View File

@@ -15,6 +15,7 @@ B<openssl> B<smime>
[B<-pk7out>]
[B<-[cipher]>]
[B<-in file>]
[B<-no_alt_chains>]
[B<-certfile file>]
[B<-signer file>]
[B<-recip file>]
@@ -159,7 +160,7 @@ 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 40 bit RC2 is used. Only used with B<-encrypt>.
If not specified triple DES is used. Only used with B<-encrypt>.
=item B<-nointern>
@@ -259,7 +260,7 @@ 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>
=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains>
Set various options of certificate chain verification. See
L<B<verify>|verify(1)> manual page for details.
@@ -308,28 +309,28 @@ remains DER.
=over 4
=item 0
=item Z<>0
the operation was completely successfully.
=item 1
=item Z<>1
an error occurred parsing the command options.
=item 2
=item Z<>2
one of the input files could not be read.
=item 3
=item Z<>3
an error occurred creating the PKCS#7 file or when reading the MIME
message.
=item 4
=item Z<>4
an error occurred decrypting or verifying the message.
=item 5
=item Z<>5
the message was verified correctly but an error occurred writing out
the signers certificates.
@@ -441,5 +442,6 @@ 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.
=cut

4
doc/apps/ts.pod
View File

@@ -352,7 +352,7 @@ switch always overrides the settings in the config file.
This is the main section and it specifies the name of another section
that contains all the options for the B<-reply> command. This default
section can be overriden with the B<-section> command line switch. (Optional)
section can be overridden with the B<-section> command line switch. (Optional)
=item B<oid_file>
@@ -453,7 +453,7 @@ included. Default is no. (Optional)
=head1 ENVIRONMENT VARIABLES
B<OPENSSL_CONF> contains the path of the configuration file and can be
overriden by the B<-config> command line option.
overridden by the B<-config> command line option.
=head1 EXAMPLES

2
doc/apps/tsget.pod
View File

@@ -124,7 +124,7 @@ The name of an EGD socket to get random data from. (Optional)
=item [request]...
List of files containing B<RFC 3161> DER-encoded time stamp requests. If no
requests are specifed only one request will be sent to the server and it will be
requests are specified only one request will be sent to the server and it will be
read from the standard input. (Optional)
=back

110
doc/apps/verify.pod
View File

@@ -12,6 +12,10 @@ B<openssl> B<verify>
[B<-purpose purpose>]
[B<-policy arg>]
[B<-ignore_critical>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crlfile file>]
[B<-crl_download>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-policy_check>]
@@ -22,9 +26,11 @@ B<openssl> B<verify>
[B<-extended_crl>]
[B<-use_deltas>]
[B<-policy_print>]
[B<-no_alt_chains>]
[B<-untrusted file>]
[B<-help>]
[B<-issuer_checks>]
[B<-trusted file>]
[B<-verbose>]
[B<->]
[certificates]
@@ -47,42 +53,67 @@ of the B<x509> utility). Under Unix the B<c_rehash> script will automatically
create symbolic links to a directory of certificates.
=item B<-CAfile file>
A file of trusted certificates. The file should contain multiple certificates
in PEM format concatenated together.
=item B<-attime timestamp>
Perform validation checks using time specified by B<timestamp> and not
current system time. B<timestamp> is the number of seconds since
01.01.1970 (UNIX time).
=item B<-check_ss_sig>
Verify the signature on the self-signed root CA. This is disabled by default
because it doesn't add any security.
=item B<-crlfile file>
File containing one or more CRL's (in PEM format) to load.
=item B<-crl_download>
Attempt to download CRL information for this certificate.
=item B<-crl_check>
Checks end entity certificate validity by attempting to look up a valid CRL.
If a valid CRL cannot be found an error occurs.
=item B<-untrusted file>
A file of untrusted certificates. The file should contain multiple certificates
in PEM format concatenated together.
=item B<-purpose purpose>
the intended use for the certificate. Without this option no chain verification
will be done. Currently accepted uses are B<sslclient>, B<sslserver>,
B<nssslserver>, B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION>
section for more information.
The intended use for the certificate. If this option is not specified,
B<verify> will not consider certificate purpose during chain verification.
Currently accepted uses are B<sslclient>, B<sslserver>, B<nssslserver>,
B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION> section for more
information.
=item B<-help>
prints out a usage message.
Print out a usage message.
=item B<-verbose>
print extra information about the operations being performed.
Print extra information about the operations being performed.
=item B<-issuer_checks>
print out diagnostics relating to searches for the issuer certificate
of the current certificate. This shows why each candidate issuer
certificate was rejected. However the presence of rejection messages
does not itself imply that anything is wrong: during the normal
verify process several rejections may take place.
Print out diagnostics relating to searches for the issuer certificate of the
current certificate. This shows why each candidate issuer certificate was
rejected. The presence of rejection messages does not itself imply that
anything is wrong; during the normal verification process, several
rejections may take place.
=item B<-policy arg>
Enable policy processing and add B<arg> to the user-initial-policy-set
(see RFC3280 et al). The policy B<arg> can be an object name an OID in numeric
form. This argument can appear more than once.
Enable policy processing and add B<arg> to the user-initial-policy-set (see
RFC5280). The policy B<arg> can be an object name an OID in numeric form.
This argument can appear more than once.
=item B<-policy_check>
@@ -90,41 +121,53 @@ Enables certificate policy processing.
=item B<-explicit_policy>
Set policy variable require-explicit-policy (see RFC3280 et al).
Set policy variable require-explicit-policy (see RFC5280).
=item B<-inhibit_any>
Set policy variable inhibit-any-policy (see RFC3280 et al).
Set policy variable inhibit-any-policy (see RFC5280).
=item B<-inhibit_map>
Set policy variable inhibit-policy-mapping (see RFC3280 et al).
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<-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 checking
Print out diagnostics related to policy processing.
=item B<-crl_check>
Checks end entity certificate validity by attempting to lookup a valid CRL.
Checks end entity certificate validity by attempting to look up a valid CRL.
If a valid CRL cannot be found an error occurs.
=item B<-crl_check_all>
Checks the validity of B<all> certificates in the chain by attempting
to lookup valid CRLs.
to look up valid CRLs.
=item B<-ignore_critical>
Normally if an unhandled critical extension is present which is not
supported by OpenSSL the certificate is rejected (as required by
RFC3280 et al). If this option is set critical extensions are
ignored.
supported by OpenSSL the certificate is rejected (as required by RFC5280).
If this option is set critical extensions are ignored.
=item B<-x509_strict>
Disable workarounds for broken certificates which have to be disabled
for strict X.509 compliance.
For strict X.509 compliance, disable non-compliant workarounds for broken
certificates.
=item B<-extended_crl>
@@ -142,16 +185,15 @@ because it doesn't add any security.
=item B<->
marks the last option. All arguments following this are assumed to be
Indicates the last option. All arguments following this are assumed to be
certificate files. This is useful if the first certificate filename begins
with a B<->.
=item B<certificates>
one or more certificates to verify. If no certificate filenames are included
then an attempt is made to read a certificate from standard input. They should
all be in PEM format.
One or more certificates to verify. If no certificates are given, B<verify>
will attempt to read a certificate from standard input. Certificates must be
in PEM format.
=back
@@ -386,7 +428,7 @@ an application specific error. Unused.
=head1 BUGS
Although the issuer checks are a considerably improvement over the old technique they still
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
@@ -403,4 +445,8 @@ B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
L<x509(1)|x509(1)>
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
=cut

3
doc/apps/version.pod
View File

@@ -13,6 +13,7 @@ B<openssl version>
[B<-o>]
[B<-f>]
[B<-p>]
[B<-d>]
=head1 DESCRIPTION
@@ -38,7 +39,7 @@ the date the current version of OpenSSL was built.
option information: various options set when the library was built.
=item B<-c>
=item B<-f>
compilation flags.

35
doc/apps/x509.pod
View File

@@ -19,6 +19,7 @@ B<openssl> B<x509>
[B<-hash>]
[B<-subject_hash>]
[B<-issuer_hash>]
[B<-ocspid>]
[B<-subject>]
[B<-issuer>]
[B<-nameopt option>]
@@ -28,7 +29,9 @@ B<openssl> B<x509>
[B<-enddate>]
[B<-purpose>]
[B<-dates>]
[B<-checkend num>]
[B<-modulus>]
[B<-pubkey>]
[B<-fingerprint>]
[B<-alias>]
[B<-noout>]
@@ -41,13 +44,16 @@ B<openssl> B<x509>
[B<-days arg>]
[B<-set_serial n>]
[B<-signkey filename>]
[B<-passin arg>]
[B<-x509toreq>]
[B<-req>]
[B<-CA filename>]
[B<-CAkey filename>]
[B<-CAcreateserial>]
[B<-CAserial filename>]
[B<-force_pubkey key>]
[B<-text>]
[B<-certopt option>]
[B<-C>]
[B<-md2|-md5|-sha1|-mdc2>]
[B<-clrext>]
@@ -135,6 +141,10 @@ section for more information.
this option prevents output of the encoded version of the request.
=item B<-pubkey>
outputs the the certificate's SubjectPublicKeyInfo block in PEM format.
=item B<-modulus>
this option prints out the value of the modulus of the public key
@@ -154,6 +164,10 @@ name.
outputs the "hash" of the certificate issuer name.
=item B<-ocspid>
outputs the OCSP hash values for the subject name and public key.
=item B<-hash>
synonym for "-subject_hash" for backward compatibility reasons.
@@ -203,6 +217,11 @@ prints out the expiry date of the certificate, that is the notAfter date.
prints out the start and expiry dates of a certificate.
=item B<-checkend arg>
checks if the certificate expires within the next B<arg> seconds and exits
non-zero if yes it will expire or zero if not.
=item B<-fingerprint>
prints out the digest of the DER encoded version of the whole certificate
@@ -308,6 +327,11 @@ If the input is a certificate request then a self signed certificate
is created using the supplied private key using the subject name in
the request.
=item B<-passin arg>
the key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-clrext>
delete any extensions from a certificate. This option is used when a
@@ -395,6 +419,15 @@ specified then the extensions should either be contained in the unnamed
L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
extension section format.
=item B<-force_pubkey key>
when a certificate is created set its public key to B<key> instead of the
key in the certificate or certificate request. This option is useful for
creating certificates where the algorithm can't normally sign requests, for
example DH.
The format or B<key> can be specified using the B<-keyform> option.
=back
=head2 NAME OPTIONS
@@ -463,7 +496,7 @@ using the format \UXXXX for 16 bits and \WXXXXXXXX for 32 bits.
Also if this option is off any UTF8Strings will be converted to their
character form first.
=item B<no_type>
=item B<ignore_type>
this option does not attempt to interpret multibyte characters in any
way. That is their content octets are merely dumped as though one octet

6
doc/apps/x509v3_config.pod
View File

@@ -174,7 +174,7 @@ The IP address used in the B<IP> options can be in either IPv4 or IPv6 format.
The value of B<dirName> should point to a section containing the distinguished
name to use as a set of name value pairs. Multi values AVAs can be formed by
preceeding the name with a B<+> character.
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
@@ -301,7 +301,7 @@ Example:
O=Organisation
CN=Some Name
=head2 Certificate Policies.
This is a I<raw> extension. All the fields of this extension can be set by
@@ -390,7 +390,7 @@ Examples:
nameConstraints=permitted;email:.somedomain.com
nameConstraints=excluded;email:.com
issuingDistributionPoint = idp_section
=head2 OCSP No Check

2
doc/crypto/ASN1_STRING_length.pod
View File

@@ -3,7 +3,7 @@
=head1 NAME
ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data -
ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data, ASN1_STRING_to_UTF8 -
ASN1_STRING utility functions
=head1 SYNOPSIS

2
doc/crypto/ASN1_STRING_print_ex.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp - ASN1_STRING output routines.
ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING output routines.
=head1 SYNOPSIS

129
doc/crypto/ASN1_TIME_set.pod Normal file
View File

@@ -0,0 +1,129 @@
=pod
=head1 NAME
ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check, ASN1_TIME_set_string,
ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions.
=head1 SYNOPSIS
ASN1_TIME *ASN1_TIME_set(ASN1_TIME *s, time_t t);
ASN1_TIME *ASN1_TIME_adj(ASN1_TIME *s, time_t t,
int offset_day, long offset_sec);
int ASN1_TIME_set_string(ASN1_TIME *s, const char *str);
int ASN1_TIME_check(const ASN1_TIME *t);
int ASN1_TIME_print(BIO *b, const ASN1_TIME *s);
int ASN1_TIME_diff(int *pday, int *psec,
const ASN1_TIME *from, const ASN1_TIME *to);
=head1 DESCRIPTION
The function ASN1_TIME_set() sets the ASN1_TIME structure B<s> to the
time represented by the time_t value B<t>. If B<s> is NULL a new ASN1_TIME
structure is allocated and returned.
ASN1_TIME_adj() sets the ASN1_TIME structure B<s> to the time represented
by the time B<offset_day> and B<offset_sec> after the time_t value B<t>.
The values of B<offset_day> or B<offset_sec> can be negative to set a
time before B<t>. The B<offset_sec> value can also exceed the number of
seconds in a day. If B<s> is NULL a new ASN1_TIME structure is allocated
and returned.
ASN1_TIME_set_string() sets ASN1_TIME structure B<s> to the time
represented by string B<str> which must be in appropriate ASN.1 time
format (for example YYMMDDHHMMSSZ or YYYYMMDDHHMMSSZ).
ASN1_TIME_check() checks the syntax of ASN1_TIME structure B<s>.
ASN1_TIME_print() prints out the time B<s> to BIO B<b> in human readable
format. It will be of the format MMM DD HH:MM:SS YYYY [GMT], for example
"Feb 3 00:55:52 2015 GMT" it does not include a newline. If the time
structure has invalid format it prints out "Bad time value" and returns
an error.
ASN1_TIME_diff() sets B<*pday> and B<*psec> to the time difference between
B<from> and B<to>. If B<to> represents a time later than B<from> then
one or both (depending on the time difference) of B<*pday> and B<*psec>
will be positive. If B<to> represents a time earlier than B<from> then
one or both of B<*pday> and B<*psec> will be negative. If B<to> and B<from>
represent the same time then B<*pday> and B<*psec> will both be zero.
If both B<*pday> and B<*psec> are non-zero they will always have the same
sign. The value of B<*psec> will always be less than the number of seconds
in a day. If B<from> or B<to> is NULL the current time is used.
=head1 NOTES
The ASN1_TIME structure corresponds to the ASN.1 structure B<Time>
defined in RFC5280 et al. The time setting functions obey the rules outlined
in RFC5280: if the date can be represented by UTCTime it is used, else
GeneralizedTime is used.
The ASN1_TIME structure is represented as an ASN1_STRING internally and can
be freed up using ASN1_STRING_free().
The ASN1_TIME structure can represent years from 0000 to 9999 but no attempt
is made to correct ancient calendar changes (for example from Julian to
Gregorian calendars).
Some applications add offset times directly to a time_t value and pass the
results to ASN1_TIME_set() (or equivalent). This can cause problems as the
time_t value can overflow on some systems resulting in unexpected results.
New applications should use ASN1_TIME_adj() instead and pass the offset value
in the B<offset_sec> and B<offset_day> parameters instead of directly
manipulating a time_t value.
=head1 BUGS
ASN1_TIME_print() currently does not print out the time zone: it either prints
out "GMT" or nothing. But all certificates complying with RFC5280 et al use GMT
anyway.
=head1 EXAMPLES
Set a time structure to one hour after the current time and print it out:
#include <time.h>
#include <openssl/asn1.h>
ASN1_TIME *tm;
time_t t;
BIO *b;
t = time(NULL);
tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
b = BIO_new_fp(stdout, BIO_NOCLOSE);
ASN1_TIME_print(b, tm);
ASN1_STRING_free(tm);
BIO_free(b);
Determine if one time is later or sooner than the current time:
int day, sec;
if (!ASN1_TIME_diff(&day, &sec, NULL, to))
/* Invalid time format */
if (day > 0 || sec > 0)
printf("Later\n");
else if (day < 0 || sec < 0)
printf("Sooner\n");
else
printf("Same\n");
=head1 RETURN VALUES
ASN1_TIME_set() and ASN1_TIME_adj() return a pointer to an ASN1_TIME structure
or NULL if an error occurred.
ASN1_TIME_set_string() returns 1 if the time value is successfully set and
0 otherwise.
ASN1_TIME_check() returns 1 if the structure is syntactically correct and 0
otherwise.
ASN1_TIME_print() returns 1 if the time is successfully printed out and 0 if
an error occurred (I/O error or invalid time format).
ASN1_TIME_diff() returns 1 for sucess and 0 for failure. It can fail if the
pass ASN1_TIME structure has invalid syntax for example.
=cut

2
doc/crypto/ASN1_generate_nconf.pod
View File

@@ -61,7 +61,7 @@ Encode the B<NULL> type, the B<value> string must not be present.
=item B<INTEGER>, B<INT>
Encodes an ASN1 B<INTEGER> type. The B<value> string represents
the value of the integer, it can be preceeded by a minus sign and
the value of the integer, it can be prefaced by a minus sign and
is normally interpreted as a decimal value unless the prefix B<0x>
is included.

15
doc/crypto/BIO_f_base64.pod
View File

@@ -46,11 +46,11 @@ to standard output:
b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdout, BIO_NOCLOSE);
bio = BIO_push(b64, bio);
BIO_write(bio, message, strlen(message));
BIO_flush(bio);
BIO_push(b64, bio);
BIO_write(b64, message, strlen(message));
BIO_flush(b64);
BIO_free_all(bio);
BIO_free_all(b64);
Read Base64 encoded data from standard input and write the decoded
data to standard output:
@@ -62,11 +62,12 @@ data to standard output:
b64 = BIO_new(BIO_f_base64());
bio = BIO_new_fp(stdin, BIO_NOCLOSE);
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
bio = BIO_push(b64, bio);
while((inlen = BIO_read(bio, inbuf, 512)) > 0)
BIO_push(b64, bio);
while((inlen = BIO_read(b64, inbuf, 512)) > 0)
BIO_write(bio_out, inbuf, inlen);
BIO_free_all(bio);
BIO_flush(bio_out);
BIO_free_all(b64);
=head1 BUGS

2
doc/crypto/BIO_f_ssl.pod
View File

@@ -108,7 +108,7 @@ SSL BIOs are exceptional in that if the underlying transport
is non blocking they can still request a retry in exceptional
circumstances. Specifically this will happen if a session
renegotiation takes place during a BIO_read() operation, one
case where this happens is when SGC or step up occurs.
case where this happens is when step up occurs.
In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be
set to disable this behaviour. That is when this flag is set

2
doc/crypto/BIO_find_type.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BIO_find_type, BIO_next - BIO chain traversal
BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal
=head1 SYNOPSIS

2
doc/crypto/BIO_push.pod
View File

@@ -40,7 +40,7 @@ If the call:
BIO_push(b64, f);
is made then the new chain will be B<b64-chain>. After making the calls
is made then the new chain will be B<b64-f>. After making the calls
BIO_push(md2, b64);
BIO_push(md1, md2);

6
doc/crypto/BIO_s_accept.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port,
BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, BIO_new_accept,
BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode,
BIO_get_bind_mode, BIO_do_accept - accept BIO
@@ -59,8 +59,8 @@ the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)>
BIO_set_accept_port() uses the string B<name> to set the accept
port. The port is represented as a string of the form "host:port",
where "host" is the interface to use and "port" is the port.
Either or both values can be "*" which is interpreted as meaning
any interface or port respectively. "port" has the same syntax
The host can be can be "*" which is interpreted as meaning
any interface; "port" has the same syntax
as the port specified in BIO_set_conn_port() for connect BIOs,
that is it can be a numerical port string or a string to lookup
using getservbyname() and a string table.

2
doc/crypto/BIO_s_connect.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port,
BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port,
BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
BIO_set_nbio, BIO_do_connect - connect BIO

6
doc/crypto/BN_BLINDING_new.pod
View File

@@ -4,7 +4,7 @@
BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert,
BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex,
BN_BLINDING_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_get_flags,
BN_BLINDING_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_thread_id, BN_BLINDING_get_flags,
BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM
functions.
@@ -48,7 +48,7 @@ necessary parameters are set, by re-creating the blinding parameters.
BN_BLINDING_convert_ex() multiplies B<n> with the blinding factor B<A>.
If B<r> is not NULL a copy the inverse blinding factor B<Ai> will be
returned in B<r> (this is useful if a B<RSA> object is shared amoung
returned in B<r> (this is useful if a B<RSA> object is shared among
several threads). BN_BLINDING_invert_ex() multiplies B<n> with the
inverse blinding factor B<Ai>. If B<r> is not NULL it will be used as
the inverse blinding.
@@ -84,7 +84,7 @@ or NULL in case of an error.
BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(),
BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on
success and 0 if an error occured.
success and 0 if an error occurred.
BN_BLINDING_thread_id() returns a pointer to the thread id object
within a B<BN_BLINDING> object.

10
doc/crypto/BN_CTX_new.pod
View File

@@ -10,9 +10,12 @@ BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
BN_CTX *BN_CTX_new(void);
void BN_CTX_free(BN_CTX *c);
Deprecated:
void BN_CTX_init(BN_CTX *c);
void BN_CTX_free(BN_CTX *c);
=head1 DESCRIPTION
@@ -22,8 +25,7 @@ is rather expensive when used in conjunction with repeated subroutine
calls, the B<BN_CTX> structure is used.
BN_CTX_new() allocates and initializes a B<BN_CTX>
structure. BN_CTX_init() initializes an existing uninitialized
B<BN_CTX>.
structure.
BN_CTX_free() frees the components of the B<BN_CTX>, and if it was
created by BN_CTX_new(), also the structure itself.
@@ -31,6 +33,8 @@ If L<BN_CTX_start(3)|BN_CTX_start(3)> has been used on the B<BN_CTX>,
L<BN_CTX_end(3)|BN_CTX_end(3)> must be called before the B<BN_CTX>
may be freed by BN_CTX_free().
BN_CTX_init() (deprecated) initializes an existing uninitialized B<BN_CTX>.
This should not be used for new programs. Use BN_CTX_new() instead.
=head1 RETURN VALUES

90
doc/crypto/BN_generate_prime.pod
View File

@@ -2,12 +2,31 @@
=head1 NAME
BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test for primality
BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call,
BN_GENCB_set_old, BN_GENCB_set, BN_generate_prime, BN_is_prime,
BN_is_prime_fasttest - generate primes and test for primality
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_generate_prime_ex(BIGNUM *ret,int bits,int safe, const BIGNUM *add,
const BIGNUM *rem, BN_GENCB *cb);
int BN_is_prime_ex(const BIGNUM *p,int nchecks, BN_CTX *ctx, BN_GENCB *cb);
int BN_is_prime_fasttest_ex(const BIGNUM *p,int nchecks, BN_CTX *ctx,
int do_trial_division, BN_GENCB *cb);
int BN_GENCB_call(BN_GENCB *cb, int a, int b);
#define BN_GENCB_set_old(gencb, callback, cb_arg) ...
#define BN_GENCB_set(gencb, callback, cb_arg) ...
Deprecated:
BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add,
BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg);
@@ -20,27 +39,27 @@ BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test
=head1 DESCRIPTION
BN_generate_prime() generates a pseudo-random prime number of B<num>
bits.
BN_generate_prime_ex() generates a pseudo-random prime number of
bit length B<bits>.
If B<ret> is not B<NULL>, it will be used to store the number.
If B<callback> is not B<NULL>, it is called as follows:
If B<cb> is not B<NULL>, it is used as follows:
=over 4
=item *
B<callback(0, i, cb_arg)> is called after generating the i-th
B<BN_GENCB_call(cb, 0, i)> is called after generating the i-th
potential prime number.
=item *
While the number is being tested for primality, B<callback(1, j,
cb_arg)> is called as described below.
While the number is being tested for primality,
B<BN_GENCB_call(cb, 1, j)> is called as described below.
=item *
When a prime has been found, B<callback(2, i, cb_arg)> is called.
When a prime has been found, B<BN_GENCB_call(cb, 2, i)> is called.
=back
@@ -54,37 +73,66 @@ generator.
If B<safe> is true, it will be a safe prime (i.e. a prime p so
that (p-1)/2 is also prime).
The PRNG must be seeded prior to calling BN_generate_prime().
The PRNG must be seeded prior to calling BN_generate_prime_ex().
The prime number generation has a negligible error probability.
BN_is_prime() and BN_is_prime_fasttest() test if the number B<a> is
BN_is_prime_ex() and BN_is_prime_fasttest_ex() test if the number B<p> is
prime. The following tests are performed until one of them shows that
B<a> is composite; if B<a> passes all these tests, it is considered
B<p> is composite; if B<p> passes all these tests, it is considered
prime.
BN_is_prime_fasttest(), when called with B<do_trial_division == 1>,
BN_is_prime_fasttest_ex(), when called with B<do_trial_division == 1>,
first attempts trial division by a number of small primes;
if no divisors are found by this test and B<callback> is not B<NULL>,
B<callback(1, -1, cb_arg)> is called.
if no divisors are found by this test and B<cb> is not B<NULL>,
B<BN_GENCB_call(cb, 1, -1)> is called.
If B<do_trial_division == 0>, this test is skipped.
Both BN_is_prime() and BN_is_prime_fasttest() perform a Miller-Rabin
probabilistic primality test with B<checks> iterations. If
B<checks == BN_prime_checks>, a number of iterations is used that
Both BN_is_prime_ex() and BN_is_prime_fasttest_ex() perform a Miller-Rabin
probabilistic primality test with B<nchecks> iterations. If
B<nchecks == BN_prime_checks>, a number of iterations is used that
yields a false positive rate of at most 2^-80 for random input.
If B<callback> is not B<NULL>, B<callback(1, j, cb_arg)> is called
If B<cb> is not B<NULL>, B<BN_GENCB_call(cb, 1, j)> is called
after the j-th iteration (j = 0, 1, ...). B<ctx> is a
pre-allocated B<BN_CTX> (to save the overhead of allocating and
freeing the structure in a loop), or B<NULL>.
BN_GENCB_call calls the callback function held in the B<BN_GENCB> structure
and passes the ints B<a> and B<b> as arguments. There are two types of
B<BN_GENCB> structure that are supported: "new" style and "old" style. New
programs should prefer the "new" style, whilst the "old" style is provided
for backwards compatibility purposes.
For "new" style callbacks a BN_GENCB structure should be initialised with a
call to BN_GENCB_set, where B<gencb> is a B<BN_GENCB *>, B<callback> is of
type B<int (*callback)(int, int, BN_GENCB *)> and B<cb_arg> is a B<void *>.
"Old" style callbacks are the same except they are initialised with a call
to BN_GENCB_set_old and B<callback> is of type
B<void (*callback)(int, int, void *)>.
A callback is invoked through a call to B<BN_GENCB_call>. This will check
the type of the callback and will invoke B<callback(a, b, gencb)> for new
style callbacks or B<callback(a, b, cb_arg)> for old style.
BN_generate_prime (deprecated) works in the same way as
BN_generate_prime_ex but expects an old style callback function
directly in the B<callback> parameter, and an argument to pass to it in
the B<cb_arg>. Similarly BN_is_prime and BN_is_prime_fasttest are
deprecated and can be compared to BN_is_prime_ex and
BN_is_prime_fasttest_ex respectively.
=head1 RETURN VALUES
BN_generate_prime_ex() return 1 on success or 0 on error.
BN_is_prime_ex(), BN_is_prime_fasttest_ex(), BN_is_prime() and
BN_is_prime_fasttest() return 0 if the number is composite, 1 if it is
prime with an error probability of less than 0.25^B<nchecks>, and
-1 on error.
BN_generate_prime() returns the prime number on success, B<NULL> otherwise.
BN_is_prime() returns 0 if the number is composite, 1 if it is
prime with an error probability of less than 0.25^B<checks>, and
-1 on error.
Callback functions should return 1 on success or 0 on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.

5
doc/crypto/BN_rand.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BN_rand, BN_pseudo_rand - generate pseudo-random number
BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-random number
=head1 SYNOPSIS
@@ -24,7 +24,8 @@ most significant bit of the random number can be zero. If B<top> is 0,
it is set to 1, and if B<top> is 1, the two most significant bits of
the number will be set to 1, so that the product of two such random
numbers will always have 2*B<bits> length. If B<bottom> is true, the
number will be odd.
number will be odd. The value of B<bits> must be zero or greater. If B<bits> is
1 then B<top> cannot also be 1.
BN_pseudo_rand() does the same, but pseudo-random numbers generated by
this function are not necessarily unpredictable. They can be used for

8
doc/crypto/BN_set_bit.pod
View File

@@ -37,12 +37,12 @@ BN_mask_bits() truncates B<a> to an B<n> bit number
shorter than B<n> bits.
BN_lshift() shifts B<a> left by B<n> bits and places the result in
B<r> (C<r=a*2^n>). BN_lshift1() shifts B<a> left by one and places
the result in B<r> (C<r=2*a>).
B<r> (C<r=a*2^n>). Note that B<n> must be non-negative. BN_lshift1() shifts
B<a> left by one and places the result in B<r> (C<r=2*a>).
BN_rshift() shifts B<a> right by B<n> bits and places the result in
B<r> (C<r=a/2^n>). BN_rshift1() shifts B<a> right by one and places
the result in B<r> (C<r=a/2>).
B<r> (C<r=a/2^n>). Note that B<n> must be non-negative. BN_rshift1() shifts
B<a> right by one and places the result in B<r> (C<r=a/2>).
For the shift functions, B<r> and B<a> may be the same variable.

2
doc/crypto/CMS_add0_cert.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_get1_crls, - CMS certificate and CRL utility functions
CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_get1_crls, - CMS certificate and CRL utility functions
=head1 SYNOPSIS

101
doc/crypto/CMS_add1_signer.pod Normal file
View File

@@ -0,0 +1,101 @@
=pod
=head1 NAME
CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure.
=head1 SYNOPSIS
#include <openssl/cms.h>
CMS_SignerInfo *CMS_add1_signer(CMS_ContentInfo *cms, X509 *signcert, EVP_PKEY *pkey, const EVP_MD *md, unsigned int flags);
int CMS_SignerInfo_sign(CMS_SignerInfo *si);
=head1 DESCRIPTION
CMS_add1_signer() adds a signer with certificate B<signcert> and private
key B<pkey> using message digest B<md> to CMS_ContentInfo SignedData
structure B<cms>.
The CMS_ContentInfo structure should be obtained from an initial call to
CMS_sign() with the flag B<CMS_PARTIAL> set or in the case or re-signing a
valid CMS_ContentInfo SignedData structure.
If the B<md> parameter is B<NULL> then the default digest for the public
key algorithm will be used.
Unless the B<CMS_REUSE_DIGEST> flag is set the returned CMS_ContentInfo
structure is not complete and must be finalized either by streaming (if
applicable) or a call to CMS_final().
The CMS_SignerInfo_sign() function will explicitly sign a CMS_SignerInfo
structure, its main use is when B<CMS_REUSE_DIGEST> and B<CMS_PARTIAL> flags
are both set.
=head1 NOTES
The main purpose of CMS_add1_signer() is to provide finer control
over a CMS signed data structure where the simpler CMS_sign() function defaults
are not appropriate. For example if multiple signers or non default digest
algorithms are needed. New attributes can also be added using the returned
CMS_SignerInfo structure and the CMS attribute utility functions or the
CMS signed receipt request functions.
Any of the following flags (ored together) can be passed in the B<flags>
parameter.
If B<CMS_REUSE_DIGEST> is set then an attempt is made to copy the content
digest value from the CMS_ContentInfo structure: to add a signer to an existing
structure. An error occurs if a matching digest value cannot be found to copy.
The returned CMS_ContentInfo structure will be valid and finalized when this
flag is set.
If B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the
CMS_SignerInfo structure will not be finalized so additional attributes
can be added. In this case an explicit call to CMS_SignerInfo_sign() is
needed to finalize it.
If B<CMS_NOCERTS> is set the signer's certificate will not be included in the
CMS_ContentInfo structure, the signer's certificate must still be supplied in
the B<signcert> parameter though. This can reduce the size of the signature if
the signers certificate can be obtained by other means: for example a
previously signed message.
The SignedData structure includes several CMS signedAttributes including the
signing time, the CMS content type and the supported list of ciphers in an
SMIMECapabilities attribute. If B<CMS_NOATTR> is set then no signedAttributes
will be used. If B<CMS_NOSMIMECAP> is set then just the SMIMECapabilities are
omitted.
OpenSSL will by default identify signing certificates using issuer name
and serial number. If B<CMS_USE_KEYID> is set it will use the subject key
identifier value instead. An error occurs if the signing certificate does not
have a subject key identifier extension.
If present the SMIMECapabilities attribute indicates support for the following
algorithms in preference order: 256 bit AES, Gost R3411-94, Gost 28147-89, 192
bit AES, 128 bit AES, triple DES, 128 bit RC2, 64 bit RC2, DES and 40 bit RC2.
If any of these algorithms is not available then it will not be included: for example the GOST algorithms will not be included if the GOST ENGINE is
not loaded.
CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
structure just added, this can be used to set additional attributes
before it is finalized.
=head1 RETURN VALUES
CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo
structure just added or NULL if an error occurs.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_final(3)|CMS_final(3)>,
=head1 HISTORY
CMS_add1_signer() was added to OpenSSL 0.9.8
=cut

16
doc/crypto/CMS_decrypt.pod
View File

@@ -27,7 +27,21 @@ function or errors about unknown algorithms will occur.
Although the recipients certificate is not needed to decrypt the data it is
needed to locate the appropriate (of possible several) recipients in the CMS
structure. If B<cert> is set to NULL all possible recipients are tried.
structure.
If B<cert> is set to NULL all possible recipients are tried. This case however
is problematic. To thwart the MMA attack (Bleichenbacher's attack on
PKCS #1 v1.5 RSA padding) all recipients are tried whether they succeed or
not. If no recipient succeeds then a random symmetric key is used to decrypt
the content: this will typically output garbage and may (but is not guaranteed
to) ultimately return a padding error only. If CMS_decrypt() just returned an
error when all recipient encrypted keys failed to decrypt an attacker could
use this in a timing attack. If the special flag B<CMS_DEBUG_DECRYPT> is set
then the above behaviour is modified and an error B<is> returned if no
recipient encrypted key can be decrypted B<without> generating a random
content encryption key. Applications should use this flag with
B<extreme caution> especially in automated gateways as it can leave them
open to attack.
It is possible to determine the correct recipient key by other means (for
example looking them up in a database) and setting them in the CMS structure

16
doc/crypto/CMS_get0_RecipientInfos.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt - CMS envelopedData RecipientInfo routines
CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt - CMS envelopedData RecipientInfo routines
=head1 SYNOPSIS
@@ -20,6 +20,7 @@
int CMS_RecipientInfo_set0_key(CMS_RecipientInfo *ri, unsigned char *key, size_t keylen);
int CMS_RecipientInfo_decrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
int CMS_RecipientInfo_encrypt(CMS_ContentInfo *cms, CMS_RecipientInfo *ri);
=head1 DESCRIPTION
@@ -66,6 +67,11 @@ CMS_RecipientInfo_decrypt() attempts to decrypt CMS_RecipientInfo structure
B<ri> in structure B<cms>. A key must have been associated with the structure
first.
CMS_RecipientInfo_encrypt() attempts to encrypt CMS_RecipientInfo structure
B<ri> in structure B<cms>. A key must have been associated with the structure
first and the content encryption key must be available: for example by a
previous call to CMS_RecipientInfo_decrypt().
=head1 NOTES
The main purpose of these functions is to enable an application to lookup
@@ -81,6 +87,13 @@ any appropriate means it can then associated with the structure and
CMS_RecpientInfo_decrypt() called. If successful CMS_decrypt() can be called
with a NULL key to decrypt the enveloped content.
The CMS_RecipientInfo_encrypt() can be used to add a new recipient to an
existing enveloped data structure. Typically an application will first decrypt
an appropriate CMS_RecipientInfo structure to make the content encrypt key
available, it will then add a new recipient using a function such as
CMS_add1_recipient_cert() and finally encrypt the content encryption key
using CMS_RecipientInfo_encrypt().
=head1 RETURN VALUES
CMS_get0_RecipientInfos() returns all CMS_RecipientInfo structures, or NULL if
@@ -89,6 +102,7 @@ an error occurs.
CMS_RecipientInfo_ktri_get0_signer_id(), CMS_RecipientInfo_set0_pkey(),
CMS_RecipientInfo_kekri_get0_id(), CMS_RecipientInfo_set0_key() and
CMS_RecipientInfo_decrypt() return 1 for success or 0 if an error occurs.
CMS_RecipientInfo_encrypt() return 1 for success or 0 if an error occurs.
CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0
for a successful comparison and non zero otherwise.

8
doc/crypto/CMS_get0_SignerInfos.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_cert_cmp, CMS_set1_signer_certs - CMS signedData signer functions.
CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp, CMS_set1_signer_cert - CMS signedData signer functions.
=head1 SYNOPSIS
@@ -11,6 +11,7 @@
STACK_OF(CMS_SignerInfo) *CMS_get0_SignerInfos(CMS_ContentInfo *cms);
int CMS_SignerInfo_get0_signer_id(CMS_SignerInfo *si, ASN1_OCTET_STRING **keyid, X509_NAME **issuer, ASN1_INTEGER **sno);
ASN1_OCTET_STRING *CMS_SignerInfo_get0_signature(CMS_SignerInfo *si);
int CMS_SignerInfo_cert_cmp(CMS_SignerInfo *si, X509 *cert);
void CMS_SignerInfo_set1_signer_cert(CMS_SignerInfo *si, X509 *signer);
@@ -24,6 +25,11 @@ associated with a specific CMS_SignerInfo structure B<si>. Either the
keyidentifier will be set in B<keyid> or B<both> issuer name and serial number
in B<issuer> and B<sno>.
CMS_SignerInfo_get0_signature() retrieves the signature associated with
B<si> in a pointer to an ASN1_OCTET_STRING structure. This pointer returned
corresponds to the internal signature value if B<si> so it may be read or
modified.
CMS_SignerInfo_cert_cmp() compares the certificate B<cert> against the signer
identifier B<si>. It returns zero if the comparison is successful and non zero
if not.

22
doc/crypto/CMS_get0_type.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType - get and set CMS content types
CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content
=head1 SYNOPSIS
@@ -11,6 +11,7 @@
const ASN1_OBJECT *CMS_get0_type(CMS_ContentInfo *cms);
int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid);
const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms);
ASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms);
=head1 DESCRIPTION
@@ -26,11 +27,15 @@ undefined.
ASN1_OBJECT *CMS_get0_eContentType() returns a pointer to the embedded
content type.
CMS_get0_content() returns a pointer to the B<ASN1_OCTET_STRING> pointer
containing the embedded content.
=head1 NOTES
As the B<0> implies CMS_get0_type() and CMS_get0_eContentType() return internal
pointers which should B<not> be freed up. CMS_set1_eContentType() copies the
supplied OID and it B<should> be freed up after use.
As the B<0> implies CMS_get0_type(), CMS_get0_eContentType() and
CMS_get0_content() return internal pointers which should B<not> be freed up.
CMS_set1_eContentType() copies the supplied OID and it B<should> be freed up
after use.
The B<ASN1_OBJECT> values returned can be converted to an integer B<NID> value
using OBJ_obj2nid(). For the currently supported content types the following
@@ -43,6 +48,15 @@ values are returned:
NID_pkcs7_encrypted
NID_pkcs7_enveloped
The return value of CMS_get0_content() is a pointer to the B<ASN1_OCTET_STRING>
content pointer. That means that for example:
ASN1_OCTET_STRING **pconf = CMS_get0_content(cms);
B<*pconf> could be NULL if there is no embedded content. Applications can
access, modify or create the embedded content in a B<CMS_ContentInfo> structure
using this function. Applications usually will not need to modify the
embedded content as it is normally set by higher level functions.
=head1 RETURN VALUES

2
doc/crypto/CMS_verify.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
CMS_verify - verify a CMS SignedData structure
CMS_verify, CMS_get0_signers - verify a CMS SignedData structure
=head1 SYNOPSIS

2
doc/crypto/CONF_modules_free.pod
View File

@@ -37,7 +37,7 @@ None of the functions return a value.
=head1 SEE ALSO
L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>,
L<CONF_modules_load_file(3), CONF_modules_load_file(3)>
L<CONF_modules_load_file(3)|CONF_modules_load_file(3)>
=head1 HISTORY

89
doc/crypto/CONF_modules_load_file.pod
View File

@@ -9,9 +9,9 @@
#include <openssl/conf.h>
int CONF_modules_load_file(const char *filename, const char *appname,
unsigned long flags);
unsigned long flags);
int CONF_modules_load(const CONF *cnf, const char *appname,
unsigned long flags);
unsigned long flags);
=head1 DESCRIPTION
@@ -22,7 +22,7 @@ NULL the standard OpenSSL application name B<openssl_conf> is used.
The behaviour can be cutomized using B<flags>.
CONF_modules_load() is idential to CONF_modules_load_file() except it
read configuration information from B<cnf>.
reads configuration information from B<cnf>.
=head1 NOTES
@@ -30,7 +30,7 @@ The following B<flags> are currently recognized:
B<CONF_MFLAGS_IGNORE_ERRORS> if set errors returned by individual
configuration modules are ignored. If not set the first module error is
considered fatal and no further modules are loads.
considered fatal and no further modules are loaded.
Normally any modules errors will add error information to the error queue. If
B<CONF_MFLAGS_SILENT> is set no error information is added.
@@ -42,7 +42,84 @@ B<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file()
ignore missing configuration files. Normally a missing configuration file
return an error.
=head1 RETURN VALUE
B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the
default section pointed to by B<openssl_conf> if B<appname> does not exist.
Applications should call these functions after loading builtin modules using
OPENSSL_load_builtin_modules(), any ENGINEs for example using
ENGINE_load_builtin_engines(), any algorithms for example
OPENSSL_add_all_algorithms() and (if the application uses libssl)
SSL_library_init().
By using CONF_modules_load_file() with appropriate flags an application can
customise application configuration to best suit its needs. In some cases the
use of a configuration file is optional and its absence is not an error: in
this case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set.
Errors during configuration may also be handled differently by different
applications. For example in some cases an error may simply print out a warning
message and the application continue. In other cases an application might
consider a configuration file error as fatal and exit immediately.
Applications can use the CONF_modules_load() function if they wish to load a
configuration file themselves and have finer control over how errors are
treated.
=head1 EXAMPLES
Load a configuration file and print out any errors and exit (missing file
considered fatal):
if (CONF_modules_load_file(NULL, NULL, 0) <= 0) {
fprintf(stderr, "FATAL: error loading configuration file\n");
ERR_print_errors_fp(stderr);
exit(1);
}
Load default configuration file using the section indicated by "myapp",
tolerate missing files, but exit on other errors:
if (CONF_modules_load_file(NULL, "myapp",
CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
fprintf(stderr, "FATAL: error loading configuration file\n");
ERR_print_errors_fp(stderr);
exit(1);
}
Load custom configuration file and section, only print warnings on error,
missing configuration file ignored:
if (CONF_modules_load_file("/something/app.cnf", "myapp",
CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
fprintf(stderr, "WARNING: error loading configuration file\n");
ERR_print_errors_fp(stderr);
}
Load and parse configuration file manually, custom error handling:
FILE *fp;
CONF *cnf = NULL;
long eline;
fp = fopen("/somepath/app.cnf", "r");
if (fp == NULL) {
fprintf(stderr, "Error opening configuration file\n");
/* Other missing configuration file behaviour */
} else {
cnf = NCONF_new(NULL);
if (NCONF_load_fp(cnf, fp, &eline) == 0) {
fprintf(stderr, "Error on line %ld of configuration file\n", eline);
ERR_print_errors_fp(stderr);
/* Other malformed configuration file behaviour */
} else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
fprintf(stderr, "Error configuring application\n");
ERR_print_errors_fp(stderr);
/* Other configuration error behaviour */
}
fclose(fp);
NCONF_free(cnf);
}
=head1 RETURN VALUES
These functions return 1 for success and a zero or negative value for
failure. If module errors are not ignored the return code will reflect the
@@ -51,7 +128,7 @@ return value of the failing module (this will always be zero or negative).
=head1 SEE ALSO
L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>,
L<CONF_free(3), CONF_free(3)>, L<err(3),err(3)>
L<CONF_free(3)|CONF_free(3)>, L<err(3)|err(3)>
=head1 HISTORY

43
doc/crypto/DH_generate_parameters.pod
View File

@@ -2,32 +2,39 @@
=head1 NAME
DH_generate_parameters, DH_check - generate and check Diffie-Hellman parameters
DH_generate_parameters_ex, DH_generate_parameters,
DH_check - generate and check Diffie-Hellman parameters
=head1 SYNOPSIS
#include <openssl/dh.h>
DH *DH_generate_parameters(int prime_len, int generator,
void (*callback)(int, int, void *), void *cb_arg);
int DH_generate_parameters_ex(DH *dh, int prime_len,int generator, BN_GENCB *cb);
int DH_check(DH *dh, int *codes);
Deprecated:
DH *DH_generate_parameters(int prime_len, int generator,
void (*callback)(int, int, void *), void *cb_arg);
=head1 DESCRIPTION
DH_generate_parameters() generates Diffie-Hellman parameters that can
be shared among a group of users, and returns them in a newly
allocated B<DH> structure. The pseudo-random number generator must be
DH_generate_parameters_ex() generates Diffie-Hellman parameters that can
be shared among a group of users, and stores them in the provided B<DH>
structure. The pseudo-random number generator must be
seeded prior to calling DH_generate_parameters().
B<prime_len> is the length in bits of the safe prime to be generated.
B<generator> is a small number E<gt> 1, typically 2 or 5.
A callback function may be used to provide feedback about the progress
of the key generation. If B<callback> is not B<NULL>, it will be
of the key generation. If B<cb> is not B<NULL>, it will be
called as described in L<BN_generate_prime(3)|BN_generate_prime(3)> while a random prime
number is generated, and when a prime has been found, B<callback(3,
0, cb_arg)> is called.
number is generated, and when a prime has been found, B<BN_GENCB_call(cb, 3, 0)>
is called. See L<BN_generate_prime(3)|BN_generate_prime(3)> for information on
the BN_GENCB_call() function.
DH_check() validates Diffie-Hellman parameters. It checks that B<p> is
a safe prime, and that B<g> is a suitable generator. In the case of an
@@ -38,19 +45,21 @@ checked, i.e. it does not equal 2 or 5.
=head1 RETURN VALUES
DH_generate_parameters() returns a pointer to the DH structure, or
NULL if the parameter generation fails. The error codes can be
obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
DH_generate_parameters_ex() and DH_check() return 1 if the check could be
performed, 0 otherwise.
DH_check() returns 1 if the check could be performed, 0 otherwise.
DH_generate_parameters() (deprecated) returns a pointer to the DH structure, or
NULL if the parameter generation fails.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 NOTES
DH_generate_parameters() may run for several hours before finding a
suitable prime.
DH_generate_parameters_ex() and DH_generate_parameters() may run for several
hours before finding a suitable prime.
The parameters generated by DH_generate_parameters() are not to be
used in signature schemes.
The parameters generated by DH_generate_parameters_ex() and DH_generate_parameters()
are not to be used in signature schemes.
=head1 BUGS

54
doc/crypto/DSA_generate_parameters.pod
View File

@@ -2,20 +2,26 @@
=head1 NAME
DSA_generate_parameters - generate DSA parameters
DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters
=head1 SYNOPSIS
#include <openssl/dsa.h>
int DSA_generate_parameters_ex(DSA *dsa, int bits,
const unsigned char *seed,int seed_len,
int *counter_ret, unsigned long *h_ret, BN_GENCB *cb);
Deprecated:
DSA *DSA_generate_parameters(int bits, unsigned char *seed,
int seed_len, int *counter_ret, unsigned long *h_ret,
void (*callback)(int, int, void *), void *cb_arg);
=head1 DESCRIPTION
DSA_generate_parameters() generates primes p and q and a generator g
for use in the DSA.
DSA_generate_parameters_ex() generates primes p and q and a generator g
for use in the DSA and stores the result in B<dsa>.
B<bits> is the length of the prime to be generated; the DSS allows a
maximum of 1024 bits.
@@ -25,64 +31,74 @@ generated at random. Otherwise, the seed is used to generate
them. If the given seed does not yield a prime q, a new random
seed is chosen and placed at B<seed>.
DSA_generate_parameters() places the iteration count in
DSA_generate_parameters_ex() places the iteration count in
*B<counter_ret> and a counter used for finding a generator in
*B<h_ret>, unless these are B<NULL>.
A callback function may be used to provide feedback about the progress
of the key generation. If B<callback> is not B<NULL>, it will be
called as follows:
of the key generation. If B<cb> is not B<NULL>, it will be
called as shown below. For information on the BN_GENCB structure and the
BN_GENCB_call function discussed below, refer to
L<BN_generate_prime(3)|BN_generate_prime(3)>.
=over 4
=item *
When a candidate for q is generated, B<callback(0, m++, cb_arg)> is called
When a candidate for q is generated, B<BN_GENCB_call(cb, 0, m++)> is called
(m is 0 for the first candidate).
=item *
When a candidate for q has passed a test by trial division,
B<callback(1, -1, cb_arg)> is called.
B<BN_GENCB_call(cb, 1, -1)> is called.
While a candidate for q is tested by Miller-Rabin primality tests,
B<callback(1, i, cb_arg)> is called in the outer loop
B<BN_GENCB_call(cb, 1, i)> is called in the outer loop
(once for each witness that confirms that the candidate may be prime);
i is the loop counter (starting at 0).
=item *
When a prime q has been found, B<callback(2, 0, cb_arg)> and
B<callback(3, 0, cb_arg)> are called.
When a prime q has been found, B<BN_GENCB_call(cb, 2, 0)> and
B<BN_GENCB_call(cb, 3, 0)> are called.
=item *
Before a candidate for p (other than the first) is generated and tested,
B<callback(0, counter, cb_arg)> is called.
B<BN_GENCB_call(cb, 0, counter)> is called.
=item *
When a candidate for p has passed the test by trial division,
B<callback(1, -1, cb_arg)> is called.
B<BN_GENCB_call(cb, 1, -1)> is called.
While it is tested by the Miller-Rabin primality test,
B<callback(1, i, cb_arg)> is called in the outer loop
B<BN_GENCB_call(cb, 1, i)> is called in the outer loop
(once for each witness that confirms that the candidate may be prime).
i is the loop counter (starting at 0).
=item *
When p has been found, B<callback(2, 1, cb_arg)> is called.
When p has been found, B<BN_GENCB_call(cb, 2, 1)> is called.
=item *
When the generator has been found, B<callback(3, 1, cb_arg)> is called.
When the generator has been found, B<BN_GENCB_call(cb, 3, 1)> is called.
=back
DSA_generate_parameters() (deprecated) works in much the same way as for DSA_generate_parameters_ex, except that no B<dsa> parameter is passed and
instead a newly allocated B<DSA> structure is returned. Additionally "old
style" callbacks are used instead of the newer BN_GENCB based approach.
Refer to L<BN_generate_prime(3)|BN_generate_prime(3)> for further information.
=head1 RETURN VALUE
DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise.
DSA_generate_parameters() returns a pointer to the DSA structure, or
B<NULL> if the parameter generation fails. The error codes can be
obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
B<NULL> if the parameter generation fails.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 BUGS
@@ -91,7 +107,7 @@ Seed lengths E<gt> 20 are not supported.
=head1 SEE ALSO
L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>,
L<DSA_free(3)|DSA_free(3)>
L<DSA_free(3)|DSA_free(3)>, L<BN_generate_prime(3)|BN_generate_prime(3)>
=head1 HISTORY

60
doc/crypto/EC_GFp_simple_method.pod Normal file
View File

@@ -0,0 +1,60 @@
=pod
=head1 NAME
EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type - Functions for obtaining B<EC_METHOD> objects.
=head1 SYNOPSIS
#include <openssl/ec.h>
const EC_METHOD *EC_GFp_simple_method(void);
const EC_METHOD *EC_GFp_mont_method(void);
const EC_METHOD *EC_GFp_nist_method(void);
const EC_METHOD *EC_GFp_nistp224_method(void);
const EC_METHOD *EC_GFp_nistp256_method(void);
const EC_METHOD *EC_GFp_nistp521_method(void);
const EC_METHOD *EC_GF2m_simple_method(void);
int EC_METHOD_get_field_type(const EC_METHOD *meth);
=head1 DESCRIPTION
The Elliptic Curve library provides a number of different implementations through a single common interface.
When constructing a curve using EC_GROUP_new (see L<EC_GROUP_new(3)|EC_GROUP_new(3)>) an
implementation method must be provided. The functions described here all return a const pointer to an
B<EC_METHOD> structure that can be passed to EC_GROUP_NEW. It is important that the correct implementation
type for the form of curve selected is used.
For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_method.
For Fp curves the lowest common denominator implementation is the EC_GFp_simple_method implementation. All
other implementations are based on this one. EC_GFp_mont_method builds on EC_GFp_simple_method but adds the
use of montgomery multiplication (see L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>). EC_GFp_nist_method
offers an implementation optimised for use with NIST recommended curves (NIST curves are available through
EC_GROUP_new_by_curve_name as described in L<EC_GROUP_new(3)|EC_GROUP_new(3)>).
The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521_method offer 64 bit
optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these
implementations are not available on all platforms.
EC_METHOD_get_field_type identifies what type of field the EC_METHOD structure supports, which will be either
F2^m or Fp. If the field type is Fp then the value B<NID_X9_62_prime_field> is returned. If the field type is
F2^m then the value B<NID_X9_62_characteristic_two_field> is returned. These values are defined in the
obj_mac.h header file.
=head1 RETURN VALUES
All EC_GFp* functions and EC_GF2m_simple_method always return a const pointer to an EC_METHOD structure.
EC_METHOD_get_field_type returns an integer that identifies the type of field the EC_METHOD structure supports.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>,
L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>
=cut

174
doc/crypto/EC_GROUP_copy.pod Normal file
View File

@@ -0,0 +1,174 @@
=pod
=head1 NAME
EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp, EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, EC_GROUP_get_pentanomial_basis - Functions for manipulating B<EC_GROUP> objects.
=head1 SYNOPSIS
#include <openssl/ec.h>
#include <openssl/bn.h>
int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src);
EC_GROUP *EC_GROUP_dup(const EC_GROUP *src);
const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group);
int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor);
const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group);
int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx);
int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx);
void EC_GROUP_set_curve_name(EC_GROUP *group, int nid);
int EC_GROUP_get_curve_name(const EC_GROUP *group);
void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag);
int EC_GROUP_get_asn1_flag(const EC_GROUP *group);
void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form);
point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *);
unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x);
size_t EC_GROUP_get_seed_len(const EC_GROUP *);
size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len);
int EC_GROUP_get_degree(const EC_GROUP *group);
int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx);
int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx);
int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx);
int EC_GROUP_get_basis_type(const EC_GROUP *);
int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k);
int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1,
unsigned int *k2, unsigned int *k3);
=head1 DESCRIPTION
EC_GROUP_copy copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
EC_GROUP_dup creates a new EC_GROUP object and copies the content from B<src> to the newly created
EC_GROUP object.
EC_GROUP_method_of obtains the EC_METHOD of B<group>.
EC_GROUP_set_generator sets curve paramaters that must be agreed by all participants using the curve. These
paramaters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the
curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and
n-1 where n is the B<order>. The B<order> multipied by the B<cofactor> gives the number of points on the curve.
EC_GROUP_get0_generator returns the generator for the identified B<group>.
The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided B<order> and B<cofactor> parameters
with the respective order and cofactors for the B<group>.
The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively
(see L<EC_GROUP_new(3)|EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name
will return 0.
The asn1_flag value on a curve is used to determine whether there is a specific ASN1 OID to describe the curve or not.
If the asn1_flag is 1 then this is a named curve with an associated ASN1 OID. If not then asn1_flag is 0. The functions
EC_GROUP_get_asn1_flag and EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve. If set then
the curve_name must also be set.
The point_coversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA).
point_conversion_form_t is an enum defined as follows:
typedef enum {
/** the point is encoded as z||x, where the octet z specifies
* which solution of the quadratic equation y is */
POINT_CONVERSION_COMPRESSED = 2,
/** the point is encoded as z||x||y, where z is the octet 0x02 */
POINT_CONVERSION_UNCOMPRESSED = 4,
/** the point is encoded as z||x||y, where the octet z specifies
* which solution of the quadratic equation y is */
POINT_CONVERSION_HYBRID = 6
} point_conversion_form_t;
For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by
the octets for x, followed by the octets for y.
For any given x co-ordinate for a point on a curve it is possible to derive two possible y values. For
POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of
the two possible solutions for y has been used, followed by the octets for x.
For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two
possible solutions for y has been used, followed by the octets for x, followed by the octets for y.
The functions EC_GROUP_set_point_conversion_form and EC_GROUP_get_point_conversion_form set and get the point_conversion_form
for the curve respectively.
ANSI X9.62 (ECDSA standard) defines a method of generating the curve parameter b from a random number. This provides advantages
in that a parameter obtained in this way is highly unlikely to be susceptible to special purpose attacks, or have any trapdoors in it.
If the seed is present for a curve then the b parameter was generated in a verifiable fashion using that seed. The OpenSSL EC library
does not use this seed value but does enable you to inspect it using EC_GROUP_get0_seed. This returns a pointer to a memory block
containing the seed that was used. The length of the memory block can be obtained using EC_GROUP_get_seed_len. A number of the
builtin curves within the library provide seed values that can be obtained. It is also possible to set a custom seed using
EC_GROUP_set_seed and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use
this seed value, although it will be preserved in any ASN1 based communications.
EC_GROUP_get_degree gets the degree of the field. For Fp fields this will be the number of bits in p. For F2^m fields this will be
the value m.
The function EC_GROUP_check_discriminant calculates the discriminant for the curve and verifies that it is valid.
For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is
simply b. In either case for the curve to be valid the discriminant must be non zero.
The function EC_GROUP_check performs a number of checks on a curve to verify that it is valid. Checks performed include
verifying that the discriminant is non zero; that a generator has been defined; that the generator is on the curve and has
the correct order.
EC_GROUP_cmp compares B<a> and B<b> to determine whether they represent the same curve or not.
The functions EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis should only be called for curves
defined over an F2^m field. Addition and multiplication operations within an F2^m field are performed using an irreducible polynomial
function f(x). This function is either a trinomial of the form:
f(x) = x^m + x^k + 1 with m > k >= 1
or a pentanomial of the form:
f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1
The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The
function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similary
the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>,
B<k2> and B<k3> respectively.
=head1 RETURN VALUES
The following functions return 1 on success or 0 on error: EC_GROUP_copy, EC_GROUP_set_generator, EC_GROUP_check,
EC_GROUP_check_discriminant, EC_GROUP_get_trinomial_basis and EC_GROUP_get_pentanomial_basis.
EC_GROUP_dup returns a pointer to the duplicated curve, or NULL on error.
EC_GROUP_method_of returns the EC_METHOD implementation in use for the given curve or NULL on error.
EC_GROUP_get0_generator returns the generator for the given curve or NULL on error.
EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get_asn1_flag, EC_GROUP_get_point_conversion_form
and EC_GROUP_get_degree return the order, cofactor, curve name (NID), ASN1 flag, point_conversion_form and degree for the
specified curve respectively. If there is no curve name associated with a curve then EC_GROUP_get_curve_name will return 0.
EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not
specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified.
EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is
0, the the return value will be 1. On error 0 is returned.
EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.
EC_GROUP_get_basis_type returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a
trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>,
L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
=cut

95
doc/crypto/EC_GROUP_new.pod Normal file
View File

@@ -0,0 +1,95 @@
=pod
=head1 NAME
EC_GROUP_new, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, EC_get_builtin_curves - Functions for creating and destroying B<EC_GROUP> objects.
=head1 SYNOPSIS
#include <openssl/ec.h>
#include <openssl/bn.h>
EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
void EC_GROUP_free(EC_GROUP *group);
void EC_GROUP_clear_free(EC_GROUP *group);
EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
EC_GROUP *EC_GROUP_new_by_curve_name(int nid);
int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx);
int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx);
size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems);
=head1 DESCRIPTION
Within the library there are two forms of elliptic curve that are of interest. The first form is those defined over the
prime field Fp. The elements of Fp are the integers 0 to p-1, where p is a prime number. This gives us a revised
elliptic curve equation as follows:
y^2 mod p = x^3 +ax + b mod p
The second form is those defined over a binary field F2^m where the elements of the field are integers of length at
most m bits. For this form the elliptic curve equation is modified to:
y^2 + xy = x^3 + ax^2 + b (where b != 0)
Operations in a binary field are performed relative to an B<irreducible polynomial>. All such curves with OpenSSL
use a trinomial or a pentanomial for this parameter.
A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>). It is then necessary to call either EC_GROUP_set_curve_GFp or
EC_GROUP_set_curve_GF2m as appropriate to create a curve defined over Fp or over F2^m respectively.
EC_GROUP_set_curve_GFp sets the curve parameters B<p>, B<a> and B<b> for a curve over Fp stored in B<group>.
EC_group_get_curve_GFp obtains the previously set curve parameters.
EC_GROUP_set_curve_GF2m sets the equivalent curve parameters for a curve over F2^m. In this case B<p> represents
the irreducible polybnomial - each bit represents a term in the polynomial. Therefore there will either be three
or five bits set dependant on whether the polynomial is a trinomial or a pentanomial.
EC_group_get_curve_GF2m obtains the previously set curve parameters.
The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and the
appropriate EC_group_set_curve function. An appropriate default implementation method will be used.
Whilst the library can be used to create any curve using the functions described above, there are also a number of
predefined curves that are available. In order to obtain a list of all of the predefined curves, call the function
EC_get_builtin_curves. The parameter B<r> should be an array of EC_builtin_curve structures of size B<nitems>. The function
will populate the B<r> array with information about the builtin curves. If B<nitems> is less than the total number of
curves available, then the first B<nitems> curves will be returned. Otherwise the total number of curves will be
provided. The return value is the total number of curves available (whether that number has been populated in B<r> or
not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available.
The EC_builtin_curve structure is defined as follows:
typedef struct {
int nid;
const char *comment;
} EC_builtin_curve;
Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve.
In order to construct a builtin curve use the function EC_GROUP_new_by_curve_name and provide the B<nid> of the curve to
be constructed.
EC_GROUP_free frees the memory associated with the EC_GROUP.
EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory.
=head1 RETURN VALUES
All EC_GROUP_new* functions return a pointer to the newly constructed group, or NULL on error.
EC_get_builtin_curves returns the number of builtin curves that are available.
EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m return 1 on success or 0 on error.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
=cut

108
doc/crypto/EC_KEY_new.pod Normal file
View File

@@ -0,0 +1,108 @@
=pod
=head1 NAME
EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, EC_KEY_get_enc_flags, EC_KEY_set_enc_flags, EC_KEY_get_conv_form, EC_KEY_set_conv_form, EC_KEY_get_key_method_data, EC_KEY_insert_key_method_data, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates - Functions for creating, destroying and manipulating B<EC_KEY> objects.
=head1 SYNOPSIS
#include <openssl/ec.h>
#include <openssl/bn.h>
EC_KEY *EC_KEY_new(void);
int EC_KEY_get_flags(const EC_KEY *key);
void EC_KEY_set_flags(EC_KEY *key, int flags);
void EC_KEY_clear_flags(EC_KEY *key, int flags);
EC_KEY *EC_KEY_new_by_curve_name(int nid);
void EC_KEY_free(EC_KEY *key);
EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src);
EC_KEY *EC_KEY_dup(const EC_KEY *src);
int EC_KEY_up_ref(EC_KEY *key);
const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key);
int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group);
const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key);
int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv);
const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key);
int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub);
point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key);
void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform);
void *EC_KEY_get_key_method_data(EC_KEY *key,
void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *));
void EC_KEY_insert_key_method_data(EC_KEY *key, void *data,
void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *));
void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag);
int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx);
int EC_KEY_generate_key(EC_KEY *key);
int EC_KEY_check_key(const EC_KEY *key);
int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y);
=head1 DESCRIPTION
An EC_KEY represents a public key and (optionaly) an associated private key. A new EC_KEY (with no associated curve) can be constructed by calling EC_KEY_new.
The reference count for the newly created EC_KEY is initially set to 1. A curve can be associated with the EC_KEY by calling
EC_KEY_set_group.
Alternatively a new EC_KEY can be constructed by calling EC_KEY_new_by_curve_name and supplying the nid of the associated curve. Refer to L<EC_GROUP_new(3)|EC_GROUP_new(3)> for a description of curve names. This function simply wraps calls to EC_KEY_new and
EC_GROUP_new_by_curve_name.
Calling EC_KEY_free decrements the reference count for the EC_KEY object, and if it has dropped to zero then frees the memory associated
with it.
EC_KEY_copy copies the contents of the EC_KEY in B<src> into B<dest>.
EC_KEY_dup creates a new EC_KEY object and copies B<ec_key> into it.
EC_KEY_up_ref increments the reference count associated with the EC_KEY object.
EC_KEY_generate_key generates a new public and private key for the supplied B<eckey> object. B<eckey> must have an EC_GROUP object
associated with it before calling this function. The private key is a random integer (0 < priv_key < order, where order is the order
of the EC_GROUP object). The public key is an EC_POINT on the curve calculated by multiplying the generator for the curve by the
private key.
EC_KEY_check_key performs various sanity checks on the EC_KEY object to confirm that it is valid.
EC_KEY_set_public_key_affine_coordinates sets the public key for B<key> based on its affine co-ordinates, i.e. it constructs an EC_POINT
object based on the supplied B<x> and B<y> values and sets the public key to be this EC_POINT. It will also performs certain sanity checks
on the key to confirm that it is valid.
The functions EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, and EC_KEY_set_public_key get and set the EC_GROUP object, the private key and the EC_POINT public key for the B<key> respectively.
The functions EC_KEY_get_conv_form and EC_KEY_set_conv_form get and set the point_conversion_form for the B<key>. For a description
of point_conversion_forms please refer to L<EC_POINT_new(3)|EC_POINT_new(3)>.
EC_KEY_insert_key_method_data and EC_KEY_get_key_method_data enable the caller to associate arbitary additional data specific to the
elliptic curve scheme being used with the EC_KEY object. This data is treated as a "black box" by the ec library. The data to be stored by EC_KEY_insert_key_method_data is provided in the B<data> parameter, which must have have associated functions for duplicating, freeing and "clear_freeing" the data item. If a subsequent EC_KEY_get_key_method_data call is issued, the functions for duplicating, freeing and "clear_freeing" the data item must be provided again, and they must be the same as they were when the data item was inserted.
EC_KEY_set_flags sets the flags in the B<flags> parameter on the EC_KEY object. Any flags that are already set are left set. The currently defined standard flags are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH and is defined in ecdh.h. EC_KEY_get_flags returns the current flags that are set for this EC_KEY. EC_KEY_clear_flags clears the flags indicated by the B<flags> parameter. All other flags are left in their existing state.
EC_KEY_set_asn1_flag sets the asn1_flag on the underlying EC_GROUP object (if set). Refer to L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> for further information on the asn1_flag.
EC_KEY_precompute_mult stores multiples of the underlying EC_GROUP generator for faster point multiplication. See also L<EC_POINT_add(3)|EC_POINT_add(3)>.
=head1 RETURN VALUES
EC_KEY_new, EC_KEY_new_by_curve_name and EC_KEY_dup return a pointer to the newly created EC_KEY object, or NULL on error.
EC_KEY_get_flags returns the flags associated with the EC_KEY object as an integer.
EC_KEY_copy returns a pointer to the destination key, or NULL on error.
EC_KEY_up_ref, EC_KEY_set_group, EC_KEY_set_private_key, EC_KEY_set_public_key, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key and EC_KEY_set_public_key_affine_coordinates return 1 on success or 0 on error.
EC_KEY_get0_group returns the EC_GROUP associated with the EC_KEY.
EC_KEY_get0_private_key returns the private key associated with the EC_KEY.
EC_KEY_get_conv_form return the point_conversion_form for the EC_KEY.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>,
L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, L<EC_POINT_new(3)|EC_POINT_new(3)>,
L<EC_POINT_add(3)|EC_POINT_add(3)>,
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>,
L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
=cut

72
doc/crypto/EC_POINT_add.pod Normal file
View File

@@ -0,0 +1,72 @@
=pod
=head1 NAME
EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on B<EC_POINT> objects.
=head1 SYNOPSIS
#include <openssl/ec.h>
#include <openssl/bn.h>
int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx);
int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx);
int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p);
int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx);
int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx);
int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx);
int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx);
int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx);
int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx);
int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx);
int EC_GROUP_have_precompute_mult(const EC_GROUP *group);
=head1 DESCRIPTION
EC_POINT_add adds the two points B<a> and B<b> and places the result in B<r>. Similarly EC_POINT_dbl doubles the point B<a> and places the
result in B<r>. In both cases it is valid for B<r> to be one of B<a> or B<b>.
EC_POINT_invert calculates the inverse of the supplied point B<a>. The result is placed back in B<a>.
The function EC_POINT_is_at_infinity tests whether the supplied point is at infinity or not.
EC_POINT_is_on_curve tests whether the supplied point is on the curve or not.
EC_POINT_cmp compares the two supplied points and tests whether or not they are equal.
The functions EC_POINT_make_affine and EC_POINTs_make_affine force the internal representation of the EC_POINT(s) into the affine
co-ordinate system. In the case of EC_POINTs_make_affine the value B<num> provides the number of points in the array B<points> to be
forced.
EC_POINT_mul calculates the value generator * B<n> + B<q> * B<m> and stores the result in B<r>. The value B<n> may be NULL in which case the result is just B<q> * B<m>.
EC_POINTs_mul calculates the value generator * B<n> + B<q[0]> * B<m[0]> + ... + B<q[num-1]> * B<m[num-1]>. As for EC_POINT_mul the value
B<n> may be NULL.
The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst
EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> for information
about the generator.
=head1 RETURN VALUES
The following functions return 1 on success or 0 on error: EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_make_affine,
EC_POINTs_make_affine, EC_POINTs_make_affine, EC_POINT_mul, EC_POINTs_mul and EC_GROUP_precompute_mult.
EC_POINT_is_at_infinity returns 1 if the point is at infinity, or 0 otherwise.
EC_POINT_is_on_curve returns 1 if the point is on the curve, 0 if not, or -1 on error.
EC_POINT_cmp returns 1 if the points are not equal, 0 if they are, or -1 on error.
EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 if not.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
=cut

128
doc/crypto/EC_POINT_new.pod Normal file
View File

@@ -0,0 +1,128 @@
=pod
=head1 NAME
EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates, EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex, EC_POINT_hex2point - Functions for creating, destroying and manipulating B<EC_POINT> objects.
=head1 SYNOPSIS
#include <openssl/ec.h>
#include <openssl/bn.h>
EC_POINT *EC_POINT_new(const EC_GROUP *group);
void EC_POINT_free(EC_POINT *point);
void EC_POINT_clear_free(EC_POINT *point);
int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src);
EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group);
const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);
int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point);
int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx);
int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group,
const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx);
int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx);
int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group,
const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
const BIGNUM *x, int y_bit, BN_CTX *ctx);
int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p,
const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx);
int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group,
const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p,
const BIGNUM *x, int y_bit, BN_CTX *ctx);
size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p,
point_conversion_form_t form,
unsigned char *buf, size_t len, BN_CTX *ctx);
int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p,
const unsigned char *buf, size_t len, BN_CTX *ctx);
BIGNUM *EC_POINT_point2bn(const EC_GROUP *, const EC_POINT *,
point_conversion_form_t form, BIGNUM *, BN_CTX *);
EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *,
EC_POINT *, BN_CTX *);
char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *,
point_conversion_form_t form, BN_CTX *);
EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *,
EC_POINT *, BN_CTX *);
=head1 DESCRIPTION
An EC_POINT represents a point on a curve. A new point is constructed by calling the function EC_POINT_new and providing the B<group>
object that the point relates to.
EC_POINT_free frees the memory associated with the EC_POINT.
EC_POINT_clear_free destroys any sensitive data held within the EC_POINT and then frees its memory.
EC_POINT_copy copies the point B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
EC_POINT_dup creates a new EC_POINT object and copies the content from B<src> to the newly created
EC_POINT object.
EC_POINT_method_of obtains the EC_METHOD associated with B<point>.
A valid point on a curve is the special point at infinity. A point is set to be at infinity by calling EC_POINT_set_to_infinity.
The affine co-ordinates for a point describe a point in terms of its x and y position. The functions
EC_POINT_set_affine_coordinates_GFp and EC_POINT_set_affine_coordinates_GF2m set the B<x> and B<y> co-ordinates for the point
B<p> defined over the curve given in B<group>.
As well as the affine co-ordinates, a point can alternatively be described in terms of its Jacobian
projective co-ordinates (for Fp curves only). Jacobian projective co-ordinates are expressed as three values x, y and z. Working in
this co-ordinate system provides more efficient point multiplication operations.
A mapping exists between Jacobian projective co-ordinates and affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian projective to affine co-ordinates is simple. The co-ordinate (x, y) is
mapped to (x, y, 1). To set or get the projective co-ordinates use EC_POINT_set_Jprojective_coordinates_GFp and
EC_POINT_get_Jprojective_coordinates_GFp respectively.
Points can also be described in terms of their compressed co-ordinates. For a point (x, y), for any given value for x such that the point is
on the curve there will only ever be two possible values for y. Therefore a point can be set using the EC_POINT_set_compressed_coordinates_GFp
and EC_POINT_set_compressed_coordinates_GF2m functions where B<x> is the x co-ordinate and B<y_bit> is a value 0 or 1 to identify which of
the two possible values for y should be used.
In addition EC_POINTs can be converted to and from various external
representations. Supported representations are octet strings, BIGNUMs and
hexadecimal. Octet strings are stored in a buffer along with an associated
buffer length. A point held in a BIGNUM is calculated by converting the point to
an octet string and then converting that octet string into a BIGNUM integer.
Points in hexadecimal format are stored in a NULL terminated character string
where each character is one of the printable values 0-9 or A-F (or a-f).
The functions EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex and EC_POINT_hex2point convert
from and to EC_POINTs for the formats: octet string, BIGNUM and hexadecimal respectively.
The function EC_POINT_point2oct must be supplied with a buffer long enough to store the octet string. The return value provides the number of
octets stored. Calling the function with a NULL buffer will not perform the conversion but will still return the required buffer length.
The function EC_POINT_point2hex will allocate sufficient memory to store the hexadecimal string. It is the caller's responsibility to free
this memory with a subsequent call to OPENSSL_free().
=head1 RETURN VALUES
EC_POINT_new and EC_POINT_dup return the newly allocated EC_POINT or NULL on error.
The following functions return 1 on success or 0 on error: EC_POINT_copy, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates_GFp,
EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp,
EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m,
EC_POINT_set_compressed_coordinates_GF2m and EC_POINT_oct2point.
EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT.
EC_POINT_point2oct returns the length of the required buffer, or 0 on error.
EC_POINT_point2bn returns the pointer to the BIGNUM supplied, or NULL on error.
EC_POINT_bn2point returns the pointer to the EC_POINT supplied, or NULL on error.
EC_POINT_point2hex returns a pointer to the hex string, or NULL on error.
EC_POINT_hex2point returns the pointer to the EC_POINT supplied, or NULL on error.
=head1 SEE ALSO
L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>,
L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>,
L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>
=cut

9
doc/crypto/ERR_get_error.pod
View File

@@ -49,11 +49,14 @@ additionally store the file name and line number where
the error occurred in *B<file> and *B<line>, unless these are B<NULL>.
ERR_get_error_line_data(), ERR_peek_error_line_data() and
ERR_get_last_error_line_data() store additional data and flags
ERR_peek_last_error_line_data() store additional data and flags
associated with the error code in *B<data>
and *B<flags>, unless these are B<NULL>. *B<data> contains a string
if *B<flags>&B<ERR_TXT_STRING>. If it has been allocated by OPENSSL_malloc(),
*B<flags>&B<ERR_TXT_MALLOCED> is true.
if *B<flags>&B<ERR_TXT_STRING> is true.
An application B<MUST NOT> free the *B<data> pointer (or any other pointers
returned by these functions) with OPENSSL_free() as freeing is handled
automatically by the error library.
=head1 RETURN VALUES

21
doc/crypto/ERR_remove_state.pod
View File

@@ -2,26 +2,35 @@
=head1 NAME
ERR_remove_state - free a thread's error queue
ERR_remove_thread_state, ERR_remove_state - free a thread's error queue
=head1 SYNOPSIS
#include <openssl/err.h>
void ERR_remove_thread_state(const CRYPTO_THREADID *tid);
Deprecated:
void ERR_remove_state(unsigned long pid);
=head1 DESCRIPTION
ERR_remove_state() frees the error queue associated with thread B<pid>.
If B<pid> == 0, the current thread will have its error queue removed.
ERR_remove_thread_state() frees the error queue associated with thread B<tid>.
If B<tid> == B<NULL>, the current thread will have its error queue removed.
Since error queue data structures are allocated automatically for new
threads, they must be freed when threads are terminated in order to
avoid memory leaks.
ERR_remove_state is deprecated and has been replaced by
ERR_remove_thread_state. Since threads in OpenSSL are no longer identified
by unsigned long values any argument to this function is ignored. Calling
ERR_remove_state is equivalent to B<ERR_remove_thread_state(NULL)>.
=head1 RETURN VALUE
ERR_remove_state() returns no value.
ERR_remove_thread_state and ERR_remove_state() return no value.
=head1 SEE ALSO
@@ -29,6 +38,8 @@ L<err(3)|err(3)>
=head1 HISTORY
ERR_remove_state() is available in all versions of SSLeay and OpenSSL.
ERR_remove_state() is available in all versions of SSLeay and OpenSSL. It
was deprecated in OpenSSL 1.0.0 when ERR_remove_thread_state was introduced
and thread IDs were introduced to identify threads instead of 'unsigned long'.
=cut

11
doc/crypto/EVP_BytesToKey.pod
View File

@@ -17,7 +17,7 @@ EVP_BytesToKey - password based encryption routine
EVP_BytesToKey() derives a key and IV from various parameters. B<type> is
the cipher to derive the key and IV for. B<md> is the message digest to use.
The B<salt> paramter is used as a salt in the derivation: it should point to
The B<salt> parameter is used as a salt in the derivation: it should point to
an 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing
B<datal> bytes which is used to derive the keying data. B<count> is the
iteration count to use. The derived key and IV will be written to B<key>
@@ -36,8 +36,8 @@ If the total key and IV length is less than the digest length and
B<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5
otherwise a non standard extension is used to derive the extra data.
Newer applications should use more standard algorithms such as PKCS#5
v2.0 for key derivation.
Newer applications should use a more modern algorithm such as PBKDF2 as
defined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC.
=head1 KEY DERIVATION ALGORITHM
@@ -55,7 +55,10 @@ the IV.
=head1 RETURN VALUES
EVP_BytesToKey() returns the size of the derived key in bytes.
If B<data> is NULL, then EVP_BytesToKey() returns the number of bytes
needed to store the derived key.
Otherwise, EVP_BytesToKey() returns the size of the derived key in bytes,
or 0 on error.
=head1 SEE ALSO

103
doc/crypto/EVP_DigestInit.pod
View File

@@ -4,9 +4,10 @@
EVP_MD_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate,
EVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, EVP_MAX_MD_SIZE,
EVP_MD_CTX_copy_ex, EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size,
EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type,
EVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1, EVP_dss, EVP_dss1, EVP_mdc2,
EVP_MD_CTX_copy_ex, EVP_DigestInit, EVP_DigestFinal, EVP_MD_CTX_copy, EVP_MD_type,
EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size,
EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1,
EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_dss, EVP_dss1, EVP_mdc2,
EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj -
EVP digest routines
@@ -25,24 +26,23 @@ EVP digest routines
int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx);
void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx);
int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in);
int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in);
int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md,
unsigned int *s);
int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in);
int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in);
#define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */
#define EVP_MAX_MD_SIZE 64 /* SHA512 */
int EVP_MD_type(const EVP_MD *md);
int EVP_MD_pkey_type(const EVP_MD *md);
int EVP_MD_size(const EVP_MD *md);
int EVP_MD_block_size(const EVP_MD *md);
#define EVP_MD_type(e) ((e)->type)
#define EVP_MD_pkey_type(e) ((e)->pkey_type)
#define EVP_MD_size(e) ((e)->md_size)
#define EVP_MD_block_size(e) ((e)->block_size)
#define EVP_MD_CTX_md(e) (e)->digest)
#define EVP_MD_CTX_size(e) EVP_MD_size((e)->digest)
const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);
#define EVP_MD_CTX_size(e) EVP_MD_size(EVP_MD_CTX_md(e))
#define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest)
#define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest)
@@ -56,6 +56,11 @@ EVP digest routines
const EVP_MD *EVP_mdc2(void);
const EVP_MD *EVP_ripemd160(void);
const EVP_MD *EVP_sha224(void);
const EVP_MD *EVP_sha256(void);
const EVP_MD *EVP_sha384(void);
const EVP_MD *EVP_sha512(void);
const EVP_MD *EVP_get_digestbyname(const char *name);
#define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a))
#define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a))
@@ -124,15 +129,17 @@ B<EVP_MD_CTX>.
EVP_MD_pkey_type() returns the NID of the public key signing algorithm associated
with this digest. For example EVP_sha1() is associated with RSA so this will
return B<NID_sha1WithRSAEncryption>. This "link" between digests and signature
algorithms may not be retained in future versions of OpenSSL.
return B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms
are no longer linked this function is only retained for compatibility
reasons.
EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_mdc2() and EVP_ripemd160()
return B<EVP_MD> structures for the MD2, MD5, SHA, SHA1, MDC2 and RIPEMD160 digest
algorithms respectively. The associated signature algorithm is RSA in each case.
EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_sha224(), EVP_sha256(),
EVP_sha384(), EVP_sha512(), EVP_mdc2() and EVP_ripemd160() return B<EVP_MD>
structures for the MD2, MD5, SHA, SHA1, SHA224, SHA256, SHA384, SHA512, MDC2
and RIPEMD160 digest algorithms respectively.
EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest
algorithms but using DSS (DSA) for the signature algorithm. Note: there is
algorithms but using DSS (DSA) for the signature algorithm. Note: there is
no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are
however retained for compatibility.
@@ -154,9 +161,8 @@ EVP_MD_CTX_copy_ex() returns 1 if successful or 0 for failure.
EVP_MD_type(), EVP_MD_pkey_type() and EVP_MD_type() return the NID of the
corresponding OBJECT IDENTIFIER or NID_undef if none exists.
EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size(e), EVP_MD_size(),
EVP_MD_CTX_block_size() and EVP_MD_block_size() return the digest or block
size in bytes.
EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() and
EVP_MD_CTX_block_size() return the digest or block size in bytes.
EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(),
EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the
@@ -171,21 +177,34 @@ The B<EVP> interface to message digests should almost always be used in
preference to the low level interfaces. This is because the code then becomes
transparent to the digest used and much more flexible.
SHA1 is the digest of choice for new applications. The other digest algorithms
are still in common use.
New applications should use the SHA2 digest algorithms such as SHA256.
The other digest algorithms are still in common use.
For most applications the B<impl> parameter to EVP_DigestInit_ex() will be
set to NULL to use the default digest implementation.
The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are
The functions EVP_DigestInit(), EVP_DigestFinal() and EVP_MD_CTX_copy() are
obsolete but are retained to maintain compatibility with existing code. New
applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and
applications should use EVP_DigestInit_ex(), EVP_DigestFinal_ex() and
EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context
instead of initializing and cleaning it up on each call and allow non default
implementations of digests to be specified.
In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use
memory leaks will occur.
memory leaks will occur.
Stack allocation of EVP_MD_CTX structures is common, for example:
EVP_MD_CTX mctx;
EVP_MD_CTX_init(&mctx);
This will cause binary compatibility issues if the size of EVP_MD_CTX
structure changes (this will only happen with a major release of OpenSSL).
Applications wishing to avoid this should use EVP_MD_CTX_create() instead:
EVP_MD_CTX *mctx;
mctx = EVP_MD_CTX_create();
=head1 EXAMPLE
@@ -197,7 +216,7 @@ digest name passed on the command line.
main(int argc, char *argv[])
{
EVP_MD_CTX mdctx;
EVP_MD_CTX *mdctx;
const EVP_MD *md;
char mess1[] = "Test Message\n";
char mess2[] = "Hello World\n";
@@ -218,23 +237,27 @@ digest name passed on the command line.
exit(1);
}
EVP_MD_CTX_init(&mdctx);
EVP_DigestInit_ex(&mdctx, md, NULL);
EVP_DigestUpdate(&mdctx, mess1, strlen(mess1));
EVP_DigestUpdate(&mdctx, mess2, strlen(mess2));
EVP_DigestFinal_ex(&mdctx, md_value, &md_len);
EVP_MD_CTX_cleanup(&mdctx);
mdctx = EVP_MD_CTX_create();
EVP_DigestInit_ex(mdctx, md, NULL);
EVP_DigestUpdate(mdctx, mess1, strlen(mess1));
EVP_DigestUpdate(mdctx, mess2, strlen(mess2));
EVP_DigestFinal_ex(mdctx, md_value, &md_len);
EVP_MD_CTX_destroy(mdctx);
printf("Digest is: ");
for(i = 0; i < md_len; i++) printf("%02x", md_value[i]);
for(i = 0; i < md_len; i++)
printf("%02x", md_value[i]);
printf("\n");
/* Call this once before exit. */
EVP_cleanup();
exit(0);
}
=head1 SEE ALSO
L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>,
L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>,
L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)>
L<dgst(1)|dgst(1)>,
L<evp(3)|evp(3)>
=head1 HISTORY
@@ -247,10 +270,10 @@ and EVP_DigestFinal_ex() were added in OpenSSL 0.9.7.
EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(),
EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() were
changed to return truely const EVP_MD * in OpenSSL 0.9.7.
changed to return truly const EVP_MD * in OpenSSL 0.9.7.
The link between digests and signing algorithms was fixed in OpenSSL 1.0 and
later, so now EVP_sha1() can be used with RSA and DSA, there is no need to
later, so now EVP_sha1() can be used with RSA and DSA; there is no need to
use EVP_dss1() any more.
OpenSSL 1.0 and later does not include the MD2 digest algorithm in the

6
doc/crypto/EVP_DigestVerifyInit.pod
View File

@@ -11,7 +11,7 @@ EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP signat
int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx,
const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey);
int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t siglen);
int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, const unsigned char *sig, size_t siglen);
=head1 DESCRIPTION
@@ -38,7 +38,7 @@ or a negative value for failure. In particular a return value of -2 indicates
the operation is not supported by the public key algorithm.
Unlike other functions the return value 0 from EVP_DigestVerifyFinal() only
indicates that the signature did not not verify successfully (that is tbs did
indicates that the signature did not verify successfully (that is tbs did
not match the original data or the signature was of invalid form) it is not an
indication of a more serious error.
@@ -59,7 +59,7 @@ For some key types and parameters the random number generator must be seeded
or the operation will fail.
The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest
context. This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can
context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can
be called later to digest and verify additional data.
Since only a copy of the digest context is ever finalized the context must

160
doc/crypto/EVP_EncryptInit.pod
View File

@@ -16,7 +16,17 @@ EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length,
EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data,
EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags,
EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param,
EVP_CIPHER_CTX_set_padding - EVP cipher routines
EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_des_cbc, EVP_des_ecb,
EVP_des_cfb, EVP_des_ofb, EVP_des_ede_cbc, EVP_des_ede, EVP_des_ede_ofb,
EVP_des_ede_cfb, EVP_des_ede3_cbc, EVP_des_ede3, EVP_des_ede3_ofb,
EVP_des_ede3_cfb, EVP_desx_cbc, EVP_rc4, EVP_rc4_40, EVP_idea_cbc,
EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_idea_cbc, EVP_rc2_cbc,
EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc,
EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc,
EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, EVP_rc5_32_12_16_cbc,
EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb,
EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ccm,
EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines
=head1 SYNOPSIS
@@ -115,7 +125,7 @@ writes the encrypted version to B<out>. This function can be called
multiple times to encrypt successive blocks of data. The amount
of data written depends on the block alignment of the encrypted data:
as a result the amount of data written may be anything from zero bytes
to (inl + cipher_block_size - 1) so B<outl> should contain sufficient
to (inl + cipher_block_size - 1) so B<out> should contain sufficient
room. The actual number of bytes written is placed in B<outl>.
If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts
@@ -152,7 +162,7 @@ does not remain in memory.
EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a
similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex and
EVP_CipherInit_ex() except the B<ctx> paramter does not need to be
EVP_CipherInit_ex() except the B<ctx> parameter does not need to be
initialized and they always use the default cipher implementation.
EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() behave in a
@@ -231,8 +241,7 @@ or the parameters cannot be set (for example the RC2 effective key length
is not supported.
EVP_CIPHER_CTX_ctrl() allows various cipher specific parameters to be determined
and set. Currently only the RC2 effective key length and the number of rounds of
RC5 can be set.
and set.
=head1 RETURN VALUES
@@ -338,13 +347,96 @@ RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a
cipher with an additional "number of rounds" parameter. By default the key length is set to 128
bits and 12 rounds.
=item EVP_aes_128_gcm(void), EVP_aes_192_gcm(void), EVP_aes_256_gcm(void)
AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively.
These ciphers require additional control operations to function correctly: see
L<GCM mode> section below for details.
=item EVP_aes_128_ccm(void), EVP_aes_192_ccm(void), EVP_aes_256_ccm(void)
AES Counter with CBC-MAC Mode (CCM) for 128, 192 and 256 bit keys respectively.
These ciphers require additional control operations to function correctly: see
CCM mode section below for details.
=back
=head1 GCM Mode
For GCM mode ciphers the behaviour of the EVP interface is subtly altered and
several GCM specific ctrl operations are supported.
To specify any additional authenticated data (AAD) a call to EVP_CipherUpdate(),
EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output
parameter B<out> set to B<NULL>.
When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal()
indicates if the operation was successful. If it does not indicate success
the authentication operation has failed and any output data B<MUST NOT>
be used as it is corrupted.
The following ctrls are supported in GCM mode:
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, ivlen, NULL);
Sets the GCM IV length: this call can only be made before specifying an IV. If
not called a default IV length is used (96 bits for AES).
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, taglen, tag);
Writes B<taglen> bytes of the tag value to the buffer indicated by B<tag>.
This call can only be made when encrypting data and B<after> all data has been
processed (e.g. after an EVP_EncryptFinal() call).
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, taglen, tag);
Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal
when decrypting data and must be made B<before> any data is processed (e.g.
before any EVP_DecryptUpdate() call).
See L<EXAMPLES> below for an example of the use of GCM mode.
=head1 CCM Mode
The behaviour of CCM mode ciphers is similar to CCM mode but with a few
additional requirements and different ctrl values.
Like GCM mode any additional authenticated data (AAD) is passed by calling
EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output
parameter B<out> set to B<NULL>. Additionally the total plaintext or ciphertext
length B<MUST> be passed to EVP_CipherUpdate(), EVP_EncryptUpdate() or
EVP_DecryptUpdate() with the output and input parameters (B<in> and B<out>)
set to B<NULL> and the length passed in the B<inl> parameter.
The following ctrls are supported in CCM mode:
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, taglen, tag);
This call is made to set the expected B<CCM> tag value when decrypting or
the length of the tag (with the B<tag> parameter set to NULL) when encrypting.
The tag length is often referred to as B<M>. If not set a default value is
used (12 for AES).
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL);
Sets the CCM B<L> value. If not set a default is used (8 for AES).
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, ivlen, NULL);
Sets the CCM nonce (IV) length: this call can only be made before specifying
an nonce value. The nonce length is given by B<15 - L> so it is 7 by default
for AES.
=head1 NOTES
Where possible the B<EVP> interface to symmetric ciphers should be used in
preference to the low level interfaces. This is because the code then becomes
transparent to the cipher used and much more flexible.
transparent to the cipher used and much more flexible. Additionally, the
B<EVP> interface will ensure the use of platform specific cryptographic
acceleration such as AES-NI (the low level interfaces do not provide the
guarantee).
PKCS padding works by adding B<n> padding bytes of value B<n> to make the total
length of the encrypted data a multiple of the block size. Padding is always
@@ -384,27 +476,7 @@ for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode.
=head1 EXAMPLES
Get the number of rounds used in RC5:
int nrounds;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC5_ROUNDS, 0, &nrounds);
Get the RC2 effective key length:
int key_bits;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_RC2_KEY_BITS, 0, &key_bits);
Set the number of rounds used in RC5:
int nrounds;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC5_ROUNDS, nrounds, NULL);
Set the effective key length used in RC2:
int key_bits;
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_RC2_KEY_BITS, key_bits, NULL);
Encrypt a string using blowfish:
Encrypt a string using IDEA:
int do_crypt(char *outfile)
{
@@ -418,8 +490,9 @@ Encrypt a string using blowfish:
char intext[] = "Some Crypto Text";
EVP_CIPHER_CTX ctx;
FILE *out;
EVP_CIPHER_CTX_init(&ctx);
EVP_EncryptInit_ex(&ctx, EVP_bf_cbc(), NULL, key, iv);
EVP_EncryptInit_ex(&ctx, EVP_idea_cbc(), NULL, key, iv);
if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext)))
{
@@ -448,28 +521,34 @@ Encrypt a string using blowfish:
}
The ciphertext from the above example can be decrypted using the B<openssl>
utility with the command line:
utility with the command line (shown on two lines for clarity):
S<openssl bf -in cipher.bin -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 -d>
openssl idea -d <filename
-K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708
General encryption, decryption function example using FILE I/O and RC2 with an
80 bit key:
General encryption and decryption function example using FILE I/O and AES128
with a 128-bit key:
int do_crypt(FILE *in, FILE *out, int do_encrypt)
{
/* Allow enough space in output buffer for additional block */
inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
int inlen, outlen;
EVP_CIPHER_CTX ctx;
/* Bogus key and IV: we'd normally set these from
* another source.
*/
unsigned char key[] = "0123456789";
unsigned char iv[] = "12345678";
/* Don't set key or IV because we will modify the parameters */
unsigned char key[] = "0123456789abcdeF";
unsigned char iv[] = "1234567887654321";
/* Don't set key or IV right away; we want to check lengths */
EVP_CIPHER_CTX_init(&ctx);
EVP_CipherInit_ex(&ctx, EVP_rc2(), NULL, NULL, NULL, do_encrypt);
EVP_CIPHER_CTX_set_key_length(&ctx, 10);
/* We finished modifying parameters so now we can set key and IV */
EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
do_encrypt);
OPENSSL_assert(EVP_CIPHER_CTX_key_length(&ctx) == 16);
OPENSSL_assert(EVP_CIPHER_CTX_iv_length(&ctx) == 16);
/* Now we can set key and IV */
EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
for(;;)
@@ -508,4 +587,7 @@ EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(),
EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in
OpenSSL 0.9.7.
IDEA appeared in OpenSSL 0.9.7 but was often disabled due to
patent concerns; the last patents expired in 2012.
=cut

12
doc/crypto/EVP_PKEY_CTX_ctrl.pod
View File

@@ -2,7 +2,13 @@
=head1 NAME
EVP_PKEY_ctrl, EVP_PKEY_ctrl_str - algorithm specific control operations
EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_get_default_digest_nid,
EVP_PKEY_CTX_set_signature_md, EVP_PKEY_CTX_set_rsa_padding,
EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_rsa_keygen_bits,
EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_dsa_paramgen_bits,
EVP_PKEY_CTX_set_dh_paramgen_prime_len,
EVP_PKEY_CTX_set_dh_paramgen_generator,
EVP_PKEY_CTX_set_ec_paramgen_curve_nid - algorithm specific control operations
=head1 SYNOPSIS
@@ -45,7 +51,7 @@ B<p1> and B<p2>.
Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will
instead call one of the algorithm specific macros below.
The function EVP_PKEY_ctrl_str() allows an application to send an algorithm
The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm
specific control operation to a context B<ctx> in string form. This is
intended to be used for options specified on the command line or in text
files. The commands supported are documented in the openssl utility
@@ -117,7 +123,7 @@ L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>

4
doc/crypto/EVP_PKEY_cmp.pod
View File

@@ -23,10 +23,10 @@ doesn't use parameters.
The function EVP_PKEY_copy_parameters() copies the parameters from key
B<from> to key B<to>.
The funcion EVP_PKEY_cmp_parameters() compares the parameters of keys
The function EVP_PKEY_cmp_parameters() compares the parameters of keys
B<a> and B<b>.
The funcion EVP_PKEY_cmp() compares the public key components and paramters
The function EVP_PKEY_cmp() compares the public key components and paramters
(if present) of keys B<a> and B<b>.
=head1 NOTES

2
doc/crypto/EVP_PKEY_decrypt.pod
View File

@@ -83,7 +83,7 @@ L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
=head1 HISTORY

2
doc/crypto/EVP_PKEY_derive.pod
View File

@@ -84,7 +84,7 @@ L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
=head1 HISTORY

14
doc/crypto/EVP_PKEY_encrypt.pod
View File

@@ -43,19 +43,23 @@ indicates the operation is not supported by the public key algorithm.
=head1 EXAMPLE
Encrypt data using OAEP (for RSA keys):
Encrypt data using OAEP (for RSA keys). See also L<PEM_read_PUBKEY(3)|pem(3)> or
L<d2i_X509(3)|d2i_X509(3)> for means to load a public key. You may also simply
set 'eng = NULL;' to start with the default OpenSSL RSA implementation:
#include <openssl/evp.h>
#include <openssl/rsa.h>
#include <openssl/engine.h>
EVP_PKEY_CTX *ctx;
ENGINE *eng;
unsigned char *out, *in;
size_t outlen, inlen;
EVP_PKEY *key;
/* NB: assumes key in, inlen are already set up
/* NB: assumes eng, key, in, inlen are already set up,
* and that key is an RSA public key
*/
ctx = EVP_PKEY_CTX_new(key);
ctx = EVP_PKEY_CTX_new(key,eng);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_encrypt_init(ctx) <= 0)
@@ -79,11 +83,13 @@ Encrypt data using OAEP (for RSA keys):
=head1 SEE ALSO
L<d2i_X509(3)|d2i_X509(3)>,
L<engine(3)|engine(3)>,
L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
=head1 HISTORY

2
doc/crypto/EVP_PKEY_get_default_digest.pod
View File

@@ -32,7 +32,7 @@ public key algorithm.
L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
=head1 HISTORY

2
doc/crypto/EVP_PKEY_keygen.pod
View File

@@ -151,7 +151,7 @@ L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
=head1 HISTORY

8
doc/crypto/EVP_PKEY_set1_RSA.pod
View File

@@ -37,7 +37,7 @@ EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or
B<NULL> if the key is not of the correct type.
EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key>
however these use the supplied B<key> internally and so B<key>
will be freed when the parent B<pkey> is freed.
@@ -54,8 +54,8 @@ In accordance with the OpenSSL naming convention the key obtained
from or assigned to the B<pkey> using the B<1> functions must be
freed as well as B<pkey>.
EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
EVP_PKEY_assign_EC_KEY() are implemented as macros.
EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
and EVP_PKEY_assign_EC_KEY() are implemented as macros.
=head1 RETURN VALUES
@@ -66,7 +66,7 @@ EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if
an error occurred.
EVP_PKEY_assign_RSA() EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure.
=head1 SEE ALSO

22
doc/crypto/EVP_PKEY_sign.pod
View File

@@ -28,9 +28,14 @@ B<sig> and the amount of data written to B<siglen>.
=head1 NOTES
EVP_PKEY_sign() does not hash the data to be signed, and therefore is
normally used to sign digests. For signing arbitrary messages, see the
L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)> and
L<EVP_SignInit(3)|EVP_SignInit(3)> signing interfaces instead.
After the call to EVP_PKEY_sign_init() algorithm specific control
operations can be performed to set any appropriate parameters for the
operation.
operation (see L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>).
The function EVP_PKEY_sign() can be called more than once on the same
context if several operations are performed using the same parameters.
@@ -49,13 +54,17 @@ Sign data using RSA with PKCS#1 padding and SHA256 digest:
#include <openssl/rsa.h>
EVP_PKEY_CTX *ctx;
/* md is a SHA-256 digest in this example. */
unsigned char *md, *sig;
size_t mdlen, siglen;
size_t mdlen = 32, siglen;
EVP_PKEY *signing_key;
/* NB: assumes signing_key, md and mdlen are already set up
* and that signing_key is an RSA private key
/*
* NB: assumes signing_key and md are set up before the next
* step. signing_key must be an RSA private key and md must
* point to the SHA-256 digest to be signed.
*/
ctx = EVP_PKEY_CTX_new(signing_key);
ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_sign_init(ctx) <= 0)
@@ -83,10 +92,11 @@ Sign data using RSA with PKCS#1 padding and SHA256 digest:
=head1 SEE ALSO
L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>,
L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
=head1 HISTORY

2
doc/crypto/EVP_PKEY_verify.pod
View File

@@ -81,7 +81,7 @@ L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verifyrecover(3)|EVP_PKEY_verifyrecover(3)>,
L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
=head1 HISTORY

103
doc/crypto/EVP_PKEY_verify_recover.pod Normal file
View File

@@ -0,0 +1,103 @@
=pod
=head1 NAME
EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using a public key algorithm
=head1 SYNOPSIS
#include <openssl/evp.h>
int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx);
int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx,
unsigned char *rout, size_t *routlen,
const unsigned char *sig, size_t siglen);
=head1 DESCRIPTION
The EVP_PKEY_verify_recover_init() function initializes a public key algorithm
context using key B<pkey> for a verify recover operation.
The EVP_PKEY_verify_recover() function recovers signed data
using B<ctx>. The signature is specified using the B<sig> and
B<siglen> parameters. If B<rout> is B<NULL> then the maximum size of the output
buffer is written to the B<routlen> parameter. If B<rout> is not B<NULL> then
before the call the B<routlen> parameter should contain the length of the
B<rout> buffer, if the call is successful recovered data is written to
B<rout> and the amount of data written to B<routlen>.
=head1 NOTES
Normally an application is only interested in whether a signature verification
operation is successful in those cases the EVP_verify() function should be
used.
Sometimes however it is useful to obtain the data originally signed using a
signing operation. Only certain public key algorithms can recover a signature
in this way (for example RSA in PKCS padding mode).
After the call to EVP_PKEY_verify_recover_init() algorithm specific control
operations can be performed to set any appropriate parameters for the
operation.
The function EVP_PKEY_verify_recover() can be called more than once on the same
context if several operations are performed using the same parameters.
=head1 RETURN VALUES
EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() return 1 for success
and 0 or a negative value for failure. In particular a return value of -2
indicates the operation is not supported by the public key algorithm.
=head1 EXAMPLE
Recover digest originally signed using PKCS#1 and SHA256 digest:
#include <openssl/evp.h>
#include <openssl/rsa.h>
EVP_PKEY_CTX *ctx;
unsigned char *rout, *sig;
size_t routlen, siglen;
EVP_PKEY *verify_key;
/* NB: assumes verify_key, sig and siglen are already set up
* and that verify_key is an RSA public key
*/
ctx = EVP_PKEY_CTX_new(verify_key);
if (!ctx)
/* Error occurred */
if (EVP_PKEY_verify_recover_init(ctx) <= 0)
/* Error */
if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0)
/* Error */
if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0)
/* Error */
/* Determine buffer length */
if (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0)
/* Error */
rout = OPENSSL_malloc(routlen);
if (!rout)
/* malloc failure */
if (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0)
/* Error */
/* Recovered data is routlen bytes written to buffer rout */
=head1 SEE ALSO
L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>,
L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>,
L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>,
L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>
=head1 HISTORY
These functions were first added to OpenSSL 1.0.0.
=cut

8
doc/crypto/EVP_SignInit.pod
View File

@@ -30,9 +30,11 @@ signature context B<ctx>. This function can be called several times on the
same B<ctx> to include additional data.
EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and
places the signature in B<sig>. The number of bytes of data written (i.e. the
length of the signature) will be written to the integer at B<s>, at most
EVP_PKEY_size(pkey) bytes will be written.
places the signature in B<sig>. B<sig> must be at least EVP_PKEY_size(pkey)
bytes in size. B<s> is an OUT paramter, and not used as an IN parameter.
The number of bytes of data written (i.e. the length of the signature)
will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes
will be written.
EVP_SignInit() initializes a signing context B<ctx> to use the default
implementation of digest B<type>.

2
doc/crypto/OPENSSL_VERSION_NUMBER.pod
View File

@@ -17,7 +17,7 @@ OPENSSL_VERSION_NUMBER, SSLeay, SSLeay_version - get OpenSSL version number
OPENSSL_VERSION_NUMBER is a numeric release version identifier:
MMNNFFPPS: major minor fix patch status
MNNFFPPS: major minor fix patch status
The status nibble has one of the values 0 for development, 1 to e for betas
1 to 14, and f for release.

44
doc/crypto/OPENSSL_config.pod
View File

@@ -15,31 +15,24 @@ OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions
OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf>
configuration file name using B<config_name>. If B<config_name> is NULL then
the default name B<openssl_conf> will be used. Any errors are ignored. Further
calls to OPENSSL_config() will have no effect. The configuration file format
is documented in the L<conf(5)|conf(5)> manual page.
the file specified in the environment variable B<OPENSSL_CONF> will be used,
and if that is not set then a system default location is used.
Errors are silently ignored.
Multiple calls have no effect.
OPENSSL_no_config() disables configuration. If called before OPENSSL_config()
no configuration takes place.
=head1 NOTES
It is B<strongly> recommended that B<all> new applications call OPENSSL_config()
or the more sophisticated functions such as CONF_modules_load() during
initialization (that is before starting any threads). By doing this
an application does not need to keep track of all configuration options
and some new functionality can be supported automatically.
It is also possible to automatically call OPENSSL_config() when an application
calls OPENSSL_add_all_algorithms() by compiling an application with the
preprocessor symbol B<OPENSSL_LOAD_CONF> #define'd. In this way configuration
can be added without source changes.
The environment variable B<OPENSSL_CONF> can be set to specify the location
of the configuration file.
Currently ASN1 OBJECTs and ENGINE configuration can be performed future
versions of OpenSSL will add new configuration options.
The OPENSSL_config() function is designed to be a very simple "call it and
forget it" function.
It is however B<much> better than nothing. Applications which need finer
control over their configuration functionality should use the configuration
functions such as CONF_modules_load() directly. This function is deprecated
and its use should be avoided.
Applications should instead call CONF_modules_load() during
initialization (that is before starting any threads).
There are several reasons why calling the OpenSSL configuration routines is
advisable. For example new ENGINE functionality was added to OpenSSL 0.9.7.
@@ -55,17 +48,6 @@ configuration file.
Applications should free up configuration at application closedown by calling
CONF_modules_free().
=head1 RESTRICTIONS
The OPENSSL_config() function is designed to be a very simple "call it and
forget it" function. As a result its behaviour is somewhat limited. It ignores
all errors silently and it can only load from the standard configuration file
location for example.
It is however B<much> better than nothing. Applications which need finer
control over their configuration functionality should use the configuration
functions such as CONF_load_modules() directly.
=head1 RETURN VALUES
Neither OPENSSL_config() nor OPENSSL_no_config() return a value.
@@ -73,7 +55,7 @@ Neither OPENSSL_config() nor OPENSSL_no_config() return a value.
=head1 SEE ALSO
L<conf(5)|conf(5)>, L<CONF_load_modules_file(3)|CONF_load_modules_file(3)>,
L<CONF_modules_free(3),CONF_modules_free(3)>
L<CONF_modules_free(3)|CONF_modules_free(3)>
=head1 HISTORY

109
doc/crypto/OPENSSL_ia32cap.pod
View File

@@ -2,42 +2,95 @@
=head1 NAME
OPENSSL_ia32cap - finding the IA-32 processor capabilities
OPENSSL_ia32cap, OPENSSL_ia32cap_loc - the IA-32 processor capabilities vector
=head1 SYNOPSIS
unsigned long *OPENSSL_ia32cap_loc(void);
#define OPENSSL_ia32cap (*(OPENSSL_ia32cap_loc()))
unsigned int *OPENSSL_ia32cap_loc(void);
#define OPENSSL_ia32cap ((OPENSSL_ia32cap_loc())[0])
=head1 DESCRIPTION
Value returned by OPENSSL_ia32cap_loc() is address of a variable
containing IA-32 processor capabilities bit vector as it appears in EDX
register after executing CPUID instruction with EAX=1 input value (see
Intel Application Note #241618). Naturally it's meaningful on IA-32[E]
platforms only. The variable is normally set up automatically upon
toolkit initialization, but can be manipulated afterwards to modify
crypto library behaviour. For the moment of this writing six bits are
significant, namely:
containing IA-32 processor capabilities bit vector as it appears in
EDX:ECX register pair after executing CPUID instruction with EAX=1
input value (see Intel Application Note #241618). Naturally it's
meaningful on x86 and x86_64 platforms only. The variable is normally
set up automatically upon toolkit initialization, but can be
manipulated afterwards to modify crypto library behaviour. For the
moment of this writing following bits are significant:
1. bit #28 denoting Hyperthreading, which is used to distiguish
cores with shared cache;
2. bit #26 denoting SSE2 support;
3. bit #25 denoting SSE support;
4. bit #23 denoting MMX support;
5. bit #20, reserved by Intel, is used to choose between RC4 code
pathes;
6. bit #4 denoting presence of Time-Stamp Counter.
=over
=item bit #4 denoting presence of Time-Stamp Counter.
=item bit #19 denoting availability of CLFLUSH instruction;
=item bit #20, reserved by Intel, is used to choose among RC4 code paths;
=item bit #23 denoting MMX support;
=item bit #24, FXSR bit, denoting availability of XMM registers;
=item bit #25 denoting SSE support;
=item bit #26 denoting SSE2 support;
=item bit #28 denoting Hyperthreading, which is used to distinguish
cores with shared cache;
=item bit #30, reserved by Intel, denotes specifically Intel CPUs;
=item bit #33 denoting availability of PCLMULQDQ instruction;
=item bit #41 denoting SSSE3, Supplemental SSE3, support;
=item bit #43 denoting AMD XOP support (forced to zero on non-AMD CPUs);
=item bit #57 denoting AES-NI instruction set extension;
=item bit #59, OSXSAVE bit, denoting availability of YMM registers;
=item bit #60 denoting AVX extension;
=item bit #62 denoting availability of RDRAND instruction;
=back
For example, clearing bit #26 at run-time disables high-performance
SSE2 code present in the crypto library. You might have to do this if
target OpenSSL application is executed on SSE2 capable CPU, but under
control of OS which does not support SSE2 extentions. Even though you
can manipulate the value programmatically, you most likely will find it
more appropriate to set up an environment variable with the same name
prior starting target application, e.g. on Intel P4 processor 'env
OPENSSL_ia32cap=0x12900010 apps/openssl', to achieve same effect
without modifying the application source code. Alternatively you can
reconfigure the toolkit with no-sse2 option and recompile.
SSE2 code present in the crypto library, while clearing bit #24
disables SSE2 code operating on 128-bit XMM register bank. You might
have to do the latter if target OpenSSL application is executed on SSE2
capable CPU, but under control of OS that does not enable XMM
registers. Even though you can manipulate the value programmatically,
you most likely will find it more appropriate to set up an environment
variable with the same name prior starting target application, e.g. on
Intel P4 processor 'env OPENSSL_ia32cap=0x16980010 apps/openssl', or
better yet 'env OPENSSL_ia32cap=~0x1000000 apps/openssl' to achieve same
effect without modifying the application source code. Alternatively you
can reconfigure the toolkit with no-sse2 option and recompile.
=cut
Less intuitive is clearing bit #28. The truth is that it's not copied
from CPUID output verbatim, but is adjusted to reflect whether or not
the data cache is actually shared between logical cores. This in turn
affects the decision on whether or not expensive countermeasures
against cache-timing attacks are applied, most notably in AES assembler
module.
The vector is further extended with EBX value returned by CPUID with
EAX=7 and ECX=0 as input. Following bits are significant:
=over
=item bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN;
=item bit #64+5 denoting availability of AVX2 instructions;
=item bit #64+8 denoting availability of BMI2 instructions, e.g. MUXL
and RORX;
=item bit #64+18 denoting availability of RDSEED instruction;
=item bit #64+19 denoting availability of ADCX and ADOX instructions;
=back

42
doc/crypto/OPENSSL_instrument_bus.pod Normal file
View File

@@ -0,0 +1,42 @@
=pod
=head1 NAME
OPENSSL_instrument_bus, OPENSSL_instrument_bus2 - instrument references to memory bus
=head1 SYNOPSIS
#ifdef OPENSSL_CPUID_OBJ
size_t OPENSSL_instrument_bus (int *vector,size_t num);
size_t OPENSSL_instrument_bus2(int *vector,size_t num,size_t max);
#endif
=head1 DESCRIPTION
It was empirically found that timings of references to primary memory
are subject to irregular, apparently non-deterministic variations. The
subroutines in question instrument these references for purposes of
gathering entropy for random number generator. In order to make it
bus-bound a 'flush cache line' instruction is used between probes. In
addition probes are added to B<vector> elements in atomic or
interlocked manner, which should contribute additional noise on
multi-processor systems. This also means that B<vector[num]> should be
zeroed upon invocation (if you want to retrieve actual probe values).
OPENSSL_instrument_bus performs B<num> probes and records the number of
oscillator cycles every probe took.
OPENSSL_instrument_bus2 on the other hand B<accumulates> consecutive
probes with the same value, i.e. in a way it records duration of
periods when probe values appeared deterministic. The subroutine
performs at most B<max> probes in attempt to fill the B<vector[num]>,
with B<max> value of 0 meaning "as many as it takes."
=head1 RETURN VALUE
Return value of 0 indicates that CPU is not capable of performing the
benchmark, either because oscillator counter or 'flush cache line' is
not available on current platform. For reference, on x86 'flush cache
line' was introduced with the SSE2 extensions.
Otherwise number of recorded values is returned.

2
doc/crypto/OPENSSL_load_builtin_modules.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
OPENSSL_load_builtin_modules - add standard configuration modules
OPENSSL_load_builtin_modules, ASN1_add_oid_module, ENGINE_add_conf_module - add standard configuration modules
=head1 SYNOPSIS

2
doc/crypto/OpenSSL_add_all_algorithms.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests -
OpenSSL_add_all_algorithms, OpenSSL_add_all_ciphers, OpenSSL_add_all_digests, EVP_cleanup -
add algorithms to internal table
=head1 SYNOPSIS

6
doc/crypto/PKCS7_verify.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
PKCS7_verify - verify a PKCS#7 signedData structure
PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure
=head1 SYNOPSIS
@@ -91,8 +91,8 @@ timestamp).
=head1 RETURN VALUES
PKCS7_verify() returns 1 for a successful verification and zero or a negative
value if an error occurs.
PKCS7_verify() returns one for a successful verification and zero
if an error occurs.
PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred.

2
doc/crypto/RAND_egd.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
RAND_egd - query entropy gathering daemon
RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes - query entropy gathering daemon
=head1 SYNOPSIS

39
doc/crypto/RSA_generate_key.pod
View File

@@ -2,28 +2,33 @@
=head1 NAME
RSA_generate_key - generate RSA key pair
RSA_generate_key_ex, RSA_generate_key - generate RSA key pair
=head1 SYNOPSIS
#include <openssl/rsa.h>
int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
Deprecated:
RSA *RSA_generate_key(int num, unsigned long e,
void (*callback)(int,int,void *), void *cb_arg);
=head1 DESCRIPTION
RSA_generate_key() generates a key pair and returns it in a newly
allocated B<RSA> structure. The pseudo-random number generator must
be seeded prior to calling RSA_generate_key().
RSA_generate_key_ex() generates a key pair and stores it in the B<RSA>
structure provided in B<rsa>. The pseudo-random number generator must
be seeded prior to calling RSA_generate_key_ex().
The modulus size will be B<num> bits, and the public exponent will be
The modulus size will be of length B<bits>, and the public exponent will be
B<e>. Key sizes with B<num> E<lt> 1024 should be considered insecure.
The exponent is an odd number, typically 3, 17 or 65537.
A callback function may be used to provide feedback about the
progress of the key generation. If B<callback> is not B<NULL>, it
will be called as follows:
progress of the key generation. If B<cb> is not B<NULL>, it
will be called as follows using the BN_GENCB_call() function
described on the L<BN_generate_prime(3)|BN_generate_prime(3)> page.
=over 4
@@ -35,32 +40,38 @@ described in L<BN_generate_prime(3)|BN_generate_prime(3)>.
=item *
When the n-th randomly generated prime is rejected as not
suitable for the key, B<callback(2, n, cb_arg)> is called.
suitable for the key, B<BN_GENCB_call(cb, 2, n)> is called.
=item *
When a random p has been found with p-1 relatively prime to B<e>,
it is called as B<callback(3, 0, cb_arg)>.
it is called as B<BN_GENCB_call(cb, 3, 0)>.
=back
The process is then repeated for prime q with B<callback(3, 1, cb_arg)>.
The process is then repeated for prime q with B<BN_GENCB_call(cb, 3, 1)>.
RSA_generate_key is deprecated (new applications should use
RSA_generate_key_ex instead). RSA_generate_key works in the same was as
RSA_generate_key_ex except it uses "old style" call backs. See
L<BN_generate_prime(3)|BN_generate_prime(3)> for further details.
=head1 RETURN VALUE
If key generation fails, RSA_generate_key() returns B<NULL>; the
error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
If key generation fails, RSA_generate_key() returns B<NULL>.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
=head1 BUGS
B<callback(2, x, cb_arg)> is used with two different meanings.
B<BN_GENCB_call(cb, 2, x)> is used with two different meanings.
RSA_generate_key() goes into an infinite loop for illegal input values.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>,
L<RSA_free(3)|RSA_free(3)>
L<RSA_free(3)|RSA_free(3)>, L<BN_generate_prime(3)|BN_generate_prime(3)>
=head1 HISTORY

14
doc/crypto/RSA_set_method.pod
View File

@@ -125,14 +125,18 @@ the default method is used.
/* sign. For backward compatibility, this is used only
* if (flags & RSA_FLAG_SIGN_VER)
*/
int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len,
unsigned char *sigret, unsigned int *siglen, RSA *rsa);
int (*rsa_sign)(int type,
const unsigned char *m, unsigned int m_length,
unsigned char *sigret, unsigned int *siglen, const RSA *rsa);
/* verify. For backward compatibility, this is used only
* if (flags & RSA_FLAG_SIGN_VER)
*/
int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len,
unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
int (*rsa_verify)(int dtype,
const unsigned char *m, unsigned int m_length,
const unsigned char *sigbuf, unsigned int siglen,
const RSA *rsa);
/* keygen. If NULL builtin RSA key generation will be used */
int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
} RSA_METHOD;

4
doc/crypto/RSA_sign.pod
View File

@@ -20,6 +20,10 @@ RSA_sign() signs the message digest B<m> of size B<m_len> using the
private key B<rsa> as specified in PKCS #1 v2.0. It stores the
signature in B<sigret> and the signature size in B<siglen>. B<sigret>
must point to RSA_size(B<rsa>) bytes of memory.
Note that PKCS #1 adds meta-data, placing limits on the size of the
key that can be used.
See L<RSA_private_encrypt(3)|RSA_private_encrypt(3)> for lower-level
operations.
B<type> denotes the message digest algorithm that was used to generate
B<m>. It usually is one of B<NID_sha1>, B<NID_ripemd160> and B<NID_md5>;

74
doc/crypto/SSLeay_version.pod Normal file
View File

@@ -0,0 +1,74 @@
=pod
=head1 NAME
SSLeay_version - retrieve version/build information about OpenSSL library
=head1 SYNOPSIS
#include <openssl/crypto.h>
const char *SSLeay_version(int type);
=head1 DESCRIPTION
SSLeay_version() returns a pointer to a constant string describing the
version of the OpenSSL library or giving information about the library
build.
The following B<type> values are supported:
=over 4
=item SSLEAY_VERSION
The version of the OpenSSL library including the release date.
=item SSLEAY_CFLAGS
The compiler flags set for the compilation process in the form
"compiler: ..." if available or "compiler: information not available"
otherwise.
=item SSLEAY_BUILT_ON
The date of the build process in the form "built on: ..." if available
or "built on: date not available" otherwise.
=item SSLEAY_PLATFORM
The "Configure" target of the library build in the form "platform: ..."
if available or "platform: information not available" otherwise.
=item SSLEAY_DIR
The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "...""
if available or "OPENSSLDIR: N/A" otherwise.
=back
=head1 RETURN VALUES
The following return values can occur:
=over 4
=item "not available"
An invalid value for B<type> was given.
=item Pointer to constant string
Textual description.
=back
=head1 SEE ALSO
L<crypto(3)|crypto(3)>
=head1 HISTORY
B<SSLEAY_DIR> was added in OpenSSL 0.9.7.
=cut

2
doc/crypto/X509_NAME_ENTRY_get_object.pod
View File

@@ -65,7 +65,7 @@ set first so the relevant field information can be looked up internally.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>,
L<OBJ_nid2obj(3),OBJ_nid2obj(3)>
L<OBJ_nid2obj(3)|OBJ_nid2obj(3)>
=head1 HISTORY

14
doc/crypto/X509_NAME_add_entry_by_txt.pod
View File

@@ -44,7 +44,7 @@ B<loc>. The deleted entry is returned and must be freed up.
=head1 NOTES
The use of string types such as B<MBSTRING_ASC> or B<MBSTRING_UTF8>
is strongly recommened for the B<type> parameter. This allows the
is strongly recommended for the B<type> parameter. This allows the
internal code to correctly determine the type of the field and to
apply length checks according to the relevant standards. This is
done using ASN1_STRING_set_by_NID().
@@ -81,14 +81,14 @@ Create an B<X509_NAME> structure:
nm = X509_NAME_new();
if (nm == NULL)
/* Some error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"C", "UK", -1, -1, 0))
if (!X509_NAME_add_entry_by_txt(nm, "C", MBSTRING_ASC,
"UK", -1, -1, 0))
/* Error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"O", "Disorganized Organization", -1, -1, 0))
if (!X509_NAME_add_entry_by_txt(nm, "O", MBSTRING_ASC,
"Disorganized Organization", -1, -1, 0))
/* Error */
if (!X509_NAME_add_entry_by_txt(nm, MBSTRING_ASC,
"CN", "Joe Bloggs", -1, -1, 0))
if (!X509_NAME_add_entry_by_txt(nm, "CN", MBSTRING_ASC,
"Joe Bloggs", -1, -1, 0))
/* Error */
=head1 RETURN VALUES

11
doc/crypto/X509_NAME_get_index_by_NID.pod
View File

@@ -29,6 +29,7 @@ and issuer names.
X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve
the next index matching B<nid> or B<obj> after B<lastpos>. B<lastpos>
should initially be set to -1. If there are no more entries -1 is returned.
If B<nid> is invalid (doesn't correspond to a valid OID) then -2 is returned.
X509_NAME_entry_count() returns the total number of entries in B<name>.
@@ -59,6 +60,14 @@ X509_NAME_get_index_by_OBJ() should be used followed by
X509_NAME_get_entry() on any matching indices and then the
various B<X509_NAME_ENTRY> utility functions on the result.
The list of all relevant B<NID_*> and B<OBJ_* codes> can be found in
the source code header files E<lt>openssl/obj_mac.hE<gt> and/or
E<lt>openssl/objects.hE<gt>.
Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID()
should check for the return value of -2. Alternatively the NID validity
can be determined first by checking OBJ_nid2obj(nid) is not NULL.
=head1 EXAMPLES
Process all entries:
@@ -91,6 +100,8 @@ Process all commonName entries:
X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ()
return the index of the next matching entry or -1 if not found.
X509_NAME_get_index_by_NID() can also return -2 if the supplied
NID is invalid.
X509_NAME_entry_count() returns the total number of entries.

10
doc/crypto/X509_STORE_CTX_get_error.pod
View File

@@ -32,7 +32,7 @@ checks.
X509_STORE_CTX_get_error_depth() returns the B<depth> of the error. This is a
non-negative integer representing where in the certificate chain the error
occurred. If it is zero it occured in the end entity certificate, one if
occurred. If it is zero it occurred in the end entity certificate, one if
it is the certificate which signed the end entity certificate and so on.
X509_STORE_CTX_get_current_cert() returns the certificate in B<ctx> which
@@ -246,11 +246,11 @@ Some feature of a certificate extension is not supported. Unused.
=item B<X509_V_ERR_PERMITTED_VIOLATION: permitted subtree violation>
A name constraint violation occured in the permitted subtrees.
A name constraint violation occurred in the permitted subtrees.
=item B<X509_V_ERR_EXCLUDED_VIOLATION: excluded subtree violation>
A name constraint violation occured in the excluded subtrees.
A name constraint violation occurred in the excluded subtrees.
=item B<X509_V_ERR_SUBTREE_MINMAX: name constraints minimum and maximum not supported>
@@ -270,7 +270,7 @@ a garbage extension or some new feature not currently supported.
=item B<X509_V_ERR_CRL_PATH_VALIDATION_ERROR: CRL path validation error>
An error occured when attempting to verify the CRL path. This error can only
An error occurred when attempting to verify the CRL path. This error can only
happen if extended CRL checking is enabled.
=item B<X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
@@ -278,6 +278,8 @@ happen if extended CRL checking is enabled.
an application specific error. This will never be returned unless explicitly
set by an application.
=back
=head1 NOTES
The above functions should be used instead of directly referencing the fields

Some files were not shown because too many files have changed in this diff Show More