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

Import OpenSSL 1.1.0f

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

209
doc/HOWTO/proxy_certificates.txt
View File

@@ -164,138 +164,151 @@ You need the following ingredients:
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. */
#include <string.h>
#include <netdb.h>
#include <openssl/x509.h>
#include <openssl/x509v3.h>
#define total_rights 25
/*
* In this example, I will use a view of granted rights as a bit
* array, one bit for each possible right.
*/
typedef struct your_rights {
unsigned char rights[total_rights / 8];
unsigned char rights[(total_rights + 7) / 8];
} YOUR_RIGHTS;
/* The following procedure will create an index for the ex_data
store in the X509 validation context the first time it's called.
Subsequent calls will return the same index. */
static int get_proxy_auth_ex_data_idx(void)
/*
* The following procedure will create an index for the ex_data
* store in the X509 validation context the first time it's called.
* Subsequent calls will return the same index. */
static int get_proxy_auth_ex_data_idx(X509_STORE_CTX *ctx)
{
static volatile int idx = -1;
if (idx < 0)
{
CRYPTO_w_lock(CRYPTO_LOCK_X509_STORE);
if (idx < 0)
{
idx = X509_STORE_CTX_get_ex_new_index(0,
"for verify callback",
NULL,NULL,NULL);
static volatile int idx = -1;
if (idx < 0) {
X509_STORE_lock(X509_STORE_CTX_get0_store(ctx));
if (idx < 0) {
idx = X509_STORE_CTX_get_ex_new_index(0,
"for verify callback",
NULL,NULL,NULL);
}
CRYPTO_w_unlock(CRYPTO_LOCK_X509_STORE);
X509_STORE_unlock(X509_STORE_CTX_get0_store(ctx));
}
return idx;
return idx;
}
/* Callback to be given to the X509 validation procedure. */
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 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
CAs, followed by the EE certificate, followed by
the possible proxy certificates. */
{
X509 *xs = ctx->current_cert;
if (ok == 1) {
/*
* It's REALLY important you keep the proxy policy
* 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
* CAs, followed by the EE certificate, followed by
* the possible proxy certificates.
*/
X509 *xs = X509_STORE_CTX_get_current_cert(ctx);
if (xs->ex_flags & EXFLAG_PROXY)
{
YOUR_RIGHTS *rights =
(YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
get_proxy_auth_ex_data_idx());
PROXY_CERT_INFO_EXTENSION *pci =
X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL);
if (X509_get_extension_flags(xs) & EXFLAG_PROXY) {
YOUR_RIGHTS *rights =
(YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
get_proxy_auth_ex_data_idx(ctx));
PROXY_CERT_INFO_EXTENSION *pci =
X509_get_ext_d2i(xs, NID_proxyCertInfo, NULL, NULL);
switch (OBJ_obj2nid(pci->proxyPolicy->policyLanguage))
{
switch (OBJ_obj2nid(pci->proxyPolicy->policyLanguage)) {
case NID_Independent:
/* Do whatever you need to grant explicit rights to
this particular proxy certificate, usually by
pulling them from some database. If there are none
to be found, clear all rights (making this and any
subsequent proxy certificate void of any rights).
*/
memset(rights->rights, 0, sizeof(rights->rights));
break;
/*
* Do whatever you need to grant explicit rights to
* this particular proxy certificate, usually by
* pulling them from some database. If there are none
* to be found, clear all rights (making this and any
* subsequent proxy certificate void of any rights).
*/
memset(rights->rights, 0, sizeof(rights->rights));
break;
case NID_id_ppl_inheritAll:
/* This is basically a NOP, we simply let the current
rights stand as they are. */
break;
/*
* This is basically a NOP, we simply let the current
* rights stand as they are.
*/
break;
default:
/* This is usually the most complex section of code.
You really do whatever you want as long as you
follow RFC 3820. In the example we use here, the
simplest thing to do is to build another, temporary
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
array. */
{
int i;
YOUR_RIGHTS tmp_rights;
memset(tmp_rights.rights, 0, sizeof(tmp_rights.rights));
/* This is usually the most complex section of code.
* You really do whatever you want as long as you
* follow RFC 3820. In the example we use here, the
* simplest thing to do is to build another, temporary
* 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
* array.
*/
{
int i;
YOUR_RIGHTS tmp_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
it and sets the bits in the YOUR_RIGHTS pointed
at by the third argument. */
process_rights((char *) pci->proxyPolicy->policy->data,
pci->proxyPolicy->policy->length,
&tmp_rights);
/*
* process_rights() is supposed to be a procedure
* that takes a string and it's length, interprets
* it and sets the bits in the YOUR_RIGHTS pointed
* at by the third argument.
*/
process_rights((char *) pci->proxyPolicy->policy->data,
pci->proxyPolicy->policy->length,
&tmp_rights);
for(i = 0; i < total_rights / 8; i++)
rights->rights[i] &= tmp_rights.rights[i];
}
break;
for(i = 0; i < total_rights / 8; i++)
rights->rights[i] &= tmp_rights.rights[i];
}
break;
}
PROXY_CERT_INFO_EXTENSION_free(pci);
}
else if (!(xs->ex_flags & EXFLAG_CA))
{
/* We have a EE certificate, let's use it to set default!
*/
YOUR_RIGHTS *rights =
(YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
get_proxy_auth_ex_data_idx());
PROXY_CERT_INFO_EXTENSION_free(pci);
} else if (!(X509_get_extension_flags(xs) & EXFLAG_CA)) {
/* We have an EE certificate, let's use it to set default! */
YOUR_RIGHTS *rights =
(YOUR_RIGHTS *)X509_STORE_CTX_get_ex_data(ctx,
get_proxy_auth_ex_data_idx(ctx));
/* The following procedure finds out what rights the owner
of the current certificate has, and sets them in the
YOUR_RIGHTS structure pointed at by the second
argument. */
set_default_rights(xs, rights);
/* The following procedure finds out what rights the owner
* of the current certificate has, and sets them in the
* YOUR_RIGHTS structure pointed at by the second
* argument.
*/
set_default_rights(xs, rights);
}
}
return ok;
return ok;
}
static int my_X509_verify_cert(X509_STORE_CTX *ctx,
YOUR_RIGHTS *needed_rights)
{
int i;
int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) = ctx->verify_cb;
YOUR_RIGHTS rights;
int ok;
int (*save_verify_cb)(int ok,X509_STORE_CTX *ctx) =
X509_STORE_CTX_get_verify_cb(ctx);
YOUR_RIGHTS rights;
X509_STORE_CTX_set_verify_cb(ctx, verify_callback);
X509_STORE_CTX_set_ex_data(ctx, get_proxy_auth_ex_data_idx(), &rights);
X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
ok = X509_verify_cert(ctx);
X509_STORE_CTX_set_verify_cb(ctx, verify_callback);
X509_STORE_CTX_set_ex_data(ctx, get_proxy_auth_ex_data_idx(ctx), &rights);
X509_STORE_CTX_set_flags(ctx, X509_V_FLAG_ALLOW_PROXY_CERTS);
ok = X509_verify_cert(ctx);
if (ok == 1)
{
ok = check_needed_rights(rights, needed_rights);
if (ok == 1) {
ok = check_needed_rights(rights, needed_rights);
}
X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb);
X509_STORE_CTX_set_verify_cb(ctx, save_verify_cb);
return ok;
return ok;
}
If you use SSL or TLS, you can easily set up a callback to have the
certificates checked properly, using the code above:

5
doc/README
View File

@@ -2,11 +2,10 @@
README This file
fingerprints.txt
PGP fingerprints of authoried release signers
PGP fingerprints of authorised release signers
standards.txt
Pointers to standards, RFC's and IETF Drafts that are
related to OpenSSL. Incomplete.
Moved to the web, https://www.openssl.org/docs/standards.html
HOWTO/
A few how-to documents; not necessarily up-to-date

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

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,19 +7,27 @@ CA.pl - friendlier interface for OpenSSL certificate programs
=head1 SYNOPSIS
B<CA.pl>
[B<-?>]
[B<-h>]
[B<-help>]
[B<-newcert>]
[B<-newreq>]
[B<-newreq-nodes>]
[B<-newca>]
[B<-xsign>]
[B<-sign>]
[B<-signreq>]
[B<-signcert>]
[B<-verify>]
[B<files>]
B<-?> |
B<-h> |
B<-help>
B<CA.pl>
B<-newcert> |
B<-newreq> |
B<-newreq-nodes> |
B<-xsign> |
B<-sign> |
B<-signCA> |
B<-signcert> |
B<-crl> |
B<-newca>
[B<-extra-cmd> extra-params]
B<CA.pl> B<-pkcs12> [B<-extra-pkcs12> extra-params] [B<certname>]
B<CA.pl> B<-verify> [B<-extra-verify> extra-params] B<certfile>...
B<CA.pl> B<-revoke> [B<-extra-ca> extra-params] B<certfile> [B<reason>]
=head1 DESCRIPTION
@@ -29,7 +36,7 @@ arguments to the B<openssl> command for some common certificate operations.
It is intended to simplify the process of certificate creation and management
by the use of some simple options.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
@@ -41,15 +48,18 @@ prints a usage message.
creates a new self signed certificate. The private key is written to the file
"newkey.pem" and the request written to the file "newreq.pem".
This argument invokes B<openssl req> command.
=item B<-newreq>
creates a new certificate request. The private key is written to the file
"newkey.pem" and the request written to the file "newreq.pem".
Executes B<openssl req> command below the hood.
=item B<-newreq-nodes>
is like B<-newreq> except that the private key will not be encrypted.
Uses B<openssl req> command.
=item B<-newca>
@@ -58,6 +68,7 @@ and B<-xsign> options). The user is prompted to enter the filename of the CA
certificates (which should also contain the private key) or by hitting ENTER
details of the CA will be prompted for. The relevant files and directories
are created in a directory called "demoCA" in the current directory.
B<openssl req> and B<openssl ca> commands are get invoked.
=item B<-pkcs12>
@@ -69,34 +80,55 @@ B<-sign> option. The PKCS#12 file can be imported directly into a browser.
If there is an additional argument on the command line it will be used as the
"friendly name" for the certificate (which is typically displayed in the browser
list box), otherwise the name "My Certificate" is used.
Delegates work to B<openssl pkcs12> command.
=item B<-sign>, B<-signreq>, B<-xsign>
=item B<-sign>, B<-signcert>, B<-xsign>
calls the B<ca> program to sign a certificate request. It expects the request
to be in the file "newreq.pem". The new certificate is written to the file
"newcert.pem" except in the case of the B<-xsign> option when it is written
to standard output.
to standard output. Leverages B<openssl ca> command.
=item B<-signCA>
this option is the same as the B<-signreq> option except it uses the configuration
file section B<v3_ca> and so makes the signed request a valid CA certificate. This
is useful when creating intermediate CA from a root CA.
Extra params are passed on to B<openssl ca> command.
=item B<-signcert>
this option is the same as B<-sign> except it expects a self signed certificate
to be present in the file "newreq.pem".
Extra params are passed on to B<openssl x509> and B<openssl ca> commands.
=item B<-crl>
generate a CRL. Executes B<openssl ca> command.
=item B<-revoke certfile [reason]>
revoke the certificate contained in the specified B<certfile>. An optional
reason may be specified, and must be one of: B<unspecified>,
B<keyCompromise>, B<CACompromise>, B<affiliationChanged>, B<superseded>,
B<cessationOfOperation>, B<certificateHold>, or B<removeFromCRL>.
Leverages B<openssl ca> command.
=item B<-verify>
verifies certificates against the CA certificate for "demoCA". If no certificates
are specified on the command line it tries to verify the file "newcert.pem".
are specified on the command line it tries to verify the file "newcert.pem".
Invokes B<openssl verify> command.
=item B<files>
=item B<-extra-req> | B<-extra-ca> | B<-extra-pkcs12> | B<-extra-x509> | B<-extra-verify> <extra-params>
one or more optional certificate file names for use with the B<-verify> command.
The purpose of these parameters is to allow optional parameters to be supplied
to B<openssl> that this command executes. The B<-extra-cmd> are specific to the
option being used and the B<openssl> command getting invoked. For example
when this command invokes B<openssl req> extra parameters can be passed on
with the B<-extra-req> parameter. The
B<openssl> commands being invoked per option are documented below.
Users should consult B<openssl> command documentation for more information.
=back
@@ -117,7 +149,7 @@ the request and finally create a PKCS#12 file containing it.
=head1 DSA CERTIFICATES
Although the B<CA.pl> creates RSA CAs and requests it is still possible to
use it with DSA certificates and requests using the L<req(1)|req(1)> command
use it with DSA certificates and requests using the L<req(1)> command
directly. The following example shows the steps that would typically be taken.
Create some DSA parameters:
@@ -137,7 +169,7 @@ enter cacert.pem when prompted for the CA file name.
Create a DSA certificate request and private key (a different set of parameters
can optionally be created first):
openssl req -out newreq.pem -newkey dsa:dsap.pem
openssl req -out newreq.pem -newkey dsa:dsap.pem
Sign the request:
@@ -158,22 +190,25 @@ be wrong. In this case the command:
perl -S CA.pl
can be used and the B<OPENSSL_CONF> environment variable changed to point to
the correct path of the configuration file "openssl.cnf".
can be used and the B<OPENSSL_CONF> environment variable changed to point to
the correct path of the configuration file.
The script is intended as a simple front end for the B<openssl> program for use
by a beginner. Its behaviour isn't always what is wanted. For more control over the
behaviour of the certificate commands call the B<openssl> command directly.
=head1 ENVIRONMENT VARIABLES
The variable B<OPENSSL_CONF> if defined allows an alternative configuration
file location to be specified, it should contain the full path to the
configuration file, not just its directory.
=head1 SEE ALSO
L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<req(1)|req(1)>, L<pkcs12(1)|pkcs12(1)>,
L<config(5)|config(5)>
L<x509(1)>, L<ca(1)>, L<req(1)>, L<pkcs12(1)>,
L<config(5)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

59
doc/apps/asn1parse.pod
View File

@@ -7,6 +7,7 @@ asn1parse - ASN.1 parsing tool
=head1 SYNOPSIS
B<openssl> B<asn1parse>
[B<-help>]
[B<-inform PEM|DER>]
[B<-in filename>]
[B<-out filename>]
@@ -20,6 +21,7 @@ B<openssl> B<asn1parse>
[B<-strparse offset>]
[B<-genstr string>]
[B<-genconf file>]
[B<-strictpem>]
=head1 DESCRIPTION
@@ -30,6 +32,10 @@ structures. It can also be used to extract data from ASN.1 formatted data.
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform> B<DER|PEM>
the input format. B<DER> is binary format and B<PEM> (the default) is base64
@@ -82,36 +88,44 @@ option can be used multiple times to "drill down" into a nested structure.
=item B<-genstr string>, B<-genconf file>
generate encoded data based on B<string>, B<file> or both using
L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format. If B<file> only is
L<ASN1_generate_nconf(3)> format. If B<file> only is
present then the string is obtained from the default section using the name
B<asn1>. The encoded data is passed through the ASN1 parser and printed out as
though it came from a file, the contents can thus be examined and written to a
file using the B<out> option.
file using the B<out> option.
=item B<-strictpem>
If this option is used then B<-inform> will be ignored. Without this option any
data in a PEM format input file will be treated as being base64 encoded and
processed whether it has the normal PEM BEGIN and END markers or not. This
option will ignore any data prior to the start of the BEGIN marker, or after an
END marker in a PEM file.
=back
=head2 OUTPUT
=head2 Output
The output will typically contain lines like this:
0:d=0 hl=4 l= 681 cons: SEQUENCE
0:d=0 hl=4 l= 681 cons: SEQUENCE
.....
229:d=3 hl=3 l= 141 prim: BIT STRING
373:d=2 hl=3 l= 162 cons: cont [ 3 ]
376:d=3 hl=3 l= 159 cons: SEQUENCE
379:d=4 hl=2 l= 29 cons: SEQUENCE
229:d=3 hl=3 l= 141 prim: BIT STRING
373:d=2 hl=3 l= 162 cons: cont [ 3 ]
376:d=3 hl=3 l= 159 cons: SEQUENCE
379:d=4 hl=2 l= 29 cons: SEQUENCE
381:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Subject Key Identifier
386:d=5 hl=2 l= 22 prim: OCTET STRING
410:d=4 hl=2 l= 112 cons: SEQUENCE
386:d=5 hl=2 l= 22 prim: OCTET STRING
410:d=4 hl=2 l= 112 cons: SEQUENCE
412:d=5 hl=2 l= 3 prim: OBJECT :X509v3 Authority Key Identifier
417:d=5 hl=2 l= 105 prim: OCTET STRING
524:d=4 hl=2 l= 12 cons: SEQUENCE
417:d=5 hl=2 l= 105 prim: OCTET STRING
524:d=4 hl=2 l= 12 cons: SEQUENCE
.....
This example is part of a self signed certificate. Each line starts with the
This example is part of a self-signed certificate. Each line starts with the
offset in decimal. B<d=XX> specifies the current depth. The depth is increased
within the scope of any SET or SEQUENCE. B<hl=XX> gives the header length
(tag and length octets) of the current type. B<l=XX> gives the length of
@@ -119,27 +133,27 @@ the contents octets.
The B<-i> option can be used to make the output more readable.
Some knowledge of the ASN.1 structure is needed to interpret the output.
Some knowledge of the ASN.1 structure is needed to interpret the output.
In this example the BIT STRING at offset 229 is the certificate public key.
The contents octets of this will contain the public key information. This can
be examined using the option B<-strparse 229> to yield:
0:d=0 hl=3 l= 137 cons: SEQUENCE
0:d=0 hl=3 l= 137 cons: SEQUENCE
3:d=1 hl=3 l= 129 prim: INTEGER :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897
135:d=1 hl=2 l= 3 prim: INTEGER :010001
=head1 NOTES
If an OID is not part of OpenSSL's internal table it will be represented in
numerical form (for example 1.2.3.4). The file passed to the B<-oid> option
numerical form (for example 1.2.3.4). The file passed to the B<-oid> option
allows additional OIDs to be included. Each line consists of three columns,
the first column is the OID in numerical format and should be followed by white
space. The second column is the "short name" which is a single word followed
by white space. The final column is the rest of the line and is the
"long name". B<asn1parse> displays the long name. Example:
C<1.2.3.4 shortName A long name>
C<1.2.3.4 shortName A long name>
=head1 EXAMPLES
@@ -180,6 +194,15 @@ ASN.1 types is not well handled (if at all).
=head1 SEE ALSO
L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>
L<ASN1_generate_nconf(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

109
doc/apps/ca.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,11 +7,13 @@ ca - sample minimal CA application
=head1 SYNOPSIS
B<openssl> B<ca>
[B<-help>]
[B<-verbose>]
[B<-config filename>]
[B<-name section>]
[B<-gencrl>]
[B<-revoke file>]
[B<-valid file>]
[B<-status serial>]
[B<-updatedb>]
[B<-crl_reason reason>]
@@ -49,6 +50,7 @@ B<openssl> B<ca>
[B<-engine id>]
[B<-subj arg>]
[B<-utf8>]
[B<-create_serial>]
[B<-multivalue-rdn>]
=head1 DESCRIPTION
@@ -60,13 +62,23 @@ and their status.
The options descriptions will be divided into each purpose.
=head1 CA OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-verbose>
this prints extra details about the operations being performed.
=item B<-config filename>
specifies the configuration file to use.
Optional; for a description of the default value,
see L<openssl(1)/COMMAND SUMMARY>.
=item B<-name section>
@@ -80,7 +92,7 @@ signed by the CA.
=item B<-ss_cert filename>
a single self signed certificate to be signed by the CA.
a single self-signed certificate to be signed by the CA.
=item B<-spkac filename>
@@ -91,7 +103,7 @@ section for information on the required input and output format.
=item B<-infiles>
if present this should be the last option, all subsequent arguments
are assumed to the the names of files containing certificate requests.
are taken as the names of files containing certificate requests.
=item B<-out filename>
@@ -128,7 +140,7 @@ the 'ps' utility) this option should be used with caution.
indicates the issued certificates are to be signed with the key
the certificate requests were signed with (given with B<-keyfile>).
Cerificate requests signed with a different key are ignored. If
Certificate requests signed with a different key are ignored. If
B<-spkac>, B<-ss_cert> or B<-gencrl> are given, B<-selfsign> is
ignored.
@@ -141,11 +153,7 @@ self-signed certificate.
=item B<-passin arg>
the key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-verbose>
this prints extra details about the operations being performed.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-notext>
@@ -167,7 +175,8 @@ the number of days to certify the certificate for.
=item B<-md alg>
the message digest to use. Possible values include md5, sha1 and mdc2.
the message digest to use.
Any digest supported by the OpenSSL B<dgst> command can be used.
This option also applies to CRLs.
=item B<-policy arg>
@@ -188,7 +197,7 @@ need this option.
=item B<-preserveDN>
Normally the DN order of a certificate is the same as the order of the
fields in the relevant policy section. When this option is set the order
fields in the relevant policy section. When this option is set the order
is the same as the request. This is largely for compatibility with the
older IE enrollment control which would only accept certificates if their
DNs match the order of the request. This is not needed for Xenroll.
@@ -214,7 +223,7 @@ to be added when a certificate is issued (defaults to B<x509_extensions>
unless the B<-extfile> option is used). If no extension section is
present then, a V1 certificate is created. If the extension section
is present (even if it is empty), then a V3 certificate is created. See the:w
L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
L<x509v3_config(5)> manual page for details of the
extension section format.
=item B<-extfile file>
@@ -238,14 +247,20 @@ characters may be escaped by \ (backslash), no spaces are skipped.
=item B<-utf8>
this option causes field values to be interpreted as UTF8 strings, by
this option causes field values to be interpreted as UTF8 strings, by
default they are interpreted as ASCII. This means that the field
values, whether prompted from a terminal or obtained from a
configuration file, must be valid UTF8 strings.
=item B<-create_serial>
if reading serial from the text file as specified in the configuration
fails, specifying this option creates a new random serial to be used as next
serial number.
=item B<-multivalue-rdn>
this option causes the -subj argument to be interpretedt with full
This option causes the -subj argument to be interpreted with full
support for multivalued RDNs. Example:
I</DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe>
@@ -275,6 +290,10 @@ the number of hours before the next CRL is due.
a filename containing a certificate to revoke.
=item B<-valid filename>
a filename containing a certificate to add a Valid certificate entry.
=item B<-status serial>
displays the revocation status of the certificate with the specified
@@ -291,7 +310,7 @@ B<CACompromise>, B<affiliationChanged>, B<superseded>, B<cessationOfOperation>,
B<certificateHold> or B<removeFromCRL>. The matching of B<reason> is case
insensitive. Setting any revocation reason will make the CRL v2.
In practive B<removeFromCRL> is not particularly useful because it is only used
In practice B<removeFromCRL> is not particularly useful because it is only used
in delta CRLs which are not currently implemented.
=item B<-crl_hold instruction>
@@ -319,7 +338,7 @@ created, if the CRL extension section is present (even if it is
empty) then a V2 CRL is created. The CRL extensions specified are
CRL extensions and B<not> CRL entry extensions. It should be noted
that some software (for example Netscape) can't handle V2 CRLs. See
L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
L<x509v3_config(5)> manual page for details of the
extension section format.
=back
@@ -353,7 +372,7 @@ any) used.
This specifies a file containing additional B<OBJECT IDENTIFIERS>.
Each line of the file should consist of the numerical form of the
object identifier followed by white space then the short name followed
by white space and finally the long name.
by white space and finally the long name.
=item B<oid_section>
@@ -380,12 +399,12 @@ CA private key. Mandatory.
=item B<RANDFILE>
a file used to read and write random number seed information, or
an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
an EGD socket (see L<RAND_egd(3)>).
=item B<default_days>
the same as the B<-days> option. The number of days to certify
a certificate for.
a certificate for.
=item B<default_startdate>
@@ -406,7 +425,7 @@ least one of these must be present to generate a CRL.
=item B<default_md>
the same as the B<-md> option. The message digest to use. Mandatory.
the same as the B<-md> option. Mandatory.
=item B<database>
@@ -508,7 +527,7 @@ this can be regarded more of a quirk than intended behaviour.
The input to the B<-spkac> command line option is a Netscape
signed public key and challenge. This will usually come from
the B<KEYGEN> tag in an HTML form to create a new private key.
the B<KEYGEN> tag in an HTML form to create a new private key.
It is however possible to create SPKACs using the B<spkac> utility.
The file should contain the variable SPKAC set to the value of
@@ -568,18 +587,18 @@ A sample configuration file with the relevant sections for B<ca>:
[ ca ]
default_ca = CA_default # The default ca section
[ CA_default ]
dir = ./demoCA # top dir
database = $dir/index.txt # index file.
new_certs_dir = $dir/newcerts # new certs dir
new_certs_dir = $dir/newcerts # new certs dir
certificate = $dir/cacert.pem # The CA cert
serial = $dir/serial # serial no file
private_key = $dir/private/cakey.pem# CA private key
RANDFILE = $dir/private/.rand # random number file
default_days = 365 # how long to certify for
default_crl_days= 30 # how long before next CRL
default_md = md5 # md to use
@@ -587,9 +606,9 @@ A sample configuration file with the relevant sections for B<ca>:
policy = policy_any # default policy
email_in_dn = no # Don't add the email into cert DN
name_opt = ca_default # Subject name display option
cert_opt = ca_default # Certificate display option
copy_extensions = none # Don't copy extensions from request
name_opt = ca_default # Subject name display option
cert_opt = ca_default # Certificate display option
copy_extensions = none # Don't copy extensions from request
[ policy_any ]
countryName = supplied
@@ -616,14 +635,9 @@ The values below reflect the default values.
./demoCA/certs - certificate output file
./demoCA/.rnd - CA random seed information
=head1 ENVIRONMENT VARIABLES
B<OPENSSL_CONF> reflects the location of master configuration file it can
be overridden by the B<-config> command line option.
=head1 RESTRICTIONS
The text database index file is a critical part of the process and
The text database index file is a critical part of the process and
if corrupted it can be difficult to fix. It is theoretically possible
to rebuild the index file from all the issued certificates and a current
CRL: however there is no option to do this.
@@ -631,18 +645,18 @@ CRL: however there is no option to do this.
V2 CRL features like delta CRLs are not currently supported.
Although several requests can be input and handled at once it is only
possible to include one SPKAC or self signed certificate.
possible to include one SPKAC or self-signed certificate.
=head1 BUGS
The use of an in memory text database can cause problems when large
The use of an in-memory text database can cause problems when large
numbers of certificates are present because, as the name implies
the database has to be kept in memory.
The B<ca> command really needs rewriting or the required functionality
exposed at either a command or interface level so a more friendly utility
(perl script or GUI) can handle things properly. The scripts B<CA.sh> and
B<CA.pl> help a little but not very much.
(perl script or GUI) can handle things properly. The script
B<CA.pl> helps a little but not very much.
Any fields in a request that are not present in a policy are silently
deleted. This does not happen if the B<-preserveDN> option is used. To
@@ -651,7 +665,7 @@ RFCs, regardless the contents of the request' subject the B<-noemailDN>
option can be used. The behaviour should be more friendly and
configurable.
Cancelling some commands by refusing to certify a certificate can
Canceling some commands by refusing to certify a certificate can
create an empty file.
=head1 WARNINGS
@@ -670,7 +684,7 @@ The B<copy_extensions> option should be used with caution. If care is
not taken then it can be a security risk. For example if a certificate
request contains a basicConstraints extension with CA:TRUE and the
B<copy_extensions> value is set to B<copyall> and the user does not spot
this when the certificate is displayed then this will hand the requestor
this when the certificate is displayed then this will hand the requester
a valid CA certificate.
This situation can be avoided by setting B<copy_extensions> to B<copy>
@@ -690,7 +704,16 @@ then even if a certificate is issued with CA:TRUE it will not be valid.
=head1 SEE ALSO
L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>,
L<config(5)|config(5)>, L<x509v3_config(5)|x509v3_config(5)>
L<req(1)>, L<spkac(1)>, L<x509(1)>, L<CA.pl(1)>,
L<config(5)>, L<x509v3_config(5)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

493
doc/apps/ciphers.pod
View File

@@ -2,16 +2,23 @@
=head1 NAME
ciphers - SSL cipher display and cipher list tool.
ciphers - SSL cipher display and cipher list tool
=head1 SYNOPSIS
B<openssl> B<ciphers>
[B<-help>]
[B<-s>]
[B<-v>]
[B<-V>]
[B<-ssl2>]
[B<-ssl3>]
[B<-tls1>]
[B<-tls1_1>]
[B<-tls1_2>]
[B<-s>]
[B<-psk>]
[B<-srp>]
[B<-stdname>]
[B<cipherlist>]
=head1 DESCRIPTION
@@ -20,39 +27,76 @@ The B<ciphers> command converts textual OpenSSL cipher lists into ordered
SSL cipher preference lists. It can be used as a test tool to determine
the appropriate cipherlist.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print a usage message.
=item B<-s>
Only list supported ciphers: those consistent with the security level, and
minimum and maximum protocol version. This is closer to the actual cipher list
an application will support.
PSK and SRP ciphers are not enabled by default: they require B<-psk> or B<-srp>
to enable them.
It also does not change the default list of supported signature algorithms.
On a server the list of supported ciphers might also exclude other ciphers
depending on the configured certificates and presence of DH parameters.
If this option is not used then all ciphers that match the cipherlist will be
listed.
=item B<-psk>
When combined with B<-s> includes cipher suites which require PSK.
=item B<-srp>
When combined with B<-s> includes cipher suites which require SRP.
=item B<-v>
Verbose option. List ciphers with a complete description of
protocol version (SSLv2 or SSLv3; the latter includes TLS), key exchange,
authentication, encryption and mac algorithms used along with any key size
restrictions and whether the algorithm is classed as an "export" cipher.
Note that without the B<-v> option, ciphers may seem to appear twice
in a cipher list; this is when similar ciphers are available for
SSL v2 and for SSL v3/TLS v1.
Verbose output: For each ciphersuite, list details as provided by
L<SSL_CIPHER_description(3)>.
=item B<-V>
Like B<-v>, but include cipher suite codes in output (hex format).
Like B<-v>, but include the official cipher suite values in hex.
=item B<-ssl3>, B<-tls1>
=item B<-tls1_2>
This lists ciphers compatible with any of SSLv3, TLSv1, TLSv1.1 or TLSv1.2.
In combination with the B<-s> option, list the ciphers which would be used if
TLSv1.2 were negotiated.
=item B<-ssl2>
=item B<-ssl3>
Only include SSLv2 ciphers.
In combination with the B<-s> option, list the ciphers which would be used if
SSLv3 were negotiated.
=item B<-h>, B<-?>
=item B<-tls1>
Print a brief usage message.
In combination with the B<-s> option, list the ciphers which would be used if
TLSv1 were negotiated.
=item B<-tls1_1>
In combination with the B<-s> option, list the ciphers which would be used if
TLSv1.1 were negotiated.
=item B<-stdname>
precede each ciphersuite by its standard name: only available is OpenSSL
is built with tracing enabled (B<enable-ssl-trace> argument to Configure).
=item B<cipherlist>
A cipher list to convert to a cipher preference list. If it is not included
a cipher list to convert to a cipher preference list. If it is not included
then the default cipher list will be used. The format is described below.
=back
@@ -94,8 +138,11 @@ as a list of ciphers to be appended to the current preference list. If the
list includes any ciphers already present they will be ignored: that is they
will not moved to the end of the list.
Additionally the cipher string B<@STRENGTH> can be used at any point to sort
the current cipher list in order of encryption algorithm key length.
The cipher string B<@STRENGTH> can be used at any point to sort the current
cipher list in order of encryption algorithm key length.
The cipher string B<@SECLEVEL=n> can be used at any point to set the security
level to B<n>.
=head1 CIPHER STRINGS
@@ -107,55 +154,42 @@ The following is a list of all permitted cipher strings and their meanings.
The default cipher list.
This is determined at compile time and is normally
B<ALL:!EXPORT:!LOW:!aNULL:!eNULL:!SSLv2>.
B<ALL:!COMPLEMENTOFDEFAULT:!eNULL>.
When used, this must be the first cipherstring specified.
=item B<COMPLEMENTOFDEFAULT>
the ciphers included in B<ALL>, but not enabled by default. Currently
this is B<ADH> and B<AECDH>. Note that this rule does not cover B<eNULL>,
which is not included by B<ALL> (use B<COMPLEMENTOFALL> if necessary).
The ciphers included in B<ALL>, but not enabled by default. Currently
this includes all RC4 and anonymous ciphers. Note that this rule does
not cover B<eNULL>, which is not included by B<ALL> (use B<COMPLEMENTOFALL> if
necessary). Note that RC4 based ciphersuites are not built into OpenSSL by
default (see the enable-weak-ssl-ciphers option to Configure).
=item B<ALL>
all cipher suites except the B<eNULL> ciphers which must be explicitly enabled;
as of OpenSSL, the B<ALL> cipher suites are reasonably ordered by default
All cipher suites except the B<eNULL> ciphers (which must be explicitly enabled
if needed).
As of OpenSSL 1.0.0, the B<ALL> cipher suites are sensibly ordered by default.
=item B<COMPLEMENTOFALL>
the cipher suites not enabled by B<ALL>, currently being B<eNULL>.
The cipher suites not enabled by B<ALL>, currently B<eNULL>.
=item B<HIGH>
"high" encryption cipher suites. This currently means those with key lengths larger
than 128 bits, and some cipher suites with 128-bit keys.
"high" encryption cipher suites. This currently means those with key lengths
larger than 128 bits, and some cipher suites with 128-bit keys.
=item B<MEDIUM>
"medium" encryption cipher suites, currently some of those using 128 bit encryption.
"medium" encryption cipher suites, currently some of those using 128 bit
encryption.
=item B<LOW>
Low strength encryption cipher suites, currently those using 64 or 56 bit
encryption algorithms but excluding export cipher suites.
As of OpenSSL 1.0.2g, these are disabled in default builds.
=item B<EXP>, B<EXPORT>
Export strength encryption algorithms. Including 40 and 56 bits algorithms.
As of OpenSSL 1.0.2g, these are disabled in default builds.
=item B<EXPORT40>
40-bit export encryption algorithms
As of OpenSSL 1.0.2g, these are disabled in default builds.
=item B<EXPORT56>
56-bit export encryption algorithms. In OpenSSL 0.9.8c and later the set of
56 bit export ciphers is empty unless OpenSSL has been explicitly configured
with support for experimental ciphers.
As of OpenSSL 1.0.2g, these are disabled in default builds.
"low" encryption cipher suites, currently those using 64 or 56 bit
encryption algorithms but excluding export cipher suites. All these
ciphersuites have been removed as of OpenSSL 1.1.0.
=item B<eNULL>, B<NULL>
@@ -163,102 +197,83 @@ The "NULL" ciphers that is those offering no encryption. Because these offer no
encryption at all and are a security risk they are not enabled via either the
B<DEFAULT> or B<ALL> cipher strings.
Be careful when building cipherlists out of lower-level primitives such as
B<kRSA> or B<aECDSA> as these do overlap with the B<eNULL> ciphers.
When in doubt, include B<!eNULL> in your cipherlist.
B<kRSA> or B<aECDSA> as these do overlap with the B<eNULL> ciphers. When in
doubt, include B<!eNULL> in your cipherlist.
=item B<aNULL>
The cipher suites offering no authentication. This is currently the anonymous
DH algorithms and anonymous ECDH algorithms. These cipher suites are vulnerable
to a "man in the middle" attack and so their use is normally discouraged.
to "man in the middle" attacks and so their use is discouraged.
These are excluded from the B<DEFAULT> ciphers, but included in the B<ALL>
ciphers.
Be careful when building cipherlists out of lower-level primitives such as
B<kDHE> or B<AES> as these do overlap with the B<aNULL> ciphers.
When in doubt, include B<!aNULL> in your cipherlist.
=item B<kRSA>, B<RSA>
=item B<kRSA>, B<aRSA>, B<RSA>
cipher suites using RSA key exchange.
Cipher suites using RSA key exchange or authentication. B<RSA> is an alias for
B<kRSA>.
=item B<kDHr>, B<kDHd>, B<kDH>
cipher suites using DH key agreement and DH certificates signed by CAs with RSA
and DSS keys or either respectively.
Cipher suites using static DH key agreement and DH certificates signed by CAs
with RSA and DSS keys or either respectively.
All these cipher suites have been removed in OpenSSL 1.1.0.
=item B<kDHE>, B<kEDH>
=item B<kDHE>, B<kEDH>, B<DH>
cipher suites using ephemeral DH key agreement, including anonymous cipher
Cipher suites using ephemeral DH key agreement, including anonymous cipher
suites.
=item B<DHE>, B<EDH>
cipher suites using authenticated ephemeral DH key agreement.
Cipher suites using authenticated ephemeral DH key agreement.
=item B<ADH>
anonymous DH cipher suites, note that this does not include anonymous Elliptic
Anonymous DH cipher suites, note that this does not include anonymous Elliptic
Curve DH (ECDH) cipher suites.
=item B<DH>
=item B<kEECDH>, B<kECDHE>, B<ECDH>
cipher suites using DH, including anonymous DH, ephemeral DH and fixed DH.
=item B<kECDHr>, B<kECDHe>, B<kECDH>
cipher suites using fixed ECDH key agreement signed by CAs with RSA and ECDSA
keys or either respectively.
=item B<kECDHE>, B<kEECDH>
cipher suites using ephemeral ECDH key agreement, including anonymous
Cipher suites using ephemeral ECDH key agreement, including anonymous
cipher suites.
=item B<ECDHE>, B<EECDH>
cipher suites using authenticated ephemeral ECDH key agreement.
Cipher suites using authenticated ephemeral ECDH key agreement.
=item B<AECDH>
anonymous Elliptic Curve Diffie Hellman cipher suites.
=item B<ECDH>
cipher suites using ECDH key exchange, including anonymous, ephemeral and
fixed ECDH.
=item B<aRSA>
cipher suites using RSA authentication, i.e. the certificates carry RSA keys.
Anonymous Elliptic Curve Diffie-Hellman cipher suites.
=item B<aDSS>, B<DSS>
cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
Cipher suites using DSS authentication, i.e. the certificates carry DSS keys.
=item B<aDH>
cipher suites effectively using DH authentication, i.e. the certificates carry
Cipher suites effectively using DH authentication, i.e. the certificates carry
DH keys.
=item B<aECDH>
cipher suites effectively using ECDH authentication, i.e. the certificates
carry ECDH keys.
All these cipher suites have been removed in OpenSSL 1.1.0.
=item B<aECDSA>, B<ECDSA>
cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA
Cipher suites using ECDSA authentication, i.e. the certificates carry ECDSA
keys.
=item B<kFZA>, B<aFZA>, B<eFZA>, B<FZA>
=item B<TLSv1.2>, B<TLSv1.0>, B<SSLv3>
ciphers suites using FORTEZZA key exchange, authentication, encryption or all
FORTEZZA algorithms. Not implemented.
Lists ciphersuites which are only supported in at least TLS v1.2, TLS v1.0 or
SSL v3.0 respectively.
Note: there are no ciphersuites specific to TLS v1.1.
Since this is only the minimum version, if, for example, TLSv1.0 is negotiated
then both TLSv1.0 and SSLv3.0 ciphersuites are available.
=item B<TLSv1.2>, B<TLSv1>, B<SSLv3>, B<SSLv2>
TLS v1.2, TLS v1.0, SSL v3.0 or SSL v2.0 cipher suites respectively. Note:
there are no ciphersuites specific to TLS v1.1.
Note: these cipher strings B<do not> change the negotiated version of SSL or
TLS, they only affect the list of available cipher suites.
=item B<AES128>, B<AES256>, B<AES>
@@ -269,88 +284,107 @@ cipher suites using 128 bit AES, 256 bit AES or either 128 or 256 bit AES.
AES in Galois Counter Mode (GCM): these ciphersuites are only supported
in TLS v1.2.
=item B<AESCCM>, B<AESCCM8>
AES in Cipher Block Chaining - Message Authentication Mode (CCM): these
ciphersuites are only supported in TLS v1.2. B<AESCCM> references CCM
cipher suites using both 16 and 8 octet Integrity Check Value (ICV)
while B<AESCCM8> only references 8 octet ICV.
=item B<CAMELLIA128>, B<CAMELLIA256>, B<CAMELLIA>
cipher suites using 128 bit CAMELLIA, 256 bit CAMELLIA or either 128 or 256 bit
CAMELLIA.
=item B<CHACHA20>
cipher suites using ChaCha20.
=item B<3DES>
cipher suites using triple DES.
=item B<DES>
cipher suites using DES (not triple DES).
Cipher suites using DES (not triple DES).
All these cipher suites have been removed in OpenSSL 1.1.0.
=item B<RC4>
cipher suites using RC4.
Cipher suites using RC4.
=item B<RC2>
cipher suites using RC2.
Cipher suites using RC2.
=item B<IDEA>
cipher suites using IDEA.
Cipher suites using IDEA.
=item B<SEED>
cipher suites using SEED.
Cipher suites using SEED.
=item B<MD5>
cipher suites using MD5.
Cipher suites using MD5.
=item B<SHA1>, B<SHA>
cipher suites using SHA1.
Cipher suites using SHA1.
=item B<SHA256>, B<SHA384>
ciphersuites using SHA256 or SHA384.
Ciphersuites using SHA256 or SHA384.
=item B<aGOST>
=item B<aGOST>
cipher suites using GOST R 34.10 (either 2001 or 94) for authenticaction
(needs an engine supporting GOST algorithms).
Cipher suites using GOST R 34.10 (either 2001 or 94) for authentication
(needs an engine supporting GOST algorithms).
=item B<aGOST01>
cipher suites using GOST R 34.10-2001 authentication.
=item B<aGOST94>
cipher suites using GOST R 34.10-94 authentication (note that R 34.10-94
standard has been expired so use GOST R 34.10-2001)
Cipher suites using GOST R 34.10-2001 authentication.
=item B<kGOST>
cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357.
Cipher suites, using VKO 34.10 key exchange, specified in the RFC 4357.
=item B<GOST94>
cipher suites, using HMAC based on GOST R 34.11-94.
Cipher suites, using HMAC based on GOST R 34.11-94.
=item B<GOST89MAC>
cipher suites using GOST 28147-89 MAC B<instead of> HMAC.
Cipher suites using GOST 28147-89 MAC B<instead of> HMAC.
=item B<PSK>
cipher suites using pre-shared keys (PSK).
All cipher suites using pre-shared keys (PSK).
=item B<kPSK>, B<kECDHEPSK>, B<kDHEPSK>, B<kRSAPSK>
Cipher suites using PSK key exchange, ECDHE_PSK, DHE_PSK or RSA_PSK.
=item B<aPSK>
Cipher suites using PSK authentication (currently all PSK modes apart from
RSA_PSK).
=item B<SUITEB128>, B<SUITEB128ONLY>, B<SUITEB192>
enables suite B mode operation using 128 (permitting 192 bit mode by peer)
Enables suite B mode of operation using 128 (permitting 192 bit mode by peer)
128 bit (not permitting 192 bit by peer) or 192 bit level of security
respectively. If used these cipherstrings should appear first in the cipher
list and anything after them is ignored. Setting Suite B mode has additional
consequences required to comply with RFC6460. In particular the supported
signature algorithms is reduced to support only ECDSA and SHA256 or SHA384,
only the elliptic curves P-256 and P-384 can be used and only the two suite B
compliant ciphersuites (ECDHE-ECDSA-AES128-GCM-SHA256 and
ECDHE-ECDSA-AES256-GCM-SHA384) are permissible.
respectively.
If used these cipherstrings should appear first in the cipher
list and anything after them is ignored.
Setting Suite B mode has additional consequences required to comply with
RFC6460.
In particular the supported signature algorithms is reduced to support only
ECDSA and SHA256 or SHA384, only the elliptic curves P-256 and P-384 can be
used and only the two suite B compliant ciphersuites
(ECDHE-ECDSA-AES128-GCM-SHA256 and ECDHE-ECDSA-AES256-GCM-SHA384) are
permissible.
=back
@@ -361,70 +395,42 @@ relevant specification and their OpenSSL equivalents. It should be noted,
that several cipher suite names do not include the authentication used,
e.g. DES-CBC3-SHA. In these cases, RSA authentication is used.
=head2 SSL v3.0 cipher suites.
=head2 SSL v3.0 cipher suites
SSL_RSA_WITH_NULL_MD5 NULL-MD5
SSL_RSA_WITH_NULL_SHA NULL-SHA
SSL_RSA_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5
SSL_RSA_WITH_RC4_128_MD5 RC4-MD5
SSL_RSA_WITH_RC4_128_SHA RC4-SHA
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5
SSL_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA
SSL_RSA_WITH_DES_CBC_SHA DES-CBC-SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
SSL_DH_DSS_WITH_DES_CBC_SHA DH-DSS-DES-CBC-SHA
SSL_DH_DSS_WITH_3DES_EDE_CBC_SHA DH-DSS-DES-CBC3-SHA
SSL_DH_RSA_WITH_DES_CBC_SHA DH-RSA-DES-CBC-SHA
SSL_DH_RSA_WITH_3DES_EDE_CBC_SHA DH-RSA-DES-CBC3-SHA
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA
SSL_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-RSA-DES-CBC-SHA
SSL_DHE_RSA_WITH_DES_CBC_SHA EDH-RSA-DES-CBC-SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE-DSS-DES-CBC3-SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE-RSA-DES-CBC3-SHA
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5 EXP-ADH-RC4-MD5
SSL_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5
SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA EXP-ADH-DES-CBC-SHA
SSL_DH_anon_WITH_DES_CBC_SHA ADH-DES-CBC-SHA
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA
SSL_FORTEZZA_KEA_WITH_NULL_SHA Not implemented.
SSL_FORTEZZA_KEA_WITH_FORTEZZA_CBC_SHA Not implemented.
SSL_FORTEZZA_KEA_WITH_RC4_128_SHA Not implemented.
=head2 TLS v1.0 cipher suites.
=head2 TLS v1.0 cipher suites
TLS_RSA_WITH_NULL_MD5 NULL-MD5
TLS_RSA_WITH_NULL_SHA NULL-SHA
TLS_RSA_EXPORT_WITH_RC4_40_MD5 EXP-RC4-MD5
TLS_RSA_WITH_RC4_128_MD5 RC4-MD5
TLS_RSA_WITH_RC4_128_SHA RC4-SHA
TLS_RSA_EXPORT_WITH_RC2_CBC_40_MD5 EXP-RC2-CBC-MD5
TLS_RSA_WITH_IDEA_CBC_SHA IDEA-CBC-SHA
TLS_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-DES-CBC-SHA
TLS_RSA_WITH_DES_CBC_SHA DES-CBC-SHA
TLS_RSA_WITH_3DES_EDE_CBC_SHA DES-CBC3-SHA
TLS_DH_DSS_EXPORT_WITH_DES40_CBC_SHA Not implemented.
TLS_DH_DSS_WITH_DES_CBC_SHA Not implemented.
TLS_DH_DSS_WITH_3DES_EDE_CBC_SHA Not implemented.
TLS_DH_RSA_EXPORT_WITH_DES40_CBC_SHA Not implemented.
TLS_DH_RSA_WITH_DES_CBC_SHA Not implemented.
TLS_DH_RSA_WITH_3DES_EDE_CBC_SHA Not implemented.
TLS_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-DSS-DES-CBC-SHA
TLS_DHE_DSS_WITH_DES_CBC_SHA EDH-DSS-CBC-SHA
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA
TLS_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA EXP-EDH-RSA-DES-CBC-SHA
TLS_DHE_RSA_WITH_DES_CBC_SHA EDH-RSA-DES-CBC-SHA
TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA
TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA DHE-DSS-DES-CBC3-SHA
TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA DHE-RSA-DES-CBC3-SHA
TLS_DH_anon_EXPORT_WITH_RC4_40_MD5 EXP-ADH-RC4-MD5
TLS_DH_anon_WITH_RC4_128_MD5 ADH-RC4-MD5
TLS_DH_anon_EXPORT_WITH_DES40_CBC_SHA EXP-ADH-DES-CBC-SHA
TLS_DH_anon_WITH_DES_CBC_SHA ADH-DES-CBC-SHA
TLS_DH_anon_WITH_3DES_EDE_CBC_SHA ADH-DES-CBC3-SHA
=head2 AES ciphersuites from RFC3268, extending TLS v1.0
@@ -489,26 +495,10 @@ algorithms, such as the B<ccgost> engine, included in the OpenSSL distribution.
Note: these ciphers can also be used in SSL v3.
TLS_RSA_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DES-CBC-SHA
TLS_RSA_EXPORT1024_WITH_RC4_56_SHA EXP1024-RC4-SHA
TLS_DHE_DSS_EXPORT1024_WITH_DES_CBC_SHA EXP1024-DHE-DSS-DES-CBC-SHA
TLS_DHE_DSS_EXPORT1024_WITH_RC4_56_SHA EXP1024-DHE-DSS-RC4-SHA
TLS_DHE_DSS_WITH_RC4_128_SHA DHE-DSS-RC4-SHA
=head2 Elliptic curve cipher suites.
TLS_ECDH_RSA_WITH_NULL_SHA ECDH-RSA-NULL-SHA
TLS_ECDH_RSA_WITH_RC4_128_SHA ECDH-RSA-RC4-SHA
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA ECDH-RSA-DES-CBC3-SHA
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA ECDH-RSA-AES128-SHA
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA ECDH-RSA-AES256-SHA
TLS_ECDH_ECDSA_WITH_NULL_SHA ECDH-ECDSA-NULL-SHA
TLS_ECDH_ECDSA_WITH_RC4_128_SHA ECDH-ECDSA-RC4-SHA
TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA ECDH-ECDSA-DES-CBC3-SHA
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA ECDH-ECDSA-AES128-SHA
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA ECDH-ECDSA-AES256-SHA
TLS_ECDHE_RSA_WITH_NULL_SHA ECDHE-RSA-NULL-SHA
TLS_ECDHE_RSA_WITH_RC4_128_SHA ECDHE-RSA-RC4-SHA
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA ECDHE-RSA-DES-CBC3-SHA
@@ -556,16 +546,6 @@ Note: these ciphers can also be used in SSL v3.
TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 DHE-DSS-AES128-GCM-SHA256
TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 DHE-DSS-AES256-GCM-SHA384
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 ECDH-RSA-AES128-SHA256
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 ECDH-RSA-AES256-SHA384
TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 ECDH-RSA-AES128-GCM-SHA256
TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 ECDH-RSA-AES256-GCM-SHA384
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 ECDH-ECDSA-AES128-SHA256
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 ECDH-ECDSA-AES256-SHA384
TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 ECDH-ECDSA-AES128-GCM-SHA256
TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 ECDH-ECDSA-AES256-GCM-SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 ECDHE-RSA-AES128-SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 ECDHE-RSA-AES256-SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 ECDHE-RSA-AES128-GCM-SHA256
@@ -581,22 +561,116 @@ Note: these ciphers can also be used in SSL v3.
TLS_DH_anon_WITH_AES_128_GCM_SHA256 ADH-AES128-GCM-SHA256
TLS_DH_anon_WITH_AES_256_GCM_SHA384 ADH-AES256-GCM-SHA384
=head2 Pre shared keying (PSK) cipheruites
RSA_WITH_AES_128_CCM AES128-CCM
RSA_WITH_AES_256_CCM AES256-CCM
DHE_RSA_WITH_AES_128_CCM DHE-RSA-AES128-CCM
DHE_RSA_WITH_AES_256_CCM DHE-RSA-AES256-CCM
RSA_WITH_AES_128_CCM_8 AES128-CCM8
RSA_WITH_AES_256_CCM_8 AES256-CCM8
DHE_RSA_WITH_AES_128_CCM_8 DHE-RSA-AES128-CCM8
DHE_RSA_WITH_AES_256_CCM_8 DHE-RSA-AES256-CCM8
ECDHE_ECDSA_WITH_AES_128_CCM ECDHE-ECDSA-AES128-CCM
ECDHE_ECDSA_WITH_AES_256_CCM ECDHE-ECDSA-AES256-CCM
ECDHE_ECDSA_WITH_AES_128_CCM_8 ECDHE-ECDSA-AES128-CCM8
ECDHE_ECDSA_WITH_AES_256_CCM_8 ECDHE-ECDSA-AES256-CCM8
TLS_PSK_WITH_RC4_128_SHA PSK-RC4-SHA
TLS_PSK_WITH_3DES_EDE_CBC_SHA PSK-3DES-EDE-CBC-SHA
TLS_PSK_WITH_AES_128_CBC_SHA PSK-AES128-CBC-SHA
TLS_PSK_WITH_AES_256_CBC_SHA PSK-AES256-CBC-SHA
=head2 Camellia HMAC-Based ciphersuites from RFC6367, extending TLS v1.2
=head2 Deprecated SSL v2.0 cipher suites.
TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-ECDSA-CAMELLIA128-SHA256
TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-ECDSA-CAMELLIA256-SHA384
TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-RSA-CAMELLIA128-SHA256
TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-RSA-CAMELLIA256-SHA384
SSL_CK_RC4_128_WITH_MD5 RC4-MD5
SSL_CK_RC4_128_EXPORT40_WITH_MD5 Not implemented.
SSL_CK_RC2_128_CBC_WITH_MD5 RC2-CBC-MD5
SSL_CK_RC2_128_CBC_EXPORT40_WITH_MD5 Not implemented.
SSL_CK_IDEA_128_CBC_WITH_MD5 IDEA-CBC-MD5
SSL_CK_DES_64_CBC_WITH_MD5 Not implemented.
SSL_CK_DES_192_EDE3_CBC_WITH_MD5 DES-CBC3-MD5
=head2 Pre-shared keying (PSK) ciphersuites
PSK_WITH_NULL_SHA PSK-NULL-SHA
DHE_PSK_WITH_NULL_SHA DHE-PSK-NULL-SHA
RSA_PSK_WITH_NULL_SHA RSA-PSK-NULL-SHA
PSK_WITH_RC4_128_SHA PSK-RC4-SHA
PSK_WITH_3DES_EDE_CBC_SHA PSK-3DES-EDE-CBC-SHA
PSK_WITH_AES_128_CBC_SHA PSK-AES128-CBC-SHA
PSK_WITH_AES_256_CBC_SHA PSK-AES256-CBC-SHA
DHE_PSK_WITH_RC4_128_SHA DHE-PSK-RC4-SHA
DHE_PSK_WITH_3DES_EDE_CBC_SHA DHE-PSK-3DES-EDE-CBC-SHA
DHE_PSK_WITH_AES_128_CBC_SHA DHE-PSK-AES128-CBC-SHA
DHE_PSK_WITH_AES_256_CBC_SHA DHE-PSK-AES256-CBC-SHA
RSA_PSK_WITH_RC4_128_SHA RSA-PSK-RC4-SHA
RSA_PSK_WITH_3DES_EDE_CBC_SHA RSA-PSK-3DES-EDE-CBC-SHA
RSA_PSK_WITH_AES_128_CBC_SHA RSA-PSK-AES128-CBC-SHA
RSA_PSK_WITH_AES_256_CBC_SHA RSA-PSK-AES256-CBC-SHA
PSK_WITH_AES_128_GCM_SHA256 PSK-AES128-GCM-SHA256
PSK_WITH_AES_256_GCM_SHA384 PSK-AES256-GCM-SHA384
DHE_PSK_WITH_AES_128_GCM_SHA256 DHE-PSK-AES128-GCM-SHA256
DHE_PSK_WITH_AES_256_GCM_SHA384 DHE-PSK-AES256-GCM-SHA384
RSA_PSK_WITH_AES_128_GCM_SHA256 RSA-PSK-AES128-GCM-SHA256
RSA_PSK_WITH_AES_256_GCM_SHA384 RSA-PSK-AES256-GCM-SHA384
PSK_WITH_AES_128_CBC_SHA256 PSK-AES128-CBC-SHA256
PSK_WITH_AES_256_CBC_SHA384 PSK-AES256-CBC-SHA384
PSK_WITH_NULL_SHA256 PSK-NULL-SHA256
PSK_WITH_NULL_SHA384 PSK-NULL-SHA384
DHE_PSK_WITH_AES_128_CBC_SHA256 DHE-PSK-AES128-CBC-SHA256
DHE_PSK_WITH_AES_256_CBC_SHA384 DHE-PSK-AES256-CBC-SHA384
DHE_PSK_WITH_NULL_SHA256 DHE-PSK-NULL-SHA256
DHE_PSK_WITH_NULL_SHA384 DHE-PSK-NULL-SHA384
RSA_PSK_WITH_AES_128_CBC_SHA256 RSA-PSK-AES128-CBC-SHA256
RSA_PSK_WITH_AES_256_CBC_SHA384 RSA-PSK-AES256-CBC-SHA384
RSA_PSK_WITH_NULL_SHA256 RSA-PSK-NULL-SHA256
RSA_PSK_WITH_NULL_SHA384 RSA-PSK-NULL-SHA384
PSK_WITH_AES_128_GCM_SHA256 PSK-AES128-GCM-SHA256
PSK_WITH_AES_256_GCM_SHA384 PSK-AES256-GCM-SHA384
ECDHE_PSK_WITH_RC4_128_SHA ECDHE-PSK-RC4-SHA
ECDHE_PSK_WITH_3DES_EDE_CBC_SHA ECDHE-PSK-3DES-EDE-CBC-SHA
ECDHE_PSK_WITH_AES_128_CBC_SHA ECDHE-PSK-AES128-CBC-SHA
ECDHE_PSK_WITH_AES_256_CBC_SHA ECDHE-PSK-AES256-CBC-SHA
ECDHE_PSK_WITH_AES_128_CBC_SHA256 ECDHE-PSK-AES128-CBC-SHA256
ECDHE_PSK_WITH_AES_256_CBC_SHA384 ECDHE-PSK-AES256-CBC-SHA384
ECDHE_PSK_WITH_NULL_SHA ECDHE-PSK-NULL-SHA
ECDHE_PSK_WITH_NULL_SHA256 ECDHE-PSK-NULL-SHA256
ECDHE_PSK_WITH_NULL_SHA384 ECDHE-PSK-NULL-SHA384
PSK_WITH_CAMELLIA_128_CBC_SHA256 PSK-CAMELLIA128-SHA256
PSK_WITH_CAMELLIA_256_CBC_SHA384 PSK-CAMELLIA256-SHA384
DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 DHE-PSK-CAMELLIA128-SHA256
DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 DHE-PSK-CAMELLIA256-SHA384
RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 RSA-PSK-CAMELLIA128-SHA256
RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 RSA-PSK-CAMELLIA256-SHA384
ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 ECDHE-PSK-CAMELLIA128-SHA256
ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 ECDHE-PSK-CAMELLIA256-SHA384
PSK_WITH_AES_128_CCM PSK-AES128-CCM
PSK_WITH_AES_256_CCM PSK-AES256-CCM
DHE_PSK_WITH_AES_128_CCM DHE-PSK-AES128-CCM
DHE_PSK_WITH_AES_256_CCM DHE-PSK-AES256-CCM
PSK_WITH_AES_128_CCM_8 PSK-AES128-CCM8
PSK_WITH_AES_256_CCM_8 PSK-AES256-CCM8
DHE_PSK_WITH_AES_128_CCM_8 DHE-PSK-AES128-CCM8
DHE_PSK_WITH_AES_256_CCM_8 DHE-PSK-AES256-CCM8
=head2 ChaCha20-Poly1305 cipher suites, extending TLS v1.2
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 ECDHE-RSA-CHACHA20-POLY1305
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 ECDHE-ECDSA-CHACHA20-POLY1305
TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 DHE-RSA-CHACHA20-POLY1305
TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 PSK-CHACHA20-POLY1305
TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 ECDHE-PSK-CHACHA20-POLY1305
TLS_DHE_PSK_WITH_CHACHA20_POLY1305_SHA256 DHE-PSK-CHACHA20-POLY1305
TLS_RSA_PSK_WITH_CHACHA20_POLY1305_SHA256 RSA-PSK-CHACHA20-POLY1305
=head2 Older names used by OpenSSL
The following names are accepted by older releases:
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA EDH-RSA-DES-CBC3-SHA (DHE-RSA-DES-CBC3-SHA)
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA EDH-DSS-DES-CBC3-SHA (DHE-DSS-DES-CBC3-SHA)
=head1 NOTES
@@ -627,19 +701,30 @@ Include all RC4 ciphers but leave out those without authentication:
openssl ciphers -v 'RC4:!COMPLEMENTOFDEFAULT'
Include all chiphers with RSA authentication but leave out ciphers without
Include all ciphers with RSA authentication but leave out ciphers without
encryption.
openssl ciphers -v 'RSA:!COMPLEMENTOFALL'
Set security level to 2 and display all ciphers consistent with level 2:
openssl ciphers -s -v 'ALL:@SECLEVEL=2'
=head1 SEE ALSO
L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ssl(3)|ssl(3)>
L<s_client(1)>, L<s_server(1)>, L<ssl(7)>
=head1 HISTORY
The B<COMPLENTOFALL> and B<COMPLEMENTOFDEFAULT> selection options
for cipherlist strings were added in OpenSSL 0.9.7.
The B<-V> option for the B<ciphers> command was added in OpenSSL 1.0.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

151
doc/apps/cms.pod
View File

@@ -7,6 +7,7 @@ cms - CMS utility
=head1 SYNOPSIS
B<openssl> B<cms>
[B<-help>]
[B<-encrypt>]
[B<-decrypt>]
[B<-sign>]
@@ -35,7 +36,36 @@ B<openssl> B<cms>
[B<-print>]
[B<-CAfile file>]
[B<-CApath dir>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-md digest>]
[B<-[cipher]>]
[B<-nointern>]
@@ -44,6 +74,8 @@ B<openssl> B<cms>
[B<-noattr>]
[B<-nosmimecap>]
[B<-binary>]
[B<-crlfeol>]
[B<-asciicrlf>]
[B<-nodetach>]
[B<-certfile file>]
[B<-certsout file>]
@@ -72,7 +104,7 @@ B<openssl> B<cms>
The B<cms> command handles S/MIME v3.1 mail. It can encrypt, decrypt, sign and
verify, compress and uncompress S/MIME messages.
=head1 COMMAND OPTIONS
=head1 OPTIONS
There are fourteen operation options that set the type of operation to be
performed. The meaning of the other options varies according to the operation
@@ -80,6 +112,10 @@ type.
=over 4
=item B<-help>
Print out a usage message.
=item B<-encrypt>
encrypt mail for the given recipient certificates. Input file is the message
@@ -153,13 +189,13 @@ B<EncrytedData> type and output the content.
=item B<-sign_receipt>
Generate and output a signed receipt for the supplied message. The input
Generate and output a signed receipt for the supplied message. The input
message B<must> contain a signed receipt request. Functionality is otherwise
similar to the B<-sign> operation.
=item B<-verify_receipt receipt>
Verify a signed receipt in filename B<receipt>. The input message B<must>
Verify a signed receipt in filename B<receipt>. The input message B<must>
contain the original receipt request. Functionality is otherwise similar
to the B<-verify> operation.
@@ -223,7 +259,7 @@ is S/MIME and it uses the multipart/signed MIME content type.
this option adds plain text (text/plain) MIME headers to the supplied
message if encrypting or signing. If decrypting or verifying it strips
off text headers: if the decrypted or verified message is not of MIME
off text headers: if the decrypted or verified message is not of MIME
type text/plain then an error occurs.
=item B<-noout>
@@ -248,6 +284,14 @@ B<-verify>. This directory must be a standard certificate directory: that
is a hash of each subject name (using B<x509 -hash>) should be linked
to each certificate.
=item B<-no-CAfile>
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-md digest>
digest algorithm to use when signing or resigning. If not present then the
@@ -257,11 +301,11 @@ default digest algorithm for the signing key will be used (usually SHA1).
the encryption algorithm to use. For example triple DES (168 bits) - B<-des3>
or 256 bit AES - B<-aes256>. Any standard algorithm name (as used by the
EVP_get_cipherbyname() function) can also be used preceded by a dash, for
example B<-aes_128_cbc>. See L<B<enc>|enc(1)> for a list of ciphers
EVP_get_cipherbyname() function) can also be used preceded by a dash, for
example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for a list of ciphers
supported by your version of OpenSSL.
If not specified triple DES is used. Only used with B<-encrypt> and
If not specified triple DES is used. Only used with B<-encrypt> and
B<-EncryptedData_create> commands.
=item B<-nointern>
@@ -300,6 +344,20 @@ effectively using CR and LF as end of line: as required by the S/MIME
specification. When this option is present no translation occurs. This
is useful when handling binary data which may not be in MIME format.
=item B<-crlfeol>
normally the output file uses a single B<LF> as end of line. When this
option is present B<CRLF> is used instead.
=item B<-asciicrlf>
when signing use ASCII CRLF format canonicalisation. This strips trailing
whitespace from all lines, deletes trailing blank lines at EOF and sets
the encapsulated content type. This option is normally used with detached
content and an output signature format of DER. This option is not normally
needed when verifying as it is enabled automatically if the encapsulated
content format is detected.
=item B<-nodetach>
when signing a message use opaque signing: this form is more resistant
@@ -343,7 +401,7 @@ identifier extension. Supported by B<-sign> and B<-encrypt> options.
=item B<-receipt_request_all -receipt_request_first>
for B<-sign> option include a signed receipt request. Indicate requests should
be provided by all receipient or first tier recipients (those mailed directly
be provided by all recipient or first tier recipients (those mailed directly
and not from a mailing list). Ignored it B<-receipt_request_from> is included.
=item B<-receipt_request_from emailaddress>
@@ -353,7 +411,7 @@ address where receipts should be supplied.
=item B<-receipt_request_to emailaddress>
Add an explicit email address where signed receipts should be sent to. This
Add an explicit email address where signed receipts should be sent to. This
option B<must> but supplied if a signed receipt it requested.
=item B<-receipt_request_print>
@@ -365,7 +423,7 @@ requests.
specify symmetric key to use. The key must be supplied in hex format and be
consistent with the algorithm used. Supported by the B<-EncryptedData_encrypt>
B<-EncrryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used
B<-EncryptedData_decrypt>, B<-encrypt> and B<-decrypt> options. When used
with B<-encrypt> or B<-decrypt> the supplied key is used to wrap or unwrap the
content encryption key using an AES key in the B<KEKRecipientInfo> type.
@@ -381,7 +439,7 @@ B<KEKRecipientInfo> structures.
set the encapsulated content type to B<type> if not supplied the B<Data> type
is used. The B<type> argument can be any valid OID name in either text or
numerical format.
numerical format.
=item B<-inkey file>
@@ -401,20 +459,20 @@ or to modify default parameters for ECDH.
=item B<-passin arg>
the private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<cert.pem...>
one or more certificates of message recipients: used when encrypting
a message.
a message.
=item B<-to, -from, -subject>
@@ -423,10 +481,16 @@ portion of a message so they may be included manually. If signing
then many S/MIME mail clients check the signers certificate's email
address matches that specified in the From: address.
=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains>
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set various certificate chain valiadition option. See the
L<B<verify>|verify(1)> manual page for details.
Set various certificate chain validation options. See the
L<verify(1)> manual page for details.
=back
@@ -438,7 +502,7 @@ a blank line. Piping the mail directly to sendmail is one way to
achieve the correct format.
The supplied message to be signed or encrypted must include the
necessary MIME headers or many S/MIME clients wont display it
necessary MIME headers or many S/MIME clients won't display it
properly (if at all). You can use the B<-text> option to automatically
add plain text headers.
@@ -459,7 +523,7 @@ The B<-resign> option uses an existing message digest when adding a new
signer. This means that attributes must be present in at least one existing
signer using the same message digest or this operation will fail.
The B<-stream> and B<-indef> options enable experimental streaming I/O support.
The B<-stream> and B<-indef> options enable streaming I/O support.
As a result the encoding is BER using indefinite length constructed encoding
and no longer DER. Streaming is supported for the B<-encrypt> operation and the
B<-sign> operation if the content is not detached.
@@ -473,10 +537,10 @@ attempt is made to locate the recipient by trying each potential recipient
in turn using the supplied private key. To thwart the MMA attack
(Bleichenbacher's attack on PKCS #1 v1.5 RSA padding) all recipients are
tried whether they succeed or not and if no recipients match the message
is "decrypted" using a random key which will typically output garbage.
is "decrypted" using a random key which will typically output garbage.
The B<-debug_decrypt> option can be used to disable the MMA attack protection
and return an error if no recipient can be found: this option should be used
with caution. For a fuller description see L<CMS_decrypt(3)|CMS_decrypt(3)>).
with caution. For a fuller description see L<CMS_decrypt(3)>).
=head1 EXIT CODES
@@ -537,29 +601,29 @@ be processed by the older B<smime> command.
Create a cleartext signed message:
openssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem
-signer mycert.pem
Create an opaque signed message
openssl cms -sign -in message.txt -text -out mail.msg -nodetach \
-signer mycert.pem
-signer mycert.pem
Create a signed message, include some additional certificates and
read the private key from another file:
openssl cms -sign -in in.txt -text -out mail.msg \
-signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
-signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
Create a signed message with two signers, use key identifier:
openssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -signer othercert.pem -keyid
-signer mycert.pem -signer othercert.pem -keyid
Send a signed message under Unix directly to sendmail, including headers:
openssl cms -sign -in in.txt -text -signer mycert.pem \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed message" | sendmail someone@somewhere
-from steve@openssl.org -to someone@somewhere \
-subject "Signed message" | sendmail someone@somewhere
Verify a message and extract the signer's certificate if successful:
@@ -568,15 +632,15 @@ Verify a message and extract the signer's certificate if successful:
Send encrypted mail using triple DES:
openssl cms -encrypt -in in.txt -from steve@openssl.org \
-to someone@somewhere -subject "Encrypted message" \
-des3 user.pem -out mail.msg
-to someone@somewhere -subject "Encrypted message" \
-des3 user.pem -out mail.msg
Sign and encrypt mail:
openssl cms -sign -in ml.txt -signer my.pem -text \
| openssl cms -encrypt -out mail.msg \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed and Encrypted message" -des3 user.pem
| openssl cms -encrypt -out mail.msg \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed and Encrypted message" -des3 user.pem
Note: the encryption command does not include the B<-text> option because the
message being encrypted already has MIME headers.
@@ -593,7 +657,7 @@ it with:
-----BEGIN PKCS7-----
-----END PKCS7-----
and using the command,
and using the command,
openssl cms -verify -inform PEM -in signature.pem -content content.txt
@@ -612,17 +676,17 @@ Add a signer to an existing message:
Sign mail using RSA-PSS:
openssl cms -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -keyopt rsa_padding_mode:pss
-signer mycert.pem -keyopt rsa_padding_mode:pss
Create encrypted mail using RSA-OAEP:
openssl cms -encrypt -in plain.txt -out mail.msg \
-recip cert.pem -keyopt rsa_padding_mode:oaep
-recip cert.pem -keyopt rsa_padding_mode:oaep
Use SHA256 KDF with an ECDH certificate:
openssl cms -encrypt -in plain.txt -out mail.msg \
-recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
-recip ecdhcert.pem -keyopt ecdh_kdf_md:sha256
=head1 BUGS
@@ -654,11 +718,20 @@ The B<keyopt> option was first added in OpenSSL 1.1.0
The use of B<-recip> to specify the recipient when encrypting mail was first
added to OpenSSL 1.1.0
Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0.
Support for RSA-OAEP and RSA-PSS was first added to OpenSSL 1.1.0.
The use of non-RSA keys with B<-encrypt> and B<-decrypt> was first added
to OpenSSL 1.1.0.
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
The -no_alt_chains options was first added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

73
doc/apps/config.pod
View File

@@ -1,4 +1,3 @@
=pod
=for comment openssl_manual_section:5
@@ -47,7 +46,8 @@ or B<${section::name}>. By using the form B<$ENV::name> environment
variables can be substituted. It is also possible to assign values to
environment variables by using the name B<ENV::name>, this will work
if the program looks up environment variables using the B<CONF> library
instead of calling B<getenv()> directly.
instead of calling getenv() directly. The value string must not exceed 64k in
length after variable expansion. Otherwise an error will occur.
It is possible to escape certain characters by using any kind of quote
or the B<\> character. By making the last character of a line a B<\>
@@ -56,21 +56,21 @@ the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognized.
=head1 OPENSSL LIBRARY CONFIGURATION
In OpenSSL 0.9.7 and later applications can automatically configure certain
Applications can automatically configure certain
aspects of OpenSSL using the master OpenSSL configuration file, or optionally
an alternative configuration file. The B<openssl> utility includes this
functionality: any sub command uses the master OpenSSL configuration file
unless an option is used in the sub command to use an alternative configuration
file.
To enable library configuration the default section needs to contain an
To enable library configuration the default section needs to contain an
appropriate line which points to the main configuration section. The default
name is B<openssl_conf> which is used by the B<openssl> utility. Other
applications may use an alternative name such as B<myapplicaton_conf>.
The configuration section should consist of a set of name value pairs which
contain specific module configuration information. The B<name> represents
the name of the I<configuration module> the meaning of the B<value> is
the name of the I<configuration module> the meaning of the B<value> is
module specific: it may, for example, represent a further configuration
section containing configuration module specific information. E.g.
@@ -91,7 +91,7 @@ section containing configuration module specific information. E.g.
The features of each configuration module are described below.
=head2 ASN1 OBJECT CONFIGURATION MODULE
=head2 ASN1 Object Configuration Module
This module has the name B<oid_section>. The value of this variable points
to a section containing name value pairs of OIDs: the name is the OID short
@@ -102,16 +102,16 @@ B<all> the B<openssl> utility sub commands can see the new objects as well
as any compliant applications. For example:
[new_oids]
some_new_oid = 1.2.3.4
some_other_oid = 1.2.3.5
In OpenSSL 0.9.8 it is also possible to set the value to the long name followed
It is also possible to set the value to the long name followed
by a comma and the numerical OID form. For example:
shortName = some object long name, 1.2.3.4
=head2 ENGINE CONFIGURATION MODULE
=head2 Engine Configuration Module
This ENGINE configuration module has the name B<engines>. The value of this
variable points to a section containing further ENGINE configuration
@@ -141,7 +141,7 @@ For example:
[bar_section]
... "bar" ENGINE specific commands ...
The command B<engine_id> is used to give the ENGINE name. If used this
The command B<engine_id> is used to give the ENGINE name. If used this
command must be first. For example:
[engine_section]
@@ -165,10 +165,10 @@ then an attempt will be made to initialize the ENGINE after all commands in
its section have been processed.
The command B<default_algorithms> sets the default algorithms an ENGINE will
supply using the functions B<ENGINE_set_default_string()>
supply using the functions ENGINE_set_default_string().
If the name matches none of the above command names it is assumed to be a
ctrl command which is sent to the ENGINE. The value of the command is the
ctrl command which is sent to the ENGINE. The value of the command is the
argument to the ctrl command. If the value is the string B<EMPTY> then no
value is sent to the command.
@@ -190,7 +190,7 @@ For example:
# Supply all default algorithms
default_algorithms = ALL
=head2 EVP CONFIGURATION MODULE
=head2 EVP Configuration Module
This modules has the name B<alg_section> which points to a section containing
algorithm commands.
@@ -208,6 +208,34 @@ For example:
fips_mode = on
=head2 SSL Configuration Module
This module has the name B<ssl_conf> which points to a section containing
SSL configurations.
Each line in the SSL configuration section contains the name of the
configuration and the section containing it.
Each configuration section consists of command value pairs for B<SSL_CONF>.
Each pair will be passed to a B<SSL_CTX> or B<SSL> structure if it calls
SSL_CTX_config() or SSL_config() with the appropriate configuration name.
Note: any characters before an initial dot in the configuration section are
ignored so the same command can be used multiple times.
For example:
ssl_conf = ssl_sect
[ssl_sect]
server = server_section
[server_section]
RSA.Certificate = server-rsa.pem
ECDSA.Certificate = server-ecdsa.pem
Ciphers = ALL:!RC4
=head1 NOTES
@@ -238,7 +266,7 @@ Here is a sample configuration file using some of the features
mentioned above.
# This is the default section.
HOME=/temp
RANDFILE= ${ENV::HOME}/.rnd
configdir=$ENV::HOME/config
@@ -264,11 +292,11 @@ This next example shows how to expand environment variables safely.
Suppose you want a variable called B<tmpfile> to refer to a
temporary filename. The directory it is placed in can determined by
the the B<TEMP> or B<TMP> environment variables but they may not be
the B<TEMP> or B<TMP> environment variables but they may not be
set to any value at all. If you just include the environment variable
names and the variable doesn't exist then this will cause an error when
an attempt is made to load the configuration file. By making use of the
default section both values can be looked up with B<TEMP> taking
default section both values can be looked up with B<TEMP> taking
priority and B</tmp> used if neither is defined:
TMP=/tmp
@@ -316,7 +344,7 @@ More complex OpenSSL library configuration. Add OID and don't enter FIPS mode:
# New OID shortname and long name
newoid2 = New OID 2 long name, 1.2.3.4.2
The above examples can be used with with any application supporting library
The above examples can be used with any application supporting library
configuration if "openssl_conf" is modified to match the appropriate "appname".
For example if the second sample file above is saved to "example.cnf" then
@@ -345,6 +373,15 @@ file.
=head1 SEE ALSO
L<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)>
L<x509(1)>, L<req(1)>, L<ca(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

22
doc/apps/crl.pod
View File

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

24
doc/apps/crl2pkcs7.pod
View File

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

122
doc/apps/dgst.pod
View File

@@ -2,18 +2,18 @@
=head1 NAME
dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md2, md4, md5, dss1 - message digests
dgst, sha, sha1, mdc2, ripemd160, sha224, sha256, sha384, sha512, md4, md5, blake2b, blake2s - message digests
=head1 SYNOPSIS
B<openssl> B<dgst>
[B<-sha|-sha1|-mdc2|-ripemd160|-sha224|-sha256|-sha384|-sha512|-md2|-md4|-md5|-dss1>]
B<openssl> B<dgst>
[B<-help>]
[B<-I<digest>>]
[B<-c>]
[B<-d>]
[B<-hex>]
[B<-binary>]
[B<-r>]
[B<-non-fips-allow>]
[B<-out filename>]
[B<-sign filename>]
[B<-keyform arg>]
@@ -22,8 +22,9 @@ B<openssl> B<dgst>
[B<-prverify filename>]
[B<-signature filename>]
[B<-hmac key>]
[B<-non-fips-allow>]
[B<-fips-fingerprint>]
[B<-engine id>]
[B<-engine_impl>]
[B<file...>]
B<openssl>
@@ -36,88 +37,92 @@ The digest functions output the message digest of a supplied file or files
in hexadecimal. The digest functions also generate and verify digital
signatures using message digests.
The generic name, B<dgst>, may be used with an option specifying the
algorithm to be used.
The default digest is I<sha256>.
A supported I<digest> name may also be used as the command name.
To see the list of supported algorithms, use the I<list --digest-commands>
command.
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-I<digest>>
Specifies name of a supported digest to be used. To see the list of
supported digests, use the command I<list --digest-commands>.
=item B<-c>
print out the digest in two digit groups separated by colons, only relevant if
Print out the digest in two digit groups separated by colons, only relevant if
B<hex> format output is used.
=item B<-d>
print out BIO debugging information.
Print out BIO debugging information.
=item B<-hex>
digest is to be output as a hex dump. This is the default case for a "normal"
Digest is to be output as a hex dump. This is the default case for a "normal"
digest as opposed to a digital signature. See NOTES below for digital
signatures using B<-hex>.
=item B<-binary>
output the digest or signature in binary form.
Output the digest or signature in binary form.
=item B<-r>
output the digest in the "coreutils" format used by programs like B<sha1sum>.
=item B<-non-fips-allow>
Allow use of non FIPS digest when in FIPS mode. This has no effect when not in
FIPS mode.
Output the digest in the "coreutils" format used by programs like B<sha1sum>.
=item B<-out filename>
filename to output to, or standard output by default.
Filename to output to, or standard output by default.
=item B<-sign filename>
digitally sign the digest using the private key in "filename".
Digitally sign the digest using the private key in "filename".
=item B<-keyform arg>
Specifies the key format to sign digest with. The DER, PEM, P12,
and ENGINE formats are supported.
=item B<-engine id>
Use engine B<id> for operations (including private key storage).
This engine is not used as source for digest algorithms, unless it is
also specified in the configuration file.
=item B<-sigopt nm:v>
Pass options to the signature algorithm during sign or verify operations.
Names and values of these options are algorithm-specific.
=item B<-passin arg>
the private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
The private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-verify filename>
verify the signature using the the public key in "filename".
Verify the signature using the public key in "filename".
The output is either "Verification OK" or "Verification Failure".
=item B<-prverify filename>
verify the signature using the the private key in "filename".
Verify the signature using the private key in "filename".
=item B<-signature filename>
the actual signature to verify.
The actual signature to verify.
=item B<-hmac key>
create a hashed MAC using "key".
Create a hashed MAC using "key".
=item B<-mac alg>
create MAC (keyed Message Authentication Code). The most popular MAC
Create MAC (keyed Message Authentication Code). The most popular MAC
algorithm is HMAC (hash-based MAC), but there are other MAC algorithms
which are not based on hash, for instance B<gost-mac> algorithm,
supported by B<ccgost> engine. MAC keys and other options should be set
@@ -128,11 +133,11 @@ via B<-macopt> parameter.
Passes options to MAC algorithm, specified by B<-mac> key.
Following options are supported by both by B<HMAC> and B<gost-mac>:
=over 8
=over 4
=item B<key:string>
Specifies MAC key as alphnumeric string (use if key contain printable
Specifies MAC key as alphanumeric string (use if key contain printable
characters only). String length must conform to any restrictions of
the MAC algorithm for example exactly 32 chars for gost-mac.
@@ -146,24 +151,31 @@ for example exactly 32 chars for gost-mac.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
A file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-non-fips-allow>
enable use of non-FIPS algorithms such as MD5 even in FIPS mode.
all others.
=item B<-fips-fingerprint>
compute HMAC using a specific key
for certain OpenSSL-FIPS operations.
Compute HMAC using a specific key for certain OpenSSL-FIPS operations.
=item B<-engine id>
Use engine B<id> for operations (including private key storage).
This engine is not used as source for digest algorithms, unless it is
also specified in the configuration file or B<-engine_impl> is also
specified.
=item B<-engine_impl>
When used with the B<-engine> option, it specifies to also use
engine B<id> for digest operations.
=item B<file...>
file or files to digest. If no files are specified then standard input is
File or files to digest. If no files are specified then standard input is
used.
=back
@@ -185,8 +197,13 @@ To verify a signature:
=head1 NOTES
The digest of choice for all new applications is SHA1. Other digests are
however still widely used.
The digest mechanisms that are available will depend on the options
used when building OpenSSL.
The B<list digest-commands> command can be used to list them.
New or agile applications should use probably use SHA-256. Other digests,
particularly SHA-1 and MD5, are still widely used for interoperating
with existing formats and protocols.
When signing a file, B<dgst> will automatically determine the algorithm
(RSA, ECC, etc) to use for signing based on the private key's ASN.1 info.
@@ -204,5 +221,18 @@ Hex signatures cannot be verified using B<openssl>. Instead, use "xxd -r"
or similar program to transform the hex signature into a binary signature
prior to verification.
=head1 HISTORY
The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0
The FIPS-related options were removed in OpenSSL 1.1.0
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

32
doc/apps/dhparam.pod
View File

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

28
doc/apps/dsa.pod
View File

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

26
doc/apps/dsaparam.pod
View File

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

50
doc/apps/ec.pod
View File

@@ -7,6 +7,7 @@ ec - EC key processing
=head1 SYNOPSIS
B<openssl> B<ec>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
@@ -23,20 +24,26 @@ B<openssl> B<ec>
[B<-pubout>]
[B<-conv_form arg>]
[B<-param_enc arg>]
[B<-no_public>]
[B<-check>]
[B<-engine id>]
=head1 DESCRIPTION
The B<ec> command processes EC keys. They can be converted between various
forms and their components printed out. B<Note> OpenSSL uses the
forms and their components printed out. B<Note> OpenSSL uses the
private key format specified in 'SEC 1: Elliptic Curve Cryptography'
(http://www.secg.org/). To convert a OpenSSL EC private key into the
(http://www.secg.org/). To convert an OpenSSL EC private key into the
PKCS#8 private key format use the B<pkcs8> command.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option with a private key uses
@@ -48,7 +55,7 @@ PKCS#8 format is also accepted.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -60,7 +67,7 @@ prompted for.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-out filename>
@@ -72,11 +79,11 @@ filename.
=item B<-passout arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-des|-des3|-idea>
These options encrypt the private key with the DES, triple DES, IDEA or
These options encrypt the private key with the DES, triple DES, IDEA or
any other cipher supported by OpenSSL before outputting it. A pass phrase is
prompted for.
If none of these options is specified the key is written in plain text. This
@@ -122,12 +129,20 @@ the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
This specifies how the elliptic curve parameters are encoded.
Possible value are: B<named_curve>, i.e. the ec parameters are
specified by a OID, or B<explicit> where the ec parameters are
explicitly given (see RFC 3279 for the definition of the
specified by an OID, or B<explicit> where the ec parameters are
explicitly given (see RFC 3279 for the definition of the
EC parameters structures). The default value is B<named_curve>.
B<Note> the B<implicitlyCA> alternative ,as specified in RFC 3279,
B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279,
is currently not implemented in OpenSSL.
=item B<-no_public>
This option omits the public key components from the private key output.
=item B<-check>
this option checks the consistency of an EC private or public key.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<ec>
@@ -155,7 +170,7 @@ To encrypt a private key using triple DES:
openssl ec -in key.pem -des3 -out keyout.pem
To convert a private key from PEM to DER format:
To convert a private key from PEM to DER format:
openssl ec -in key.pem -outform DER -out keyout.der
@@ -177,14 +192,15 @@ To change the point conversion form to B<compressed>:
=head1 SEE ALSO
L<ecparam(1)|ecparam(1)>, L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>
L<ecparam(1)>, L<dsa(1)>, L<rsa(1)>
=head1 HISTORY
=head1 COPYRIGHT
The ec command was first introduced in OpenSSL 0.9.8.
Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
=head1 AUTHOR
Nils Larsch for the OpenSSL project (http://www.openssl.org).
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

38
doc/apps/ecparam.pod
View File

@@ -7,6 +7,7 @@ ecparam - EC parameter manipulation and generation
=head1 SYNOPSIS
B<openssl ecparam>
[B<-help>]
[B<-inform DER|PEM>]
[B<-outform DER|PEM>]
[B<-in filename>]
@@ -32,16 +33,20 @@ This command is used to manipulate or generate EC parameter files.
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN.1 DER encoded
form compatible with RFC 3279 EcpkParameters. The PEM form is the default
format: it consists of the B<DER> format base64 encoded with additional
format: it consists of the B<DER> format base64 encoded with additional
header and footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -66,7 +71,7 @@ This option prints out the EC parameters in human readable form.
=item B<-C>
This option converts the EC parameters into C code. The parameters can then
be loaded by calling the B<get_ec_group_XXX()> function.
be loaded by calling the get_ec_group_XXX() function.
=item B<-check>
@@ -96,10 +101,10 @@ the preprocessor macro B<OPENSSL_EC_BIN_PT_COMP> at compile time.
This specifies how the elliptic curve parameters are encoded.
Possible value are: B<named_curve>, i.e. the ec parameters are
specified by a OID, or B<explicit> where the ec parameters are
explicitly given (see RFC 3279 for the definition of the
specified by an OID, or B<explicit> where the ec parameters are
explicitly given (see RFC 3279 for the definition of the
EC parameters structures). The default value is B<named_curve>.
B<Note> the B<implicitlyCA> alternative ,as specified in RFC 3279,
B<Note> the B<implicitlyCA> alternative, as specified in RFC 3279,
is currently not implemented in OpenSSL.
=item B<-no_seed>
@@ -109,13 +114,13 @@ is included in the ECParameters structure (see RFC 3279).
=item B<-genkey>
This option will generate a EC private key using the specified parameters.
This option will generate an EC private key using the specified parameters.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -136,7 +141,7 @@ PEM format EC parameters use the header and footer lines:
-----END EC PARAMETERS-----
OpenSSL is currently not able to generate new groups and therefore
B<ecparam> can only create EC parameters from known (named) curves.
B<ecparam> can only create EC parameters from known (named) curves.
=head1 EXAMPLES
@@ -166,14 +171,15 @@ To print out the EC parameters to standard output:
=head1 SEE ALSO
L<ec(1)|ec(1)>, L<dsaparam(1)|dsaparam(1)>
L<ec(1)>, L<dsaparam(1)>
=head1 HISTORY
=head1 COPYRIGHT
The ecparam command was first introduced in OpenSSL 0.9.8.
Copyright 2003-2016 The OpenSSL Project Authors. All Rights Reserved.
=head1 AUTHOR
Nils Larsch for the OpenSSL project (http://www.openssl.org)
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

72
doc/apps/enc.pod
View File

@@ -7,6 +7,8 @@ enc - symmetric cipher routines
=head1 SYNOPSIS
B<openssl enc -ciphername>
[B<-help>]
[B<-ciphers>]
[B<-in filename>]
[B<-out filename>]
[B<-pass arg>]
@@ -22,7 +24,7 @@ B<openssl enc -ciphername>
[B<-salt>]
[B<-nosalt>]
[B<-z>]
[B<-md>]
[B<-md digest>]
[B<-p>]
[B<-P>]
[B<-bufsize number>]
@@ -42,6 +44,14 @@ either by itself or in addition to the encryption or decryption.
=over 4
=item B<-help>
Print out a usage message.
=item B<-ciphers>
List all supported ciphers.
=item B<-in filename>
the input filename, standard input by default.
@@ -53,17 +63,7 @@ the output filename, standard output by default.
=item B<-pass arg>
the password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-salt>
use a salt in the key derivation routines. This is the default.
=item B<-nosalt>
don't use a salt in the key derivation routines. This option B<SHOULD NOT> be
used except for test purposes or compatibility with ancient versions of OpenSSL
and SSLeay.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-e>
@@ -98,9 +98,16 @@ read the password to derive the key from the first line of B<filename>.
This is for compatibility with previous versions of OpenSSL. Superseded by
the B<-pass> argument.
=item B<-md digest>
Use the specified digest to create the key from the passphrase.
The default algorithm is sha-256.
=item B<-nosalt>
do not use a salt
don't use a salt in the key derivation routines. This option B<SHOULD NOT> be
used except for test purposes or compatibility with ancient versions of
OpenSSL.
=item B<-salt>
@@ -170,7 +177,7 @@ configuration file is read and any ENGINEs loaded.
Engines which provide entirely new encryption algorithms (such as ccgost
engine which provides gost89 algorithm) should be configured in the
configuration file. Engines, specified in the command line using -engine
options can only be used for hadrware-assisted implementations of
options can only be used for hardware-assisted implementations of
ciphers, which are supported by OpenSSL core or other engine, specified
in the configuration file.
@@ -181,7 +188,7 @@ A password will be prompted for to derive the key and IV if necessary.
The B<-salt> option should B<ALWAYS> be used if the key is being derived
from a password unless you want compatibility with previous versions of
OpenSSL and SSLeay.
OpenSSL.
Without the B<-salt> option it is possible to perform efficient dictionary
attacks on the password and to attack stream cipher encrypted data. The reason
@@ -212,7 +219,7 @@ Note that some of these ciphers can be disabled at compile time
and some are available only if an appropriate engine is configured
in the configuration file. The output of the B<enc> command run with
unsupported options (for example B<openssl enc -help>) includes a
list of ciphers, supported by your versesion of OpenSSL, including
list of ciphers, supported by your version of OpenSSL, including
ones provided by configured engines.
The B<enc> program does not support authenticated encryption modes
@@ -255,7 +262,7 @@ authentication tag.
desx DESX algorithm.
gost89 GOST 28147-89 in CFB mode (provided by ccgost engine)
gost89-cnt `GOST 28147-89 in CNT mode (provided by ccgost engine)
gost89-cnt `GOST 28147-89 in CNT mode (provided by ccgost engine)
idea-cbc IDEA algorithm in CBC mode
idea same as idea-cbc
@@ -281,13 +288,13 @@ authentication tag.
rc5-ecb RC5 cipher in ECB mode
rc5-ofb RC5 cipher in OFB mode
aes-[128|192|256]-cbc 128/192/256 bit AES in CBC mode
aes-[128|192|256] Alias for aes-[128|192|256]-cbc
aes-[128|192|256]-cfb 128/192/256 bit AES in 128 bit CFB mode
aes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode
aes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode
aes-[128|192|256]-ecb 128/192/256 bit AES in ECB mode
aes-[128|192|256]-ofb 128/192/256 bit AES in OFB mode
aes-[128|192|256]-cbc 128/192/256 bit AES in CBC mode
aes[128|192|256] Alias for aes-[128|192|256]-cbc
aes-[128|192|256]-cfb 128/192/256 bit AES in 128 bit CFB mode
aes-[128|192|256]-cfb1 128/192/256 bit AES in 1 bit CFB mode
aes-[128|192|256]-cfb8 128/192/256 bit AES in 8 bit CFB mode
aes-[128|192|256]-ecb 128/192/256 bit AES in ECB mode
aes-[128|192|256]-ofb 128/192/256 bit AES in OFB mode
=head1 EXAMPLES
@@ -297,11 +304,11 @@ Just base64 encode a binary file:
Decode the same file
openssl base64 -d -in file.b64 -out file.bin
openssl base64 -d -in file.b64 -out file.bin
Encrypt a file using triple DES in CBC mode using a prompted password:
openssl des3 -salt -in file.txt -out file.des3
openssl des3 -salt -in file.txt -out file.des3
Decrypt a file using a supplied password:
@@ -330,4 +337,17 @@ The B<enc> program only supports a fixed number of algorithms with
certain parameters. So if, for example, you want to use RC2 with a
76 bit key or RC4 with an 84 bit key you can't use this program.
=head1 HISTORY
The default digest was changed from MD5 to SHA256 in Openssl 1.1.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

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

18
doc/apps/errstr.pod
View File

@@ -11,10 +11,14 @@ B<openssl errstr error_code>
=head1 DESCRIPTION
Sometimes an application will not load error message and only
numerical forms will be available. The B<errstr> utility can be used to
numerical forms will be available. The B<errstr> utility can be used to
display the meaning of the hex code. The hex code is the hex digits after the
second colon.
=head1 OPTIONS
None.
=head1 EXAMPLE
The error code:
@@ -22,18 +26,20 @@ The error code:
27594:error:2006D080:lib(32):func(109):reason(128):bss_file.c:107:
can be displayed with:
openssl errstr 2006D080
to produce the error message:
error:2006D080:BIO routines:BIO_new_file:no such file
=head1 SEE ALSO
=head1 COPYRIGHT
L<err(3)|err(3)>,
L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>,
L<SSL_load_error_strings(3)|SSL_load_error_strings(3)>
Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

27
doc/apps/gendsa.pod
View File

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

79
doc/apps/genpkey.pod
View File

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

34
doc/apps/genrsa.pod
View File

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

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

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

18
doc/apps/nseq.pod
View File

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

145
doc/apps/ocsp.pod
View File

@@ -7,6 +7,7 @@ ocsp - Online Certificate Status Protocol utility
=head1 SYNOPSIS
B<openssl> B<ocsp>
[B<-help>]
[B<-out file>]
[B<-issuer file>]
[B<-cert file>]
@@ -25,12 +26,41 @@ B<openssl> B<ocsp>
[B<-nonce>]
[B<-no_nonce>]
[B<-url URL>]
[B<-host host:n>]
[B<-header name value>]
[B<-host host:port>]
[B<-header>]
[B<-path>]
[B<-CApath dir>]
[B<-CAfile file>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-VAfile file>]
[B<-validity_period n>]
[B<-status_age n>]
@@ -65,10 +95,19 @@ The B<ocsp> command performs many common OCSP tasks. It can be used
to print out requests and responses, create requests and send queries
to an OCSP responder and behave like a mini OCSP server itself.
=head1 OCSP CLIENT OPTIONS
=head1 OPTIONS
This command operates as either a client or a server.
The options are described below, divided into those two modes.
=head2 OCSP Client Options
=over 4
=item B<-help>
Print out a usage message.
=item B<-out filename>
specify output filename, default is standard output.
@@ -107,7 +146,7 @@ Additional certificates to include in the signed request.
=item B<-nonce>, B<-no_nonce>
Add an OCSP nonce extension to a request or disable OCSP nonce addition.
Normally if an OCSP request is input using the B<respin> option no
Normally if an OCSP request is input using the B<reqin> option no
nonce is added: using the B<nonce> option will force addition of a nonce.
If an OCSP request is being created (using B<cert> and B<serial> options)
a nonce is automatically added specifying B<no_nonce> overrides this.
@@ -134,15 +173,14 @@ specify the responder URL. Both HTTP and HTTPS (SSL/TLS) URLs can be specified.
if the B<host> option is present then the OCSP request is sent to the host
B<hostname> on port B<port>. B<path> specifies the HTTP path name to use
or "/" by default.
or "/" by default. This is equivalent to specifying B<-url> with scheme
http:// and the given hostname, port, and pathname.
=item B<-header name value>
=item B<-header name=value>
If sending a request to an OCSP server, then the specified header name and
value are added to the HTTP request. Note that the B<name> and B<value> must
be specified as two separate parameters, not as a single quoted string, and
that the header name does not have the trailing colon.
Some OCSP responders require a Host header; use this flag to provide it.
Adds the header B<name> with the specified B<value> to the OCSP request
that is sent to the responder.
This may be repeated.
=item B<-timeout seconds>
@@ -153,9 +191,24 @@ connection timeout to the OCSP responder in seconds
file or pathname containing trusted CA certificates. These are used to verify
the signature on the OCSP response.
=item B<-no_alt_chains>
=item B<-no-CAfile>
See L<B<verify>|verify(1)> manual page for details.
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set different certificate verification options.
See L<verify(1)> manual page for details.
=item B<-verify_other file>
@@ -218,26 +271,29 @@ only be used for testing purposes.
=item B<-validity_period nsec>, B<-status_age age>
these options specify the range of times, in seconds, which will be tolerated
in an OCSP response. Each certificate status response includes a B<notBefore> time and
an optional B<notAfter> time. The current time should fall between these two values, but
the interval between the two times may be only a few seconds. In practice the OCSP
responder and clients clocks may not be precisely synchronised and so such a check
may fail. To avoid this the B<-validity_period> option can be used to specify an
acceptable error range in seconds, the default value is 5 minutes.
in an OCSP response. Each certificate status response includes a B<notBefore>
time and an optional B<notAfter> time. The current time should fall between
these two values, but the interval between the two times may be only a few
seconds. In practice the OCSP responder and clients clocks may not be precisely
synchronised and so such a check may fail. To avoid this the
B<-validity_period> option can be used to specify an acceptable error range in
seconds, the default value is 5 minutes.
If the B<notAfter> time is omitted from a response then this means that new status
information is immediately available. In this case the age of the B<notBefore> field
is checked to see it is not older than B<age> seconds old. By default this additional
check is not performed.
If the B<notAfter> time is omitted from a response then this means that new
status information is immediately available. In this case the age of the
B<notBefore> field is checked to see it is not older than B<age> seconds old.
By default this additional check is not performed.
=item B<-md5|-sha1|-sha256|-ripemod160|...>
=item B<-[digest]>
this option sets digest algorithm to use for certificate identification
in the OCSP request. By default SHA-1 is used.
this option sets digest algorithm to use for certificate identification in the
OCSP request. Any digest supported by the OpenSSL B<dgst> command can be used.
The default is SHA-1. This option may be used multiple times to specify the
digest used by subsequent certificate identifiers.
=back
=head1 OCSP SERVER OPTIONS
=head2 OCSP Server Options
=over 4
@@ -249,7 +305,7 @@ information.
If the B<index> option is specified the B<ocsp> utility is in responder mode, otherwise
it is in client mode. The request(s) the responder processes can be either specified on
the command line (using B<issuer> and B<serial> options), supplied in a file (using the
B<respin> option) or via external OCSP clients (if B<port> or B<url> is specified).
B<reqin> option) or via external OCSP clients (if B<port> or B<url> is specified).
If the B<index> option is present then the B<CA> and B<rsigner> options must also be
present.
@@ -286,13 +342,13 @@ option.
=item B<-nrequest number>
The OCSP server will exit after receiving B<number> requests, default unlimited.
The OCSP server will exit after receiving B<number> requests, default unlimited.
=item B<-nmin minutes>, B<-ndays days>
Number of minutes or days when fresh revocation information is available: used in the
B<nextUpdate> field. If neither option is present then the B<nextUpdate> field is
omitted meaning fresh revocation information is immediately available.
B<nextUpdate> field. If neither option is present then the B<nextUpdate> field
is omitted meaning fresh revocation information is immediately available.
=back
@@ -354,7 +410,7 @@ format of revocation is also inefficient for large quantities of revocation
data.
It is possible to run the B<ocsp> application in responder mode via a CGI
script using the B<respin> and B<respout> options.
script using the B<reqin> and B<respout> options.
=head1 EXAMPLES
@@ -362,40 +418,49 @@ Create an OCSP request and write it to a file:
openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem -reqout req.der
Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the
response to a file and print it out in text form
Send a query to an OCSP responder with URL http://ocsp.myhost.com/ save the
response to a file, print it out in text form, and verify the response:
openssl ocsp -issuer issuer.pem -cert c1.pem -cert c2.pem \
-url http://ocsp.myhost.com/ -resp_text -respout resp.der
Read in an OCSP response and print out text form:
openssl ocsp -respin resp.der -text
openssl ocsp -respin resp.der -text -noverify
OCSP server on port 8888 using a standard B<ca> configuration, and a separate
responder certificate. All requests and responses are printed to a file.
openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
-text -out log.txt
-text -out log.txt
As above but exit after processing one request:
openssl ocsp -index demoCA/index.txt -port 8888 -rsigner rcert.pem -CA demoCA/cacert.pem
-nrequest 1
Query status information using internally generated request:
Query status information using an internally generated request:
openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
-issuer demoCA/cacert.pem -serial 1
Query status information using request read from a file, write response to a
second file.
Query status information using request read from a file, and write the response
to a second file.
openssl ocsp -index demoCA/index.txt -rsigner rcert.pem -CA demoCA/cacert.pem
-reqin req.der -respout resp.der
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
The -no_alt_chains options was first added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

148
doc/apps/openssl.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -12,7 +11,7 @@ I<command>
[ I<command_opts> ]
[ I<command_args> ]
B<openssl> [ B<list-standard-commands> | B<list-message-digest-commands> | B<list-cipher-commands> | B<list-cipher-algorithms> | B<list-message-digest-algorithms> | B<list-public-key-algorithms>]
B<openssl> B<list> [ B<standard-commands> | B<digest-commands> | B<cipher-commands> | B<cipher-algorithms> | B<digest-algorithms> | B<public-key-algorithms>]
B<openssl> B<no->I<XXX> [ I<arbitrary options> ]
@@ -23,12 +22,12 @@ v2/v3) and Transport Layer Security (TLS v1) network protocols and related
cryptography standards required by them.
The B<openssl> program is a command line tool for using the various
cryptography functions of OpenSSL's B<crypto> library from the shell.
It can be used for
cryptography functions of OpenSSL's B<crypto> library from the shell.
It can be used for
o Creation and management of private keys, public keys and parameters
o Public key cryptographic operations
o Creation of X.509 certificates, CSRs and CRLs
o Creation of X.509 certificates, CSRs and CRLs
o Calculation of Message Digests
o Encryption and Decryption with Ciphers
o SSL/TLS Client and Server Tests
@@ -41,20 +40,29 @@ The B<openssl> program provides a rich variety of commands (I<command> in the
SYNOPSIS above), each of which often has a wealth of options and arguments
(I<command_opts> and I<command_args> in the SYNOPSIS).
The pseudo-commands B<list-standard-commands>, B<list-message-digest-commands>,
and B<list-cipher-commands> output a list (one entry per line) of the names
Many commands use an external configuration file for some or all of their
arguments and have a B<-config> option to specify that file.
The environment variable B<OPENSSL_CONF> can be used to specify
the location of the file.
If the environment variable is not specified, then the file is named
B<openssl.cnf> in the default certificate storage area, whose value
depends on the configuration flags specified when the OpenSSL
was built.
The list parameters B<standard-commands>, B<digest-commands>,
and B<cipher-commands> output a list (one entry per line) of the names
of all standard commands, message digest commands, or cipher commands,
respectively, that are available in the present B<openssl> utility.
The pseudo-commands B<list-cipher-algorithms> and
B<list-message-digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as:
The list parameters B<cipher-algorithms> and
B<digest-algorithms> list all cipher and message digest names, one entry per line. Aliases are listed as:
from => to
The pseudo-command B<list-public-key-algorithms> lists all supported public
The list parameter B<public-key-algorithms> lists all supported public
key algorithms.
The pseudo-command B<no->I<XXX> tests whether a command of the
The command B<no->I<XXX> tests whether a command of the
specified name is available. If no command named I<XXX> exists, it
returns 0 (success) and prints B<no->I<XXX>; otherwise it returns 1
and prints I<XXX>. In both cases, the output goes to B<stdout> and
@@ -63,11 +71,11 @@ are always ignored. Since for each cipher there is a command of the
same name, this provides an easy way for shell scripts to test for the
availability of ciphers in the B<openssl> program. (B<no->I<XXX> is
not able to detect pseudo-commands such as B<quit>,
B<list->I<...>B<-commands>, or B<no->I<XXX> itself.)
B<list>, or B<no->I<XXX> itself.)
=head2 STANDARD COMMANDS
=head2 Standard Commands
=over 10
=over 4
=item L<B<asn1parse>|asn1parse(1)>
@@ -75,7 +83,7 @@ Parse an ASN.1 sequence.
=item L<B<ca>|ca(1)>
Certificate Authority (CA) Management.
Certificate Authority (CA) Management.
=item L<B<ciphers>|ciphers(1)>
@@ -83,7 +91,7 @@ Cipher Suite Description Determination.
=item L<B<cms>|cms(1)>
CMS (Cryptographic Message Syntax) utility
CMS (Cryptographic Message Syntax) utility.
=item L<B<crl>|crl(1)>
@@ -104,9 +112,8 @@ Obsoleted by L<B<dhparam>|dhparam(1)>.
=item L<B<dhparam>|dhparam(1)>
Generation and Management of Diffie-Hellman Parameters. Superseded by
L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>
Generation and Management of Diffie-Hellman Parameters. Superseded by
L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>.
=item L<B<dsa>|dsa(1)>
@@ -114,16 +121,16 @@ DSA Data Management.
=item L<B<dsaparam>|dsaparam(1)>
DSA Parameter Generation and Management. Superseded by
L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>
DSA Parameter Generation and Management. Superseded by
L<B<genpkey>|genpkey(1)> and L<B<pkeyparam>|pkeyparam(1)>.
=item L<B<ec>|ec(1)>
EC (Elliptic curve) key processing
EC (Elliptic curve) key processing.
=item L<B<ecparam>|ecparam(1)>
EC parameter manipulation and generation
EC parameter manipulation and generation.
=item L<B<enc>|enc(1)>
@@ -131,7 +138,7 @@ Encoding with Ciphers.
=item L<B<engine>|engine(1)>
Engine (loadble module) information and manipulation.
Engine (loadable module) information and manipulation.
=item L<B<errstr>|errstr(1)>
@@ -144,8 +151,8 @@ Obsoleted by L<B<dhparam>|dhparam(1)>.
=item L<B<gendsa>|gendsa(1)>
Generation of DSA Private Key from Parameters. Superseded by
L<B<genpkey>|genpkey(1)> and L<B<pkey>|pkey(1)>
Generation of DSA Private Key from Parameters. Superseded by
L<B<genpkey>|genpkey(1)> and L<B<pkey>|pkey(1)>.
=item L<B<genpkey>|genpkey(1)>
@@ -153,11 +160,11 @@ Generation of Private Key or Parameters.
=item L<B<genrsa>|genrsa(1)>
Generation of RSA Private Key. Superceded by L<B<genpkey>|genpkey(1)>.
Generation of RSA Private Key. Superseded by L<B<genpkey>|genpkey(1)>.
=item L<B<nseq>|nseq(1)>
Create or examine a netscape certificate sequence
Create or examine a Netscape certificate sequence.
=item L<B<ocsp>|ocsp(1)>
@@ -203,7 +210,7 @@ RSA key management.
=item L<B<rsautl>|rsautl(1)>
RSA utility for signing, verification, encryption, and decryption. Superseded
by L<B<pkeyutl>|pkeyutl(1)>
by L<B<pkeyutl>|pkeyutl(1)>.
=item L<B<s_client>|s_client(1)>
@@ -239,11 +246,11 @@ Algorithm Speed Measurement.
=item L<B<spkac>|spkac(1)>
SPKAC printing and generating utility
SPKAC printing and generating utility.
=item L<B<ts>|ts(1)>
Time Stamping Authority tool (client/server)
Time Stamping Authority tool (client/server).
=item L<B<verify>|verify(1)>
@@ -259,9 +266,9 @@ X.509 Certificate Data Management.
=back
=head2 MESSAGE DIGEST COMMANDS
=head2 Message Digest Commands
=over 10
=over 4
=item B<md2>
@@ -279,11 +286,11 @@ MDC2 Digest
RMD-160 Digest
=item B<sha>
=item B<sha>
SHA Digest
=item B<sha1>
=item B<sha1>
SHA-1 Digest
@@ -305,9 +312,9 @@ SHA-512 Digest
=back
=head2 ENCODING AND CIPHER COMMANDS
=head2 Encoding and Cipher Commands
=over 10
=over 4
=item B<base64>
@@ -351,7 +358,22 @@ RC5 Cipher
=back
=head1 PASS PHRASE ARGUMENTS
=head1 OPTIONS
Details of which options are available depend on the specific command.
This section describes some common options with common behavior.
=head2 Common Options
=over 4
=item B<-help>
Provides a terse summary of all options.
=back
=head2 Pass Phrase Options
Several commands accept password arguments, typically using B<-passin>
and B<-passout> for input and output passwords respectively. These allow
@@ -361,23 +383,23 @@ password argument is given and a password is required then the user is
prompted to enter one: this will typically be read from the current
terminal with echoing turned off.
=over 10
=over 4
=item B<pass:password>
the actual password is B<password>. Since the password is visible
The actual password is B<password>. Since the password is visible
to utilities (like 'ps' under Unix) this form should only be used
where security is not important.
=item B<env:var>
obtain the password from the environment variable B<var>. Since
Obtain the password from the environment variable B<var>. Since
the environment of other processes is visible on certain platforms
(e.g. ps under certain Unix OSes) this option should be used with caution.
=item B<file:pathname>
the first line of B<pathname> is the password. If the same B<pathname>
The first line of B<pathname> is the password. If the same B<pathname>
argument is supplied to B<-passin> and B<-passout> arguments then the first
line will be used for the input password and the next line for the output
password. B<pathname> need not refer to a regular file: it could for example
@@ -385,38 +407,44 @@ refer to a device or named pipe.
=item B<fd:number>
read the password from the file descriptor B<number>. This can be used to
Read the password from the file descriptor B<number>. This can be used to
send the data via a pipe for example.
=item B<stdin>
read the password from standard input.
Read the password from standard input.
=back
=head1 SEE ALSO
L<asn1parse(1)|asn1parse(1)>, L<ca(1)|ca(1)>, L<config(5)|config(5)>,
L<crl(1)|crl(1)>, L<crl2pkcs7(1)|crl2pkcs7(1)>, L<dgst(1)|dgst(1)>,
L<dhparam(1)|dhparam(1)>, L<dsa(1)|dsa(1)>, L<dsaparam(1)|dsaparam(1)>,
L<enc(1)|enc(1)>, L<gendsa(1)|gendsa(1)>, L<genpkey(1)|genpkey(1)>,
L<genrsa(1)|genrsa(1)>, L<nseq(1)|nseq(1)>, L<openssl(1)|openssl(1)>,
L<passwd(1)|passwd(1)>,
L<pkcs12(1)|pkcs12(1)>, L<pkcs7(1)|pkcs7(1)>, L<pkcs8(1)|pkcs8(1)>,
L<rand(1)|rand(1)>, L<req(1)|req(1)>, L<rsa(1)|rsa(1)>,
L<rsautl(1)|rsautl(1)>, L<s_client(1)|s_client(1)>,
L<s_server(1)|s_server(1)>, L<s_time(1)|s_time(1)>,
L<smime(1)|smime(1)>, L<spkac(1)|spkac(1)>,
L<verify(1)|verify(1)>, L<version(1)|version(1)>, L<x509(1)|x509(1)>,
L<crypto(3)|crypto(3)>, L<ssl(3)|ssl(3)>, L<x509v3_config(5)|x509v3_config(5)>
L<asn1parse(1)>, L<ca(1)>, L<config(5)>,
L<crl(1)>, L<crl2pkcs7(1)>, L<dgst(1)>,
L<dhparam(1)>, L<dsa(1)>, L<dsaparam(1)>,
L<enc(1)>, L<engine(1)>, L<gendsa(1)>, L<genpkey(1)>,
L<genrsa(1)>, L<nseq(1)>, L<openssl(1)>,
L<passwd(1)>,
L<pkcs12(1)>, L<pkcs7(1)>, L<pkcs8(1)>,
L<rand(1)>, L<req(1)>, L<rsa(1)>,
L<rsautl(1)>, L<s_client(1)>,
L<s_server(1)>, L<s_time(1)>,
L<smime(1)>, L<spkac(1)>,
L<verify(1)>, L<version(1)>, L<x509(1)>,
L<crypto(7)>, L<ssl(7)>, L<x509v3_config(5)>
=head1 HISTORY
The openssl(1) document appeared in OpenSSL 0.9.2.
The B<list->I<XXX>B<-commands> pseudo-commands were added in OpenSSL 0.9.3;
The B<list->I<XXX>B<-algorithms> pseudo-commands were added in OpenSSL 1.0.0;
the B<no->I<XXX> pseudo-commands were added in OpenSSL 0.9.5a.
For notes on the availability of other commands, see their individual
manual pages.
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

14
doc/apps/passwd.pod
View File

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

84
doc/apps/pkcs12.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,9 +7,10 @@ pkcs12 - PKCS#12 file utility
=head1 SYNOPSIS
B<openssl> B<pkcs12>
[B<-help>]
[B<-export>]
[B<-chain>]
[B<-inkey filename>]
[B<-inkey file_or_id>]
[B<-certfile filename>]
[B<-name name>]
[B<-caname name>]
@@ -39,6 +39,8 @@ B<openssl> B<pkcs12>
[B<-rand file(s)>]
[B<-CAfile file>]
[B<-CApath dir>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-CSP name>]
=head1 DESCRIPTION
@@ -47,7 +49,7 @@ The B<pkcs12> command allows PKCS#12 files (sometimes referred to as
PFX files) to be created and parsed. PKCS#12 files are used by several
programs including Netscape, MSIE and MS Outlook.
=head1 COMMAND OPTIONS
=head1 OPTIONS
There are a lot of options the meaning of some depends of whether a PKCS#12 file
is being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12
@@ -57,6 +59,10 @@ file can be created by using the B<-export> option (see below).
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies filename of the PKCS#12 file to be parsed. Standard input is used
@@ -71,13 +77,13 @@ default. They are all written in PEM format.
the PKCS#12 file (i.e. input file) password source. For more information about
the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
L<openssl(1)|openssl(1)>.
L<openssl(1)>.
=item B<-passout arg>
pass phrase source to encrypt any outputted private keys with. For more
information about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section
in L<openssl(1)|openssl(1)>.
in L<openssl(1)>.
=item B<-password arg>
@@ -167,10 +173,12 @@ default. They must all be in PEM format. The order doesn't matter but one
private key and its corresponding certificate should be present. If additional
certificates are present they will also be included in the PKCS#12 file.
=item B<-inkey filename>
=item B<-inkey file_or_id>
file to read private key from. If not present then a private key must be present
in the input file.
If no engine is used, the argument is taken as a file; if an engine is
specified, the argument is given to the engine as a key identifier.
=item B<-name friendlyname>
@@ -192,13 +200,13 @@ displays them.
the PKCS#12 file (i.e. output file) password source. For more information about
the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
L<openssl(1)|openssl(1)>.
L<openssl(1)>.
=item B<-passin password>
pass phrase source to decrypt any input private keys with. For more information
about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in
L<openssl(1)|openssl(1)>.
L<openssl(1)>.
=item B<-chain>
@@ -266,8 +274,8 @@ don't attempt to provide the MAC integrity.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -281,6 +289,14 @@ CA storage as a directory. This directory must be a standard certificate
directory: that is a hash of each subject name (using B<x509 -hash>) should be
linked to each certificate.
=item B<-no-CAfile>
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-CSP name>
write B<name> as a Microsoft CSP name.
@@ -311,6 +327,16 @@ encrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can
be used to reduce the private key encryption to 40 bit RC2. A complete
description of all algorithms is contained in the B<pkcs8> manual page.
Prior 1.1 release passwords containing non-ASCII characters were encoded
in non-compliant manner, which limited interoperability, in first hand
with Windows. But switching to standard-compliant password encoding
poses problem accessing old data protected with broken encoding. For
this reason even legacy encodings is attempted when reading the
data. If you use PKCS#12 files in production application you are advised
to convert the data, because implemented heuristic approach is not
MT-safe, its sole goal is to facilitate the data upgrade with this
utility.
=head1 EXAMPLES
Parse a PKCS#12 file and output it to a file:
@@ -322,7 +348,7 @@ Output only client certificates to a file:
openssl pkcs12 -in file.p12 -clcerts -out file.pem
Don't encrypt the private key:
openssl pkcs12 -in file.p12 -out file.pem -nodes
Print some info about a PKCS#12 file:
@@ -338,31 +364,17 @@ Include some extra certificates:
openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \
-certfile othercerts.pem
=head1 BUGS
Some would argue that the PKCS#12 standard is one big bug :-)
Versions of OpenSSL before 0.9.6a had a bug in the PKCS#12 key generation
routines. Under rare circumstances this could produce a PKCS#12 file encrypted
with an invalid key. As a result some PKCS#12 files which triggered this bug
from other implementations (MSIE or Netscape) could not be decrypted
by OpenSSL and similarly OpenSSL could produce PKCS#12 files which could
not be decrypted by other implementations. The chances of producing such
a file are relatively small: less than 1 in 256.
A side effect of fixing this bug is that any old invalidly encrypted PKCS#12
files cannot no longer be parsed by the fixed version. Under such circumstances
the B<pkcs12> utility will report that the MAC is OK but fail with a decryption
error when extracting private keys.
This problem can be resolved by extracting the private keys and certificates
from the PKCS#12 file using an older version of OpenSSL and recreating the PKCS#12
file from the keys and certificates using a newer version of OpenSSL. For example:
old-openssl -in bad.p12 -out keycerts.pem
openssl -in keycerts.pem -export -name "My PKCS#12 file" -out fixed.p12
=head1 SEE ALSO
L<pkcs8(1)|pkcs8(1)>
L<pkcs8(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

22
doc/apps/pkcs7.pod
View File

@@ -7,6 +7,7 @@ pkcs7 - PKCS#7 utility
=head1 SYNOPSIS
B<openssl> B<pkcs7>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
@@ -20,10 +21,14 @@ B<openssl> B<pkcs7>
The B<pkcs7> command processes PKCS#7 files in DER or PEM format.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. B<DER> format is DER encoded PKCS#7
@@ -32,7 +37,7 @@ the DER form with header and footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -95,11 +100,20 @@ For compatibility with some CAs it will also accept:
There is no option to print out all the fields of a PKCS#7 file.
This PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315 they
This PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315 they
cannot currently parse, for example, the new CMS as described in RFC2630.
=head1 SEE ALSO
L<crl2pkcs7(1)|crl2pkcs7(1)>
L<crl2pkcs7(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

186
doc/apps/pkcs8.pod
View File

@@ -7,6 +7,7 @@ pkcs8 - PKCS#8 format private key conversion tool
=head1 SYNOPSIS
B<openssl> B<pkcs8>
[B<-help>]
[B<-topk8>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
@@ -14,15 +15,18 @@ B<openssl> B<pkcs8>
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-iter count>]
[B<-noiter>]
[B<-nocrypt>]
[B<-nooct>]
[B<-embed>]
[B<-nsdb>]
[B<-traditional>]
[B<-v2 alg>]
[B<-v2prf alg>]
[B<-v1 alg>]
[B<-engine id>]
[B<-scrypt>]
[B<-scrypt_N N>]
[B<-scrypt_r r>]
[B<-scrypt_p p>]
=head1 DESCRIPTION
@@ -30,28 +34,32 @@ The B<pkcs8> command processes private keys in PKCS#8 format. It can handle
both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-topk8>
Normally a PKCS#8 private key is expected on input and a traditional format
private key will be written. With the B<-topk8> option the situation is
reversed: it reads a traditional format private key and writes a PKCS#8
format key.
Normally a PKCS#8 private key is expected on input and a private key will be
written to the output file. With the B<-topk8> option the situation is
reversed: it reads a private key and writes a PKCS#8 format key.
=item B<-inform DER|PEM>
This specifies the input format. If a PKCS#8 format key is expected on input
then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be
expected. Otherwise the B<DER> or B<PEM> format of the traditional format
private key is used.
This specifies the input format: see L<KEY FORMATS> for more details.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
This specifies the output format: see L<KEY FORMATS> for more details.
=item B<-traditional>
When this option is present and B<-topk8> is not a traditional format private
key is written.
=item B<-in filename>
@@ -62,7 +70,7 @@ prompted for.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-out filename>
@@ -74,7 +82,13 @@ filename.
=item B<-passout arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-iter count>
When creating new PKCS#8 containers, use a given number of iterations on
the password in deriving the encryption key for the PKCS#8 output.
High values increase the time required to brute-force a PKCS#8 container.
=item B<-nocrypt>
@@ -85,50 +99,28 @@ This option does not encrypt private keys at all and should only be used
when absolutely necessary. Certain software such as some versions of Java
code signing software used unencrypted private keys.
=item B<-nooct>
This option generates RSA private keys in a broken format that some software
uses. Specifically the private key should be enclosed in a OCTET STRING
but some software just includes the structure itself without the
surrounding OCTET STRING.
=item B<-embed>
This option generates DSA keys in a broken format. The DSA parameters are
embedded inside the PrivateKey structure. In this form the OCTET STRING
contains an ASN1 SEQUENCE consisting of two structures: a SEQUENCE containing
the parameters and an ASN1 INTEGER containing the private key.
=item B<-nsdb>
This option generates DSA keys in a broken format compatible with Netscape
private key databases. The PrivateKey contains a SEQUENCE consisting of
the public and private keys respectively.
=item B<-v2 alg>
This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8
private keys are encrypted with the password based encryption algorithm
called B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it
was the strongest encryption algorithm supported in PKCS#5 v1.5. Using
the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any
encryption algorithm such as 168 bit triple DES or 128 bit RC2 however
not many implementations support PKCS#5 v2.0 yet. If you are just using
private keys with OpenSSL then this doesn't matter.
This option sets the PKCS#5 v2.0 algorithm.
The B<alg> argument is the encryption algorithm to use, valid values include
B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used.
B<aes128>, B<aes256> and B<des3>. If this option isn't specified then B<aes256>
is used.
=item B<-v2prf alg>
This option sets the PRF algorithm to use with PKCS#5 v2.0. A typical value
values would be B<hmacWithSHA256>. If this option isn't set then the default
for the cipher is used or B<hmacWithSHA1> if there is no default.
value would be B<hmacWithSHA256>. If this option isn't set then the default
for the cipher is used or B<hmacWithSHA256> if there is no default.
Some implementations may not support custom PRF algorithms and may require
the B<hmacWithSHA1> option to work.
=item B<-v1 alg>
This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete
list of possible algorithms is included below.
This option indicates a PKCS#5 v1.5 or PKCS#12 algorithm should be used. Some
older implementations may not support PKCS#5 v2.0 and may require this option.
If not specified PKCS#5 v2.0 form is used.
=item B<-engine id>
@@ -137,10 +129,49 @@ to attempt to obtain a functional reference to the specified engine,
thus initialising it if needed. The engine will then be set as the default
for all available algorithms.
=item B<-scrypt>
uses the B<scrypt> algorithm for private key encryption using default
parameters: currently N=16384, r=8 and p=1 and AES in CBC mode with a 256 bit
key. These parameters can be modified using the B<-scrypt_N>, B<-scrypt_r>,
B<-scrypt_p> and B<-v2> options.
B<-scrypt_N N> B<-scrypt_r r> B<-scrypt_p p>
sets the scrypt B<N>, B<r> or B<p> parameters.
=back
=head1 KEY FORMATS
Various different formats are used by the pkcs8 utility. These are detailed
below.
If a key is being converted from PKCS#8 form (i.e. the B<-topk8> option is
not used) then the input file must be in PKCS#8 format. An encrypted
key is expected unless B<-nocrypt> is included.
If B<-topk8> is not used and B<PEM> mode is set the output file will be an
unencrypted private key in PKCS#8 format. If the B<-traditional> option is
used then a traditional format private key is written instead.
If B<-topk8> is not used and B<DER> mode is set the output file will be an
unencrypted private key in traditional DER format.
If B<-topk8> is used then any supported private key can be used for the input
file in a format specified by B<-inform>. The output file will be encrypted
PKCS#8 format using the specified encryption parameters unless B<-nocrypt>
is included.
=head1 NOTES
By default, when converting a key to PKCS#8 format, PKCS#5 v2.0 using 256 bit
AES with HMAC and SHA256 is used.
Some older implementations do not support PKCS#5 v2.0 format and require
the older PKCS#5 v1.5 form instead, possibly also requiring insecure weak
encryption algorithms such as 56 bit DES.
The encrypted form of a PEM encode PKCS#8 files uses the following
headers and footers:
@@ -157,13 +188,6 @@ counts are more secure that those encrypted using the traditional
SSLeay compatible formats. So if additional security is considered
important the keys should be converted.
The default encryption is only 56 bits because this is the encryption
that most current implementations of PKCS#8 will support.
Some software may use PKCS#12 password based encryption algorithms
with PKCS#8 format private keys: these are handled automatically
but there is no option to produce them.
It is possible to write out DER encoded encrypted private keys in
PKCS#8 format because the encryption details are included at an ASN1
level whereas the traditional format includes them at a PEM level.
@@ -197,20 +221,28 @@ allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.
=head1 EXAMPLES
Convert a private from traditional to PKCS#5 v2.0 format using triple
DES:
Convert a private key to PKCS#8 format using default parameters (AES with
256 bit key and B<hmacWithSHA256>):
openssl pkcs8 -in key.pem -topk8 -out enckey.pem
Convert a private key to PKCS#8 unencrypted format:
openssl pkcs8 -in key.pem -topk8 -nocrypt -out enckey.pem
Convert a private key to PKCS#5 v2.0 format using triple DES:
openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
Convert a private from traditional to PKCS#5 v2.0 format using AES with
256 bits in CBC mode and B<hmacWithSHA256> PRF:
Convert a private key to PKCS#5 v2.0 format using AES with 256 bits in CBC
mode and B<hmacWithSHA512> PRF:
openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -out enckey.pem
openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -v2prf hmacWithSHA512 -out enckey.pem
Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
(DES):
openssl pkcs8 -in key.pem -topk8 -out enckey.pem
openssl pkcs8 -in key.pem -topk8 -v1 PBE-MD5-DES -out enckey.pem
Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
(3DES):
@@ -221,9 +253,14 @@ Read a DER unencrypted PKCS#8 format private key:
openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
Convert a private key from any PKCS#8 format to traditional format:
Convert a private key from any PKCS#8 encrypted format to traditional format:
openssl pkcs8 -in pk8.pem -out key.pem
openssl pkcs8 -in pk8.pem -traditional -out key.pem
Convert a private key to PKCS#8 format, encrypting with AES-256 and with
one million iterations of the password:
openssl pkcs8 -in key.pem -topk8 -v2 aes-256-cbc -iter 1000000 -out pk8.pem
=head1 STANDARDS
@@ -243,13 +280,22 @@ PKCS#8 private key format complies with this standard.
There should be an option that prints out the encryption algorithm
in use and other details such as the iteration count.
PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private
key format for OpenSSL: for compatibility several of the utilities use
the old format at present.
=head1 SEE ALSO
L<dsa(1)|dsa(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>,
L<gendsa(1)|gendsa(1)>
L<dsa(1)>, L<rsa(1)>, L<genrsa(1)>,
L<gendsa(1)>
=head1 HISTORY
The B<-iter> option was added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

38
doc/apps/pkey.pod
View File

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

23
doc/apps/pkeyparam.pod
View File

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

109
doc/apps/pkeyutl.pod
View File

@@ -7,14 +7,15 @@ pkeyutl - public key algorithm utility
=head1 SYNOPSIS
B<openssl> B<pkeyutl>
[B<-help>]
[B<-in file>]
[B<-out file>]
[B<-sigfile file>]
[B<-inkey file>]
[B<-keyform PEM|DER>]
[B<-keyform PEM|DER|ENGINE>]
[B<-passin arg>]
[B<-peerkey file>]
[B<-peerform PEM|DER>]
[B<-peerform PEM|DER|ENGINE>]
[B<-pubin>]
[B<-certin>]
[B<-rev>]
@@ -24,20 +25,27 @@ B<openssl> B<pkeyutl>
[B<-encrypt>]
[B<-decrypt>]
[B<-derive>]
[B<-kdf algorithm>]
[B<-kdflen length>]
[B<-pkeyopt opt:value>]
[B<-hexdump>]
[B<-asn1parse>]
[B<-engine id>]
[B<-engine_impl>]
=head1 DESCRIPTION
The B<pkeyutl> command can be used to perform public key operations using
any supported algorithm.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies the input filename to read data from or standard input
@@ -48,43 +56,39 @@ if this option is not specified.
specifies the output filename to write to or standard output by
default.
=item B<-sigfile file>
Signature file, required for B<verify> operations only
=item B<-inkey file>
the input key file, by default it should be a private key.
=item B<-keyform PEM|DER>
=item B<-keyform PEM|DER|ENGINE>
the key format PEM, DER or ENGINE.
the key format PEM, DER or ENGINE. Default is PEM.
=item B<-passin arg>
the input key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-peerkey file>
the peer key file, used by key derivation (agreement) operations.
=item B<-peerform PEM|DER>
the peer key format PEM, DER or ENGINE.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<pkeyutl>
to attempt to obtain a functional reference to the specified engine,
thus initialising it if needed. The engine will then be set as the default
for all available algorithms.
=item B<-peerform PEM|DER|ENGINE>
the peer key format PEM, DER or ENGINE. Default is PEM.
=item B<-pubin>
the input file is a public key.
the input file is a public key.
=item B<-certin>
the input is a certificate containing a public key.
the input is a certificate containing a public key.
=item B<-rev>
@@ -117,6 +121,23 @@ decrypt the input data using a private key.
derive a shared secret using the peer key.
=item B<-kdf algorithm>
Use key derivation function B<algorithm>. The supported algorithms are
at present B<TLS1-PRF> and B<HKDF>.
Note: additional parameters and the KDF output length will normally have to be
set for this to work.
See L<EVP_PKEY_CTX_set_hkdf_md(3)> and L<EVP_PKEY_CTX_set_tls1_prf_md(3)>
for the supported string parameters of each algorithm.
=item B<-kdflen length>
Set the output length for KDF.
=item B<-pkeyopt opt:value>
Public key options specified as opt:value. See NOTES below for more details.
=item B<-hexdump>
hex dump the output data.
@@ -126,6 +147,18 @@ hex dump the output data.
asn1parse the output data, this is useful when combined with the
B<-verifyrecover> option when an ASN1 structure is signed.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<pkeyutl>
to attempt to obtain a functional reference to the specified engine,
thus initialising it if needed. The engine will then be set as the default
for all available algorithms.
=item B<-engine_impl>
When used with the B<-engine> option, it specifies to also use
engine B<id> for crypto operations.
=back
=head1 NOTES
@@ -153,24 +186,25 @@ long binary encoding of SHA-1 hash function output.
=head1 RSA ALGORITHM
The RSA algorithm supports encrypt, decrypt, sign, verify and verifyrecover
operations in general. Some padding modes only support some of these
operations however.
The RSA algorithm generally supports the encrypt, decrypt, sign,
verify and verifyrecover operations. However, some padding modes
support only a subset of these operations. The following additional
B<pkeyopt> values are supported:
=over 4
=item -B<rsa_padding_mode:mode>
=item B<rsa_padding_mode:mode>
This sets the RSA padding mode. Acceptable values for B<mode> are B<pkcs1> for
PKCS#1 padding, B<sslv23> for SSLv23 padding, B<none> for no padding, B<oaep>
for B<OAEP> mode, B<x931> for X9.31 mode and B<pss> for PSS.
In PKCS#1 padding if the message digest is not set then the supplied data is
In PKCS#1 padding if the message digest is not set then the supplied data is
signed or verified directly instead of using a B<DigestInfo> structure. If a
digest is set then the a B<DigestInfo> structure is used and its the length
must correspond to the digest type.
For B<oeap> mode only encryption and decryption is supported.
For B<oaep> mode only encryption and decryption is supported.
For B<x931> if the digest type is set it is used to format the block data
otherwise the first byte is used to specify the X9.31 digest ID. Sign,
@@ -207,6 +241,11 @@ verify operations use ECDSA and derive uses ECDH. Currently there are no
additional options other than B<digest>. Only the SHA1 digest can be used and
this digest is assumed by default.
=head1 X25519 ALGORITHM
The X25519 algorithm supports key derivation only. Currently there are no
additional options.
=head1 EXAMPLES
Sign some data using a private key:
@@ -229,7 +268,25 @@ Derive a shared secret value:
openssl pkeyutl -derive -inkey key.pem -peerkey pubkey.pem -out secret
Hexdump 48 bytes of TLS1 PRF using digest B<SHA256> and shared secret and
seed consisting of the single byte 0xFF:
openssl pkeyutl -kdf TLS1-PRF -kdflen 48 -pkeyopt md:SHA256 \
-pkeyopt hexsecret:ff -pkeyopt hexseed:ff -hexdump
=head1 SEE ALSO
L<genpkey(1)|genpkey(1)>, L<pkey(1)|pkey(1)>, L<rsautl(1)|rsautl(1)>
L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>
L<genpkey(1)>, L<pkey(1)>, L<rsautl(1)>
L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>,
L<EVP_PKEY_CTX_set_hkdf_md(3)>, L<EVP_PKEY_CTX_set_tls1_prf_md(3)>
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

20
doc/apps/rand.pod
View File

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

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

@@ -5,20 +5,29 @@ Original text by James Westby, contributed under the OpenSSL license.
=head1 NAME
c_rehash - Create symbolic links to files named by the hash values
c_rehash, rehash - Create symbolic links to files named by the hash values
=head1 SYNOPSIS
B<c_rehash>
B<[-old]>
B<openssl>
B<rehash>
B<[-h]>
B<[-help]>
B<[-old]>
B<[-n]>
B<[-v]>
[ I<directory>...]
B<c_rehash>
I<flags...>
=head1 DESCRIPTION
B<c_rehash> scans directories and calculates a hash value of each
On some platforms, the OpenSSL B<rehash> command is available as
an external script called B<c_rehash>. They are functionally equivalent,
except for minor differences noted below.
B<rehash> scans directories and calculates a hash value of each
C<.pem>, C<.crt>, C<.cer>, or C<.crl>
file in the specified directory list and creates symbolic links
for each file, where the name of the link is the hash value.
@@ -28,18 +37,19 @@ directories to be set up like this in order to find certificates.
If any directories are named on the command line, then those are
processed in turn. If not, then the B<SSL_CERT_DIR> environment variable
is consulted; this shold be a colon-separated list of directories,
is consulted; this should be a colon-separated list of directories,
like the Unix B<PATH> variable.
If that is not set then the default directory (installation-specific
but often B</usr/local/ssl/certs>) is processed.
In order for a directory to be processed, the user must have write
permissions on that directory, otherwise it will be skipped.
permissions on that directory, otherwise an error will be generated.
The links created are of the form C<HHHHHHHH.D>, where each B<H>
is a hexadecimal character and B<D> is a single decimal digit.
When processing a directory, B<c_rehash> will first remove all links
that have a name in that syntax. If you have links in that format
used for other purposes, they will be removed.
When processing a directory, B<rehash> will first remove all links
that have a name in that syntax, even if they are being used for some
other purpose.
To skip the removal step, use the B<-n> flag.
Hashes for CRL's look similar except the letter B<r> appears after
the period, like this: C<HHHHHHHH.rD>.
@@ -50,9 +60,13 @@ full SHA-1 fingerprint. A warning will be displayed if a duplicate
is found.
A warning will also be displayed if there are files that
cannot be parsed as either a certificate or a CRL.
cannot be parsed as either a certificate or a CRL or if
more than one such object appears in the file.
The program uses the B<openssl> program to compute the hashes and
=head2 Script Configuration
The B<c_rehash> script
uses the B<openssl> program to compute the hashes and
fingerprints. If not found in the user's B<PATH>, then set the
B<OPENSSL> environment variable to the full pathname.
Any program can be used, it will be invoked as follows for either
@@ -69,15 +83,15 @@ optionally prefixed with some text and an equals sign.
=over 4
=item B<-help> B<-h>
Display a brief usage message.
=item B<-old>
Use old-style hashing (MD5, as opposed to SHA-1) for generating
links for releases before 1.0.0. Note that current versions will
not use the old style.
=item B<-h>
Display a brief usage message.
links to be used for releases before 1.0.0.
Note that current versions will not use the old style.
=item B<-n>
@@ -87,13 +101,13 @@ This is needed when keeping new and old-style links in the same directory.
=item B<-v>
Print messages about old links removed and new links created.
By default, B<c_rehash> only lists each directory as it is processed.
By default, B<rehash> only lists each directory as it is processed.
=back
=head1 ENVIRONMENT
=over
=over 4
=item B<OPENSSL>
@@ -109,6 +123,17 @@ Ignored if directories are listed on the command line.
=head1 SEE ALSO
L<openssl(1)|openssl(1)>,
L<crl(1)|crl(1)>.
L<x509(1)|x509(1)>.
L<openssl(1)>,
L<crl(1)>.
L<x509(1)>.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

195
doc/apps/req.pod
View File

@@ -1,13 +1,13 @@
=pod
=head1 NAME
req - PKCS#10 certificate request and certificate generating utility.
req - PKCS#10 certificate request and certificate generating utility
=head1 SYNOPSIS
B<openssl> B<req>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
@@ -34,8 +34,6 @@ B<openssl> B<req>
[B<-x509>]
[B<-days n>]
[B<-set_serial n>]
[B<-asn1-kludge>]
[B<-no-asn1-kludge>]
[B<-newhdr>]
[B<-extensions section>]
[B<-reqexts section>]
@@ -54,10 +52,14 @@ The B<req> command primarily creates and processes certificate requests
in PKCS#10 format. It can additionally create self signed certificates
for use as root CAs for example.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -67,7 +69,7 @@ footer lines.
=item B<-outform DER|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -79,7 +81,7 @@ options (B<-new> and B<-newkey>) are not specified.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-out filename>
@@ -89,7 +91,7 @@ default.
=item B<-passout arg>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-text>
@@ -127,18 +129,11 @@ in the configuration file and any requested extensions.
If the B<-key> option is not used it will generate a new RSA private
key using information specified in the configuration file.
=item B<-subj arg>
Replaces subject field of input request with specified data and outputs
modified request. The arg must be formatted as
I</type0=value0/type1=value1/type2=...>,
characters may be escaped by \ (backslash), no spaces are skipped.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
@@ -152,13 +147,13 @@ the default key size, specified in the configuration file is used.
All other algorithms support the B<-newkey alg:file> form, where file may be
an algorithm parameter file, created by the B<genpkey -genparam> command
or and X.509 certificate for a key with approriate algorithm.
or and X.509 certificate for a key with appropriate algorithm.
B<param:file> generates a key using the parameter file or certificate B<file>,
the algorithm is determined by the parameters. B<algname:file> use algorithm
B<algname> and parameter file B<file>: the two algorithms must match or an
error occurs. B<algname> just uses algorithm B<algname>, and parameters,
if neccessary should be specified via B<-pkeyopt> parameter.
if necessary should be specified via B<-pkeyopt> parameter.
B<dsa:filename> generates a DSA key using the parameters
in the file B<filename>. B<ec:filename> generates EC key (usable both with
@@ -198,8 +193,9 @@ will not be encrypted.
=item B<-[digest]>
this specifies the message digest to sign the request with (such as
B<-md5>, B<-sha1>). This overrides the digest algorithm specified in
this specifies the message digest to sign the request.
Any digest supported by the OpenSSL B<dgst> command can be used.
This overrides the digest algorithm specified in
the configuration file.
Some public key algorithms may override this choice. For instance, DSA
@@ -208,9 +204,9 @@ GOST R 34.11-94 (B<-md_gost94>).
=item B<-config filename>
this allows an alternative configuration file to be specified,
this overrides the compile time filename or any specified in
the B<OPENSSL_CONF> environment variable.
this allows an alternative configuration file to be specified.
Optional; for a description of the default value,
see L<openssl(1)/COMMAND SUMMARY>.
=item B<-subj arg>
@@ -237,6 +233,9 @@ a self signed root CA. The extensions added to the certificate
using the B<set_serial> option, a large random number will be used for
the serial number.
If existing request is specified with the B<-in> option, it is converted
to the self signed certificate otherwise new request is created.
=item B<-days n>
when the B<-x509> option is being used this specifies the number of
@@ -246,7 +245,6 @@ days to certify the certificate for. The default is 30 days.
serial number to use when outputting a self signed certificate. This
may be specified as a decimal value or a hex value if preceded by B<0x>.
It is possible to use negative serial numbers but this is not recommended.
=item B<-extensions section>
@@ -260,7 +258,7 @@ a variety of purposes.
=item B<-utf8>
this option causes field values to be interpreted as UTF8 strings, by
this option causes field values to be interpreted as UTF8 strings, by
default they are interpreted as ASCII. This means that the field
values, whether prompted from a terminal or obtained from a
configuration file, must be valid UTF8 strings.
@@ -270,36 +268,16 @@ configuration file, must be valid UTF8 strings.
option which determines how the subject or issuer names are displayed. The
B<option> argument can be a single option or multiple options separated by
commas. Alternatively the B<-nameopt> switch may be used more than once to
set multiple options. See the L<x509(1)|x509(1)> manual page for details.
set multiple options. See the L<x509(1)> manual page for details.
=item B<-reqopt>
customise the output format used with B<-text>. The B<option> argument can be
a single option or multiple options separated by commas.
a single option or multiple options separated by commas.
See discission of the B<-certopt> parameter in the L<B<x509>|x509(1)>
See discussion of the B<-certopt> parameter in the L<x509(1)>
command.
=item B<-asn1-kludge>
by default the B<req> command outputs certificate requests containing
no attributes in the correct PKCS#10 format. However certain CAs will only
accept requests containing no attributes in an invalid form: this
option produces this invalid format.
More precisely the B<Attributes> in a PKCS#10 certificate request
are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so
if no attributes are present then they should be encoded as an
empty B<SET OF>. The invalid form does not include the empty
B<SET OF> whereas the correct form does.
It should be noted that very few CAs still require the use of this option.
=item B<-no-asn1-kludge>
Reverses effect of B<-asn1-kludge>
=item B<-newhdr>
Adds the word B<NEW> to the PEM file header and footer lines on the outputted
@@ -365,7 +343,7 @@ overridden by the B<-keyout> option.
This specifies a file containing additional B<OBJECT IDENTIFIERS>.
Each line of the file should consist of the numerical form of the
object identifier followed by white space then the short name followed
by white space and finally the long name.
by white space and finally the long name.
=item B<oid_section>
@@ -377,7 +355,7 @@ and long names are the same when this option is used.
=item B<RANDFILE>
This specifies a filename in which random number seed information is
placed and read from, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
placed and read from, or an EGD socket (see L<RAND_egd(3)>).
It is used for private key generation.
=item B<encrypt_key>
@@ -388,9 +366,10 @@ option. For compatibility B<encrypt_rsa_key> is an equivalent option.
=item B<default_md>
This option specifies the digest algorithm to use. Possible values
include B<md5 sha1 mdc2>. If not present then MD5 is used. This
option can be overridden on the command line.
This option specifies the digest algorithm to use.
Any digest supported by the OpenSSL B<dgst> command can be used.
If not present then MD5 is used.
This option can be overridden on the command line.
=item B<string_mask>
@@ -398,7 +377,7 @@ This option masks out the use of certain string types in certain
fields. Most users will not need to change this option.
It can be set to several values B<default> which is also the default
option uses PrintableStrings, T61Strings and BMPStrings if the
option uses PrintableStrings, T61Strings and BMPStrings if the
B<pkix> value is used then only PrintableStrings and BMPStrings will
be used. This follows the PKIX recommendation in RFC2459. If the
B<utf8only> option is used then only UTF8Strings will be used: this
@@ -410,8 +389,8 @@ problems with BMPStrings and UTF8Strings: in particular Netscape.
this specifies the configuration file section containing a list of
extensions to add to the certificate request. It can be overridden
by the B<-reqexts> command line switch. See the
L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
by the B<-reqexts> command line switch. See the
L<x509v3_config(5)> manual page for details of the
extension section format.
=item B<x509_extensions>
@@ -521,8 +500,8 @@ Generate a self signed root certificate:
Example of a file pointed to by the B<oid_file> option:
1.2.3.4 shortName A longer Name
1.2.3.6 otherName Other longer Name
1.2.3.4 shortName A longer Name
1.2.3.6 otherName Other longer Name
Example of a section pointed to by B<oid_section> making use of variable
expansion:
@@ -533,65 +512,65 @@ expansion:
Sample configuration file prompting for field values:
[ req ]
default_bits = 2048
default_keyfile = privkey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
x509_extensions = v3_ca
default_bits = 2048
default_keyfile = privkey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
req_extensions = v3_ca
dirstring_type = nobmp
[ req_distinguished_name ]
countryName = Country Name (2 letter code)
countryName_default = AU
countryName_min = 2
countryName_max = 2
countryName = Country Name (2 letter code)
countryName_default = AU
countryName_min = 2
countryName_max = 2
localityName = Locality Name (eg, city)
localityName = Locality Name (eg, city)
organizationalUnitName = Organizational Unit Name (eg, section)
organizationalUnitName = Organizational Unit Name (eg, section)
commonName = Common Name (eg, YOUR name)
commonName_max = 64
commonName = Common Name (eg, YOUR name)
commonName_max = 64
emailAddress = Email Address
emailAddress_max = 40
emailAddress = Email Address
emailAddress_max = 40
[ req_attributes ]
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20
[ v3_ca ]
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer:always
basicConstraints = CA:true
basicConstraints = critical, CA:true
Sample configuration containing all field values:
RANDFILE = $ENV::HOME/.rnd
RANDFILE = $ENV::HOME/.rnd
[ req ]
default_bits = 2048
default_keyfile = keyfile.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
prompt = no
output_password = mypass
default_bits = 2048
default_keyfile = keyfile.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
prompt = no
output_password = mypass
[ req_distinguished_name ]
C = GB
ST = Test State or Province
L = Test Locality
O = Organization Name
OU = Organizational Unit Name
CN = Common Name
emailAddress = test@email.address
C = GB
ST = Test State or Province
L = Test Locality
O = Organization Name
OU = Organizational Unit Name
CN = Common Name
emailAddress = test@email.address
[ req_attributes ]
challengePassword = A challenge password
challengePassword = A challenge password
=head1 NOTES
@@ -618,13 +597,13 @@ by the script in an extendedKeyUsage extension.
The following messages are frequently asked about:
Using configuration from /some/path/openssl.cnf
Unable to load config info
Using configuration from /some/path/openssl.cnf
Unable to load config info
This is followed some time later by...
unable to find 'distinguished_name' in config
problems making Certificate Request
unable to find 'distinguished_name' in config
problems making Certificate Request
The first error message is the clue: it can't find the configuration
file! Certain operations (like examining a certificate request) don't
@@ -647,13 +626,6 @@ then the B<SET OF> is missing and the encoding is technically invalid (but
it is tolerated). See the description of the command line option B<-asn1-kludge>
for more information.
=head1 ENVIRONMENT VARIABLES
The variable B<OPENSSL_CONF> if defined allows an alternative configuration
file location to be specified, it will be overridden by the B<-config> command
line switch if it is present. For compatibility reasons the B<SSLEAY_CONF>
environment variable serves the same purpose but its use is discouraged.
=head1 BUGS
OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
@@ -673,8 +645,17 @@ address in subjectAltName should be input by the user.
=head1 SEE ALSO
L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
L<gendsa(1)|gendsa(1)>, L<config(5)|config(5)>,
L<x509v3_config(5)|x509v3_config(5)>
L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
L<gendsa(1)>, L<config(5)>,
L<x509v3_config(5)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

40
doc/apps/rsa.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,13 +7,13 @@ rsa - RSA key processing tool
=head1 SYNOPSIS
B<openssl> B<rsa>
[B<-help>]
[B<-inform PEM|NET|DER>]
[B<-outform PEM|NET|DER>]
[B<-in filename>]
[B<-passin arg>]
[B<-out filename>]
[B<-passout arg>]
[B<-sgckey>]
[B<-aes128>]
[B<-aes192>]
[B<-aes256>]
@@ -42,10 +41,14 @@ traditional SSLeay compatible format for private key encryption: newer
applications should use the more secure PKCS#8 format using the B<pkcs8>
utility.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|NET|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -57,7 +60,7 @@ section.
=item B<-outform DER|NET|PEM>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -69,7 +72,7 @@ prompted for.
=item B<-passin arg>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-out filename>
@@ -81,12 +84,7 @@ filename.
=item B<-passout password>
the output file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
=item B<-sgckey>
use the modified NET algorithm used with some versions of Microsoft IIS and SGC
keys.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-aes128|-aes192|-aes256|-camellia128|-camellia192|-camellia256|-des|-des3|-idea>
@@ -101,7 +99,7 @@ These options can only be used with PEM format output files.
=item B<-text>
prints out the various public or private key components in
plain text in addition to the encoded version.
plain text in addition to the encoded version.
=item B<-noout>
@@ -165,8 +163,7 @@ files. To use these with the utility, view the file with a binary editor
and look for the string "private-key", then trace back to the byte
sequence 0x30, 0x82 (this is an ASN1 SEQUENCE). Copy all the data
from this point onwards to another file and use that as the input
to the B<rsa> utility with the B<-inform NET> option. If you get
an error after entering the password try the B<-sgckey> option.
to the B<rsa> utility with the B<-inform NET> option.
=head1 EXAMPLES
@@ -178,7 +175,7 @@ To encrypt a private key using triple DES:
openssl rsa -in key.pem -des3 -out keyout.pem
To convert a private key from PEM to DER format:
To convert a private key from PEM to DER format:
openssl rsa -in key.pem -outform DER -out keyout.der
@@ -204,7 +201,16 @@ without having to manually edit them.
=head1 SEE ALSO
L<pkcs8(1)|pkcs8(1)>, L<dsa(1)|dsa(1)>, L<genrsa(1)|genrsa(1)>,
L<gendsa(1)|gendsa(1)>
L<pkcs8(1)>, L<dsa(1)>, L<genrsa(1)>,
L<gendsa(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

63
doc/apps/rsautl.pod
View File

@@ -7,9 +7,11 @@ rsautl - RSA utility
=head1 SYNOPSIS
B<openssl> B<rsautl>
[B<-help>]
[B<-in file>]
[B<-out file>]
[B<-inkey file>]
[B<-keyform PEM|DER|ENGINE>]
[B<-pubin>]
[B<-certin>]
[B<-sign>]
@@ -27,10 +29,14 @@ B<openssl> B<rsautl>
The B<rsautl> command can be used to sign, verify, encrypt and decrypt
data using the RSA algorithm.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies the input filename to read data from or standard input
@@ -45,18 +51,22 @@ default.
the input key file, by default it should be an RSA private key.
=item B<-keyform PEM|DER|ENGINE>
the key format PEM, DER or ENGINE.
=item B<-pubin>
the input file is an RSA public key.
the input file is an RSA public key.
=item B<-certin>
the input is a certificate containing an RSA public key.
the input is a certificate containing an RSA public key.
=item B<-sign>
sign the input data and output the signed result. This requires
and RSA private key.
an RSA private key.
=item B<-verify>
@@ -126,24 +136,24 @@ example in certs/pca-cert.pem . Running B<asn1parse> as follows yields:
openssl asn1parse -in pca-cert.pem
0:d=0 hl=4 l= 742 cons: SEQUENCE
4:d=1 hl=4 l= 591 cons: SEQUENCE
8:d=2 hl=2 l= 3 cons: cont [ 0 ]
0:d=0 hl=4 l= 742 cons: SEQUENCE
4:d=1 hl=4 l= 591 cons: SEQUENCE
8:d=2 hl=2 l= 3 cons: cont [ 0 ]
10:d=3 hl=2 l= 1 prim: INTEGER :02
13:d=2 hl=2 l= 1 prim: INTEGER :00
16:d=2 hl=2 l= 13 cons: SEQUENCE
16:d=2 hl=2 l= 13 cons: SEQUENCE
18:d=3 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
29:d=3 hl=2 l= 0 prim: NULL
31:d=2 hl=2 l= 92 cons: SEQUENCE
33:d=3 hl=2 l= 11 cons: SET
35:d=4 hl=2 l= 9 cons: SEQUENCE
29:d=3 hl=2 l= 0 prim: NULL
31:d=2 hl=2 l= 92 cons: SEQUENCE
33:d=3 hl=2 l= 11 cons: SET
35:d=4 hl=2 l= 9 cons: SEQUENCE
37:d=5 hl=2 l= 3 prim: OBJECT :countryName
42:d=5 hl=2 l= 2 prim: PRINTABLESTRING :AU
....
599:d=1 hl=2 l= 13 cons: SEQUENCE
599:d=1 hl=2 l= 13 cons: SEQUENCE
601:d=2 hl=2 l= 9 prim: OBJECT :md5WithRSAEncryption
612:d=2 hl=2 l= 0 prim: NULL
614:d=1 hl=3 l= 129 prim: BIT STRING
612:d=2 hl=2 l= 0 prim: NULL
614:d=1 hl=3 l= 129 prim: BIT STRING
The final BIT STRING contains the actual signature. It can be extracted with:
@@ -151,18 +161,18 @@ The final BIT STRING contains the actual signature. It can be extracted with:
openssl asn1parse -in pca-cert.pem -out sig -noout -strparse 614
The certificate public key can be extracted with:
openssl x509 -in test/testx509.pem -pubkey -noout >pubkey.pem
The signature can be analysed with:
openssl rsautl -in sig -verify -asn1parse -inkey pubkey.pem -pubin
0:d=0 hl=2 l= 32 cons: SEQUENCE
2:d=1 hl=2 l= 12 cons: SEQUENCE
0:d=0 hl=2 l= 32 cons: SEQUENCE
2:d=1 hl=2 l= 12 cons: SEQUENCE
4:d=2 hl=2 l= 8 prim: OBJECT :md5
14:d=2 hl=2 l= 0 prim: NULL
16:d=1 hl=2 l= 16 prim: OCTET STRING
14:d=2 hl=2 l= 0 prim: NULL
16:d=1 hl=2 l= 16 prim: OCTET STRING
0000 - f3 46 9e aa 1a 4a 73 c9-37 ea 93 00 48 25 08 b5 .F...Js.7...H%..
This is the parsed version of an ASN1 DigestInfo structure. It can be seen that
@@ -180,4 +190,15 @@ which it can be seen agrees with the recovered value above.
=head1 SEE ALSO
L<dgst(1)|dgst(1)>, L<rsa(1)|rsa(1)>, L<genrsa(1)|genrsa(1)>
L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

320
doc/apps/s_client.pod
View File

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

345
doc/apps/s_server.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,7 +7,14 @@ s_server - SSL/TLS server program
=head1 SYNOPSIS
B<openssl> B<s_server>
[B<-accept port>]
[B<-help>]
[B<-port port>]
[B<-accept val>]
[B<-naccept count>]
[B<-unix val>]
[B<-unlink>]
[B<-4>]
[B<-6>]
[B<-context id>]
[B<-verify depth>]
[B<-Verify depth>]
@@ -33,21 +39,62 @@ B<openssl> B<s_server>
[B<-state>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-no_check_time>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_return_error>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-nocert>]
[B<-client_sigalgs sigalglist>]
[B<-named_curve curve>]
[B<-cipher cipherlist>]
[B<-serverpref>]
[B<-quiet>]
[B<-no_tmp_rsa>]
[B<-ssl2>]
[B<-ssl3>]
[B<-tls1>]
[B<-no_ssl2>]
[B<-tls1_1>]
[B<-tls1_2>]
[B<-dtls>]
[B<-dtls1>]
[B<-dtls1_2>]
[B<-listen>]
[B<-async>]
[B<-split_send_frag>]
[B<-max_pipelines>]
[B<-read_buf>]
[B<-no_ssl3>]
[B<-no_tls1>]
[B<-no_tls1_1>]
[B<-no_tls1_2>]
[B<-no_dhe>]
[B<-bugs>]
[B<-hack>]
[B<-comp>]
[B<-no_comp>]
[B<-brief>]
[B<-www>]
[B<-WWW>]
[B<-HTTP>]
@@ -72,15 +119,48 @@ for connections on a given port using SSL/TLS.
=head1 OPTIONS
In addition to the options below the B<s_server> utility also supports the
common and server only options documented in the
in the "Supported Command Line Commands" section of the L<SSL_CONF_cmd(3)>
manual page.
=over 4
=item B<-accept port>
=item B<-help>
the TCP port to listen on for connections. If not specified 4433 is used.
Print out a usage message.
=item B<-port port>
The TCP port to listen on for connections. If not specified 4433 is used.
=item B<-accept val>
The optional TCP host and port to listen on for connections. If not specified, *:4433 is used.
=item B<-naccept count>
The server will exit after receiving B<number> connections, default unlimited.
=item B<-unix val>
Unix domain socket to accept on.
=item B<-unlink>
For -unix, unlink existing socket first.
=item B<-4>
Use IPv4 only.
=item B<-6>
Use IPv6 only.
=item B<-context id>
sets the SSL context id. It can be given any string value. If this option
Sets the SSL context id. It can be given any string value. If this option
is not present a default value will be used.
=item B<-cert certname>
@@ -105,12 +185,12 @@ The private format to use: DER or PEM. PEM is the default.
=item B<-pass arg>
the private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
The private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-dcert filename>, B<-dkey keyname>
specify an additional certificate and private key, these behave in the
Specify an additional certificate and private key, these behave in the
same manner as the B<-cert> and B<-key> options except there is no default
if they are not specified (no additional certificate and key is used). As
noted above some cipher suites require a certificate containing a key of
@@ -121,42 +201,27 @@ by using an appropriate certificate.
=item B<-dcertform format>, B<-dkeyform format>, B<-dpass arg>
additional certificate and private key format and passphrase respectively.
Additional certificate and private key format and passphrase respectively.
=item B<-nocert>
if this option is set then no certificate is used. This restricts the
If this option is set then no certificate is used. This restricts the
cipher suites available to the anonymous ones (currently just anonymous
DH).
=item B<-dhparam filename>
the DH parameter file to use. The ephemeral DH cipher suites generate keys
The DH parameter file to use. The ephemeral DH cipher suites generate keys
using a set of DH parameters. If not specified then an attempt is made to
load the parameters from the server certificate file. If this fails then
a static set of parameters hard coded into the s_server program will be used.
load the parameters from the server certificate file.
If this fails then a static set of parameters hard coded into the B<s_server>
program will be used.
=item B<-no_dhe>
if this option is set then no DH parameters will be loaded effectively
If this option is set then no DH parameters will be loaded effectively
disabling the ephemeral DH cipher suites.
=item B<-no_tmp_rsa>
certain export cipher suites sometimes use a temporary RSA key, this option
disables temporary RSA key generation.
=item B<-verify depth>, B<-Verify depth>
The verify depth to use. This specifies the maximum length of the
client certificate chain and makes the server request a certificate from
the client. With the B<-verify> option a certificate is requested but the
client does not have to send one, with the B<-Verify> option the client
must supply a certificate or an error occurs.
If the ciphersuite cannot request a client certificate (for example an
anonymous ciphersuite or PSK) this option has no effect.
=item B<-crl_check>, B<-crl_check_all>
Check the peer certificate has not been revoked by its CA.
@@ -176,37 +241,78 @@ and to use when attempting to build the server certificate chain. The list
is also used in the list of acceptable client CAs passed to the client when
a certificate is requested.
=item B<-no_alt_chains>
=item B<-no-CAfile>
See the L<B<verify>|verify(1)> manual page for details.
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-verify depth>, B<-Verify depth>
The verify depth to use. This specifies the maximum length of the
client certificate chain and makes the server request a certificate from
the client. With the B<-verify> option a certificate is requested but the
client does not have to send one, with the B<-Verify> option the client
must supply a certificate or an error occurs.
If the ciphersuite cannot request a client certificate (for example an
anonymous ciphersuite or PSK) this option has no effect.
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-no_check_time>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set different peer certificate verification options.
See the L<verify(1)> manual page for details.
=item B<-verify_return_error>
Verification errors normally just print a message but allow the
connection to continue, for debugging purposes.
If this option is used, then verification errors close the connection.
=item B<-state>
prints out the SSL session states.
Prints the SSL session states.
=item B<-debug>
print extensive debugging information including a hex dump of all traffic.
Print extensive debugging information including a hex dump of all traffic.
=item B<-msg>
show all protocol messages with hex dump.
Show all protocol messages with hex dump.
=item B<-trace>
Show verbose trace output of protocol messages. OpenSSL needs to be compiled
with B<enable-ssl-trace> for this option to work.
=item B<-msgfile>
File to send output of B<-msg> or B<-trace> to, default standard output.
=item B<-nbio_test>
tests non blocking I/O
Tests non blocking I/O
=item B<-nbio>
turns on non blocking I/O
Turns on non blocking I/O
=item B<-crlf>
this option translated a line feed from the terminal into CR+LF.
This option translated a line feed from the terminal into CR+LF.
=item B<-quiet>
inhibit printing of session and certificate information.
Inhibit printing of session and certificate information.
=item B<-psk_hint hint>
@@ -221,22 +327,96 @@ given as a hexadecimal number without leading 0x, for example -psk
=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-tls1_1>, B<-tls1_2>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>, B<-no_tls1_1>, B<-no_tls1_2>
These options require or disable the use of the specified SSL or TLS protocols.
By default the initial handshake uses a I<version-flexible> method which will
negotiate the highest mutually supported protocol version.
By default B<s_server> will negotiate the highest mutually supported protocol
version.
When a specific TLS version is required, only that version will be accepted
from the client.
=item B<-dtls>, B<-dtls1>, B<-dtls1_2>
These options make B<s_server> use DTLS protocols instead of TLS.
With B<-dtls>, B<s_server> will negotiate any supported DTLS protocol version,
whilst B<-dtls1> and B<-dtls1_2> will only support DTLSv1.0 and DTLSv1.2
respectively.
=item B<-listen>
This option can only be used in conjunction with one of the DTLS options above.
With this option B<s_server> will listen on a UDP port for incoming connections.
Any ClientHellos that arrive will be checked to see if they have a cookie in
them or not.
Any without a cookie will be responded to with a HelloVerifyRequest.
If a ClientHello with a cookie is received then B<s_server> will connect to
that peer and complete the handshake.
=item B<-async>
Switch on asynchronous mode. Cryptographic operations will be performed
asynchronously. This will only have an effect if an asynchronous capable engine
is also used via the B<-engine> option. For test purposes the dummy async engine
(dasync) can be used (if available).
=item B<-split_send_frag int>
The size used to split data for encrypt pipelines. If more data is written in
one go than this value then it will be split into multiple pipelines, up to the
maximum number of pipelines defined by max_pipelines. This only has an effect if
a suitable ciphersuite has been negotiated, an engine that supports pipelining
has been loaded, and max_pipelines is greater than 1. See
L<SSL_CTX_set_split_send_fragment(3)> for further information.
=item B<-max_pipelines int>
The maximum number of encrypt/decrypt pipelines to be used. This will only have
an effect if an engine has been loaded that supports pipelining (e.g. the dasync
engine) and a suitable ciphersuite has been negotiated. The default value is 1.
See L<SSL_CTX_set_max_pipelines(3)> for further information.
=item B<-read_buf int>
The default read buffer size to be used for connections. This will only have an
effect if the buffer size is larger than the size that would otherwise be used
and pipelining is in use (see L<SSL_CTX_set_default_read_buffer_len(3)> for
further information).
=item B<-bugs>
there are several known bug in SSL and TLS implementations. Adding this
There are several known bug in SSL and TLS implementations. Adding this
option enables various workarounds.
=item B<-hack>
=item B<-comp>
this option enables a further workaround for some some early Netscape
SSL code (?).
Enable negotiation of TLS compression.
This option was introduced in OpenSSL 1.1.0.
TLS compression is not recommended and is off by default as of
OpenSSL 1.1.0.
=item B<-no_comp>
Disable negotiation of TLS compression.
TLS compression is not recommended and is off by default as of
OpenSSL 1.1.0.
=item B<-brief>
Provide a brief summary of connection parameters instead of the normal verbose
output.
=item B<-client_sigalgs sigalglist>
Signature algorithms to support for client certificate authentication
(colon-separated list)
=item B<-named_curve curve>
Specifies the elliptic curve to use. NOTE: this is single curve, not a list.
For a list of all possible curves, use:
$ openssl ecparam -list_curves
=item B<-cipher cipherlist>
this allows the cipher list used by the server to be modified. When
This allows the cipher list used by the server to be modified. When
the client sends a list of supported ciphers the first client cipher
also included in the server list is used. Because the client specifies
the preference order, the order of the server cipherlist irrelevant. See
@@ -244,62 +424,67 @@ the B<ciphers> command for more information.
=item B<-serverpref>
use the server's cipher preferences, rather than the client's preferences.
Use the server's cipher preferences, rather than the client's preferences.
=item B<-tlsextdebug>
print out a hex dump of any TLS extensions received from the server.
Print a hex dump of any TLS extensions received from the server.
=item B<-no_ticket>
disable RFC4507bis session ticket support.
Disable RFC4507bis session ticket support.
=item B<-www>
sends a status message back to the client when it connects. This includes
lots of information about the ciphers used and various session parameters.
Sends a status message back to the client when it connects. This includes
information about the ciphers used and various session parameters.
The output is in HTML format so this option will normally be used with a
web browser.
=item B<-WWW>
emulates a simple web server. Pages will be resolved relative to the
Emulates a simple web server. Pages will be resolved relative to the
current directory, for example if the URL https://myhost/page.html is
requested the file ./page.html will be loaded.
=item B<-HTTP>
emulates a simple web server. Pages will be resolved relative to the
Emulates a simple web server. Pages will be resolved relative to the
current directory, for example if the URL https://myhost/page.html is
requested the file ./page.html will be loaded. The files loaded are
assumed to contain a complete and correct HTTP response (lines that
are part of the HTTP response line and headers must end with CRLF).
=item B<-rev>
Simple test server which just reverses the text received from the client
and sends it back to the server. Also sets B<-brief>.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<s_server>
Specifying an engine (by its unique B<id> string) will cause B<s_server>
to attempt to obtain a functional reference to the specified engine,
thus initialising it if needed. The engine will then be set as the default
for all available algorithms.
=item B<-id_prefix arg>
generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful
Generate SSL/TLS session IDs prefixed by B<arg>. This is mostly useful
for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple
servers, when each of which might be generating a unique range of session
IDs (eg. with a certain prefix).
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
A file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<-serverinfo file>
a file containing one or more blocks of PEM data. Each PEM block
A file containing one or more blocks of PEM data. Each PEM block
must encode a TLS ServerHello extension (2 bytes type, 2 bytes length,
followed by "length" bytes of extension data). If the client sends
an empty TLS ClientHello extension matching the type, the corresponding
@@ -307,24 +492,24 @@ ServerHello extension will be returned.
=item B<-no_resumption_on_reneg>
set SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION flag.
Set the B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> option.
=item B<-status>
enables certificate status request support (aka OCSP stapling).
Enables certificate status request support (aka OCSP stapling).
=item B<-status_verbose>
enables certificate status request support (aka OCSP stapling) and gives
Enables certificate status request support (aka OCSP stapling) and gives
a verbose printout of the OCSP response.
=item B<-status_timeout nsec>
sets the timeout for OCSP response to B<nsec> seconds.
Sets the timeout for OCSP response to B<nsec> seconds.
=item B<-status_url url>
sets a fallback responder URL to use if no responder URL is present in the
Sets a fallback responder URL to use if no responder URL is present in the
server certificate. Without this option an error is returned if the server
certificate does not contain a responder address.
@@ -346,7 +531,7 @@ Protocol names are printable ASCII strings, for example "http/1.1" or
If a connection request is established with an SSL client and neither the
B<-www> nor the B<-WWW> option has been used then normally any data received
from the client is displayed and any key presses will be sent to the client.
from the client is displayed and any key presses will be sent to the client.
Certain single letter commands are also recognized which perform special
operations: these are listed below.
@@ -401,10 +586,10 @@ The session parameters can printed out using the B<sess_id> program.
=head1 BUGS
Because this program has a lot of options and also because some of
the techniques used are rather old, the C source of s_server is rather
hard to read and not a model of how things should be done. A typical
SSL server program would be much simpler.
Because this program has a lot of options and also because some of the
techniques used are rather old, the C source of B<s_server> is rather hard to
read and not a model of how things should be done.
A typical SSL server program would be much simpler.
The output of common ciphers is wrong: it just gives the list of ciphers that
OpenSSL recognizes and the client supports.
@@ -414,10 +599,20 @@ unknown cipher suites a client says it supports.
=head1 SEE ALSO
L<sess_id(1)|sess_id(1)>, L<s_client(1)|s_client(1)>, L<ciphers(1)|ciphers(1)>
L<SSL_CONF_cmd(3)>,
L<sess_id(1)>, L<s_client(1)>, L<ciphers(1)>
=head1 HISTORY
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
The -no_alt_chains options was first added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

49
doc/apps/s_time.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,18 +7,20 @@ s_time - SSL/TLS performance timing program
=head1 SYNOPSIS
B<openssl> B<s_time>
[B<-help>]
[B<-connect host:port>]
[B<-www page>]
[B<-cert filename>]
[B<-key filename>]
[B<-CApath directory>]
[B<-CAfile filename>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-reuse>]
[B<-new>]
[B<-verify depth>]
[B<-nbio>]
[B<-time seconds>]
[B<-ssl2>]
[B<-ssl3>]
[B<-bugs>]
[B<-cipher cipherlist>]
@@ -36,6 +37,10 @@ transferred (if any), and calculates the average time spent for one connection.
=over 4
=item B<-help>
Print out a usage message.
=item B<-connect host:port>
This specifies the host and optional port to connect to.
@@ -76,6 +81,14 @@ also used when building the client certificate chain.
A file containing trusted certificates to use during server authentication
and to use when attempting to build the client certificate chain.
=item B<-no-CAfile>
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-new>
performs the timing test using a new session ID for each connection.
@@ -92,18 +105,17 @@ specified, they are both on by default and executed in sequence.
turns on non-blocking I/O.
=item B<-ssl2>, B<-ssl3>
=item B<-ssl3>
these options disable the use of certain SSL or TLS protocols. By default
the initial handshake uses a method which should be compatible with all
servers and permit them to use SSL v3, SSL v2 or TLS as appropriate.
servers and permit them to use SSL v3 or TLS as appropriate.
The timing program is not as rich in options to turn protocols on and off as
the L<s_client(1)|s_client(1)> program and may not connect to all servers.
the L<s_client(1)> program and may not connect to all servers.
Unfortunately there are a lot of ancient and broken servers in use which
cannot handle this technique and will fail to connect. Some servers only
work if TLS is turned off with the B<-ssl3> option; others
will only support SSL v2 and may need the B<-ssl2> option.
work if TLS is turned off with the B<-ssl3> option.
=item B<-bugs>
@@ -115,7 +127,7 @@ option enables various workarounds.
this allows the cipher list sent by the client to be modified. Although
the server determines which cipher suite is used it should take the first
supported cipher in the list sent by the client.
See the L<ciphers(1)|ciphers(1)> command for more information.
See the L<ciphers(1)> command for more information.
=item B<-time length>
@@ -133,11 +145,11 @@ To connect to an SSL HTTP server and get the default page the command
openssl s_time -connect servername:443 -www / -CApath yourdir -CAfile yourfile.pem -cipher commoncipher [-ssl3]
would typically be used (https uses port 443). 'commoncipher' is a cipher to
which both client and server can agree, see the L<ciphers(1)|ciphers(1)> command
which both client and server can agree, see the L<ciphers(1)> command
for details.
If the handshake fails then there are several possible causes, if it is
nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>,
nothing obvious like no client certificate then the B<-bugs> and
B<-ssl3> options can be tried
in case it is a buggy server. In particular you should play with these
options B<before> submitting a bug report to an OpenSSL mailing list.
@@ -146,10 +158,10 @@ A frequent problem when attempting to get client certificates working
is that a web client complains it has no certificates or gives an empty
list to choose from. This is normally because the server is not sending
the clients certificate authority in its "acceptable CA list" when it
requests a certificate. By using L<s_client(1)|s_client(1)> the CA list can be
requests a certificate. By using L<s_client(1)> the CA list can be
viewed and checked. However some servers only request client authentication
after a specific URL is requested. To obtain the list in this case it
is necessary to use the B<-prexit> option of L<s_client(1)|s_client(1)> and
is necessary to use the B<-prexit> option of L<s_client(1)> and
send an HTTP request for an appropriate page.
If a certificate is specified on the command line using the B<-cert>
@@ -160,7 +172,7 @@ on the command line is no guarantee that the certificate works.
=head1 BUGS
Because this program does not have all the options of the
L<s_client(1)|s_client(1)> program to turn protocols on and off, you may not be
L<s_client(1)> program to turn protocols on and off, you may not be
able to measure the performance of all protocols with all servers.
The B<-verify> option should really exit if the server verification
@@ -168,6 +180,15 @@ fails.
=head1 SEE ALSO
L<s_client(1)|s_client(1)>, L<s_server(1)|s_server(1)>, L<ciphers(1)|ciphers(1)>
L<s_client(1)>, L<s_server(1)>, L<ciphers(1)>
=head1 COPYRIGHT
Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

38
doc/apps/sess_id.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,8 +7,9 @@ sess_id - SSL/TLS session handling utility
=head1 SYNOPSIS
B<openssl> B<sess_id>
[B<-help>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-outform PEM|DER|NSS>]
[B<-in filename>]
[B<-out filename>]
[B<-text>]
@@ -24,8 +24,14 @@ master key) in human readable format. Since this is a diagnostic tool that
needs some knowledge of the SSL protocol to use properly, most users will
not need to use it.
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM>
This specifies the input format. The B<DER> option uses an ASN1 DER encoded
@@ -33,10 +39,11 @@ format containing session details. The precise format can vary from one version
to the next. The B<PEM> form is the default format: it consists of the B<DER>
format base64 encoded with additional header and footer lines.
=item B<-outform DER|PEM>
=item B<-outform DER|PEM|NSS>
This specifies the output format, the options have the same meaning as the
B<-inform> option.
This specifies the output format. The B<PEM> and B<DER> options have the same meaning
as the B<-inform> option. The B<NSS> option outputs the session id and the master key
in NSS keylog format.
=item B<-in filename>
@@ -51,7 +58,7 @@ output if this option is not specified.
=item B<-text>
prints out the various public or private key components in
plain text in addition to the encoded version.
plain text in addition to the encoded version.
=item B<-cert>
@@ -65,7 +72,7 @@ this option prevents output of the encoded version of the session.
=item B<-context ID>
this option can set the session id so the output session information uses the
supplied ID. The ID can be any string of characters. This option wont normally
supplied ID. The ID can be any string of characters. This option won't normally
be used.
=back
@@ -91,7 +98,7 @@ Theses are described below in more detail.
=item B<Protocol>
this is the protocol in use TLSv1, SSLv3 or SSLv2.
this is the protocol in use TLSv1.2, TLSv1.1, TLSv1 or SSLv3.
=item B<Cipher>
@@ -110,10 +117,6 @@ the session ID context in hex format.
this is the SSL session master key.
=item B<Key-Arg>
the key argument, this is only used in SSL v2.
=item B<Start Time>
this is the session start time represented as an integer in standard Unix format.
@@ -146,6 +149,15 @@ The cipher and start time should be printed out in human readable form.
=head1 SEE ALSO
L<ciphers(1)|ciphers(1)>, L<s_server(1)|s_server(1)>
L<ciphers(1)>, L<s_server(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

121
doc/apps/smime.pod
View File

@@ -7,21 +7,54 @@ smime - S/MIME utility
=head1 SYNOPSIS
B<openssl> B<smime>
[B<-help>]
[B<-encrypt>]
[B<-decrypt>]
[B<-sign>]
[B<-resign>]
[B<-verify>]
[B<-pk7out>]
[B<-binary>]
[B<-crlfeol>]
[B<-[cipher]>]
[B<-in file>]
[B<-CAfile file>]
[B<-CApath dir>]
[B<-no-CAfile>]
[B<-no-CApath>]
[B<-attime timestamp>]
[B<-check_ss_sig>]
[B<-crl_check>]
[B<-crl_check_all>]
[B<-explicit_policy>]
[B<-extended_crl>]
[B<-ignore_critical>]
[B<-inhibit_any>]
[B<-inhibit_map>]
[B<-partial_chain>]
[B<-policy arg>]
[B<-policy_check>]
[B<-policy_print>]
[B<-purpose purpose>]
[B<-suiteB_128>]
[B<-suiteB_128_only>]
[B<-suiteB_192>]
[B<-trusted_first>]
[B<-no_alt_chains>]
[B<-use_deltas>]
[B<-auth_level num>]
[B<-verify_depth num>]
[B<-verify_email email>]
[B<-verify_hostname hostname>]
[B<-verify_ip ip>]
[B<-verify_name name>]
[B<-x509_strict>]
[B<-certfile file>]
[B<-signer file>]
[B<-recip file>]
[B<-inform SMIME|PEM|DER>]
[B<-passin arg>]
[B<-inkey file>]
[B<-inkey file_or_id>]
[B<-out file>]
[B<-outform SMIME|PEM|DER>]
[B<-content file>]
@@ -41,13 +74,17 @@ B<openssl> B<smime>
The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and
verify S/MIME messages.
=head1 COMMAND OPTIONS
=head1 OPTIONS
There are six operation options that set the type of operation to be performed.
The meaning of the other options varies according to the operation type.
=over 4
=item B<-help>
Print out a usage message.
=item B<-encrypt>
encrypt mail for the given recipient certificates. Input file is the message
@@ -136,7 +173,7 @@ is S/MIME and it uses the multipart/signed MIME content type.
this option adds plain text (text/plain) MIME headers to the supplied
message if encrypting or signing. If decrypting or verifying it strips
off text headers: if the decrypted or verified message is not of MIME
off text headers: if the decrypted or verified message is not of MIME
type text/plain then an error occurs.
=item B<-CAfile file>
@@ -150,6 +187,14 @@ B<-verify>. This directory must be a standard certificate directory: that
is a hash of each subject name (using B<x509 -hash>) should be linked
to each certificate.
=item B<-no-CAfile>
Do not load the trusted CA certificates from the default file location
=item B<-no-CApath>
Do not load the trusted CA certificates from the default directory location
=item B<-md digest>
digest algorithm to use when signing or resigning. If not present then the
@@ -159,8 +204,8 @@ default digest algorithm for the signing key will be used (usually SHA1).
the encryption algorithm to use. For example DES (56 bits) - B<-des>,
triple DES (168 bits) - B<-des3>,
EVP_get_cipherbyname() function) can also be used preceded by a dash, for
example B<-aes_128_cbc>. See L<B<enc>|enc(1)> for list of ciphers
EVP_get_cipherbyname() function) can also be used preceded by a dash, for
example B<-aes-128-cbc>. See L<B<enc>|enc(1)> for list of ciphers
supported by your version of OpenSSL.
If not specified triple DES is used. Only used with B<-encrypt>.
@@ -205,6 +250,11 @@ effectively using CR and LF as end of line: as required by the S/MIME
specification. When this option is present no translation occurs. This
is useful when handling binary data which may not be in MIME format.
=item B<-crlfeol>
normally the output file uses a single B<LF> as end of line. When this
option is present B<CRLF> is used instead.
=item B<-nodetach>
when signing a message use opaque signing: this form is more resistant
@@ -230,31 +280,33 @@ verification was successful.
the recipients certificate when decrypting a message. This certificate
must match one of the recipients of the message or an error occurs.
=item B<-inkey file>
=item B<-inkey file_or_id>
the private key to use when signing or decrypting. This must match the
corresponding certificate. If this option is not specified then the
private key must be included in the certificate file specified with
the B<-recip> or B<-signer> file. When signing this option can be used
multiple times to specify successive keys.
If no engine is used, the argument is taken as a file; if an engine is
specified, the argument is given to the engine as a key identifier.
=item B<-passin arg>
the private key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-rand file(s)>
a file or files containing random data used to seed the random number
generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>).
Multiple files can be specified separated by a OS-dependent character.
generator, or an EGD socket (see L<RAND_egd(3)>).
Multiple files can be specified separated by an OS-dependent character.
The separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for
all others.
=item B<cert.pem...>
one or more certificates of message recipients: used when encrypting
a message.
a message.
=item B<-to, -from, -subject>
@@ -263,10 +315,16 @@ portion of a message so they may be included manually. If signing
then many S/MIME mail clients check the signers certificate's email
address matches that specified in the From: address.
=item B<-purpose, -ignore_critical, -issuer_checks, -crl_check, -crl_check_all, -policy_check, -extended_crl, -x509_strict, -policy -check_ss_sig -no_alt_chains>
=item B<-attime>, B<-check_ss_sig>, B<-crl_check>, B<-crl_check_all>,
B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>, B<-inhibit_any>,
B<-inhibit_map>, B<-no_alt_chains>, B<-partial_chain>, B<-policy>,
B<-policy_check>, B<-policy_print>, B<-purpose>, B<-suiteB_128>,
B<-suiteB_128_only>, B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>,
B<-auth_level>, B<-verify_depth>, B<-verify_email>, B<-verify_hostname>,
B<-verify_ip>, B<-verify_name>, B<-x509_strict>
Set various options of certificate chain verification. See
L<B<verify>|verify(1)> manual page for details.
L<verify(1)> manual page for details.
=back
@@ -278,7 +336,7 @@ a blank line. Piping the mail directly to sendmail is one way to
achieve the correct format.
The supplied message to be signed or encrypted must include the
necessary MIME headers or many S/MIME clients wont display it
necessary MIME headers or many S/MIME clients won't display it
properly (if at all). You can use the B<-text> option to automatically
add plain text headers.
@@ -299,7 +357,7 @@ The B<-resign> option uses an existing message digest when adding a new
signer. This means that attributes must be present in at least one existing
signer using the same message digest or this operation will fail.
The B<-stream> and B<-indef> options enable experimental streaming I/O support.
The B<-stream> and B<-indef> options enable streaming I/O support.
As a result the encoding is BER using indefinite length constructed encoding
and no longer DER. Streaming is supported for the B<-encrypt> operation and the
B<-sign> operation if the content is not detached.
@@ -345,29 +403,29 @@ the signers certificates.
Create a cleartext signed message:
openssl smime -sign -in message.txt -text -out mail.msg \
-signer mycert.pem
-signer mycert.pem
Create an opaque signed message:
openssl smime -sign -in message.txt -text -out mail.msg -nodetach \
-signer mycert.pem
-signer mycert.pem
Create a signed message, include some additional certificates and
read the private key from another file:
openssl smime -sign -in in.txt -text -out mail.msg \
-signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
-signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
Create a signed message with two signers:
openssl smime -sign -in message.txt -text -out mail.msg \
-signer mycert.pem -signer othercert.pem
-signer mycert.pem -signer othercert.pem
Send a signed message under Unix directly to sendmail, including headers:
openssl smime -sign -in in.txt -text -signer mycert.pem \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed message" | sendmail someone@somewhere
-from steve@openssl.org -to someone@somewhere \
-subject "Signed message" | sendmail someone@somewhere
Verify a message and extract the signer's certificate if successful:
@@ -376,15 +434,15 @@ Verify a message and extract the signer's certificate if successful:
Send encrypted mail using triple DES:
openssl smime -encrypt -in in.txt -from steve@openssl.org \
-to someone@somewhere -subject "Encrypted message" \
-des3 user.pem -out mail.msg
-to someone@somewhere -subject "Encrypted message" \
-des3 user.pem -out mail.msg
Sign and encrypt mail:
openssl smime -sign -in ml.txt -signer my.pem -text \
| openssl smime -encrypt -out mail.msg \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed and Encrypted message" -des3 user.pem
| openssl smime -encrypt -out mail.msg \
-from steve@openssl.org -to someone@somewhere \
-subject "Signed and Encrypted message" -des3 user.pem
Note: the encryption command does not include the B<-text> option because the
message being encrypted already has MIME headers.
@@ -401,7 +459,7 @@ it with:
-----BEGIN PKCS7-----
-----END PKCS7-----
and using the command:
and using the command:
openssl smime -verify -inform PEM -in signature.pem -content content.txt
@@ -445,6 +503,15 @@ structures may cause parsing errors.
The use of multiple B<-signer> options and the B<-resign> command were first
added in OpenSSL 1.0.0
The -no_alt_chains options was first added to OpenSSL 1.0.2b.
The -no_alt_chains options was first added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

58
doc/apps/speed.pod
View File

@@ -7,41 +7,27 @@ speed - test library performance
=head1 SYNOPSIS
B<openssl speed>
[B<-help>]
[B<-engine id>]
[B<md2>]
[B<mdc2>]
[B<md5>]
[B<hmac>]
[B<sha1>]
[B<rmd160>]
[B<idea-cbc>]
[B<rc2-cbc>]
[B<rc5-cbc>]
[B<bf-cbc>]
[B<des-cbc>]
[B<des-ede3>]
[B<rc4>]
[B<rsa512>]
[B<rsa1024>]
[B<rsa2048>]
[B<rsa4096>]
[B<dsa512>]
[B<dsa1024>]
[B<dsa2048>]
[B<idea>]
[B<rc2>]
[B<des>]
[B<rsa>]
[B<blowfish>]
[B<-elapsed>]
[B<-evp algo>]
[B<-decrypt>]
[B<algorithm...>]
=head1 DESCRIPTION
This command is used to test the performance of cryptographic algorithms.
To see the list of supported algorithms, use the I<list --digest-commands>
or I<list --cipher-commands> command.
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-engine id>
specifying an engine (by its unique B<id> string) will cause B<speed>
@@ -49,6 +35,19 @@ to attempt to obtain a functional reference to the specified engine,
thus initialising it if needed. The engine will then be set as the default
for all available algorithms.
=item B<-elapsed>
Measure time in real time instead of CPU time. It can be useful when testing
speed of hardware engines.
=item B<-evp algo>
Use the specified cipher or message digest algorithm via the EVP interface.
=item B<-decrypt>
Time the decryption instead of encryption. Affects only the EVP testing.
=item B<[zero or more test algorithms]>
If any options are given, B<speed> tests those algorithms, otherwise all of
@@ -56,4 +55,13 @@ the above are tested.
=back
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

20
doc/apps/spkac.pod
View File

@@ -7,6 +7,7 @@ spkac - SPKAC printing and generating utility
=head1 SYNOPSIS
B<openssl> B<spkac>
[B<-help>]
[B<-in filename>]
[B<-out filename>]
[B<-key keyfile>]
@@ -25,10 +26,14 @@ The B<spkac> command processes Netscape signed public key and challenge
(SPKAC) files. It can print out their contents, verify the signature and
produce its own SPKACs from a supplied private key.
=head1 COMMAND OPTIONS
=head1 OPTIONS
=over 4
=item B<-help>
Print out a usage message.
=item B<-in filename>
This specifies the input filename to read from or standard input if this
@@ -48,7 +53,7 @@ present.
=item B<-passin password>
the input file password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-challenge string>
@@ -128,6 +133,15 @@ to be used in a "replay attack".
=head1 SEE ALSO
L<ca(1)|ca(1)>
L<ca(1)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

213
doc/apps/ts.pod
View File

@@ -12,8 +12,8 @@ B<-query>
[B<-config> configfile]
[B<-data> file_to_hash]
[B<-digest> digest_bytes]
[B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...>]
[B<-policy> object_id]
[B<-[digest]>]
[B<-tspolicy> object_id]
[B<-no_nonce>]
[B<-cert>]
[B<-in> request.tsq]
@@ -27,9 +27,10 @@ B<-reply>
[B<-queryfile> request.tsq]
[B<-passin> password_src]
[B<-signer> tsa_cert.pem]
[B<-inkey> private.pem]
[B<-inkey> file_or_id]
[B<-sha1|-sha224|-sha256|-sha384|-sha512>]
[B<-chain> certs_file.pem]
[B<-policy> object_id]
[B<-tspolicy> object_id]
[B<-in> response.tsr]
[B<-token_in>]
[B<-out> response.tsr]
@@ -47,6 +48,38 @@ B<-verify>
[B<-CApath> trusted_cert_path]
[B<-CAfile> trusted_certs.pem]
[B<-untrusted> cert_file.pem]
[I<verify options>]
I<verify options:>
[-attime timestamp]
[-check_ss_sig]
[-crl_check]
[-crl_check_all]
[-explicit_policy]
[-extended_crl]
[-ignore_critical]
[-inhibit_any]
[-inhibit_map]
[-issuer_checks]
[-no_alt_chains]
[-no_check_time]
[-partial_chain]
[-policy arg]
[-policy_check]
[-policy_print]
[-purpose purpose]
[-suiteB_128]
[-suiteB_128_only]
[-suiteB_192]
[-trusted_first]
[-use_deltas]
[-auth_level num]
[-verify_depth num]
[-verify_email email]
[-verify_hostname hostname]
[-verify_ip ip]
[-verify_name name]
[-x509_strict]
=head1 DESCRIPTION
@@ -106,9 +139,9 @@ MS-Windows, B<,> for VMS and B<:> for all other platforms. (Optional)
=item B<-config> configfile
The configuration file to use, this option overrides the
B<OPENSSL_CONF> environment variable. Only the OID section
of the config file is used with the B<-query> command. (Optional)
The configuration file to use.
Optional; for a description of the default value,
see L<openssl(1)/COMMAND SUMMARY>.
=item B<-data> file_to_hash
@@ -121,16 +154,16 @@ parameter is specified. (Optional)
It is possible to specify the message imprint explicitly without the data
file. The imprint must be specified in a hexadecimal format, two characters
per byte, the bytes optionally separated by colons (e.g. 1A:F6:01:... or
1AF601...). The number of bytes must match the message digest algorithm
1AF601...). The number of bytes must match the message digest algorithm
in use. (Optional)
=item B<-md2>|B<-md4>|B<-md5>|B<-sha>|B<-sha1>|B<-mdc2>|B<-ripemd160>|B<...>
=item B<-[digest]>
The message digest to apply to the data file, it supports all the message
digest algorithms that are supported by the openssl B<dgst> command.
The message digest to apply to the data file.
Any digest supported by the OpenSSL B<dgst> command can be used.
The default is SHA-1. (Optional)
=item B<-policy> object_id
=item B<-tspolicy> object_id
The policy that the client expects the TSA to use for creating the
time stamp token. Either the dotted OID notation or OID names defined
@@ -154,7 +187,6 @@ response. (Optional)
This option specifies a previously created time stamp request in DER
format that will be printed into the output file. Useful when you need
to examine the content of a request in human-readable
format. (Optional)
=item B<-out> request.tsq
@@ -183,13 +215,14 @@ otherwise it is a time stamp token (ContentInfo).
=item B<-config> configfile
The configuration file to use, this option overrides the
B<OPENSSL_CONF> environment variable. See B<CONFIGURATION FILE
OPTIONS> for configurable variables. (Optional)
The configuration file to use.
Optional; for a description of the default value,
see L<openssl(1)/COMMAND SUMMARY>.
See B<CONFIGURATION FILE OPTIONS> for configurable variables.
=item B<-section> tsa_section
The name of the config file section conatining the settings for the
The name of the config file section containing the settings for the
response generation. If not specified the default TSA section is
used, see B<CONFIGURATION FILE OPTIONS> for details. (Optional)
@@ -200,7 +233,7 @@ The name of the file containing a DER encoded time stamp request. (Optional)
=item B<-passin> password_src
Specifies the password source for the private key of the TSA. See
B<PASS PHRASE ARGUMENTS> in L<openssl(1)|openssl(1)>. (Optional)
B<PASS PHRASE ARGUMENTS> in L<openssl(1)>. (Optional)
=item B<-signer> tsa_cert.pem
@@ -210,10 +243,17 @@ timeStamping. The extended key usage must also be critical, otherwise
the certificate is going to be refused. Overrides the B<signer_cert>
variable of the config file. (Optional)
=item B<-inkey> private.pem
=item B<-inkey> file_or_id
The signer private key of the TSA in PEM format. Overrides the
B<signer_key> config file option. (Optional)
If no engine is used, the argument is taken as a file; if an engine is
specified, the argument is given to the engine as a key identifier.
=item B<-sha1|-sha224|-sha256|-sha384|-sha512>
Signing digest to use. Overrides the B<signer_digest> config file
option. (Optional)
=item B<-chain> certs_file.pem
@@ -224,7 +264,7 @@ contain the certificate chain for the signer certificate from its
issuer upwards. The B<-reply> command does not build a certificate
chain automatically. (Optional)
=item B<-policy> object_id
=item B<-tspolicy> object_id
The default policy to use for the response unless the client
explicitly requires a particular TSA policy. The OID can be specified
@@ -283,7 +323,7 @@ data file. The B<-verify> command does not use the configuration file.
=item B<-data> file_to_hash
The response or token must be verified against file_to_hash. The file
is hashed with the message digest algorithm specified in the token.
is hashed with the message digest algorithm specified in the token.
The B<-digest> and B<-queryfile> options must not be specified with this one.
(Optional)
@@ -311,16 +351,16 @@ of a time stamp response (TimeStampResp). (Optional)
=item B<-CApath> trusted_cert_path
The name of the directory containing the trused CA certificates of the
client. See the similar option of L<verify(1)|verify(1)> for additional
The name of the directory containing the trusted CA certificates of the
client. See the similar option of L<verify(1)> for additional
details. Either this option or B<-CAfile> must be specified. (Optional)
=item B<-CAfile> trusted_certs.pem
The name of the file containing a set of trusted self-signed CA
certificates in PEM format. See the similar option of
L<verify(1)|verify(1)> for additional details. Either this option
The name of the file containing a set of trusted self-signed CA
certificates in PEM format. See the similar option of
L<verify(1)> for additional details. Either this option
or B<-CApath> must be specified.
(Optional)
@@ -332,12 +372,24 @@ certificate. This file must contain the TSA signing certificate and
all intermediate CA certificates unless the response includes them.
(Optional)
=item I<verify options>
The options B<-attime timestamp>, B<-check_ss_sig>, B<-crl_check>,
B<-crl_check_all>, B<-explicit_policy>, B<-extended_crl>, B<-ignore_critical>,
B<-inhibit_any>, B<-inhibit_map>, B<-issuer_checks>, B<-no_alt_chains>,
B<-no_check_time>, B<-partial_chain>, B<-policy>, B<-policy_check>,
B<-policy_print>, B<-purpose>, B<-suiteB_128>, B<-suiteB_128_only>,
B<-suiteB_192>, B<-trusted_first>, B<-use_deltas>, B<-auth_level>,
B<-verify_depth>, B<-verify_email>, B<-verify_hostname>, B<-verify_ip>,
B<-verify_name>, and B<-x509_strict> can be used to control timestamp
verification. See L<verify(1)>.
=back
=head1 CONFIGURATION FILE OPTIONS
The B<-query> and B<-reply> commands make use of a configuration file
defined by the B<OPENSSL_CONF> environment variable. See L<config(5)|config(5)>
The B<-query> and B<-reply> commands make use of a configuration file.
See L<config(5)>
for a general description of the syntax of the config file. The
B<-query> command uses only the symbolic OID names section
and it can work without it. However, the B<-reply> command needs the
@@ -348,7 +400,7 @@ switch always overrides the settings in the config file.
=over 4
=item B<tsa> section, B<default_tsa>
=item B<tsa> section, B<default_tsa>
This is the main section and it specifies the name of another section
that contains all the options for the B<-reply> command. This default
@@ -356,15 +408,15 @@ section can be overridden with the B<-section> command line switch. (Optional)
=item B<oid_file>
See L<ca(1)|ca(1)> for description. (Optional)
See L<ca(1)> for description. (Optional)
=item B<oid_section>
See L<ca(1)|ca(1)> for description. (Optional)
See L<ca(1)> for description. (Optional)
=item B<RANDFILE>
See L<ca(1)|ca(1)> for description. (Optional)
See L<ca(1)> for description. (Optional)
=item B<serial>
@@ -375,8 +427,8 @@ generation a new file is created with serial number 1. (Mandatory)
=item B<crypto_device>
Specifies the OpenSSL engine that will be set as the default for
all available algorithms. The default value is builtin, you can specify
Specifies the OpenSSL engine that will be set as the default for
all available algorithms. The default value is builtin, you can specify
any other engines supported by OpenSSL (e.g. use chil for the NCipher HSM).
(Optional)
@@ -396,10 +448,15 @@ option. (Optional)
The private key of the TSA in PEM format. The same as the B<-inkey>
command line option. (Optional)
=item B<signer_digest>
Signing digest to use. The same as the
B<-sha1|-sha224|-sha256|-sha384|-sha512> command line option. (Optional)
=item B<default_policy>
The default policy to use when the request does not mandate any
policy. The same as the B<-policy> command line option. (Optional)
policy. The same as the B<-tspolicy> command line option. (Optional)
=item B<other_policies>
@@ -419,7 +476,7 @@ the components is missing zero is assumed for that field. (Optional)
=item B<clock_precision_digits>
Specifies the maximum number of digits, which represent the fraction of
Specifies the maximum number of digits, which represent the fraction of
seconds, that need to be included in the time field. The trailing zeroes
must be removed from the time, so there might actually be fewer digits,
or no fraction of seconds at all. Supported only on UNIX platforms.
@@ -450,42 +507,37 @@ included. Default is no. (Optional)
=back
=head1 ENVIRONMENT VARIABLES
B<OPENSSL_CONF> contains the path of the configuration file and can be
overridden by the B<-config> command line option.
=head1 EXAMPLES
All the examples below presume that B<OPENSSL_CONF> is set to a proper
configuration file, e.g. the example configuration file
configuration file, e.g. the example configuration file
openssl/apps/openssl.cnf will do.
=head2 Time Stamp Request
To create a time stamp request for design1.txt with SHA-1
To create a time stamp request for design1.txt with SHA-1
without nonce and policy and no certificate is required in the response:
openssl ts -query -data design1.txt -no_nonce \
-out design1.tsq
-out design1.tsq
To create a similar time stamp request with specifying the message imprint
explicitly:
openssl ts -query -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
-no_nonce -out design1.tsq
-no_nonce -out design1.tsq
To print the content of the previous request in human readable format:
openssl ts -query -in design1.tsq -text
To create a time stamp request which includes the MD-5 digest
To create a time stamp request which includes the MD-5 digest
of design2.txt, requests the signer certificate and nonce,
specifies a policy id (assuming the tsa_policy1 name is defined in the
OID section of the config file):
openssl ts -query -data design2.txt -md5 \
-policy tsa_policy1 -cert -out design2.tsq
-tspolicy tsa_policy1 -cert -out design2.tsq
=head2 Time Stamp Response
@@ -493,8 +545,8 @@ Before generating a response a signing certificate must be created for
the TSA that contains the B<timeStamping> critical extended key usage extension
without any other key usage extensions. You can add the
'extendedKeyUsage = critical,timeStamping' line to the user certificate section
of the config file to generate a proper certificate. See L<req(1)|req(1)>,
L<ca(1)|ca(1)>, L<x509(1)|x509(1)> for instructions. The examples
of the config file to generate a proper certificate. See L<req(1)>,
L<ca(1)>, L<x509(1)> for instructions. The examples
below assume that cacert.pem contains the certificate of the CA,
tsacert.pem is the signing certificate issued by cacert.pem and
tsakey.pem is the private key of the TSA.
@@ -502,7 +554,7 @@ tsakey.pem is the private key of the TSA.
To create a time stamp response for a request:
openssl ts -reply -queryfile design1.tsq -inkey tsakey.pem \
-signer tsacert.pem -out design1.tsr
-signer tsacert.pem -out design1.tsr
If you want to use the settings in the config file you could just write:
@@ -534,61 +586,76 @@ valid response:
To verify a time stamp reply against a request:
openssl ts -verify -queryfile design1.tsq -in design1.tsr \
-CAfile cacert.pem -untrusted tsacert.pem
-CAfile cacert.pem -untrusted tsacert.pem
To verify a time stamp reply that includes the certificate chain:
openssl ts -verify -queryfile design2.tsq -in design2.tsr \
-CAfile cacert.pem
-CAfile cacert.pem
To verify a time stamp token against the original data file:
openssl ts -verify -data design2.txt -in design2.tsr \
-CAfile cacert.pem
-CAfile cacert.pem
To verify a time stamp token against a message imprint:
openssl ts -verify -digest b7e5d3f93198b38379852f2c04e78d73abdd0f4b \
-in design2.tsr -CAfile cacert.pem
-in design2.tsr -CAfile cacert.pem
You could also look at the 'test' directory for more examples.
=head1 BUGS
=for comment foreign manuals: procmail(1), perl(1)
If you find any bugs or you have suggestions please write to
Zoltan Glozik <zglozik@opentsa.org>. Known issues:
=over 4
=over 2
=item * No support for time stamps over SMTP, though it is quite easy
to implement an automatic e-mail based TSA with L<procmail(1)|procmail(1)>
and L<perl(1)|perl(1)>. HTTP server support is provided in the form of
=item *
No support for time stamps over SMTP, though it is quite easy
to implement an automatic e-mail based TSA with L<procmail(1)>
and L<perl(1)>. HTTP server support is provided in the form of
a separate apache module. HTTP client support is provided by
L<tsget(1)|tsget(1)>. Pure TCP/IP protocol is not supported.
L<tsget(1)>. Pure TCP/IP protocol is not supported.
=item * The file containing the last serial number of the TSA is not
=item *
The file containing the last serial number of the TSA is not
locked when being read or written. This is a problem if more than one
instance of L<openssl(1)|openssl(1)> is trying to create a time stamp
instance of L<openssl(1)> is trying to create a time stamp
response at the same time. This is not an issue when using the apache
server module, it does proper locking.
=item * Look for the FIXME word in the source files.
=item *
=item * The source code should really be reviewed by somebody else, too.
Look for the FIXME word in the source files.
=item * More testing is needed, I have done only some basic tests (see
=item *
The source code should really be reviewed by somebody else, too.
=item *
More testing is needed, I have done only some basic tests (see
test/testtsa).
=back
=cut
=head1 AUTHOR
Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org)
=head1 SEE ALSO
L<tsget(1)|tsget(1)>, L<openssl(1)|openssl(1)>, L<req(1)|req(1)>,
L<x509(1)|x509(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
L<config(5)|config(5)>
L<tsget(1)>, L<openssl(1)>, L<req(1)>,
L<x509(1)>, L<ca(1)>, L<genrsa(1)>,
L<config(5)>
=head1 COPYRIGHT
Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

45
doc/apps/tsget.pod
View File

@@ -33,15 +33,15 @@ line.
The tool sends the following HTTP request for each time stamp request:
POST url HTTP/1.1
User-Agent: OpenTSA tsget.pl/<version>
Host: <host>:<port>
Pragma: no-cache
Content-Type: application/timestamp-query
Accept: application/timestamp-reply
Content-Length: length of body
POST url HTTP/1.1
User-Agent: OpenTSA tsget.pl/<version>
Host: <host>:<port>
Pragma: no-cache
Content-Type: application/timestamp-query
Accept: application/timestamp-reply
Content-Length: length of body
...binary request specified by the user...
...binary request specified by the user...
B<tsget> expects a response of type application/timestamp-reply, which is
written to a file without any interpretation.
@@ -142,7 +142,7 @@ time stamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests
and at port 8443 for HTTPS requests, the TSA service is available at the /tsa
absolute path.
Get a time stamp response for file1.tsq over HTTP, output is written to
Get a time stamp response for file1.tsq over HTTP, output is written to
file1.tsr:
tsget -h http://tsa.opentsa.org:8080/tsa file1.tsq
@@ -151,44 +151,49 @@ Get a time stamp response for file1.tsq and file2.tsq over HTTP showing
progress, output is written to file1.reply and file2.reply respectively:
tsget -h http://tsa.opentsa.org:8080/tsa -v -e .reply \
file1.tsq file2.tsq
file1.tsq file2.tsq
Create a time stamp request, write it to file3.tsq, send it to the server and
write the response to file3.tsr:
openssl ts -query -data file3.txt -cert | tee file3.tsq \
| tsget -h http://tsa.opentsa.org:8080/tsa \
-o file3.tsr
| tsget -h http://tsa.opentsa.org:8080/tsa \
-o file3.tsr
Get a time stamp response for file1.tsq over HTTPS without client
authentication:
tsget -h https://tsa.opentsa.org:8443/tsa \
-C cacerts.pem file1.tsq
-C cacerts.pem file1.tsq
Get a time stamp response for file1.tsq over HTTPS with certificate-based
client authentication (it will ask for the passphrase if client_key.pem is
protected):
tsget -h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \
-k client_key.pem -c client_cert.pem file1.tsq
-k client_key.pem -c client_cert.pem file1.tsq
You can shorten the previous command line if you make use of the B<TSGET>
environment variable. The following commands do the same as the previous
example:
TSGET='-h https://tsa.opentsa.org:8443/tsa -C cacerts.pem \
-k client_key.pem -c client_cert.pem'
-k client_key.pem -c client_cert.pem'
export TSGET
tsget file1.tsq
=head1 AUTHOR
Zoltan Glozik <zglozik@opentsa.org>, OpenTSA project (http://www.opentsa.org)
=head1 SEE ALSO
L<openssl(1)|openssl(1)>, L<ts(1)|ts(1)>, L<curl(1)|curl(1)>,
L<openssl(1)>, L<ts(1)>, L<curl(1)>,
B<RFC 3161>
=head1 COPYRIGHT
Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

637
doc/apps/verify.pod
View File

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

19
doc/apps/version.pod
View File

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

111
doc/apps/x509.pod
View File

@@ -1,4 +1,3 @@
=pod
=head1 NAME
@@ -8,6 +7,7 @@ x509 - Certificate display and signing utility
=head1 SYNOPSIS
B<openssl> B<x509>
[B<-help>]
[B<-inform DER|PEM|NET>]
[B<-outform DER|PEM|NET>]
[B<-keyform DER|PEM>]
@@ -55,7 +55,7 @@ B<openssl> B<x509>
[B<-text>]
[B<-certopt option>]
[B<-C>]
[B<-md2|-md5|-sha1|-mdc2>]
[B<-[digest]>]
[B<-clrext>]
[B<-extfile filename>]
[B<-extensions section>]
@@ -73,10 +73,14 @@ various sections.
=head1 OPTIONS
=head2 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
=head2 Input, Output, and General Purpose Options
=over 4
=item B<-help>
Print out a usage message.
=item B<-inform DER|PEM|NET>
This specifies the input format normally the command will expect an X509
@@ -88,7 +92,7 @@ obsolete.
=item B<-outform DER|PEM|NET>
This specifies the output format, the options have the same meaning as the
This specifies the output format, the options have the same meaning as the
B<-inform> option.
=item B<-in filename>
@@ -101,12 +105,14 @@ if this option is not specified.
This specifies the output filename to write to or standard output by
default.
=item B<-md2|-md5|-sha1|-mdc2>
=item B<-[digest]>
the digest to use. This affects any signing or display option that uses a message
digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. If not
specified then SHA1 is used. If the key being used to sign with is a DSA key
then this option has no effect: SHA1 is always used with DSA keys.
the digest to use.
This affects any signing or display option that uses a message
digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options.
Any digest supported by the OpenSSL B<dgst> command can be used.
If not specified then SHA1 is used with B<-fingerprint> or
the default digest for the signing algorithm is used, typically SHA256.
=item B<-engine id>
@@ -117,7 +123,7 @@ for all available algorithms.
=back
=head2 DISPLAY OPTIONS
=head2 Display Options
Note: the B<-alias> and B<-purpose> options are also display options
but are described in the B<TRUST SETTINGS> section.
@@ -143,7 +149,7 @@ this option prevents output of the encoded version of the request.
=item B<-pubkey>
outputs the the certificate's SubjectPublicKeyInfo block in PEM format.
outputs the certificate's SubjectPublicKeyInfo block in PEM format.
=item B<-modulus>
@@ -233,9 +239,7 @@ this outputs the certificate in the form of a C source file.
=back
=head2 TRUST SETTINGS
Please note these options are currently experimental and may well change.
=head2 Trust Settings
A B<trusted certificate> is an ordinary certificate which has several
additional pieces of information attached to it such as the permitted
@@ -286,9 +290,12 @@ clears all the prohibited or rejected uses of the certificate.
=item B<-addtrust arg>
adds a trusted certificate use. Any object name can be used here
but currently only B<clientAuth> (SSL client use), B<serverAuth>
(SSL server use) and B<emailProtection> (S/MIME email) are used.
adds a trusted certificate use.
Any object name can be used here but currently only B<clientAuth> (SSL client
use), B<serverAuth> (SSL server use), B<emailProtection> (S/MIME email) and
B<anyExtendedKeyUsage> are used.
As of OpenSSL 1.1.0, the last of these blocks all purposes when rejected or
enables all purposes when trusted.
Other OpenSSL applications may define additional uses.
=item B<-addreject arg>
@@ -304,7 +311,7 @@ EXTENSIONS> section.
=back
=head2 SIGNING OPTIONS
=head2 Signing Options
The B<x509> utility can be used to sign certificates and requests: it
can thus behave like a "mini CA".
@@ -314,14 +321,15 @@ can thus behave like a "mini CA".
=item B<-signkey filename>
this option causes the input file to be self signed using the supplied
private key.
private key.
If the input file is a certificate it sets the issuer name to the
subject name (i.e. makes it self signed) changes the public key to the
supplied value and changes the start and end dates. The start date is
set to the current time and the end date is set to a value determined
by the B<-days> option. Any certificate extensions are retained unless
the B<-clrext> option is supplied.
the B<-clrext> option is supplied; this includes, for example, any existing
key identifier extensions.
If the input is a certificate request then a self signed certificate
is created using the supplied private key using the subject name in
@@ -330,7 +338,7 @@ the request.
=item B<-passin arg>
the key password source. For more information about the format of B<arg>
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)>.
=item B<-clrext>
@@ -366,8 +374,7 @@ the B<-signkey> or B<-CA> options. If used in conjunction with the B<-CA>
option the serial number file (as specified by the B<-CAserial> or
B<-CAcreateserial> options) is not used.
The serial number can be decimal or hex (if preceded by B<0x>). Negative
serial numbers can also be specified but their use is not recommended.
The serial number can be decimal or hex (if preceded by B<0x>).
=item B<-CA filename>
@@ -395,15 +402,16 @@ an even number of hex digits with the serial number to use. After each
use the serial number is incremented and written out to the file again.
The default filename consists of the CA certificate file base name with
".srl" appended. For example if the CA certificate file is called
".srl" appended. For example if the CA certificate file is called
"mycacert.pem" it expects to find a serial number file called "mycacert.srl".
=item B<-CAcreateserial>
with this option the CA serial number file is created if it does not exist:
it will contain the serial number "02" and the certificate being signed will
have the 1 as its serial number. Normally if the B<-CA> option is specified
and the serial number file does not exist it is an error.
have the 1 as its serial number. If the B<-CA> option is specified
and the serial number file does not exist a random number is generated;
this is the recommended practice.
=item B<-extfile filename>
@@ -416,7 +424,7 @@ the section to add certificate extensions from. If this option is not
specified then the extensions should either be contained in the unnamed
(default) section or the default section should contain a variable called
"extensions" which contains the section to use. See the
L<x509v3_config(5)|x509v3_config(5)> manual page for details of the
L<x509v3_config(5)> manual page for details of the
extension section format.
=item B<-force_pubkey key>
@@ -430,7 +438,7 @@ The format or B<key> can be specified using the B<-keyform> option.
=back
=head2 NAME OPTIONS
=head2 Name Options
The B<nameopt> command line switch determines how the subject and issuer
names are displayed. If no B<nameopt> switch is present the default "oneline"
@@ -442,7 +450,7 @@ a B<-> to turn the option off. Only the first four will normally be used.
=item B<compat>
use the old format. This is equivalent to specifying no name options at all.
use the old format.
=item B<RFC2253>
@@ -455,7 +463,7 @@ B<sep_comma_plus>, B<dn_rev> and B<sname>.
a oneline format which is more readable than RFC2253. It is equivalent to
specifying the B<esc_2253>, B<esc_ctrl>, B<esc_msb>, B<utf8>, B<dump_nostr>,
B<dump_der>, B<use_quote>, B<sep_comma_plus_space>, B<space_eq> and B<sname>
options.
options. This is the I<default> of no name options are given explicitly.
=item B<multiline>
@@ -464,10 +472,15 @@ B<space_eq>, B<lname> and B<align>.
=item B<esc_2253>
escape the "special" characters required by RFC2253 in a field That is
escape the "special" characters required by RFC2253 in a field. That is
B<,+"E<lt>E<gt>;>. Additionally B<#> is escaped at the beginning of a string
and a space character at the beginning or end of a string.
=item B<esc_2254>
escape the "special" characters required by RFC2254 in a field. That is
the B<NUL> character as well as and B<()*>.
=item B<esc_ctrl>
escape control characters. That is those with ASCII values less than
@@ -568,7 +581,7 @@ name.
=back
=head2 TEXT OPTIONS
=head2 Text Options
As well as customising the name output format, it is also possible to
customise the actual fields printed using the B<certopt> options when
@@ -693,20 +706,20 @@ Convert a certificate request into a self signed certificate using
extensions for a CA:
openssl x509 -req -in careq.pem -extfile openssl.cnf -extensions v3_ca \
-signkey key.pem -out cacert.pem
-signkey key.pem -out cacert.pem
Sign a certificate request using the CA certificate above and add user
certificate extensions:
openssl x509 -req -in req.pem -extfile openssl.cnf -extensions v3_usr \
-CA cacert.pem -CAkey key.pem -CAcreateserial
-CA cacert.pem -CAkey key.pem -CAcreateserial
Set a certificate to be trusted for SSL client use and change set its alias to
"Steve's Class 1 CA"
openssl x509 -in cert.pem -addtrust clientAuth \
-setalias "Steve's Class 1 CA" -out trust.pem
-setalias "Steve's Class 1 CA" -out trust.pem
=head1 NOTES
@@ -821,7 +834,7 @@ Otherwise it is the same as a normal SSL server.
The extended key usage extension must be absent or include the "email
protection" OID. Netscape certificate type must be absent or should have the
S/MIME bit set. If the S/MIME bit is not set in netscape certificate type
S/MIME bit set. If the S/MIME bit is not set in Netscape certificate type
then the SSL client bit is tolerated as an alternative but a warning is shown:
this is because some Verisign certificates don't set the S/MIME bit.
@@ -840,7 +853,7 @@ if the keyUsage extension is present.
The extended key usage extension must be absent or include the "email
protection" OID. Netscape certificate type must be absent or must have the
S/MIME CA bit set: this is used as a work around if the basicConstraints
extension is absent.
extension is absent.
=item B<CRL Signing>
@@ -866,25 +879,27 @@ be checked.
There should be options to explicitly set such things as start and end
dates rather than an offset from the current time.
The code to implement the verify behaviour described in the B<TRUST SETTINGS>
is currently being developed. It thus describes the intended behaviour rather
than the current behaviour. It is hoped that it will represent reality in
OpenSSL 0.9.5 and later.
=head1 SEE ALSO
L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<genrsa(1)|genrsa(1)>,
L<gendsa(1)|gendsa(1)>, L<verify(1)|verify(1)>,
L<x509v3_config(5)|x509v3_config(5)>
L<req(1)>, L<ca(1)>, L<genrsa(1)>,
L<gendsa(1)>, L<verify(1)>,
L<x509v3_config(5)>
=head1 HISTORY
Before OpenSSL 0.9.8, the default digest for RSA keys was MD5.
The hash algorithm used in the B<-subject_hash> and B<-issuer_hash> options
before OpenSSL 1.0.0 was based on the deprecated MD5 algorithm and the encoding
of the distinguished name. In OpenSSL 1.0.0 and later it is based on a
canonical version of the DN using SHA1. This means that any directories using
the old form must have their links rebuilt using B<c_rehash> or similar.
the old form must have their links rebuilt using B<c_rehash> or similar.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

82
doc/apps/x509v3_config.pod
View File

@@ -88,7 +88,7 @@ only be used to sign end user certificates and not further CAs.
Key usage is a multi valued extension consisting of a list of names of the
permitted key usages.
The supporte names are: digitalSignature, nonRepudiation, keyEncipherment,
The supported names are: digitalSignature, nonRepudiation, keyEncipherment,
dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly
and decipherOnly.
@@ -108,24 +108,24 @@ These can either be object short names or the dotted numerical form of OIDs.
While any OID can be used only certain values make sense. In particular the
following PKIX, NS and MS values are meaningful:
Value Meaning
----- -------
serverAuth SSL/TLS Web Server Authentication.
clientAuth SSL/TLS Web Client Authentication.
codeSigning Code signing.
emailProtection E-mail Protection (S/MIME).
timeStamping Trusted Timestamping
msCodeInd Microsoft Individual Code Signing (authenticode)
msCodeCom Microsoft Commercial Code Signing (authenticode)
msCTLSign Microsoft Trust List Signing
msSGC Microsoft Server Gated Crypto
msEFS Microsoft Encrypted File System
nsSGC Netscape Server Gated Crypto
Value Meaning
----- -------
serverAuth SSL/TLS Web Server Authentication.
clientAuth SSL/TLS Web Client Authentication.
codeSigning Code signing.
emailProtection E-mail Protection (S/MIME).
timeStamping Trusted Timestamping
OCSPSigning OCSP Signing
ipsecIKE ipsec Internet Key Exchange
msCodeInd Microsoft Individual Code Signing (authenticode)
msCodeCom Microsoft Commercial Code Signing (authenticode)
msCTLSign Microsoft Trust List Signing
msEFS Microsoft Encrypted File System
Examples:
extendedKeyUsage=critical,codeSigning,1.2.3.4
extendedKeyUsage=nsSGC,msSGC
extendedKeyUsage=serverAuth,clientAuth
=head2 Subject Key Identifier.
@@ -167,7 +167,7 @@ registered ID: OBJECT IDENTIFIER), B<IP> (an IP address), B<dirName>
(a distinguished name) and otherName.
The email option include a special 'copy' value. This will automatically
include and email addresses contained in the certificate subject name in
include any email addresses contained in the certificate subject name in
the extension.
The IP address used in the B<IP> options can be in either IPv4 or IPv6 format.
@@ -178,7 +178,7 @@ prefacing the name with a B<+> character.
otherName can include arbitrary data associated with an OID: the value
should be the OID followed by a semicolon and the content in standard
L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format.
L<ASN1_generate_nconf(3)> format.
Examples:
@@ -202,7 +202,7 @@ Examples:
The issuer alternative name option supports all the literal options of
subject alternative name. It does B<not> support the email:copy option because
that would not make sense. It does support an additional issuer:copy option
that will copy all the subject alternative name values from the issuer
that will copy all the subject alternative name values from the issuer
certificate (if possible).
Example:
@@ -224,7 +224,7 @@ Example:
authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
=head2 CRL distribution points.
=head2 CRL distribution points
This is a multi-valued extension whose options can be either in name:value pair
using the same form as subject alternative name or a single value representing
@@ -358,7 +358,7 @@ Some software (for example some versions of MSIE) may require ia5org.
=head2 Policy Constraints
This is a multi-valued extension which consisting of the names
B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative intger
B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative integer
value. At least one component must be present.
Example:
@@ -380,7 +380,7 @@ Example:
The name constraints extension is a multi-valued extension. The name should
begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of
the name and the value follows the syntax of subjectAltName except email:copy
is not supported and the B<IP> form should consist of an IP addresses and
is not supported and the B<IP> form should consist of an IP addresses and
subnet mask separated by a B</>.
Examples:
@@ -401,6 +401,20 @@ Example:
noCheck = ignored
=head2 TLS Feature (aka Must Staple)
This is a multi-valued extension consisting of a list of TLS extension
identifiers. Each identifier may be a number (0..65535) or a supported name.
When a TLS client sends a listed extension, the TLS server is expected to
include that extension in its reply.
The supported names are: B<status_request> and B<status_request_v2>.
Example:
tlsfeature = status_request
=head1 DEPRECATED EXTENSIONS
The following extensions are non standard, Netscape specific and largely
@@ -441,7 +455,7 @@ the data is formatted correctly for the given extension type.
There are two ways to encode arbitrary extensions.
The first way is to use the word ASN1 followed by the extension content
using the same syntax as L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>.
using the same syntax as L<ASN1_generate_nconf(3)>.
For example:
1.2.3.4=critical,ASN1:UTF8String:Some random data
@@ -491,7 +505,7 @@ will produce an error but the equivalent form:
[subject_alt_section]
subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
is valid.
is valid.
Due to the behaviour of the OpenSSL B<conf> library the same field name
can only occur once in a section. This means that:
@@ -510,20 +524,18 @@ will only recognize the last value. This can be worked around by using the form:
email.1=steve@here
email.2=steve@there
=head1 HISTORY
The X509v3 extension code was first added to OpenSSL 0.9.2.
Policy mappings, inhibit any policy and name constraints support was added in
OpenSSL 0.9.8
The B<directoryName> and B<otherName> option as well as the B<ASN1> option
for arbitrary extensions was added in OpenSSL 0.9.8
=head1 SEE ALSO
L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>,
L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>
L<req(1)>, L<ca(1)>, L<x509(1)>,
L<ASN1_generate_nconf(3)>
=head1 COPYRIGHT
Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

45
doc/c-indentation.el
View File

@@ -1,45 +0,0 @@
; This Emacs Lisp file defines a C indentation style that closely
; follows most aspects of the one that is used throughout SSLeay,
; and hence in OpenSSL.
;
; This definition is for the "CC mode" package, which is the default
; mode for editing C source files in Emacs 20, not for the older
; c-mode.el (which was the default in less recent releaes of Emacs 19).
;
; Copy the definition in your .emacs file or use M-x eval-buffer.
; To activate this indentation style, visit a C file, type
; M-x c-set-style <RET> (or C-c . for short), and enter "eay".
; To toggle the auto-newline feature of CC mode, type C-c C-a.
;
; Apparently statement blocks that are not introduced by a statement
; such as "if" and that are not the body of a function cannot
; be handled too well by CC mode with this indentation style,
; so you have to indent them manually (you can use C-q tab).
;
; For suggesting improvements, please send e-mail to bodo@openssl.org.
(c-add-style "eay"
'((c-basic-offset . 8)
(indent-tabs-mode . t)
(c-comment-only-line-offset . 0)
(c-hanging-braces-alist)
(c-offsets-alist . ((defun-open . +)
(defun-block-intro . 0)
(class-open . +)
(class-close . +)
(block-open . 0)
(block-close . 0)
(substatement-open . +)
(statement . 0)
(statement-block-intro . 0)
(statement-case-open . +)
(statement-case-intro . +)
(case-label . -)
(label . -)
(arglist-cont-nonempty . +)
(topmost-intro . -)
(brace-list-close . 0)
(brace-list-intro . 0)
(brace-list-open . +)
))))

133
doc/crypto/ASN1_INTEGER_get_int64.pod Normal file
View File

@@ -0,0 +1,133 @@
=pod
=head1 NAME
ASN1_INTEGER_get_uint64, ASN1_INTEGER_set_uint64,
ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN
- ASN.1 INTEGER and ENUMERATED utilities
=head1 SYNOPSIS
#include <openssl/asn1.h>
int ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a);
int ASN1_INTEGER_get(const ASN1_INTEGER *a, long v);
int ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r);
long ASN1_INTEGER_set(const ASN1_INTEGER *a);
int ASN1_INTEGER_get_uint64(uint64_t *pr, const ASN1_INTEGER *a);
int ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t r);
ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai);
BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);
int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_INTEGER *a);
long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);
int ASN1_ENUMERATED_set_int64(ASN1_INTEGER *a, int64_t r);
int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);
ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(BIGNUM *bn, ASN1_ENUMERATED *ai);
BIGNUM *ASN1_ENUMERATED_to_BN(ASN1_ENUMERATED *ai, BIGNUM *bn);
=head1 DESCRIPTION
These functions convert to and from B<ASN1_INTEGER> and B<ASN1_ENUMERATED>
structures.
ASN1_INTEGER_get_int64() converts an B<ASN1_INTEGER> into an B<int64_t> type
If successful it returns 1 and sets B<*pr> to the value of B<a>. If it fails
(due to invalid type or the value being too big to fit into an B<int64_t> type)
it returns 0.
ASN1_INTEGER_get_uint64() is similar to ASN1_INTEGER_get_int64_t() except it
converts to a B<uint64_t> type and an error is returned if the passed integer
is negative.
ASN1_INTEGER_get() also returns the value of B<a> but it returns 0 if B<a> is
NULL and -1 on error (which is ambiguous because -1 is a legitimate value for
an B<ASN1_INTEGER>). New applications should use ASN1_INTEGER_get_int64()
instead.
ASN1_INTEGER_set_int64() sets the value of B<ASN1_INTEGER> B<a> to the
B<int64_t> value B<r>.
ASN1_INTEGER_set_uint64() sets the value of B<ASN1_INTEGER> B<a> to the
B<uint64_t> value B<r>.
ASN1_INTEGER_set() sets the value of B<ASN1_INTEGER> B<a> to the B<long> value
B<v>.
BN_to_ASN1_INTEGER() converts B<BIGNUM> B<bn> to an B<ASN1_INTEGER>. If B<ai>
is NULL a new B<ASN1_INTEGER> structure is returned. If B<ai> is not NULL then
the existing structure will be used instead.
ASN1_INTEGER_to_BN() converts ASN1_INTEGER B<ai> into a B<BIGNUM>. If B<bn> is
NULL a new B<BIGNUM> structure is returned. If B<bn> is not NULL then the
existing structure will be used instead.
ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_set_int64(),
ASN1_ENUMERATED_set(), BN_to_ASN1_ENUMERATED() and ASN1_ENUMERATED_to_BN()
behave in an identical way to their ASN1_INTEGER counterparts except they
operate on an B<ASN1_ENUMERATED> value.
ASN1_ENUMERATED_get() returns the value of B<a> in a similar way to
ASN1_INTEGER_get() but it returns B<0xffffffffL> if the value of B<a> will not
fit in a long type. New applications should use ASN1_ENUMERATED_get_int64()
instead.
=head1 NOTES
In general an B<ASN1_INTEGER> or B<ASN1_ENUMERATED> type can contain an
integer of almost arbitrary size and so cannot always be represented by a C
B<int64_t> type. However in many cases (for example version numbers) they
represent small integers which can be more easily manipulated if converted to
an appropriate C integer type.
=head1 BUGS
The ambiguous return values of ASN1_INTEGER_get() and ASN1_ENUMERATED_get()
mean these functions should be avoided if possible. They are retained for
compatibility. Normally the ambiguous return values are not legitimate
values for the fields they represent.
=head1 RETURN VALUES
ASN1_INTEGER_set_int64(), ASN1_INTEGER_set(), ASN1_ENUMERATED_set_int64() and
ASN1_ENUMERATED_set() return 1 for success and 0 for failure. They will only
fail if a memory allocation error occurs.
ASN1_INTEGER_get_int64() and ASN1_ENUMERATED_get_int64() return 1 for success
and 0 for failure. They will fail if the passed type is incorrect (this will
only happen if there is a programming error) or if the value exceeds the range
of an B<int64_t> type.
BN_to_ASN1_INTEGER() and BN_to_ASN1_ENUMERATED() return an B<ASN1_INTEGER> or
B<ASN1_ENUMERATED> structure respectively or NULL if an error occurs. They will
only fail due to a memory allocation error.
ASN1_INTEGER_to_BN() and ASN1_ENUMERATED_to_BN() return a B<BIGNUM> structure
of NULL if an error occurs. They can fail if the passed type is incorrect
(due to programming error) or due to a memory allocation failure.
=head1 SEE ALSO
L<ERR_get_error(3)>
=head1 HISTORY
ASN1_INTEGER_set_int64(), ASN1_INTEGER_get_int64(),
ASN1_ENUMERATED_set_int64() and ASN1_ENUMERATED_get_int64()
were added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

18
doc/crypto/ASN1_OBJECT_new.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions
ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions
=head1 SYNOPSIS
@@ -16,9 +16,10 @@ ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions
The ASN1_OBJECT allocation routines, allocate and free an
ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER.
ASN1_OBJECT_new() allocates and initializes a ASN1_OBJECT structure.
ASN1_OBJECT_new() allocates and initializes an ASN1_OBJECT structure.
ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>.
If B<a> is NULL, nothing is done.
=head1 NOTES
@@ -29,17 +30,22 @@ such as OBJ_nid2obj() are used instead.
=head1 RETURN VALUES
If the allocation fails, ASN1_OBJECT_new() returns B<NULL> and sets an error
code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
code that can be obtained by L<ERR_get_error(3)>.
Otherwise it returns a pointer to the newly allocated structure.
ASN1_OBJECT_free() returns no value.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)|d2i_ASN1_OBJECT(3)>
L<ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)>
=head1 HISTORY
=head1 COPYRIGHT
ASN1_OBJECT_new() and ASN1_OBJECT_free() are available in all versions of SSLeay and OpenSSL.
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

32
doc/crypto/ASN1_STRING_length.pod
View File

@@ -3,14 +3,15 @@
=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_to_UTF8 -
ASN1_STRING utility functions
ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data,
ASN1_STRING_to_UTF8 - ASN1_STRING utility functions
=head1 SYNOPSIS
#include <openssl/asn1.h>
int ASN1_STRING_length(ASN1_STRING *x);
const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x);
unsigned char * ASN1_STRING_data(ASN1_STRING *x);
ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
@@ -19,9 +20,9 @@ ASN1_STRING utility functions
int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
int ASN1_STRING_type(ASN1_STRING *x);
int ASN1_STRING_type(const ASN1_STRING *x);
int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in);
int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
=head1 DESCRIPTION
@@ -29,10 +30,14 @@ These functions allow an B<ASN1_STRING> structure to be manipulated.
ASN1_STRING_length() returns the length of the content of B<x>.
ASN1_STRING_data() returns an internal pointer to the data of B<x>.
ASN1_STRING_get0_data() returns an internal pointer to the data of B<x>.
Since this is an internal pointer it should B<not> be freed or
modified in any way.
ASN1_STRING_data() is similar to ASN1_STRING_get0_data() except the
returned value is not constant. This function is deprecated:
applications should use ASN1_STRING_get0_data() instead.
ASN1_STRING_dup() returns a copy of the structure B<a>.
ASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two
@@ -48,12 +53,12 @@ such as B<V_ASN1_OCTET_STRING>.
ASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the
converted data is allocated in a buffer in B<*out>. The length of
B<out> is returned or a negative error code. The buffer B<*out>
should be free using OPENSSL_free().
should be freed using OPENSSL_free().
=head1 NOTES
Almost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING>
structure. Other types such as B<ASN1_OCTET_STRING> are simply typedefed
structure. Other types such as B<ASN1_OCTET_STRING> are simply typedef'ed
to B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents.
B<ASN1_STRING> is also used for some B<CHOICE> types which consist
entirely of primitive string types such as B<DirectoryString> and
@@ -72,12 +77,17 @@ character in big endian format, UTF8String will be in UTF8 format.
Similar care should be take to ensure the data is in the correct format
when calling ASN1_STRING_set().
=head1 RETURN VALUES
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
L<ERR_get_error(3)>
=head1 HISTORY
=head1 COPYRIGHT
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

12
doc/crypto/ASN1_STRING_new.pod
View File

@@ -22,6 +22,7 @@ ASN1_STRING_type_new() returns an allocated B<ASN1_STRING> structure of
type B<type>.
ASN1_STRING_free() frees up B<a>.
If B<a> is NULL nothing is done.
=head1 NOTES
@@ -37,10 +38,15 @@ ASN1_STRING_free() does not return a value.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
L<ERR_get_error(3)>
=head1 HISTORY
=head1 COPYRIGHT
TBA
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

29
doc/crypto/ASN1_STRING_print_ex.pod
View File

@@ -2,16 +2,18 @@
=head1 NAME
ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING output routines.
ASN1_tag2str, ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print
- ASN1_STRING output routines
=head1 SYNOPSIS
#include <openssl/asn1.h>
int ASN1_STRING_print_ex(BIO *out, ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print_ex_fp(FILE *fp, ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print(BIO *out, ASN1_STRING *str);
int ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags);
int ASN1_STRING_print(BIO *out, const ASN1_STRING *str);
const char *ASN1_tag2str(int tag);
=head1 DESCRIPTION
@@ -26,11 +28,13 @@ ASN1_STRING_print() prints B<str> to B<out> but using a different format to
ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF)
with '.'.
ASN1_tag2str() returns a human-readable name of the specified ASN.1 B<tag>.
=head1 NOTES
ASN1_STRING_print() is a legacy function which should be avoided in new applications.
Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is
Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is
suitable, or on UTF8 terminals B<ASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB>.
The complete set of supported options for B<flags> is listed below.
@@ -75,7 +79,7 @@ Normally non character string types (such as OCTET STRING) are assumed to be
one byte per character, if B<ASN1_STRFLGS_DUMP_UNKNOWN> is set then they will
be dumped instead.
When a type is dumped normally just the content octets are printed, if
When a type is dumped normally just the content octets are printed, if
B<ASN1_STRFLGS_DUMP_DER> is set then the complete encoding is dumped
instead (including tag and length octets).
@@ -86,11 +90,16 @@ equivalent to:
=head1 SEE ALSO
L<X509_NAME_print_ex(3)|X509_NAME_print_ex(3)>,
L<ASN1_tag2str(3)|ASN1_tag2str(3)>
L<X509_NAME_print_ex(3)>,
L<ASN1_tag2str(3)>
=head1 HISTORY
=head1 COPYRIGHT
TBA
Copyright 2002-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

15
doc/crypto/ASN1_TIME_set.pod
View File

@@ -3,7 +3,7 @@
=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.
ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions
=head1 SYNOPSIS
@@ -100,7 +100,7 @@ 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 */
/* Invalid time format */
if (day > 0 || sec > 0)
printf("Later\n");
@@ -123,7 +123,16 @@ 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
ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the
pass ASN1_TIME structure has invalid syntax for example.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

100
doc/crypto/ASN1_TYPE_get.pod Normal file
View File

@@ -0,0 +1,100 @@
=pod
=head1 NAME
ASN1_TYPE_get, ASN1_TYPE_set, ASN1_TYPE_set1, ASN1_TYPE_cmp, ASN1_TYPE_unpack_sequence, ASN1_TYPE_pack_sequence - ASN1_TYPE utility
functions
=head1 SYNOPSIS
#include <openssl/asn1.h>
int ASN1_TYPE_get(const ASN1_TYPE *a);
void ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value);
int ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value);
int ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b);
void *ASN1_TYPE_unpack_sequence(const ASN1_ITEM *it, const ASN1_TYPE *t);
ASN1_TYPE *ASN1_TYPE_pack_sequence(const ASN1_ITEM *it, void *s,
ASN1_TYPE **t);
=head1 DESCRIPTION
These functions allow an ASN1_TYPE structure to be manipulated. The
ASN1_TYPE structure can contain any ASN.1 type or constructed type
such as a SEQUENCE: it is effectively equivalent to the ASN.1 ANY type.
ASN1_TYPE_get() returns the type of B<a>.
ASN1_TYPE_set() sets the value of B<a> to B<type> and B<value>. This
function uses the pointer B<value> internally so it must B<not> be freed
up after the call.
ASN1_TYPE_set1() sets the value of B<a> to B<type> a copy of B<value>.
ASN1_TYPE_cmp() compares ASN.1 types B<a> and B<b> and returns 0 if
they are identical and non-zero otherwise.
ASN1_TYPE_unpack_sequence() attempts to parse the SEQUENCE present in
B<t> using the ASN.1 structure B<it>. If successful it returns a pointer
to the ASN.1 structure corresponding to B<it> which must be freed by the
caller. If it fails it return NULL.
ASN1_TYPE_pack_sequence() attempts to encode the ASN.1 structure B<s>
corresponding to B<it> into an ASN1_TYPE. If successful the encoded
ASN1_TYPE is returned. If B<t> and B<*t> are not NULL the encoded type
is written to B<t> overwriting any existing data. If B<t> is not NULL
but B<*t> is NULL the returned ASN1_TYPE is written to B<*t>.
=head1 NOTES
The type and meaning of the B<value> parameter for ASN1_TYPE_set() and
ASN1_TYPE_set1() is determined by the B<type> parameter.
If B<type> is V_ASN1_NULL B<value> is ignored. If B<type> is V_ASN1_BOOLEAN
then the boolean is set to TRUE if B<value> is not NULL. If B<type> is
V_ASN1_OBJECT then value is an ASN1_OBJECT structure. Otherwise B<type>
is and ASN1_STRING structure. If B<type> corresponds to a primitive type
(or a string type) then the contents of the ASN1_STRING contain the content
octets of the type. If B<type> corresponds to a constructed type or
a tagged type (V_ASN1_SEQUENCE, V_ASN1_SET or V_ASN1_OTHER) then the
ASN1_STRING contains the entire ASN.1 encoding verbatim (including tag and
length octets).
ASN1_TYPE_cmp() may not return zero if two types are equivalent but have
different encodings. For example the single content octet of the boolean TRUE
value under BER can have any non-zero encoding but ASN1_TYPE_cmp() will
only return zero if the values are the same.
If either or both of the parameters passed to ASN1_TYPE_cmp() is NULL the
return value is non-zero. Technically if both parameters are NULL the two
types could be absent OPTIONAL fields and so should match, however passing
NULL values could also indicate a programming error (for example an
unparseable type which returns NULL) for types which do B<not> match. So
applications should handle the case of two absent values separately.
=head1 RETURN VALUES
ASN1_TYPE_get() returns the type of the ASN1_TYPE argument.
ASN1_TYPE_set() does not return a value.
ASN1_TYPE_set1() returns 1 for success and 0 for failure.
ASN1_TYPE_cmp() returns 0 if the types are identical and non-zero otherwise.
ASN1_TYPE_unpack_sequence() returns a pointer to an ASN.1 structure or
NULL on failure.
ASN1_TYPE_pack_sequence() return an ASN1_TYPE structure if it succeeds or
NULL on failure.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

37
doc/crypto/ASN1_generate_nconf.pod
View File

@@ -8,8 +8,8 @@ ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions
#include <openssl/asn1.h>
ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf);
ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf);
ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf);
ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf);
=head1 DESCRIPTION
@@ -19,7 +19,7 @@ in an B<ASN1_TYPE> structure.
B<str> contains the string to encode B<nconf> or B<cnf> contains
the optional configuration information where additional strings
will be read from. B<nconf> will typically come from a config
file wherease B<cnf> is obtained from an B<X509V3_CTX> structure
file whereas B<cnf> is obtained from an B<X509V3_CTX> structure
which will typically be used by X509 v3 certificate extension
functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional
configuration will be used.
@@ -30,7 +30,7 @@ The actual data encoded is determined by the string B<str> and
the configuration information. The general format of the string
is:
=over 2
=over 4
=item B<[modifier,]type[:value]>
@@ -40,19 +40,19 @@ That is zero or more comma separated modifiers followed by a type
followed by an optional colon and a value. The formats of B<type>,
B<value> and B<modifier> are explained below.
=head2 SUPPORTED TYPES
=head2 Supported Types
The supported types are listed below. Unless otherwise specified
only the B<ASCII> format is permissible.
=over 2
=over 4
=item B<BOOLEAN>, B<BOOL>
This encodes a boolean type. The B<value> string is mandatory and
should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>,
B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no>
are acceptable.
are acceptable.
=item B<NULL>
@@ -78,12 +78,12 @@ a short name, a long name or numerical format.
=item B<UTCTIME>, B<UTC>
Encodes an ASN1 B<UTCTime> structure, the value should be in
the format B<YYMMDDHHMMSSZ>.
the format B<YYMMDDHHMMSSZ>.
=item B<GENERALIZEDTIME>, B<GENTIME>
Encodes an ASN1 B<GeneralizedTime> structure, the value should be in
the format B<YYYYMMDDHHMMSSZ>.
the format B<YYYYMMDDHHMMSSZ>.
=item B<OCTETSTRING>, B<OCT>
@@ -119,14 +119,14 @@ will be encoded.
=back
=head2 MODIFIERS
=head2 Modifiers
Modifiers affect the following structure, they can be used to
add EXPLICIT or IMPLICIT tagging, add wrappers or to change
the string format of the final type and value. The supported
formats are documented below.
=over 2
=over 4
=item B<EXPLICIT>, B<EXP>
@@ -181,7 +181,7 @@ A BITSTRING with bits 1 and 5 set and all others zero:
FORMAT:BITLIST,BITSTRING:1,5
A more complex example using a config file to produce a
SEQUENCE consiting of a BOOL an OID and a UTF8String:
SEQUENCE consisting of a BOOL an OID and a UTF8String:
asn1 = SEQUENCE:seq_section
@@ -252,14 +252,19 @@ structure:
ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
The error codes that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
The error codes that can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>
L<ERR_get_error(3)>
=head1 HISTORY
=head1 COPYRIGHT
ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8
Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

144
doc/crypto/ASYNC_WAIT_CTX_new.pod Normal file
View File

@@ -0,0 +1,144 @@
=pod
=head1 NAME
ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd - functions to manage
waiting for asynchronous jobs to complete
=head1 SYNOPSIS
#include <openssl/async.h>
ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void);
void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx);
int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key,
OSSL_ASYNC_FD fd,
void *custom_data,
void (*cleanup)(ASYNC_WAIT_CTX *, const void *,
OSSL_ASYNC_FD, void *));
int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key,
OSSL_ASYNC_FD *fd, void **custom_data);
int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd,
size_t *numfds);
int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd,
size_t *numaddfds, OSSL_ASYNC_FD *delfd,
size_t *numdelfds);
int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key);
=head1 DESCRIPTION
For an overview of how asynchronous operations are implemented in OpenSSL see
L<ASYNC_start_job(3)>. An ASYNC_WAIT_CTX object represents an asynchronous
"session", i.e. a related set of crypto operations. For example in SSL terms
this would have a one-to-one correspondence with an SSL connection.
Application code must create an ASYNC_WAIT_CTX using the ASYNC_WAIT_CTX_new()
function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When
the job is started it is associated with the ASYNC_WAIT_CTX for the duration of
that job. An ASYNC_WAIT_CTX should only be used for one ASYNC_JOB at any one
time, but can be reused after an ASYNC_JOB has finished for a subsequent
ASYNC_JOB. When the session is complete (e.g. the SSL connection is closed),
application code cleans up with ASYNC_WAIT_CTX_free().
ASYNC_WAIT_CTXs can have "wait" file descriptors associated with them. Calling
ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an ASYNC_WAIT_CTX in
the B<ctx> parameter will return the wait file descriptors associated with that
job in B<*fd>. The number of file descriptors returned will be stored in
B<*numfds>. It is the caller's responsibility to ensure that sufficient memory
has been allocated in B<*fd> to receive all the file descriptors. Calling
ASYNC_WAIT_CTX_get_all_fds() with a NULL B<fd> value will return no file
descriptors but will still populate B<*numfds>. Therefore application code is
typically expected to call this function twice: once to get the number of fds,
and then again when sufficient memory has been allocated. If only one
asynchronous engine is being used then normally this call will only ever return
one fd. If multiple asynchronous engines are being used then more could be
returned.
The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds
have changed since the last call time ASYNC_start_job() returned an ASYNC_PAUSE
result (or since the ASYNC_WAIT_CTX was created if no ASYNC_PAUSE result has
been received). The B<numaddfds> and B<numdelfds> parameters will be populated
with the number of fds added or deleted respectively. B<*addfd> and B<*delfd>
will be populated with the list of added and deleted fds respectively. Similarly
to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not
NULL then the caller is responsible for ensuring sufficient memory is allocated.
Implementors of async aware code (e.g. engines) are encouraged to return a
stable fd for the lifetime of the ASYNC_WAIT_CTX in order to reduce the "churn"
of regularly changing fds - although no guarantees of this are provided to
applications.
Applications can wait for the file descriptor to be ready for "read" using a
system function call such as select or poll (being ready for "read" indicates
that the job should be resumed). If no file descriptor is made available then an
application will have to periodically "poll" the job by attempting to restart it
to see if it is ready to continue.
Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from the job
via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for waiting
on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done by an
engine immediately prior to calling ASYNC_pause_job() and not by end user code.
An existing association with a file descriptor can be obtained using
ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of
these functions requires a B<key> value which is unique to the async aware
code. This could be any unique value but a good candidate might be the
B<ENGINE *> for the engine. The B<custom_data> parameter can be any value, and
will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The
ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup"
routine. This can be NULL but if provided will automatically get called when
the ASYNC_WAIT_CTX is freed, and gives the engine the opportunity to close the
fd or any other resources. Note: The "cleanup" routine does not get called if
the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd().
An example of typical usage might be an async capable engine. User code would
initiate cryptographic operations. The engine would initiate those operations
asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by
ASYNC_pause_job() to return control to the user code. The user code can then
perform other tasks or wait for the job to be ready by calling "select" or other
similar function on the wait file descriptor. The engine can signal to the user
code that the job should be resumed by making the wait file descriptor
"readable". Once resumed the engine should clear the wake signal on the wait
file descriptor.
=head1 RETURN VALUES
ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or
NULL on error.
ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on
success or 0 on error.
=head1 NOTES
On Windows platforms the openssl/async.h header is dependent on some
of the types customarily made available by including windows.h. The
application developer is likely to require control over when the latter
is included, commonly as one of the first included headers. Therefore
it is defined as an application developer's responsibility to include
windows.h prior to async.h.
=head1 SEE ALSO
L<crypto(3)>, L<ASYNC_start_job(3)>
=head1 HISTORY
ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd,
ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds,
ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd were first added to
OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

330
doc/crypto/ASYNC_start_job.pod Normal file
View File

@@ -0,0 +1,330 @@
=pod
=head1 NAME
ASYNC_get_wait_ctx,
ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job,
ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable
- asynchronous job management functions
=head1 SYNOPSIS
#include <openssl/async.h>
int ASYNC_init_thread(size_t max_size, size_t init_size);
void ASYNC_cleanup_thread(void);
int ASYNC_start_job(ASYNC_JOB **job, ASYNC_WAIT_CTX *ctx, int *ret,
int (*func)(void *), void *args, size_t size);
int ASYNC_pause_job(void);
ASYNC_JOB *ASYNC_get_current_job(void);
ASYNC_WAIT_CTX *ASYNC_get_wait_ctx(ASYNC_JOB *job);
void ASYNC_block_pause(void);
void ASYNC_unblock_pause(void);
int ASYNC_is_capable(void);
=head1 DESCRIPTION
OpenSSL implements asynchronous capabilities through an ASYNC_JOB. This
represents code that can be started and executes until some event occurs. At
that point the code can be paused and control returns to user code until some
subsequent event indicates that the job can be resumed.
The creation of an ASYNC_JOB is a relatively expensive operation. Therefore, for
efficiency reasons, jobs can be created up front and reused many times. They are
held in a pool until they are needed, at which point they are removed from the
pool, used, and then returned to the pool when the job completes. If the user
application is multi-threaded, then ASYNC_init_thread() may be called for each
thread that will initiate asynchronous jobs. Before
user code exits per-thread resources need to be cleaned up. This will normally
occur automatically (see L<OPENSSL_init_crypto(3)>) but may be explicitly
initiated by using ASYNC_cleanup_thread(). No asynchronous jobs must be
outstanding for the thread when ASYNC_cleanup_thread() is called. Failing to
ensure this will result in memory leaks.
The B<max_size> argument limits the number of ASYNC_JOBs that will be held in
the pool. If B<max_size> is set to 0 then no upper limit is set. When an
ASYNC_JOB is needed but there are none available in the pool already then one
will be automatically created, as long as the total of ASYNC_JOBs managed by the
pool does not exceed B<max_size>. When the pool is first initialised
B<init_size> ASYNC_JOBs will be created immediately. If ASYNC_init_thread() is
not called before the pool is first used then it will be called automatically
with a B<max_size> of 0 (no upper limit) and an B<init_size> of 0 (no ASYNC_JOBs
created up front).
An asynchronous job is started by calling the ASYNC_start_job() function.
Initially B<*job> should be NULL. B<ctx> should point to an ASYNC_WAIT_CTX
object created through the L<ASYNC_WAIT_CTX_new(3)> function. B<ret> should
point to a location where the return value of the asynchronous function should
be stored on completion of the job. B<func> represents the function that should
be started asynchronously. The data pointed to by B<args> and of size B<size>
will be copied and then passed as an argument to B<func> when the job starts.
ASYNC_start_job will return one of the following values:
=over 4
=item B<ASYNC_ERR>
An error occurred trying to start the job. Check the OpenSSL error queue (e.g.
see L<ERR_print_errors(3)>) for more details.
=item B<ASYNC_NO_JOBS>
There are no jobs currently available in the pool. This call can be retried
again at a later time.
=item B<ASYNC_PAUSE>
The job was successfully started but was "paused" before it completed (see
ASYNC_pause_job() below). A handle to the job is placed in B<*job>. Other work
can be performed (if desired) and the job restarted at a later time. To restart
a job call ASYNC_start_job() again passing the job handle in B<*job>. The
B<func>, B<args> and B<size> parameters will be ignored when restarting a job.
When restarting a job ASYNC_start_job() B<must> be called from the same thread
that the job was originally started from.
=item B<ASYNC_FINISH>
The job completed. B<*job> will be NULL and the return value from B<func> will
be placed in B<*ret>.
=back
At any one time there can be a maximum of one job actively running per thread
(you can have many that are paused). ASYNC_get_current_job() can be used to get
a pointer to the currently executing ASYNC_JOB. If no job is currently executing
then this will return NULL.
If executing within the context of a job (i.e. having been called directly or
indirectly by the function "func" passed as an argument to ASYNC_start_job())
then ASYNC_pause_job() will immediately return control to the calling
application with ASYNC_PAUSE returned from the ASYNC_start_job() call. A
subsequent call to ASYNC_start_job passing in the relevant ASYNC_JOB in the
B<*job> parameter will resume execution from the ASYNC_pause_job() call. If
ASYNC_pause_job() is called whilst not within the context of a job then no
action is taken and ASYNC_pause_job() returns immediately.
ASYNC_get_wait_ctx() can be used to get a pointer to the ASYNC_WAIT_CTX
for the B<job>. ASYNC_WAIT_CTXs can have a "wait" file descriptor associated
with them. Applications can wait for the file descriptor to be ready for "read"
using a system function call such as select or poll (being ready for "read"
indicates that the job should be resumed). If no file descriptor is made
available then an application will have to periodically "poll" the job by
attempting to restart it to see if it is ready to continue.
An example of typical usage might be an async capable engine. User code would
initiate cryptographic operations. The engine would initiate those operations
asynchronously and then call L<ASYNC_WAIT_CTX_set_wait_fd(3)> followed by
ASYNC_pause_job() to return control to the user code. The user code can then
perform other tasks or wait for the job to be ready by calling "select" or other
similar function on the wait file descriptor. The engine can signal to the user
code that the job should be resumed by making the wait file descriptor
"readable". Once resumed the engine should clear the wake signal on the wait
file descriptor.
The ASYNC_block_pause() function will prevent the currently active job from
pausing. The block will remain in place until a subsequent call to
ASYNC_unblock_pause(). These functions can be nested, e.g. if you call
ASYNC_block_pause() twice then you must call ASYNC_unblock_pause() twice in
order to re-enable pausing. If these functions are called while there is no
currently active job then they have no effect. This functionality can be useful
to avoid deadlock scenarios. For example during the execution of an ASYNC_JOB an
application acquires a lock. It then calls some cryptographic function which
invokes ASYNC_pause_job(). This returns control back to the code that created
the ASYNC_JOB. If that code then attempts to acquire the same lock before
resuming the original job then a deadlock can occur. By calling
ASYNC_block_pause() immediately after acquiring the lock and
ASYNC_unblock_pause() immediately before releasing it then this situation cannot
occur.
Some platforms cannot support async operations. The ASYNC_is_capable() function
can be used to detect whether the current platform is async capable or not.
=head1 RETURN VALUES
ASYNC_init_thread returns 1 on success or 0 otherwise.
ASYNC_start_job returns one of ASYNC_ERR, ASYNC_NO_JOBS, ASYNC_PAUSE or
ASYNC_FINISH as described above.
ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when
not within the context of an ASYNC_JOB then this is counted as success so 1 is
returned.
ASYNC_get_current_job returns a pointer to the currently executing ASYNC_JOB or
NULL if not within the context of a job.
ASYNC_get_wait_ctx() returns a pointer to the ASYNC_WAIT_CTX for the job.
ASYNC_is_capable() returns 1 if the current platform is async capable or 0
otherwise.
=head1 NOTES
On Windows platforms the openssl/async.h header is dependent on some
of the types customarily made available by including windows.h. The
application developer is likely to require control over when the latter
is included, commonly as one of the first included headers. Therefore
it is defined as an application developer's responsibility to include
windows.h prior to async.h.
=head1 EXAMPLE
The following example demonstrates how to use most of the core async APIs:
#ifdef _WIN32
# include <windows.h>
#endif
#include <stdio.h>
#include <unistd.h>
#include <openssl/async.h>
#include <openssl/crypto.h>
int unique = 0;
void cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw)
{
OSSL_ASYNC_FD *w = (OSSL_ASYNC_FD *)vw;
close(r);
close(*w);
OPENSSL_free(w);
}
int jobfunc(void *arg)
{
ASYNC_JOB *currjob;
unsigned char *msg;
int pipefds[2] = {0, 0};
OSSL_ASYNC_FD *wptr;
char buf = 'X';
currjob = ASYNC_get_current_job();
if (currjob != NULL) {
printf("Executing within a job\n");
} else {
printf("Not executing within a job - should not happen\n");
return 0;
}
msg = (unsigned char *)arg;
printf("Passed in message is: %s\n", msg);
if (pipe(pipefds) != 0) {
printf("Failed to create pipe\n");
return 0;
}
wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD));
if (wptr == NULL) {
printf("Failed to malloc\n");
return 0;
}
*wptr = pipefds[1];
ASYNC_WAIT_CTX_set_wait_fd(ASYNC_get_wait_ctx(currjob), &unique,
pipefds[0], wptr, cleanup);
/*
* Normally some external event would cause this to happen at some
* later point - but we do it here for demo purposes, i.e.
* immediately signalling that the job is ready to be woken up after
* we return to main via ASYNC_pause_job().
*/
write(pipefds[1], &buf, 1);
/* Return control back to main */
ASYNC_pause_job();
/* Clear the wake signal */
read(pipefds[0], &buf, 1);
printf ("Resumed the job after a pause\n");
return 1;
}
int main(void)
{
ASYNC_JOB *job = NULL;
ASYNC_WAIT_CTX *ctx = NULL;
int ret;
OSSL_ASYNC_FD waitfd;
fd_set waitfdset;
size_t numfds;
unsigned char msg[13] = "Hello world!";
printf("Starting...\n");
ctx = ASYNC_WAIT_CTX_new();
if (ctx == NULL) {
printf("Failed to create ASYNC_WAIT_CTX\n");
abort();
}
for (;;) {
switch(ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) {
case ASYNC_ERR:
case ASYNC_NO_JOBS:
printf("An error occurred\n");
goto end;
case ASYNC_PAUSE:
printf("Job was paused\n");
break;
case ASYNC_FINISH:
printf("Job finished with return value %d\n", ret);
goto end;
}
/* Wait for the job to be woken */
printf("Waiting for the job to be woken up\n");
if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds)
|| numfds > 1) {
printf("Unexpected number of fds\n");
abort();
}
ASYNC_WAIT_CTX_get_all_fds(ctx, &waitfd, &numfds);
FD_ZERO(&waitfdset);
FD_SET(waitfd, &waitfdset);
select(waitfd + 1, &waitfdset, NULL, NULL, NULL);
}
end:
ASYNC_WAIT_CTX_free(ctx);
printf("Finishing\n");
return 0;
}
The expected output from executing the above example program is:
Starting...
Executing within a job
Passed in message is: Hello world!
Job was paused
Waiting for the job to be woken up
Resumed the job after a pause
Job finished with return value 1
Finishing
=head1 SEE ALSO
L<crypto(3)>, L<ERR_print_errors(3)>
=head1 HISTORY
ASYNC_init_thread, ASYNC_cleanup_thread,
ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_get_wait_ctx(),
ASYNC_block_pause(), ASYNC_unblock_pause() and ASYNC_is_capable() were first
added to OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

33
doc/crypto/blowfish.pod → doc/crypto/BF_encrypt.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
blowfish, BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt,
BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt,
BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption
=head1 SYNOPSIS
@@ -14,16 +14,16 @@ BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption
void BF_ecb_encrypt(const unsigned char *in, unsigned char *out,
BF_KEY *key, int enc);
void BF_cbc_encrypt(const unsigned char *in, unsigned char *out,
long length, BF_KEY *schedule, unsigned char *ivec, int enc);
long length, BF_KEY *schedule, unsigned char *ivec, int enc);
void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out,
long length, BF_KEY *schedule, unsigned char *ivec, int *num,
long length, BF_KEY *schedule, unsigned char *ivec, int *num,
int enc);
void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out,
long length, BF_KEY *schedule, unsigned char *ivec, int *num);
long length, BF_KEY *schedule, unsigned char *ivec, int *num);
const char *BF_options(void);
void BF_encrypt(BF_LONG *data,const BF_KEY *key);
void BF_decrypt(BF_LONG *data,const BF_KEY *key);
void BF_encrypt(BF_LONG *data, const BF_KEY *key);
void BF_decrypt(BF_LONG *data, const BF_KEY *key);
=head1 DESCRIPTION
@@ -33,7 +33,7 @@ by Counterpane (see http://www.counterpane.com/blowfish.html ).
Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data.
It uses a variable size key, but typically, 128 bit (16 byte) keys are
considered good for strong encryption. Blowfish can be used in the same
modes as DES (see L<des_modes(7)|des_modes(7)>). Blowfish is currently one
modes as DES (see L<des_modes(7)>). Blowfish is currently one
of the faster block ciphers. It is quite a bit faster than DES, and much
faster than IDEA or RC2.
@@ -52,7 +52,7 @@ everything after the first 64 bits is ignored.
The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt()
all operate on variable length data. They all take an initialization vector
B<ivec> which needs to be passed along into the next call of the same function
B<ivec> which needs to be passed along into the next call of the same function
for the same message. B<ivec> may be initialized with anything, but the
recipient needs to know what it was initialized with, or it won't be able
to decrypt. Some programs and protocols simplify this, like SSH, where
@@ -97,16 +97,21 @@ None of the functions presented here return any value.
=head1 NOTE
Applications should use the higher level functions
L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling the
blowfish functions directly.
L<EVP_EncryptInit(3)> etc. instead of calling these
functions directly.
=head1 SEE ALSO
L<des_modes(7)|des_modes(7)>
L<EVP_EncryptInit(3)>,
L<des_modes(7)>
=head1 HISTORY
=head1 COPYRIGHT
The Blowfish functions are available in all versions of SSLeay and OpenSSL.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

125
doc/crypto/BIO_ADDR.pod Normal file
View File

@@ -0,0 +1,125 @@
=pod
=head1 NAME
BIO_ADDR, BIO_ADDR_new, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake,
BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport,
BIO_ADDR_hostname_string, BIO_ADDR_service_string,
BIO_ADDR_path_string - BIO_ADDR routines
=head1 SYNOPSIS
#include <sys/types.h>
#include <openssl/bio.h>
typedef union bio_addr_st BIO_ADDR;
BIO_ADDR *BIO_ADDR_new(void);
void BIO_ADDR_free(BIO_ADDR *);
void BIO_ADDR_clear(BIO_ADDR *ap);
int BIO_ADDR_rawmake(BIO_ADDR *ap, int family,
const void *where, size_t wherelen, unsigned short port);
int BIO_ADDR_family(const BIO_ADDR *ap);
int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l);
unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap);
char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric);
char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric);
char *BIO_ADDR_path_string(const BIO_ADDR *ap);
=head1 DESCRIPTION
The B<BIO_ADDR> type is a wrapper around all types of socket
addresses that OpenSSL deals with, currently transparently
supporting AF_INET, AF_INET6 and AF_UNIX according to what's
available on the platform at hand.
BIO_ADDR_new() creates a new unfilled B<BIO_ADDR>, to be used
with routines that will fill it with information, such as
BIO_accept_ex().
BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new().
BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets
it back to an uninitialised state.
BIO_ADDR_rawmake() takes a protocol B<family>, an byte array of
size B<wherelen> with an address in network byte order pointed at
by B<where> and a port number in network byte order in B<port> (except
for the B<AF_UNIX> protocol family, where B<port> is meaningless and
therefore ignored) and populates the given B<BIO_ADDR> with them.
In case this creates a B<AF_UNIX> B<BIO_ADDR>, B<wherelen> is expected
to be the length of the path string (not including the terminating
NUL, such as the result of a call to strlen()).
I<Read on about the addresses in L</RAW ADDRESSES> below>.
BIO_ADDR_family() returns the protocol family of the given
B<BIO_ADDR>. The possible non-error results are one of the
constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the
BIO_ADDR has not been initialised.
BIO_ADDR_rawaddress() will write the raw address of the given
B<BIO_ADDR> in the area pointed at by B<p> if B<p> is non-NULL,
and will set B<*l> to be the amount of bytes the raw address
takes up if B<l> is non-NULL.
A technique to only find out the size of the address is a call
with B<p> set to B<NULL>. The raw address will be in network byte
order, most significant byte first.
In case this is a B<AF_UNIX> B<BIO_ADDR>, B<l> gets the length of the
path string (not including the terminating NUL, such as the result of
a call to strlen()).
I<Read on about the addresses in L</RAW ADDRESSES> below>.
BIO_ADDR_rawport() returns the raw port of the given B<BIO_ADDR>.
The raw port will be in network byte order.
BIO_ADDR_hostname_string() returns a character string with the
hostname of the given B<BIO_ADDR>. If B<numeric> is 1, the string
will contain the numerical form of the address. This only works for
B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The
returned string has been allocated on the heap and must be freed
with OPENSSL_free().
BIO_ADDR_service_string() returns a character string with the
service name of the port of the given B<BIO_ADDR>. If B<numeric>
is 1, the string will contain the port number. This only works
for B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The
returned string has been allocated on the heap and must be freed
with OPENSSL_free().
BIO_ADDR_path_string() returns a character string with the path
of the given B<BIO_ADDR>. This only works for B<BIO_ADDR> of the
protocol family AF_UNIX. The returned string has been allocated
on the heap and must be freed with OPENSSL_free().
=head1 RAW ADDRESSES
Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a
network byte order address of a specific site. Internally, those are
treated as a pointer to B<struct in_addr> (for B<AF_INET>), B<struct
in6_addr> (for B<AF_INET6>) or B<char *> (for B<AF_UNIX>), all
depending on the protocol family the address is for.
=head1 RETURN VALUES
The string producing functions BIO_ADDR_hostname_string(),
BIO_ADDR_service_string() and BIO_ADDR_path_string() will
return B<NULL> on error and leave an error indication on the
OpenSSL error stack.
All other functions described here return 0 or B<NULL> when the
information they should return isn't available.
=head1 SEE ALSO
L<BIO_connect(3)>, L<BIO_s_connect(3)>
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

91
doc/crypto/BIO_ADDRINFO.pod Normal file
View File

@@ -0,0 +1,91 @@
=pod
=head1 NAME
BIO_lookup_type,
BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free,
BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol,
BIO_ADDRINFO_address,
BIO_lookup
- BIO_ADDRINFO type and routines
=head1 SYNOPSIS
#include <sys/types.h>
#include <openssl/bio.h>
typedef union bio_addrinfo_st BIO_ADDRINFO;
enum BIO_lookup_type {
BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER
};
int BIO_lookup(const char *node, const char *service,
enum BIO_lookup_type lookup_type,
int family, int socktype, BIO_ADDRINFO **res);
const BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai);
int BIO_ADDRINFO_family(const BIO_ADDRINFO *bai);
int BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai);
int BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai);
const BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai);
void BIO_ADDRINFO_free(BIO_ADDRINFO *bai);
=head1 DESCRIPTION
The B<BIO_ADDRINFO> type is a wrapper for address information
types provided on your platform.
B<BIO_ADDRINFO> normally forms a chain of several that can be
picked at one by one.
BIO_lookup() looks up a specified B<host> and B<service>, and
uses B<lookup_type> to determine what the default address should
be if B<host> is B<NULL>. B<family>, B<socktype> are used to
determine what protocol family and protocol should be used for
the lookup. B<family> can be any of AF_INET, AF_INET6, AF_UNIX and
AF_UNSPEC, and B<socktype> can be SOCK_STREAM or SOCK_DGRAM.
B<res> points at a pointer to hold the start of a B<BIO_ADDRINFO>
chain.
For the family B<AF_UNIX>, BIO_lookup() will ignore the B<service>
parameter and expects the B<node> parameter to hold the path to the
socket file.
BIO_ADDRINFO_family() returns the family of the given
B<BIO_ADDRINFO>. The result will be one of the constants
AF_INET, AF_INET6 and AF_UNIX.
BIO_ADDRINFO_socktype() returns the socket type of the given
B<BIO_ADDRINFO>. The result will be one of the constants
SOCK_STREAM and SOCK_DGRAM.
BIO_ADDRINFO_protocol() returns the protocol id of the given
B<BIO_ADDRINFO>. The result will be one of the constants
IPPROTO_TCP and IPPROTO_UDP.
BIO_ADDRINFO_address() returns the underlying B<BIO_ADDR>
of the given B<BIO_ADDRINFO>.
BIO_ADDRINFO_next() returns the next B<BIO_ADDRINFO> in the chain
from the given one.
BIO_ADDRINFO_free() frees the chain of B<BIO_ADDRINFO> starting
with the given one.
=head1 RETURN VALUES
BIO_lookup() returns 1 on success and 0 when an error occurred, and
will leave an error indication on the OpenSSL error stack in that case.
All other functions described here return 0 or B<NULL> when the
information they should return isn't available.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

112
doc/crypto/BIO_connect.pod Normal file
View File

@@ -0,0 +1,112 @@
=pod
=head1 NAME
BIO_socket, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO
socket communication setup routines
=head1 SYNOPSIS
#include <openssl/bio.h>
int BIO_socket(int domain, int socktype, int protocol, int options);
int BIO_connect(int sock, const BIO_ADDR *addr, int options);
int BIO_listen(int sock, const BIO_ADDR *addr, int options);
int BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options);
int BIO_closesocket(int sock);
=head1 DESCRIPTION
BIO_socket() creates a socket in the domain B<domain>, of type
B<socktype> and B<protocol>. Socket B<options> are currently unused,
but is present for future use.
BIO_connect() connects B<sock> to the address and service given by
B<addr>. Connection B<options> may be zero or any combination of
B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK> and B<BIO_SOCK_NODELAY>.
The flags are described in L</FLAGS> below.
BIO_listen() has B<sock> start listening on the address and service
given by B<addr>. Connection B<options> may be zero or any
combination of B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK>,
B<BIO_SOCK_NODELAY>, B<BIO_SOCK_REUSEADDR> and B<BIO_SOCK_V6_ONLY>.
The flags are described in L</FLAGS> below.
BIO_accept_ex() waits for an incoming connections on the given
socket B<accept_sock>. When it gets a connection, the address and
port of the peer gets stored in B<peer> if that one is non-NULL.
Accept B<options> may be zero or B<BIO_SOCK_NONBLOCK>, and is applied
on the accepted socket. The flags are described in L</FLAGS> below.
BIO_closesocket() closes B<sock>.
=head1 FLAGS
=over 4
=item BIO_SOCK_KEEPALIVE
Enables regular sending of keep-alive messages.
=item BIO_SOCK_NONBLOCK
Sets the socket to non-blocking mode.
=item BIO_SOCK_NODELAY
Corresponds to B<TCP_NODELAY>, and disables the Nagle algorithm. With
this set, any data will be sent as soon as possible instead of being
buffered until there's enough for the socket to send out in one go.
=item BIO_SOCK_REUSEADDR
Try to reuse the address and port combination for a recently closed
port.
=item BIO_SOCK_V6_ONLY
When creating an IPv6 socket, make it only listen for IPv6 addresses
and not IPv4 addresses mapped to IPv6.
=back
These flags are bit flags, so they are to be combined with the
C<|> operator, for example:
BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK);
=head1 RETURN VALUES
BIO_socket() returns the socket number on success or B<INVALID_SOCKET>
(-1) on error. When an error has occurred, the OpenSSL error stack
will hold the error data and errno has the system error.
BIO_connect() and BIO_listen() return 1 on success or 0 on error.
When an error has occurred, the OpenSSL error stack will hold the error
data and errno has the system error.
BIO_accept_ex() returns the accepted socket on success or
B<INVALID_SOCKET> (-1) on error. When an error has occurred, the
OpenSSL error stack will hold the error data and errno has the system
error.
=head1 HISTORY
BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(),
BIO_get_accept_socket() and BIO_accept() are deprecated since OpenSSL
1.1. Use the functions described above instead.
=head1 SEE ALSO
L<BIO_ADDR(3)>
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

36
doc/crypto/BIO_ctrl.pod
View File

@@ -5,33 +5,34 @@
BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
BIO_get_info_callback, BIO_set_info_callback - BIO control operations
BIO_get_info_callback, BIO_set_info_callback, bio_info_cb
- BIO control operations
=head1 SYNOPSIS
#include <openssl/bio.h>
long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg);
long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long));
char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg);
long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg);
typedef void (*bio_info_cb)(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg);
long BIO_callback_ctrl(BIO *b, int cmd, bio_info_cb cb);
char *BIO_ptr_ctrl(BIO *bp, int cmd, long larg);
long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg);
int BIO_reset(BIO *b);
int BIO_seek(BIO *b, int ofs);
int BIO_tell(BIO *b);
int BIO_flush(BIO *b);
int BIO_eof(BIO *b);
int BIO_set_close(BIO *b,long flag);
int BIO_set_close(BIO *b, long flag);
int BIO_get_close(BIO *b);
int BIO_pending(BIO *b);
int BIO_wpending(BIO *b);
size_t BIO_ctrl_pending(BIO *b);
size_t BIO_ctrl_wpending(BIO *b);
int BIO_get_info_callback(BIO *b,bio_info_cb **cbp);
int BIO_set_info_callback(BIO *b,bio_info_cb *cb);
typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
int BIO_get_info_callback(BIO *b, bio_info_cb **cbp);
int BIO_set_info_callback(BIO *b, bio_info_cb *cb);
=head1 DESCRIPTION
@@ -94,7 +95,7 @@ return the amount of pending data.
=head1 NOTES
BIO_flush(), because it can write data may return 0 or -1 indicating
that the call should be retried later in a similar manner to BIO_write().
that the call should be retried later in a similar manner to BIO_write_ex().
The BIO_should_retry() call should be used and appropriate action taken
is the call fails.
@@ -121,8 +122,15 @@ operation.
Some of the return values are ambiguous and care should be taken. In
particular a return value of 0 can be returned if an operation is not
supported, if an error occurred, if EOF has not been reached and in
the case of BIO_seek() on a file BIO for a successful operation.
the case of BIO_seek() on a file BIO for a successful operation.
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

21
doc/crypto/BIO_f_base64.pod
View File

@@ -4,12 +4,14 @@
BIO_f_base64 - base64 BIO filter
=for comment multiple includes
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>
BIO_METHOD * BIO_f_base64(void);
const BIO_METHOD *BIO_f_base64(void);
=head1 DESCRIPTION
@@ -17,7 +19,7 @@ BIO_f_base64() returns the base64 BIO method. This is a filter
BIO that base64 encodes any data written through it and decodes
any data read through it.
Base64 BIOs do not support BIO_gets() or BIO_puts().
Base64 BIOs do not support BIO_gets() or BIO_puts().
BIO_flush() on a base64 BIO that is being written through is
used to signal that no more data is to be encoded: this is used
@@ -63,8 +65,8 @@ data to standard output:
bio = BIO_new_fp(stdin, BIO_NOCLOSE);
bio_out = BIO_new_fp(stdout, BIO_NOCLOSE);
BIO_push(b64, bio);
while((inlen = BIO_read(b64, inbuf, 512)) > 0)
BIO_write(bio_out, inbuf, inlen);
while((inlen = BIO_read(b64, inbuf, 512)) > 0)
BIO_write(bio_out, inbuf, inlen);
BIO_flush(bio_out);
BIO_free_all(b64);
@@ -77,6 +79,13 @@ data following the base64 encoded block to be misinterpreted.
There should be some way of specifying a test that the BIO can perform
to reliably determine EOF (for example a MIME boundary).
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

44
doc/crypto/BIO_f_buffer.pod
View File

@@ -2,19 +2,25 @@
=head1 NAME
BIO_f_buffer - buffering BIO
BIO_get_buffer_num_lines,
BIO_set_read_buffer_size,
BIO_set_write_buffer_size,
BIO_set_buffer_size,
BIO_set_buffer_read_data,
BIO_f_buffer
- buffering BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_f_buffer(void);
const BIO_METHOD *BIO_f_buffer(void);
#define BIO_get_buffer_num_lines(b) BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL)
#define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0)
#define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1)
#define BIO_set_buffer_size(b,size) BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL)
#define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf)
long BIO_get_buffer_num_lines(BIO *b);
long BIO_set_read_buffer_size(BIO *b, long size);
long BIO_set_write_buffer_size(BIO *b, long size);
long BIO_set_buffer_size(BIO *b, long size);
long BIO_set_buffer_read_data(BIO *b, void *buf, long num);
=head1 DESCRIPTION
@@ -41,6 +47,8 @@ is expanded.
=head1 NOTES
These functions, other than BIO_f_buffer(), are implemented as macros.
Buffering BIOs implement BIO_gets() by using BIO_read() operations on the
next BIO in the chain. By prepending a buffering BIO to a chain it is therefore
possible to provide BIO_gets() functionality if the following BIOs do not
@@ -66,9 +74,19 @@ there was an error.
=head1 SEE ALSO
L<BIO(3)|BIO(3)>,
L<BIO_reset(3)|BIO_reset(3)>,
L<BIO_flush(3)|BIO_flush(3)>,
L<BIO_pop(3)|BIO_pop(3)>,
L<BIO_ctrl(3)|BIO_ctrl(3)>,
L<BIO_int_ctrl(3)|BIO_ctrl(3)>
L<BIO(3)>,
L<BIO_reset(3)>,
L<BIO_flush(3)>,
L<BIO_pop(3)>,
L<BIO_ctrl(3)>.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

23
doc/crypto/BIO_f_cipher.pod
View File

@@ -4,14 +4,16 @@
BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter
=for comment multiple includes
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>
BIO_METHOD * BIO_f_cipher(void);
void BIO_set_cipher(BIO *b,const EVP_CIPHER *cipher,
unsigned char *key, unsigned char *iv, int enc);
const BIO_METHOD *BIO_f_cipher(void);
void BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher,
unsigned char *key, unsigned char *iv, int enc);
int BIO_get_cipher_status(BIO *b)
int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx)
@@ -22,7 +24,7 @@ BIO that encrypts any data written through it, and decrypts any data
read from it. It is a BIO wrapper for the cipher routines
EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal().
Cipher BIOs do not support BIO_gets() or BIO_puts().
Cipher BIOs do not support BIO_gets() or BIO_puts().
BIO_flush() on an encryption BIO that is being written through is
used to signal that no more data is to be encrypted: this is used
@@ -48,7 +50,7 @@ When encrypting BIO_flush() B<must> be called to flush the final block
through the BIO. If it is not then the final block will fail a subsequent
decrypt.
When decrypting an error on the final block is signalled by a zero
When decrypting an error on the final block is signaled by a zero
return value from the read operation. A successful decrypt followed
by EOF will also return zero for the final read. BIO_get_cipher_status()
should be called to determine if the decrypt was successful.
@@ -67,10 +69,13 @@ for failure.
BIO_get_cipher_ctx() currently always returns 1.
=head1 EXAMPLES
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
=head1 SEE ALSO
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
TBA
=cut

56
doc/crypto/BIO_f_md.pod
View File

@@ -4,15 +4,17 @@
BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter
=for comment multiple includes
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/evp.h>
BIO_METHOD * BIO_f_md(void);
int BIO_set_md(BIO *b,EVP_MD *md);
int BIO_get_md(BIO *b,EVP_MD **mdp);
int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp);
const BIO_METHOD *BIO_f_md(void);
int BIO_set_md(BIO *b, EVP_MD *md);
int BIO_get_md(BIO *b, EVP_MD **mdp);
int BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp);
=head1 DESCRIPTION
@@ -58,10 +60,8 @@ If an application needs to call BIO_gets() or BIO_puts() through
a chain containing digest BIOs then this can be done by prepending
a buffering BIO.
Before OpenSSL 1.0.0 the call to BIO_get_md_ctx() would only work if the BIO
had been initialized for example by calling BIO_set_md() ). In OpenSSL
1.0.0 and later the context is always returned and the BIO is state is set
to initialized. This allows applications to initialize the context externally
Calling BIO_get_md_ctx() will return the context and initialize the BIO
state. This allows applications to initialize the context externally
if the standard calls such as BIO_set_md() are not sufficiently flexible.
=head1 RETURN VALUES
@@ -105,9 +105,9 @@ The next example digests data by reading through a chain instead:
BIO_set_md(mdtmp, EVP_md5());
bio = BIO_push(mdtmp, bio);
do {
rdlen = BIO_read(bio, buf, sizeof(buf));
rdlen = BIO_read(bio, buf, sizeof(buf));
/* Might want to do something with the data here */
} while(rdlen > 0);
} while (rdlen > 0);
This next example retrieves the message digests from a BIO chain and
outputs them. This could be used with the examples above.
@@ -116,18 +116,18 @@ outputs them. This could be used with the examples above.
unsigned char mdbuf[EVP_MAX_MD_SIZE];
int mdlen;
int i;
mdtmp = bio; /* Assume bio has previously been set up */
mdtmp = bio; /* Assume bio has previously been set up */
do {
EVP_MD *md;
mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
if(!mdtmp) break;
BIO_get_md(mdtmp, &md);
EVP_MD *md;
mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
if (!mdtmp) break;
BIO_get_md(mdtmp, &md);
printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));
mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
printf("\n");
mdtmp = BIO_next(mdtmp);
} while(mdtmp);
mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
for (i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
printf("\n");
mdtmp = BIO_next(mdtmp);
} while (mdtmp);
BIO_free_all(bio);
@@ -139,6 +139,18 @@ and BIO_puts() should be passed to the next BIO in the chain and digest
the data passed through and that digests should be retrieved using a
separate BIO_ctrl() call.
=head1 SEE ALSO
=head1 HISTORY
TBA
Before OpenSSL 1.0.0., the call to BIO_get_md_ctx() would only work if the
BIO was initialized first.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/crypto/BIO_f_null.pod
View File

@@ -8,7 +8,7 @@ BIO_f_null - null filter
#include <openssl/bio.h>
BIO_METHOD * BIO_f_null(void);
const BIO_METHOD * BIO_f_null(void);
=head1 DESCRIPTION
@@ -27,6 +27,13 @@ As may be apparent a null filter BIO is not particularly useful.
BIO_f_null() returns the null filter BIO method.
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

220
doc/crypto/BIO_f_ssl.pod
View File

@@ -2,41 +2,42 @@
=head1 NAME
BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes,
BIO_do_handshake,
BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode,
BIO_set_ssl_renegotiate_bytes,
BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl,
BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id,
BIO_ssl_shutdown - SSL BIO
=for comment multiple includes
=head1 SYNOPSIS
#include <openssl/bio.h>
#include <openssl/ssl.h>
BIO_METHOD *BIO_f_ssl(void);
const BIO_METHOD *BIO_f_ssl(void);
#define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl)
#define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp)
#define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL)
#define BIO_set_ssl_renegotiate_bytes(b,num) \
BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL);
#define BIO_set_ssl_renegotiate_timeout(b,seconds) \
BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL);
#define BIO_get_num_renegotiates(b) \
BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL);
long BIO_set_ssl(BIO *b, SSL *ssl, long c);
long BIO_get_ssl(BIO *b, SSL **sslp);
long BIO_set_ssl_mode(BIO *b, long client);
long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
long BIO_get_num_renegotiates(BIO *b);
BIO *BIO_new_ssl(SSL_CTX *ctx,int client);
BIO *BIO_new_ssl(SSL_CTX *ctx, int client);
BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
int BIO_ssl_copy_session_id(BIO *to,BIO *from);
int BIO_ssl_copy_session_id(BIO *to, BIO *from);
void BIO_ssl_shutdown(BIO *bio);
#define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)
long BIO_do_handshake(BIO *b);
=head1 DESCRIPTION
BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which
is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to
SSL I/O.
SSL I/O.
I/O performed on an SSL BIO communicates using the SSL protocol with
the SSLs read and write BIOs. If an SSL connection is not established
@@ -63,7 +64,7 @@ BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client>
is 1 client mode is set. If B<client> is 0 server mode is set.
BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count
to B<num>. When set after every B<num> bytes of I/O (read and write)
to B<num>. When set after every B<num> bytes of I/O (read and write)
the SSL session is automatically renegotiated. B<num> must be at
least 512 bytes.
@@ -84,7 +85,7 @@ BIO_new_buffer_ssl_connect() creates a new BIO chain consisting
of a buffering BIO, an SSL BIO (using B<ctx>) and a connect
BIO.
BIO_ssl_copy_session_id() copies an SSL session id between
BIO_ssl_copy_session_id() copies an SSL session id between
BIO chains B<from> and B<to>. It does this by locating the
SSL BIOs in each chain and calling SSL_copy_session_id() on
the internal SSL pointer.
@@ -110,7 +111,7 @@ circumstances. Specifically this will happen if a session
renegotiation takes place during a BIO_read() operation, one
case where this happens is when step up occurs.
In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be
The SSL flag SSL_AUTO_RETRY can be
set to disable this behaviour. That is when this flag is set
an SSL BIO using a blocking transport will never request a
retry.
@@ -124,15 +125,15 @@ Applications do not have to call BIO_do_handshake() but may wish
to do so to separate the handshake process from other I/O
processing.
=head1 RETURN VALUES
TBA
BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.
=head1 EXAMPLE
This SSL/TLS client example, attempts to retrieve a page from an
SSL/TLS web server. The I/O routines are identical to those of the
unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>.
unencrypted example in L<BIO_s_connect(3)>.
BIO *sbio, *out;
int len;
@@ -140,57 +141,48 @@ unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>.
SSL_CTX *ctx;
SSL *ssl;
ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();
/* XXX Seed the PRNG if needed. */
/* We would seed the PRNG here if the platform didn't
* do it automatically
*/
ctx = SSL_CTX_new(TLS_client_method());
ctx = SSL_CTX_new(SSLv23_client_method());
/* We'd normally set some stuff like the verify paths and
* mode here because as things stand this will connect to
* any server whose certificate is signed by any CA.
*/
/* XXX Set verify paths and mode here. */
sbio = BIO_new_ssl_connect(ctx);
BIO_get_ssl(sbio, &ssl);
if(!ssl) {
fprintf(stderr, "Can't locate SSL pointer\n");
/* whatever ... */
if (ssl == NULL) {
fprintf(stderr, "Can't locate SSL pointer\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
/* We might want to do other things with ssl here */
/* XXX We might want to do other things with ssl here */
BIO_set_conn_hostname(sbio, "localhost:https");
/* An empty host part means the loopback address */
BIO_set_conn_hostname(sbio, ":https");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if(BIO_do_connect(sbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
if (BIO_do_connect(sbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
exit(1);
}
if (BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error establishing SSL connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
if(BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error establishing SSL connection\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
}
/* Could examine ssl here to get connection info */
/* XXX Could examine ssl here to get connection info */
BIO_puts(sbio, "GET / HTTP/1.0\n\n");
for(;;) {
len = BIO_read(sbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(out, tmpbuf, len);
for ( ; ; ) {
len = BIO_read(sbio, tmpbuf, 1024);
if (len <= 0)
break;
BIO_write(out, tmpbuf, len);
}
BIO_free_all(sbio);
BIO_free(out);
@@ -206,106 +198,83 @@ a client and also echoes the request to standard output.
SSL_CTX *ctx;
SSL *ssl;
ERR_load_crypto_strings();
ERR_load_SSL_strings();
OpenSSL_add_all_algorithms();
/* XXX Seed the PRNG if needed. */
/* Might seed PRNG here */
ctx = SSL_CTX_new(SSLv23_server_method());
if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM)
|| !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM)
|| !SSL_CTX_check_private_key(ctx)) {
fprintf(stderr, "Error setting up SSL_CTX\n");
ERR_print_errors_fp(stderr);
return 0;
ctx = SSL_CTX_new(TLS_server_method());
if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM)
|| !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM)
|| !SSL_CTX_check_private_key(ctx)) {
fprintf(stderr, "Error setting up SSL_CTX\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Might do other things here like setting verify locations and
* DH and/or RSA temporary key callbacks
*/
/* XXX Other things like set verify locations, EDH temp callbacks. */
/* New SSL BIO setup as server */
sbio=BIO_new_ssl(ctx,0);
sbio = BIO_new_ssl(ctx, 0);
BIO_get_ssl(sbio, &ssl);
if(!ssl) {
fprintf(stderr, "Can't locate SSL pointer\n");
/* whatever ... */
if (ssl == NULL) {
fprintf(stderr, "Can't locate SSL pointer\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Don't want any retries */
SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY);
/* Create the buffering BIO */
bbio = BIO_new(BIO_f_buffer());
/* Add to chain */
sbio = BIO_push(bbio, sbio);
acpt = BIO_new_accept("4433");
acpt=BIO_new_accept("4433");
/* By doing this when a new connection is established
/*
* By doing this when a new connection is established
* we automatically have sbio inserted into it. The
* BIO chain is now 'swallowed' by the accept BIO and
* will be freed when the accept BIO is freed.
* will be freed when the accept BIO is freed.
*/
BIO_set_accept_bios(acpt,sbio);
BIO_set_accept_bios(acpt, sbio);
out = BIO_new_fp(stdout, BIO_NOCLOSE);
/* Setup accept BIO */
if(BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error setting up accept BIO\n");
ERR_print_errors_fp(stderr);
return 0;
if (BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error setting up accept BIO\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Now wait for incoming connection */
if(BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error in connection\n");
ERR_print_errors_fp(stderr);
return 0;
if (BIO_do_accept(acpt) <= 0) {
fprintf(stderr, "Error in connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* We only want one connection so remove and free
* accept BIO
*/
/* We only want one connection so remove and free accept BIO */
sbio = BIO_pop(acpt);
BIO_free_all(acpt);
if(BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error in SSL handshake\n");
ERR_print_errors_fp(stderr);
return 0;
if (BIO_do_handshake(sbio) <= 0) {
fprintf(stderr, "Error in SSL handshake\n");
ERR_print_errors_fp(stderr);
exit(1);
}
BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n");
BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n");
BIO_puts(sbio, "--------------------------------------------------\r\n");
for(;;) {
len = BIO_gets(sbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(sbio, tmpbuf, len);
BIO_write(out, tmpbuf, len);
/* Look for blank line signifying end of headers*/
if((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n')) break;
for ( ; ; ) {
len = BIO_gets(sbio, tmpbuf, 1024);
if (len <= 0)
break;
BIO_write(sbio, tmpbuf, len);
BIO_write(out, tmpbuf, len);
/* Look for blank line signifying end of headers*/
if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n')
break;
}
BIO_puts(sbio, "--------------------------------------------------\r\n");
BIO_puts(sbio, "\r\n");
/* Since there is a buffering BIO present we had better flush it */
BIO_flush(sbio);
BIO_free_all(sbio);
=head1 BUGS
@@ -317,6 +286,13 @@ explicitly being popped (e.g. a pop higher up the chain). Applications which
included workarounds for this bug (e.g. freeing BIOs more than once) should
be modified to handle this fix or they may free up an already freed BIO.
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

77
doc/crypto/BIO_find_type.pod
View File

@@ -8,46 +8,23 @@ BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal
#include <openssl/bio.h>
BIO * BIO_find_type(BIO *b,int bio_type);
BIO * BIO_next(BIO *b);
#define BIO_method_type(b) ((b)->method->type)
#define BIO_TYPE_NONE 0
#define BIO_TYPE_MEM (1|0x0400)
#define BIO_TYPE_FILE (2|0x0400)
#define BIO_TYPE_FD (4|0x0400|0x0100)
#define BIO_TYPE_SOCKET (5|0x0400|0x0100)
#define BIO_TYPE_NULL (6|0x0400)
#define BIO_TYPE_SSL (7|0x0200)
#define BIO_TYPE_MD (8|0x0200)
#define BIO_TYPE_BUFFER (9|0x0200)
#define BIO_TYPE_CIPHER (10|0x0200)
#define BIO_TYPE_BASE64 (11|0x0200)
#define BIO_TYPE_CONNECT (12|0x0400|0x0100)
#define BIO_TYPE_ACCEPT (13|0x0400|0x0100)
#define BIO_TYPE_PROXY_CLIENT (14|0x0200)
#define BIO_TYPE_PROXY_SERVER (15|0x0200)
#define BIO_TYPE_NBIO_TEST (16|0x0200)
#define BIO_TYPE_NULL_FILTER (17|0x0200)
#define BIO_TYPE_BER (18|0x0200)
#define BIO_TYPE_BIO (19|0x0400)
#define BIO_TYPE_DESCRIPTOR 0x0100
#define BIO_TYPE_FILTER 0x0200
#define BIO_TYPE_SOURCE_SINK 0x0400
BIO *BIO_find_type(BIO *b, int bio_type);
BIO *BIO_next(BIO *b);
int BIO_method_type(const BIO *b);
=head1 DESCRIPTION
The BIO_find_type() searches for a BIO of a given type in a chain, starting
at BIO B<b>. If B<type> is a specific type (such as BIO_TYPE_MEM) then a search
at BIO B<b>. If B<type> is a specific type (such as B<BIO_TYPE_MEM>) then a search
is made for a BIO of that type. If B<type> is a general type (such as
B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is
searched for. BIO_find_type() returns the next matching BIO or NULL if none is
found.
Note: not all the B<BIO_TYPE_*> types above have corresponding BIO implementations.
The following general types are defined:
B<BIO_TYPE_DESCRIPTOR>, B<BIO_TYPE_FILTER>, and B<BIO_TYPE_SOURCE_SINK>.
For a list of the specific types, see the B<openssl/bio.h> header file.
BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs
in a chain or used in conjunction with BIO_find_type() to find all BIOs of a
@@ -63,36 +40,30 @@ BIO_next() returns the next BIO in a chain.
BIO_method_type() returns the type of the BIO B<b>.
=head1 NOTES
BIO_next() was added to OpenSSL 0.9.6 to provide a 'clean' way to traverse a BIO
chain or find multiple matches using BIO_find_type(). Previous versions had to
use:
next = bio->next_bio;
=head1 BUGS
BIO_find_type() in OpenSSL 0.9.5a and earlier could not be safely passed a
NULL pointer for the B<b> argument.
=head1 EXAMPLE
Traverse a chain looking for digest BIOs:
BIO *btmp;
btmp = in_bio; /* in_bio is chain to search through */
btmp = in_bio; /* in_bio is chain to search through */
do {
btmp = BIO_find_type(btmp, BIO_TYPE_MD);
if(btmp == NULL) break; /* Not found */
/* btmp is a digest BIO, do something with it ...*/
...
btmp = BIO_find_type(btmp, BIO_TYPE_MD);
if (btmp == NULL) break; /* Not found */
/* btmp is a digest BIO, do something with it ...*/
...
btmp = BIO_next(btmp);
} while(btmp);
btmp = BIO_next(btmp);
} while (btmp);
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

65
doc/crypto/BIO_get_data.pod Normal file
View File

@@ -0,0 +1,65 @@
=pod
=head1 NAME
BIO_set_data, BIO_get_data, BIO_set_init, BIO_get_init, BIO_set_shutdown,
BIO_get_shutdown - functions for managing BIO state information
=head1 SYNOPSIS
#include <openssl/bio.h>
void BIO_set_data(BIO *a, void *ptr);
void *BIO_get_data(BIO *a);
void BIO_set_init(BIO *a, int init);
int BIO_get_init(BIO *a);
void BIO_set_shutdown(BIO *a, int shut);
int BIO_get_shutdown(BIO *a);
=head1 DESCRIPTION
These functions are mainly useful when implementing a custom BIO.
The BIO_set_data() function associates the custom data pointed to by B<ptr> with
the BIO. This data can subsequently be retrieved via a call to BIO_get_data().
This can be used by custom BIOs for storing implementation specific information.
The BIO_set_init() function sets the value of the BIO's "init" flag to indicate
whether initialisation has been completed for this BIO or not. A non-zero value
indicates that initialisation is complete, whilst zero indicates that it is not.
Often initialisation will complete during initial construction of the BIO. For
some BIOs however, initialisation may not complete until after additional steps
have occurred (for example through calling custom ctrls). The BIO_get_init()
function returns the value of the "init" flag.
The BIO_set_shutdown() and BIO_get_shutdown() functions set and get the state of
this BIO's shutdown (i.e. BIO_CLOSE) flag. If set then the underlying resource
is also closed when the BIO is freed.
=head1 RETURN VALUES
BIO_get_data() returns a pointer to the implementation specific custom data
associated with this BIO, or NULL if none has been set.
BIO_get_init() returns the state of the BIO's init flag.
BIO_get_shutdown() returns the stat of the BIO's shutdown (i.e. BIO_CLOSE) flag.
=head1 SEE ALSO
L<bio>, L<BIO_meth_new>
=head1 HISTORY
The functions described here were added in OpenSSL version 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

64
doc/crypto/BIO_get_ex_new_index.pod Normal file
View File

@@ -0,0 +1,64 @@
=pod
=head1 NAME
BIO_get_ex_new_index, BIO_set_ex_data, BIO_get_ex_data,
ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data,
UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data,
X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data,
X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data,
X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data,
DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data,
DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data,
ECDH_get_ex_new_index, ECDH_set_ex_data, ECDH_get_ex_data,
ECDSA_get_ex_new_index, ECDSA_set_ex_data, ECDSA_get_ex_data,
RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data
- application-specific data
=for comment generic
=head1 SYNOPSIS
#include <openssl/x509.h>
int TYPE_get_ex_new_index(long argl, void *argp,
CRYPTO_EX_new *new_func,
CRYPTO_EX_dup *dup_func,
CRYPTO_EX_free *free_func);
int TYPE_set_ex_data(TYPE *d, int idx, void *arg);
void *TYPE_get_ex_data(TYPE *d, int idx);
=head1 DESCRIPTION
In the description here, I<TYPE> is used a placeholder
for any of the OpenSSL datatypes listed in
L<CRYPTO_get_ex_new_index(3)>.
These functions handle application-specific data for OpenSSL data
structures.
TYPE_get_new_ex_index() is a macro that calls CRYPTO_get_ex_new_index()
with the correct B<index> value.
TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with
an offset into the opaque exdata part of the TYPE object.
TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with an
an offset into the opaque exdata part of the TYPE object.
=head1 SEE ALSO
L<CRYPTO_get_ex_new_index(3)>.
=head1 COPYRIGHT
Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

131
doc/crypto/BIO_meth_new.pod Normal file
View File

@@ -0,0 +1,131 @@
=pod
=head1 NAME
BIO_get_new_index,
BIO_meth_new, BIO_meth_free, BIO_meth_get_write, BIO_meth_set_write,
BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts,
BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl,
BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy,
BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,
BIO_meth_set_callback_ctrl - Routines to build up BIO methods
=head1 SYNOPSIS
#include <openssl/bio.h>
int BIO_get_new_index(void);
BIO_METHOD *BIO_meth_new(int type, const char *name);
void BIO_meth_free(BIO_METHOD *biom);
int (*BIO_meth_get_write(BIO_METHOD *biom)) (BIO *, const char *, int);
int BIO_meth_set_write(BIO_METHOD *biom,
int (*write) (BIO *, const char *, int));
int (*BIO_meth_get_read(BIO_METHOD *biom)) (BIO *, char *, int);
int BIO_meth_set_read(BIO_METHOD *biom,
int (*read) (BIO *, char *, int));
int (*BIO_meth_get_puts(BIO_METHOD *biom)) (BIO *, const char *);
int BIO_meth_set_puts(BIO_METHOD *biom,
int (*puts) (BIO *, const char *));
int (*BIO_meth_get_gets(BIO_METHOD *biom)) (BIO *, char *, int);
int BIO_meth_set_gets(BIO_METHOD *biom,
int (*gets) (BIO *, char *, int));
long (*BIO_meth_get_ctrl(BIO_METHOD *biom)) (BIO *, int, long, void *);
int BIO_meth_set_ctrl(BIO_METHOD *biom,
long (*ctrl) (BIO *, int, long, void *));
int (*BIO_meth_get_create(BIO_METHOD *bion)) (BIO *);
int BIO_meth_set_create(BIO_METHOD *biom, int (*create) (BIO *));
int (*BIO_meth_get_destroy(BIO_METHOD *biom)) (BIO *);
int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy) (BIO *));
long (*BIO_meth_get_callback_ctrl(BIO_METHOD *biom))
(BIO *, int, bio_info_cb *);
int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,
long (*callback_ctrl) (BIO *, int,
bio_info_cb *));
=head1 DESCRIPTION
The B<BIO_METHOD> type is a structure used for the implementation of new BIO
types. It provides a set of of functions used by OpenSSL for the implementation
of the various BIO capabilities. See the L<bio> page for more information.
BIO_meth_new() creates a new B<BIO_METHOD> structure. It should be given a
unique integer B<type> and a string that represents its B<name>.
Use BIO_get_new_index() to get the value for B<type>.
The set of
standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples
include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a
type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs
should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor
based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the
"descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type> page for
more information.
BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
associated with it.
BIO_meth_get_write() and BIO_meth_set_write() get and set the function used for
writing arbitrary length data to the BIO respectively. This function will be
called in response to the application calling BIO_write(). The parameters for
the function have the same meaning as for BIO_write().
BIO_meth_get_read() and BIO_meth_set_read() get and set the function used for
reading arbitrary length data from the BIO respectively. This function will be
called in response to the application calling BIO_read(). The parameters for the
function have the same meaning as for BIO_read().
BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for
writing a NULL terminated string to the BIO respectively. This function will be
called in response to the application calling BIO_puts(). The parameters for
the function have the same meaning as for BIO_puts().
BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically
used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)>
page for more information). This function will be called in response to the
application calling BIO_gets(). The parameters for the function have the same
meaning as for BIO_gets().
BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for
processing ctrl messages in the BIO respectively. See the L<BIO_ctrl> page for
more information. This function will be called in response to the application
calling BIO_ctrl(). The parameters for the function have the same meaning as for
BIO_ctrl().
BIO_meth_get_create() and BIO_meth_set_create() get and set the function used
for creating a new instance of the BIO respectively. This function will be
called in response to the application calling BIO_new() and passing
in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the
memory for the new BIO, and a pointer to this newly allocated structure will
be passed as a parameter to the function.
BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used
for destroying an instance of a BIO respectively. This function will be
called in response to the application calling BIO_free(). A pointer to the BIO
to be destroyed is passed as a parameter. The destroy function should be used
for BIO specific clean up. The memory for the BIO itself should not be freed by
this function.
BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the
function used for processing callback ctrl messages in the BIO respectively. See
the L<BIO_callback_ctrl(3)> page for more information. This function will be called
in response to the application calling BIO_callback_ctrl(). The parameters for
the function have the same meaning as for BIO_callback_ctrl().
=head1 SEE ALSO
L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read>, L<BIO_new>
=head1 HISTORY
The functions described here were added in OpenSSL version 1.1.0.
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

47
doc/crypto/BIO_new.pod
View File

@@ -2,57 +2,57 @@
=head1 NAME
BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions
BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all,
BIO_set - BIO allocation and freeing functions
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO * BIO_new(BIO_METHOD *type);
int BIO_set(BIO *a,BIO_METHOD *type);
int BIO_free(BIO *a);
void BIO_vfree(BIO *a);
void BIO_free_all(BIO *a);
BIO * BIO_new(const BIO_METHOD *type);
int BIO_set(BIO *a, const BIO_METHOD *type);
int BIO_up_ref(BIO *a);
int BIO_free(BIO *a);
void BIO_vfree(BIO *a);
void BIO_free_all(BIO *a);
=head1 DESCRIPTION
The BIO_new() function returns a new BIO using method B<type>.
BIO_set() sets the method of an already existing BIO.
BIO_up_ref() increments the reference count associated with the BIO object.
BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO
but it does not return a value. Calling BIO_free() may also have some effect
but it does not return a value.
If B<a> is NULL nothing is done.
Calling BIO_free() may also have some effect
on the underlying I/O structure, for example it may close the file being
referred to under certain circumstances. For more details see the individual
BIO_METHOD descriptions.
BIO_free_all() frees up an entire BIO chain, it does not halt if an error
occurs freeing up an individual BIO in the chain.
If B<a> is NULL nothing is done.
=head1 RETURN VALUES
BIO_new() returns a newly created BIO or NULL if the call fails.
BIO_set(), BIO_free() return 1 for success and 0 for failure.
BIO_set(), BIO_up_ref() and BIO_free() return 1 for success and 0 for failure.
BIO_free_all() and BIO_vfree() do not return values.
=head1 NOTES
Some BIOs (such as memory BIOs) can be used immediately after calling
BIO_new(). Others (such as file BIOs) need some additional initialization,
and frequently a utility function exists to create and initialize such BIOs.
If BIO_free() is called on a BIO chain it will only free one BIO resulting
in a memory leak.
Calling BIO_free_all() a single BIO has the same effect as calling BIO_free()
Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free()
on it other than the discarded return value.
Normally the B<type> argument is supplied by a function which returns a
pointer to a BIO_METHOD. There is a naming convention for such functions:
a source/sink BIO is normally called BIO_s_*() and a filter BIO
BIO_f_*();
=head1 HISTORY
BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.
=head1 EXAMPLE
@@ -60,6 +60,13 @@ Create a memory BIO:
BIO *mem = BIO_new(BIO_s_mem());
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

15
doc/crypto/BIO_new_CMS.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BIO_new_CMS - CMS streaming filter BIO
BIO_new_CMS - CMS streaming filter BIO
=head1 SYNOPSIS
@@ -56,11 +56,20 @@ occurred. The error can be obtained from ERR_get_error(3).
=head1 SEE ALSO
L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>,
L<CMS_encrypt(3)|CMS_encrypt(3)>
L<ERR_get_error(3)>, L<CMS_sign(3)>,
L<CMS_encrypt(3)>
=head1 HISTORY
BIO_new_CMS() was added to OpenSSL 1.0.0
=head1 COPYRIGHT
Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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

@@ -0,0 +1,74 @@
=pod
=head1 NAME
BIO_hostserv_priorities,
BIO_parse_hostserv
- utility routines to parse a standard host and service string
=head1 SYNOPSIS
#include <openssl/bio.h>
enum BIO_hostserv_priorities {
BIO_PARSE_PRIO_HOST, BIO_PARSE_PRIO_SERV
};
int BIO_parse_hostserv(const char *hostserv, char **host, char **service,
enum BIO_hostserv_priorities hostserv_prio);
=head1 DESCRIPTION
BIO_parse_hostserv() will parse the information given in B<hostserv>,
create strings with the host name and service name and give those
back via B<host> and B<service>. Those will need to be freed after
they are used. B<hostserv_prio> helps determine if B<hostserv> shall
be interpreted primarily as a host name or a service name in ambiguous
cases.
The syntax the BIO_parse_hostserv() recognises is:
host + ':' + service
host + ':' + '*'
host + ':'
':' + service
'*' + ':' + service
host
service
The host part can be a name or an IP address. If it's a IPv6
address, it MUST be enclosed in brackets, such as '[::1]'.
The service part can be a service name or its port number.
The returned values will depend on the given B<hostserv> string
and B<hostserv_prio>, as follows:
host + ':' + service => *host = "host", *service = "service"
host + ':' + '*' => *host = "host", *service = NULL
host + ':' => *host = "host", *service = NULL
':' + service => *host = NULL, *service = "service"
'*' + ':' + service => *host = NULL, *service = "service"
in case no ':' is present in the string, the result depends on
hostserv_prio, as follows:
when hostserv_prio == BIO_PARSE_PRIO_HOST
host => *host = "host", *service untouched
when hostserv_prio == BIO_PARSE_PRIO_SERV
service => *host untouched, *service = "service"
=head1 SEE ALSO
L<BIO_ADDRINFO(3)>
=head1 COPYRIGHT
Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

50
doc/crypto/BIO_printf.pod Normal file
View File

@@ -0,0 +1,50 @@
=pod
=head1 NAME
BIO_printf, BIO_vprintf, BIO_snprintf, BIO_vsnprintf
- formatted output to a BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
int BIO_printf(BIO *bio, const char *format, ...)
int BIO_vprintf(BIO *bio, const char *format, va_list args)
int BIO_snprintf(char *buf, size_t n, const char *format, ...)
int BIO_vsnprintf(char *buf, size_t n, const char *format, va_list args)
=head1 DESCRIPTION
BIO_printf() is similar to the standard C printf() function, except that
the output is sent to the specified BIO, B<bio>, rather than standard
output. All common format specifiers are supported.
BIO_vprintf() is similar to the vprintf() function found on many platforms,
the output is sent to the specified BIO, B<bio>, rather than standard
output. All common format specifiers are supported. The argument
list B<args> is a stdarg argument list.
BIO_snprintf() is for platforms that do not have the common snprintf()
function. It is like sprintf() except that the size parameter, B<n>,
specifies the size of the output buffer.
BIO_vsnprintf() is to BIO_snprintf() as BIO_vprintf() is to BIO_printf().
=head1 RETURN VALUES
All functions return the number of bytes written, or -1 on error.
For BIO_snprintf() and BIO_vsnprintf() this includes when the output
buffer is too small.
=head1 COPYRIGHT
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

28
doc/crypto/BIO_push.pod
View File

@@ -2,14 +2,15 @@
=head1 NAME
BIO_push, BIO_pop - add and remove BIOs from a chain.
BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO * BIO_push(BIO *b,BIO *append);
BIO * BIO_pop(BIO *b);
BIO *BIO_push(BIO *b, BIO *append);
BIO *BIO_pop(BIO *b);
void BIO_set_next(BIO *b, BIO *next);
=head1 DESCRIPTION
@@ -21,6 +22,10 @@ in the chain, or NULL if there is no next BIO. The removed BIO then
becomes a single BIO with no association with the original chain,
it can thus be freed or attached to a different chain.
BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to
by B<next>. The new chain may include some of the same BIOs from the old chain
or it may be completely different.
=head1 NOTES
The names of these functions are perhaps a little misleading. BIO_push()
@@ -66,4 +71,19 @@ BIO.
=head1 SEE ALSO
TBA
L<bio>
=head1 HISTORY
The BIO_set_next() function was added in OpenSSL version 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

35
doc/crypto/BIO_read.pod
View File

@@ -8,10 +8,10 @@ BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
#include <openssl/bio.h>
int BIO_read(BIO *b, void *buf, int len);
int BIO_gets(BIO *b, char *buf, int size);
int BIO_write(BIO *b, const void *buf, int len);
int BIO_puts(BIO *b, const char *buf);
int BIO_read(BIO *b, void *buf, int len);
int BIO_gets(BIO *b, char *buf, int size);
int BIO_write(BIO *b, const void *buf, int len);
int BIO_puts(BIO *b, const char *buf);
=head1 DESCRIPTION
@@ -20,20 +20,22 @@ the data in B<buf>.
BIO_gets() performs the BIOs "gets" operation and places the data
in B<buf>. Usually this operation will attempt to read a line of data
from the BIO of maximum length B<len>. There are exceptions to this
however, for example BIO_gets() on a digest BIO will calculate and
from the BIO of maximum length B<len-1>. There are exceptions to this,
however; for example, BIO_gets() on a digest BIO will calculate and
return the digest and other BIOs may not support BIO_gets() at all.
The returned string is always NUL-terminated.
BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>.
BIO_puts() attempts to write a null terminated string B<buf> to BIO B<b>.
BIO_puts() attempts to write a NUL-terminated string B<buf> to BIO B<b>.
=head1 RETURN VALUES
All these functions return either the amount of data successfully read or
written (if the return value is positive) or that no data was successfully
read or written if the result is 0 or -1. If the return value is -2 then
the operation is not implemented in the specific BIO type.
the operation is not implemented in the specific BIO type. The trailing
NUL is not included in the length returned by BIO_gets().
=head1 NOTES
@@ -52,15 +54,24 @@ I/O structure and may block as a result. Instead select() (or equivalent)
should be combined with non blocking I/O so successive reads will request
a retry instead of blocking.
See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to
See L<BIO_should_retry(3)> for details of how to
determine the cause of a retry and other I/O issues.
If the BIO_gets() function is not supported by a BIO then it possible to
work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)>
work around this by adding a buffering BIO L<BIO_f_buffer(3)>
to the chain.
=head1 SEE ALSO
L<BIO_should_retry(3)|BIO_should_retry(3)>
L<BIO_should_retry(3)>
TBA
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

117
doc/crypto/BIO_s_accept.pod
View File

@@ -2,17 +2,20 @@
=head1 NAME
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
BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name,
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
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD *BIO_s_accept(void);
const BIO_METHOD *BIO_s_accept(void);
long BIO_set_accept_port(BIO *b, char *name);
long BIO_set_accept_name(BIO *b, char *name);
char *BIO_get_accept_name(BIO *b);
long BIO_set_accept_port(BIO *b, char *port);
char *BIO_get_accept_port(BIO *b);
BIO *BIO_new_accept(char *host_port);
@@ -21,11 +24,7 @@ BIO_get_bind_mode, BIO_do_accept - accept BIO
long BIO_set_accept_bios(BIO *b, char *bio);
long BIO_set_bind_mode(BIO *b, long mode);
long BIO_get_bind_mode(BIO *b, long dummy);
#define BIO_BIND_NORMAL 0
#define BIO_BIND_REUSEADDR_IF_UNUSED 1
#define BIO_BIND_REUSEADDR 2
long BIO_get_bind_mode(BIO *b);
int BIO_do_accept(BIO *b);
@@ -49,23 +48,30 @@ If the close flag is set on an accept BIO then any active
connection on that chain is shutdown and the socket closed when
the BIO is freed.
Calling BIO_reset() on a accept BIO will close any active
Calling BIO_reset() on an accept BIO will close any active
connection and reset the BIO into a state where it awaits another
incoming connection.
BIO_get_fd() and BIO_set_fd() can be called to retrieve or set
the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)>
the accept socket. See L<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",
BIO_set_accept_name() uses the string B<name> to set the accept
name. The name is represented as a string of the form "host:port",
where "host" is the interface to use and "port" is the port.
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.
The host can be "*" or empty which is interpreted as meaning
any interface. If the host is an IPv6 address, it has to be
enclosed in brackets, for example "[::1]:https". "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.
BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into
BIO_set_accept_port() uses the string B<port> to set the accept
port. "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.
BIO_new_accept() combines BIO_new() and BIO_set_accept_name() into
a single call: that is it creates a new accept BIO with port
B<host_port>.
@@ -74,19 +80,19 @@ BIO_set_nbio_accept() sets the accept socket to blocking mode
BIO_set_accept_bios() can be used to set a chain of BIOs which
will be duplicated and prepended to the chain when an incoming
connection is received. This is useful if, for example, a
connection is received. This is useful if, for example, a
buffering or SSL BIO is required for each connection. The
chain of BIOs must not be freed after this call, they will
be automatically freed when the accept BIO is freed.
BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve
the current bind mode. If BIO_BIND_NORMAL (the default) is set
the current bind mode. If B<BIO_BIND_NORMAL> (the default) is set
then another socket cannot be bound to the same port. If
BIO_BIND_REUSEADDR is set then other sockets can bind to the
same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and
B<BIO_BIND_REUSEADDR> is set then other sockets can bind to the
same port. If B<BIO_BIND_REUSEADDR_IF_UNUSED> is set then and
attempt is first made to use BIO_BIN_NORMAL, if this fails
and the port is not in use then a second attempt is made
using BIO_BIND_REUSEADDR.
using B<BIO_BIND_REUSEADDR>.
BIO_do_accept() serves two functions. When it is first
called, after the accept BIO has been setup, it will attempt
@@ -137,13 +143,24 @@ then it is an indication that an accept attempt would block: the application
should take appropriate action to wait until the underlying socket has
accepted a connection and retry the call.
BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(),
BIO_set_accept_bios(), BIO_set_bind_mode(), BIO_get_bind_mode() and
BIO_do_accept() are macros.
BIO_set_accept_name(), BIO_get_accept_name(), BIO_set_accept_port(),
BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(),
BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros.
=head1 RETURN VALUES
TBA
BIO_do_accept(),
BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(),
BIO_set_accept_bios(), and BIO_set_bind_mode(), return 1 for success and 0 or
-1 for failure.
BIO_get_accept_name() returns the accept name or NULL on error.
BIO_get_accept_port() returns the port as a string or NULL on error.
BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or -1 on failure.
BIO_new_accept() returns a BIO or NULL on error.
=head1 EXAMPLE
@@ -151,34 +168,36 @@ This example accepts two connections on port 4444, sends messages
down each and finally closes both down.
BIO *abio, *cbio, *cbio2;
ERR_load_crypto_strings();
abio = BIO_new_accept("4444");
/* First call to BIO_accept() sets up accept BIO */
if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error setting up accept\n");
ERR_print_errors_fp(stderr);
exit(0);
abio = BIO_new_accept("4444");
if (BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error setting up accept\n");
ERR_print_errors_fp(stderr);
exit(1);
}
/* Wait for incoming connection */
if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(0);
if (BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
fprintf(stderr, "Connection 1 established\n");
/* Retrieve BIO for connection */
cbio = BIO_pop(abio);
BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n");
fprintf(stderr, "Sent out data on connection 1\n");
/* Wait for another connection */
if(BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(0);
if (BIO_do_accept(abio) <= 0) {
fprintf(stderr, "Error accepting connection\n");
ERR_print_errors_fp(stderr);
exit(1);
}
fprintf(stderr, "Connection 2 established\n");
/* Close accept BIO to refuse further connections */
cbio2 = BIO_pop(abio);
BIO_free(abio);
@@ -186,10 +205,18 @@ down each and finally closes both down.
fprintf(stderr, "Sent out data on connection 2\n");
BIO_puts(cbio, "Connection 1: Second connection established\n");
/* Close the two established connections */
BIO_free(cbio);
BIO_free(cbio2);
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

58
doc/crypto/BIO_s_bio.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair,
BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request,
BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
@@ -11,24 +11,22 @@ BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
#include <openssl/bio.h>
BIO_METHOD *BIO_s_bio(void);
const BIO_METHOD *BIO_s_bio(void);
#define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2)
#define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL)
int BIO_make_bio_pair(BIO *b1, BIO *b2);
int BIO_destroy_bio_pair(BIO *b);
int BIO_shutdown_wr(BIO *b);
#define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL)
#define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL)
#define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL)
int BIO_set_write_buf_size(BIO *b, long size);
size_t BIO_get_write_buf_size(BIO *b, long size);
int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
#define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL)
int BIO_get_write_guarantee(BIO *b);
size_t BIO_ctrl_get_write_guarantee(BIO *b);
#define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL)
int BIO_get_read_request(BIO *b);
size_t BIO_ctrl_get_read_request(BIO *b);
int BIO_ctrl_reset_read_request(BIO *b);
=head1 DESCRIPTION
@@ -65,7 +63,7 @@ up any half of the pair will automatically destroy the association.
BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further
writes on BIO B<b> are allowed (they will return an error). Reads on the other
half of the pair will return any pending data or EOF when all pending data has
been read.
been read.
BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>.
If the size is not initialized a default value is used. This is currently
@@ -123,6 +121,11 @@ never sent!
BIO_eof() is true if no data is in the peer BIO and the peer BIO has been
shutdown.
BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(),
BIO_set_write_buf_size(), BIO_get_write_buf_size(),
BIO_get_write_guarantee(), and BIO_get_read_request() are implemented
as macros.
=head1 RETURN VALUES
BIO_new_bio_pair() returns 1 on success, with the new BIOs available in
@@ -139,9 +142,9 @@ without having to go through the SSL-interface.
BIO *internal_bio, *network_bio;
...
BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);
SSL_set_bio(ssl, internal_bio, internal_bio);
SSL_operations();
SSL_operations(); //e.g SSL_read and SSL_write
...
application | TLS-engine
@@ -150,12 +153,16 @@ without having to go through the SSL-interface.
| /\ ||
| || \/
| BIO-pair (internal_bio)
+----------< BIO-pair (network_bio)
| BIO-pair (network_bio)
| || /\
| \/ ||
+-----------< BIO_operations()
| |
socket |
| |
socket
...
SSL_free(ssl); /* implicitly frees internal_bio */
SSL_free(ssl); /* implicitly frees internal_bio */
BIO_free(network_bio);
...
@@ -165,13 +172,13 @@ buffer is full or the read buffer is drained. Then the application has to
flush the write buffer and/or fill the read buffer.
Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO
and must be transfered to the network. Use BIO_ctrl_get_read_request() to
and must be transferred to the network. Use BIO_ctrl_get_read_request() to
find out, how many bytes must be written into the buffer before the
SSL_operation() can successfully be continued.
=head1 WARNING
As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ
As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ
condition, but there is still data in the write buffer. An application must
not rely on the error value of SSL_operation() but must assure that the
write buffer is always flushed first. Otherwise a deadlock may occur as
@@ -179,7 +186,16 @@ the peer might be waiting for the data before being able to continue.
=head1 SEE ALSO
L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
L<BIO_should_retry(3)|BIO_should_retry(3)>, L<BIO_read(3)|BIO_read(3)>
L<SSL_set_bio(3)>, L<ssl(3)>, L<bio(3)>,
L<BIO_should_retry(3)>, L<BIO_read(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

76
doc/crypto/BIO_s_connect.pod
View File

@@ -2,27 +2,26 @@
=head1 NAME
BIO_set_conn_address, BIO_get_conn_address,
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_get_conn_hostname,
BIO_get_conn_port,
BIO_set_nbio, BIO_do_connect - connect BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
BIO_METHOD * BIO_s_connect(void);
const BIO_METHOD * BIO_s_connect(void);
BIO *BIO_new_connect(char *name);
long BIO_set_conn_hostname(BIO *b, char *name);
long BIO_set_conn_port(BIO *b, char *port);
long BIO_set_conn_ip(BIO *b, char *ip);
long BIO_set_conn_int_port(BIO *b, char *port);
char *BIO_get_conn_hostname(BIO *b);
char *BIO_get_conn_port(BIO *b);
char *BIO_get_conn_ip(BIO *b);
long BIO_get_conn_int_port(BIO *b);
long BIO_set_conn_address(BIO *b, BIO_ADDR *addr);
const char *BIO_get_conn_hostname(BIO *b);
const char *BIO_get_conn_port(BIO *b);
const BIO_ADDR *BIO_get_conn_address(BIO *b);
long BIO_set_nbio(BIO *b, long n);
@@ -57,36 +56,33 @@ it also returns the socket . If B<c> is not NULL it should be of
type (int *).
BIO_set_conn_hostname() uses the string B<name> to set the hostname.
The hostname can be an IP address. The hostname can also include the
port in the form hostname:port . It is also acceptable to use the
form "hostname/any/other/path" or "hostname:port/any/other/path".
The hostname can be an IP address; if the address is an IPv6 one, it
must be enclosed with brackets. The hostname can also include the
port in the form hostname:port.
BIO_set_conn_port() sets the port to B<port>. B<port> can be the
numerical form or a string such as "http". A string will be looked
up first using getservbyname() on the host platform but if that
fails a standard table of port names will be used. Currently the
list is http, telnet, socks, https, ssl, ftp, gopher and wais.
fails a standard table of port names will be used. This internal
list is http, telnet, socks, https, ssl, ftp, and gopher.
BIO_set_conn_ip() sets the IP address to B<ip> using binary form,
that is four bytes specifying the IP address in big-endian form.
BIO_set_conn_int_port() sets the port using B<port>. B<port> should
be of type (int *).
BIO_set_conn_address() sets the address and port information using
a BIO_ADDR(3ssl).
BIO_get_conn_hostname() returns the hostname of the connect BIO or
NULL if the BIO is initialized but no hostname is set.
This return value is an internal pointer which should not be modified.
BIO_get_conn_port() returns the port as a string.
This return value is an internal pointer which should not be modified.
BIO_get_conn_ip() returns the IP address in binary form.
BIO_get_conn_int_port() returns the port as an int.
BIO_get_conn_address() returns the address information as a BIO_ADDR.
This return value is an internal pointer which should not be modified.
BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is
zero then blocking I/O is set. If B<n> is 1 then non blocking I/O
is set. Blocking I/O is the default. The call to BIO_set_nbio()
should be made before the connection is established because
should be made before the connection is established because
non blocking I/O is set during the connect process.
BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
@@ -169,19 +165,20 @@ to retrieve a page and copy the result to standard output.
BIO *cbio, *out;
int len;
char tmpbuf[1024];
ERR_load_crypto_strings();
cbio = BIO_new_connect("localhost:http");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if(BIO_do_connect(cbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
/* whatever ... */
}
if (BIO_do_connect(cbio) <= 0) {
fprintf(stderr, "Error connecting to server\n");
ERR_print_errors_fp(stderr);
exit(1);
}
BIO_puts(cbio, "GET / HTTP/1.0\n\n");
for(;;) {
len = BIO_read(cbio, tmpbuf, 1024);
if(len <= 0) break;
BIO_write(out, tmpbuf, len);
for ( ; ; ) {
len = BIO_read(cbio, tmpbuf, 1024);
if (len <= 0)
break;
BIO_write(out, tmpbuf, len);
}
BIO_free(cbio);
BIO_free(out);
@@ -189,4 +186,15 @@ to retrieve a page and copy the result to standard output.
=head1 SEE ALSO
TBA
L<BIO_ADDR(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

51
doc/crypto/BIO_s_fd.pod
View File

@@ -8,10 +8,10 @@ BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
#include <openssl/bio.h>
BIO_METHOD * BIO_s_fd(void);
const BIO_METHOD *BIO_s_fd(void);
#define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd)
#define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c)
int BIO_set_fd(BIO *b, int fd, int c);
int BIO_get_fd(BIO *b, int *c);
BIO *BIO_new_fd(int fd, int close_flag);
@@ -23,46 +23,43 @@ round the platforms file descriptor routines such as read() and write().
BIO_read() and BIO_write() read or write the underlying descriptor.
BIO_puts() is supported but BIO_gets() is not.
If the close flag is set then then close() is called on the underlying
If the close flag is set then close() is called on the underlying
file descriptor when the BIO is freed.
BIO_reset() attempts to change the file pointer to the start of file
using lseek(fd, 0, 0).
such as by using B<lseek(fd, 0, 0)>.
BIO_seek() sets the file pointer to position B<ofs> from start of file
using lseek(fd, ofs, 0).
such as by using B<lseek(fd, ofs, 0)>.
BIO_tell() returns the current file position by calling lseek(fd, 0, 1).
BIO_tell() returns the current file position such as by calling
B<lseek(fd, 0, 1)>.
BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close
flag to B<c>.
BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also
returns the file descriptor. If B<c> is not NULL it should be of type
(int *).
returns the file descriptor.
BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
=head1 NOTES
The behaviour of BIO_read() and BIO_write() depends on the behavior of the
platforms read() and write() calls on the descriptor. If the underlying
platforms read() and write() calls on the descriptor. If the underlying
file descriptor is in a non blocking mode then the BIO will behave in the
manner described in the L<BIO_read(3)|BIO_read(3)> and L<BIO_should_retry(3)|BIO_should_retry(3)>
manner described in the L<BIO_read(3)> and L<BIO_should_retry(3)>
manual pages.
File descriptor BIOs should not be used for socket I/O. Use socket BIOs
instead.
BIO_set_fd() and BIO_get_fd() are implemented as macros.
=head1 RETURN VALUES
BIO_s_fd() returns the file descriptor BIO method.
BIO_reset() returns zero for success and -1 if an error occurred.
BIO_seek() and BIO_tell() return the current file position or -1
is an error occurred. These values reflect the underlying lseek()
behaviour.
BIO_set_fd() always returns 1.
BIO_get_fd() returns the file descriptor or -1 if the BIO has not
@@ -76,14 +73,26 @@ occurred.
This is a file descriptor BIO version of "Hello World":
BIO *out;
out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
BIO_printf(out, "Hello World\n");
BIO_free(out);
=head1 SEE ALSO
L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
L<BIO_reset(3)|BIO_reset(3)>, L<BIO_read(3)|BIO_read(3)>,
L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>
L<BIO_seek(3)>, L<BIO_tell(3)>,
L<BIO_reset(3)>, L<BIO_read(3)>,
L<BIO_write(3)>, L<BIO_puts(3)>,
L<BIO_gets(3)>, L<BIO_printf(3)>,
L<BIO_set_close(3)>, L<BIO_get_close(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

41
doc/crypto/BIO_s_file.pod
View File

@@ -10,12 +10,12 @@ BIO_rw_filename - FILE bio
#include <openssl/bio.h>
BIO_METHOD * BIO_s_file(void);
const BIO_METHOD * BIO_s_file(void);
BIO *BIO_new_file(const char *filename, const char *mode);
BIO *BIO_new_fp(FILE *stream, int flags);
BIO_set_fp(BIO *b,FILE *fp, int flags);
BIO_get_fp(BIO *b,FILE **fpp);
BIO_set_fp(BIO *b, FILE *fp, int flags);
BIO_get_fp(BIO *b, FILE **fpp);
int BIO_read_filename(BIO *b, char *name)
int BIO_write_filename(BIO *b, char *name)
@@ -92,15 +92,15 @@ Alternative technique:
BIO *bio_out;
bio_out = BIO_new(BIO_s_file());
if(bio_out == NULL) /* Error ... */
if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
if (bio_out == NULL) /* Error ... */
if (!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */
BIO_printf(bio_out, "Hello World\n");
Write to a file:
BIO *out;
out = BIO_new_file("filename.txt", "w");
if(!out) /* Error occurred */
if (!out) /* Error occurred */
BIO_printf(out, "Hello World\n");
BIO_free(out);
@@ -108,8 +108,8 @@ Alternative technique:
BIO *out;
out = BIO_new(BIO_s_file());
if(out == NULL) /* Error ... */
if(!BIO_write_filename(out, "filename.txt")) /* Error ... */
if (out == NULL) /* Error ... */
if (!BIO_write_filename(out, "filename.txt")) /* Error ... */
BIO_printf(out, "Hello World\n");
BIO_free(out);
@@ -128,7 +128,7 @@ BIO_seek() returns the same value as the underlying fseek() function:
BIO_tell() returns the current file position.
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
BIO_rw_filename() return 1 for success or 0 for failure.
=head1 BUGS
@@ -140,9 +140,20 @@ occurred this differs from other types of BIO which will typically return
=head1 SEE ALSO
L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>,
L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>,
L<BIO_read(3)|BIO_read(3)>,
L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>,
L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>,
L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)>
L<BIO_seek(3)>, L<BIO_tell(3)>,
L<BIO_reset(3)>, L<BIO_flush(3)>,
L<BIO_read(3)>,
L<BIO_write(3)>, L<BIO_puts(3)>,
L<BIO_gets(3)>, L<BIO_printf(3)>,
L<BIO_set_close(3)>, L<BIO_get_close(3)>
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

45
doc/crypto/BIO_s_mem.pod
View File

@@ -2,6 +2,7 @@
=head1 NAME
BIO_s_secmem,
BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
@@ -9,23 +10,27 @@ BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
#include <openssl/bio.h>
BIO_METHOD * BIO_s_mem(void);
const BIO_METHOD * BIO_s_mem(void);
const BIO_METHOD * BIO_s_secmem(void);
BIO_set_mem_eof_return(BIO *b,int v)
BIO_set_mem_eof_return(BIO *b, int v)
long BIO_get_mem_data(BIO *b, char **pp)
BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c)
BIO_get_mem_ptr(BIO *b,BUF_MEM **pp)
BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c)
BIO_get_mem_ptr(BIO *b, BUF_MEM **pp)
BIO *BIO_new_mem_buf(const void *buf, int len);
=head1 DESCRIPTION
BIO_s_mem() return the memory BIO method function.
BIO_s_mem() return the memory BIO method function.
A memory BIO is a source/sink BIO which uses memory for its I/O. Data
written to a memory BIO is stored in a BUF_MEM structure which is extended
as appropriate to accommodate the stored data.
BIO_s_secmem() is like BIO_s_mem() except that the secure heap is used
for buffer storage.
Any data written to a memory BIO can be recalled by reading from it.
Unless the memory BIO is read only any data read from it is deleted from
the BIO.
@@ -35,9 +40,10 @@ Memory BIOs support BIO_gets() and BIO_puts().
If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying
BUF_MEM structure is also freed.
Calling BIO_reset() on a read write memory BIO clears any data in it. On a
read only BIO it restores the BIO to its original state and the read only
data can be read again.
Calling BIO_reset() on a read write memory BIO clears any data in it if the
flag BIO_FLAGS_NONCLEAR_RST is not set. On a read only BIO or if the flag
BIO_FLAGS_NONCLEAR_RST is set it restores the BIO to its original state and
the data can be read again.
BIO_eof() is true if no data is in the BIO.
@@ -79,22 +85,19 @@ read in small chunks the operation can be very slow. The use of a read only
memory BIO avoids this problem. If the BIO must be read write then adding
a buffering BIO to the chain will speed up the process.
Calling BIO_set_mem_buf() on a BIO created with BIO_new_secmem() will
give undefined results, including perhaps a program crash.
=head1 BUGS
There should be an option to set the maximum size of a memory BIO.
There should be a way to "rewind" a read write BIO without destroying
its contents.
The copying operation should not occur after every small read of a large BIO
to improve efficiency.
=head1 EXAMPLE
Create a memory BIO and write some data to it:
BIO *mem = BIO_new(BIO_s_mem());
BIO_puts(mem, "Hello World\n");
BIO_puts(mem, "Hello World\n");
Create a read only memory BIO:
@@ -108,8 +111,14 @@ Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
BIO_get_mem_ptr(mem, &bptr);
BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
BIO_free(mem);
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/crypto/BIO_s_null.pod
View File

@@ -8,7 +8,7 @@ BIO_s_null - null data sink
#include <openssl/bio.h>
BIO_METHOD * BIO_s_null(void);
const BIO_METHOD * BIO_s_null(void);
=head1 DESCRIPTION
@@ -32,6 +32,13 @@ by adding a null sink BIO to the end of the chain
BIO_s_null() returns the null sink BIO method.
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

29
doc/crypto/BIO_s_socket.pod
View File

@@ -8,10 +8,7 @@ BIO_s_socket, BIO_new_socket - socket BIO
#include <openssl/bio.h>
BIO_METHOD *BIO_s_socket(void);
long BIO_set_fd(BIO *b, int fd, long close_flag);
long BIO_get_fd(BIO *b, int *c);
const BIO_METHOD *BIO_s_socket(void);
BIO *BIO_new_socket(int sock, int close_flag);
@@ -26,12 +23,6 @@ BIO_puts() is supported but BIO_gets() is not.
If the close flag is set then the socket is shut down and closed
when the BIO is freed.
BIO_set_fd() sets the socket of BIO B<b> to B<fd> and the close
flag to B<close_flag>.
BIO_get_fd() places the socket in B<c> if it is not NULL, it also
returns the socket. If B<c> is not NULL it should be of type (int *).
BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>.
=head1 NOTES
@@ -44,20 +35,20 @@ platforms sockets are not file descriptors and use distinct I/O routines,
Windows is one such platform. Any code mixing the two will not work on
all platforms.
BIO_set_fd() and BIO_get_fd() are macros.
=head1 RETURN VALUES
BIO_s_socket() returns the socket BIO method.
BIO_set_fd() always returns 1.
BIO_get_fd() returns the socket or -1 if the BIO has not been
initialized.
BIO_new_socket() returns the newly allocated BIO or NULL is an error
occurred.
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

191
doc/crypto/BIO_set_callback.pod
View File

@@ -2,99 +2,205 @@
=head1 NAME
BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
BIO_debug_callback - BIO callback functions
BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback,
BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback,
BIO_callback_fn_ex, BIO_callback_fn
- BIO callback functions
=head1 SYNOPSIS
#include <openssl/bio.h>
#define BIO_set_callback(b,cb) ((b)->callback=(cb))
#define BIO_get_callback(b) ((b)->callback)
#define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg))
#define BIO_get_callback_arg(b) ((b)->cb_arg)
typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,
size_t len, int argi,
long argl, int ret, size_t *processed);
typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
long argl, long ret);
long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,
long argl,long ret);
void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
typedef long (*callback)(BIO *b, int oper, const char *argp,
int argi, long argl, long retvalue);
void BIO_set_callback(BIO *b, BIO_callack_fn cb);
BIO_callack_fn BIO_get_callback(BIO *b);
void BIO_set_callback_arg(BIO *b, char *arg);
char *BIO_get_callback_arg(const BIO *b);
long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
long argl, long ret);
=head1 DESCRIPTION
BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback,
they are both macros. The callback is called during most high level BIO
operations. It can be used for debugging purposes to trace operations on
a BIO or to modify its operation.
BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO
callback. The callback is called during most high level BIO operations. It can
be used for debugging purposes to trace operations on a BIO or to modify its
operation.
BIO_set_callback() and BIO_get_callback() set and retrieve the old format BIO
callback. New code should not use these functions, but they are retained for
backwards compatbility. Any callback set via BIO_set_callback_ex() will get
called in preference to any set by BIO_set_callback().
BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be
used to set and retrieve an argument for use in the callback.
BIO_debug_callback() is a standard debugging callback which prints
out information relating to each BIO operation. If the callback
argument is set if is interpreted as a BIO to send the information
argument is set it is interpreted as a BIO to send the information
to, otherwise stderr is used.
callback() is the callback function itself. The meaning of each
argument is described below.
BIO_callback_fn_ex() is the type of the callback function and BIO_callback_fn()
is the type of the old format callback function. The meaning of each argument
is described below:
=over 4
=item B<b>
The BIO the callback is attached to is passed in B<b>.
=item B<oper>
B<oper> is set to the operation being performed. For some operations
the callback is called twice, once before and once after the actual
operation, the latter case has B<oper> or'ed with BIO_CB_RETURN.
=item B<len>
The length of the data requested to be read or written. This is only useful if
B<oper> is BIO_CB_READ, BIO_CB_WRITE or BIO_CB_GETS.
=item B<argp> B<argi> B<argl>
The meaning of the arguments B<argp>, B<argi> and B<argl> depends on
the value of B<oper>, that is the operation being performed.
B<retvalue> is the return value that would be returned to the
=item B<processed>
B<processed> is a pointer to a location which will be updated with the amount of
data that was actually read or written. Only used for BIO_CB_READ, BIO_CB_WRITE,
BIO_CB_GETS and BIO_CB_PUTS.
=item B<ret>
B<ret> is the return value that would be returned to the
application if no callback were present. The actual value returned
is the return value of the callback itself. In the case of callbacks
called before the actual BIO operation 1 is placed in retvalue, if
called before the actual BIO operation 1 is placed in B<ret>, if
the return value is not positive it will be immediately returned to
the application and the BIO operation will not be performed.
The callback should normally simply return B<retvalue> when it has
finished processing, unless if specifically wishes to modify the
=back
The callback should normally simply return B<ret> when it has
finished processing, unless it specifically wishes to modify the
value returned to the application.
=head1 CALLBACK OPERATIONS
In the notes below, B<callback> defers to the actual callback
function that is called.
=over 4
=item B<BIO_free(b)>
callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the
free operation.
callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL)
=item B<BIO_read(b, out, outl)>
or
callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L)
is called before the free operation.
=item B<BIO_read_ex(b, data, dlen, readbytes)>
callback_ex(b, BIO_CB_READ, data, dlen, 0, 0L, 1L, readbytes)
or
callback(b, BIO_CB_READ, data, dlen, 0L, 1L)
is called before the read and
callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, readbytes)
or
callback(b, BIO_CB_READ|BIO_CB_RETURN, data, dlen, 0L, retvalue)
callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before
the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
after.
=item B<BIO_write(b, in, inl)>
=item B<BIO_write(b, data, dlen, written)>
callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, written)
or
callback(b, BIO_CB_WRITE, datat, dlen, 0L, 1L)
is called before the write and
callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, written)
or
callback(b, BIO_CB_WRITE|BIO_CB_RETURN, data, dlen, 0L, retvalue)
callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before
the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
after.
=item B<BIO_gets(b, out, outl)>
=item B<BIO_gets(b, buf, size)>
callback_ex(b, BIO_CB_GETS, buf, size, 0, 0L, 1, NULL, NULL)
or
callback(b, BIO_CB_GETS, buf, size, 0L, 1L)
is called before the operation and
callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, buf, size, 0, 0L, retvalue, readbytes)
or
callback(b, BIO_CB_GETS|BIO_CB_RETURN, buf, size, 0L, retvalue)
callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before
the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
after.
=item B<BIO_puts(b, in)>
=item B<BIO_puts(b, buf)>
callback_ex(b, BIO_CB_PUTS, buf, 0, 0, 0L, 1L, NULL);
or
callback(b, BIO_CB_PUTS, buf, 0, 0L, 1L)
is called before the operation and
callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, buf, 0, 0, 0L, retvalue, written)
or
callback(b, BIO_CB_WRITE|BIO_CB_RETURN, buf, 0, 0L, retvalue)
callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before
the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
after.
=item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)>
callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and
callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL)
or
callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L)
is called before the call and
callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL)
or
callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret)
after.
=back
@@ -103,6 +209,13 @@ callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after.
The BIO_debug_callback() function is a good example, its source is
in crypto/bio/bio_cb.c
=head1 SEE ALSO
=head1 COPYRIGHT
TBA
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

54
doc/crypto/BIO_should_retry.pod
View File

@@ -2,28 +2,24 @@
=head1 NAME
BIO_should_retry, BIO_should_read, BIO_should_write,
BIO_should_read, BIO_should_write,
BIO_should_io_special, BIO_retry_type, BIO_should_retry,
BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions
BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry
functions
=head1 SYNOPSIS
#include <openssl/bio.h>
#define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ)
#define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE)
#define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL)
#define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS)
#define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY)
int BIO_should_read(BIO *b);
int BIO_should_write(BIO *b);
int BIO_should_io_special(iBIO *b);
int BIO_retry_type(BIO *b);
int BIO_should_retry(BIO *b);
#define BIO_FLAGS_READ 0x01
#define BIO_FLAGS_WRITE 0x02
#define BIO_FLAGS_IO_SPECIAL 0x04
#define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)
#define BIO_FLAGS_SHOULD_RETRY 0x08
BIO * BIO_get_retry_BIO(BIO *bio, int *reason);
int BIO_get_retry_reason(BIO *bio);
BIO *BIO_get_retry_BIO(BIO *bio, int *reason);
int BIO_get_retry_reason(BIO *bio);
void BIO_set_retry_reason(BIO *bio, int reason);
=head1 DESCRIPTION
@@ -51,7 +47,7 @@ B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of
these.
BIO_get_retry_BIO() determines the precise reason for the special
condition, it returns the BIO that caused this condition and if
condition, it returns the BIO that caused this condition and if
B<reason> is not NULL it contains the reason code. The meaning of
the reason code and the action that should be taken depends on
the type of BIO that resulted in this condition.
@@ -59,8 +55,14 @@ the type of BIO that resulted in this condition.
BIO_get_retry_reason() returns the reason for a special condition if
passed the relevant BIO, for example as returned by BIO_get_retry_BIO().
BIO_set_retry_reason() sets the retry reason for a special condition for a given
BIO. This would usually only be called by BIO implementations.
=head1 NOTES
BIO_should_read(), BIO_should_write(), BIO_should_io_special(),
BIO_retry_type(), and BIO_should_retry(), are implemented as macros.
If BIO_should_retry() returns false then the precise "error condition"
depends on the BIO type that caused it and the return code of the BIO
operation. For example if a call to BIO_read() on a socket BIO returns
@@ -94,7 +96,7 @@ available and then retry the BIO operation. By combining the retry
conditions of several non blocking BIOs in a single select() call
it is possible to service several BIOs in a single thread, though
the performance may be poor if SSL BIOs are present because long delays
can occur during the initial handshake process.
can occur during the initial handshake process.
It is possible for a BIO to block indefinitely if the underlying I/O
structure cannot process or return any data. This depends on the behaviour of
@@ -111,4 +113,20 @@ the entire structure can be read or written.
=head1 SEE ALSO
TBA
L<bio>
=head1 HISTORY
The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in
OpenSSL version 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

81
doc/crypto/BN_BLINDING_new.pod
View File

@@ -2,38 +2,37 @@
=head1 NAME
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_thread_id, BN_BLINDING_get_flags,
BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM
functions.
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_is_current_thread, BN_BLINDING_set_current_thread,
BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags,
BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM functions
=head1 SYNOPSIS
#include <openssl/bn.h>
BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai,
BIGNUM *mod);
BIGNUM *mod);
void BN_BLINDING_free(BN_BLINDING *b);
int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx);
int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx);
int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b,
BN_CTX *ctx);
BN_CTX *ctx);
int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b,
BN_CTX *ctx);
#ifndef OPENSSL_NO_DEPRECATED
unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *);
void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long);
#endif
CRYPTO_THREADID *BN_BLINDING_thread_id(BN_BLINDING *);
BN_CTX *ctx);
int BN_BLINDING_is_current_thread(BN_BLINDING *b);
void BN_BLINDING_set_current_thread(BN_BLINDING *b);
int BN_BLINDING_lock(BN_BLINDING *b);
int BN_BLINDING_unlock(BN_BLINDING *b);
unsigned long BN_BLINDING_get_flags(const BN_BLINDING *);
void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long);
BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b,
const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx),
BN_MONT_CTX *m_ctx);
const BIGNUM *e, BIGNUM *m, BN_CTX *ctx,
int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p,
const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx),
BN_MONT_CTX *m_ctx);
=head1 DESCRIPTION
@@ -41,6 +40,7 @@ BN_BLINDING_new() allocates a new B<BN_BLINDING> structure and copies
the B<A> and B<Ai> values into the newly created B<BN_BLINDING> object.
BN_BLINDING_free() frees the B<BN_BLINDING> structure.
If B<b> is NULL, nothing is done.
BN_BLINDING_update() updates the B<BN_BLINDING> parameters by squaring
the B<A> and B<Ai> or, after specific number of uses and if the
@@ -57,11 +57,16 @@ BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper
functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex()
with B<r> set to NULL.
BN_BLINDING_thread_id() provides access to the B<CRYPTO_THREADID>
object within the B<BN_BLINDING> structure. This is to help users
provide proper locking if needed for multi-threaded use. The "thread
id" object of a newly allocated B<BN_BLINDING> structure is
initialised to the thread id in which BN_BLINDING_new() was called.
BN_BLINDING_is_current_thread() returns whether the B<BN_BLINDING>
structure is owned by the current thread. This is to help users
provide proper locking if needed for multi-threaded use.
BN_BLINDING_set_current_thread() sets the current thread as the
owner of the B<BN_BLINDING> structure.
BN_BLINDING_lock() locks the B<BN_BLINDING> structure.
BN_BLINDING_unlock() unlocks the B<BN_BLINDING> structure.
BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently
there are two supported flags: B<BN_BLINDING_NO_UPDATE> and
@@ -86,30 +91,32 @@ 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 occurred.
BN_BLINDING_thread_id() returns a pointer to the thread id object
within a B<BN_BLINDING> object.
BN_BLINDING_is_current_thread() returns 1 if the current thread owns
the B<BN_BLINDING> object, 0 otherwise.
BN_BLINDING_set_current_thread() doesn't return anything.
BN_BLINDING_lock(), BN_BLINDING_unlock() return 1 if the operation
succeeded or 0 on error.
BN_BLINDING_get_flags() returns the currently set B<BN_BLINDING> flags
(a B<unsigned long> value).
BN_BLINDING_create_param() returns the newly created B<BN_BLINDING>
BN_BLINDING_create_param() returns the newly created B<BN_BLINDING>
parameters or NULL on error.
=head1 SEE ALSO
L<bn(3)|bn(3)>
=head1 HISTORY
BN_BLINDING_thread_id was first introduced in OpenSSL 1.0.0, and it
deprecates BN_BLINDING_set_thread_id and BN_BLINDING_get_thread_id.
BN_BLINDING_thread_id() was first introduced in OpenSSL 1.0.0, and it
deprecates BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id().
BN_BLINDING_convert_ex, BN_BLINDIND_invert_ex, BN_BLINDING_get_thread_id,
BN_BLINDING_set_thread_id, BN_BLINDING_set_flags, BN_BLINDING_get_flags
and BN_BLINDING_create_param were first introduced in OpenSSL 0.9.8
=head1 COPYRIGHT
=head1 AUTHOR
Copyright 2005-2017 The OpenSSL Project Authors. All Rights Reserved.
Nils Larsch for the OpenSSL project (http://www.openssl.org).
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

61
doc/crypto/BN_CTX_new.pod
View File

@@ -2,7 +2,7 @@
=head1 NAME
BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
BN_CTX_new, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures
=head1 SYNOPSIS
@@ -10,13 +10,10 @@ BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
BN_CTX *BN_CTX_new(void);
BN_CTX *BN_CTX_secure_new(void);
void BN_CTX_free(BN_CTX *c);
Deprecated:
void BN_CTX_init(BN_CTX *c);
=head1 DESCRIPTION
A B<BN_CTX> is a structure that holds B<BIGNUM> temporary variables used by
@@ -24,34 +21,56 @@ library functions. Since dynamic memory allocation to create B<BIGNUM>s
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_new() allocates and initializes a B<BN_CTX> structure.
BN_CTX_secure_new() allocates and initializes a B<BN_CTX> structure
but uses the secure heap (see L<CRYPTO_secure_malloc(3)>) to hold the
B<BIGNUM>s.
BN_CTX_free() frees the components of the B<BN_CTX>, and if it was
created by BN_CTX_new(), also the structure itself.
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>
If L<BN_CTX_start(3)> has been used on the B<BN_CTX>,
L<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.
If B<c> is NULL, nothing is done.
=head1 RETURN VALUES
BN_CTX_new() returns a pointer to the B<BN_CTX>. If the allocation fails,
it returns B<NULL> and sets an error code that can be obtained by
L<ERR_get_error(3)|ERR_get_error(3)>.
BN_CTX_new() and BN_CTX_secure_new() return a pointer to the B<BN_CTX>.
If the allocation fails,
they return B<NULL> and sets an error code that can be obtained by
L<ERR_get_error(3)>.
BN_CTX_init() and BN_CTX_free() have no return values.
BN_CTX_free() has no return values.
=head1 REMOVED FUNCTIONALITY
void BN_CTX_init(BN_CTX *c);
BN_CTX_init() is no longer available as of OpenSSL 1.1.0. Applications should
replace use of BN_CTX_init with BN_CTX_new instead:
BN_CTX *ctx;
ctx = BN_CTX_new();
if(!ctx) /* Handle error */
...
BN_CTX_free(ctx);
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>,
L<BN_CTX_start(3)|BN_CTX_start(3)>
L<ERR_get_error(3)>, L<BN_add(3)>,
L<BN_CTX_start(3)>
=head1 HISTORY
BN_CTX_new() and BN_CTX_free() are available in all versions on SSLeay
and OpenSSL. BN_CTX_init() was added in SSLeay 0.9.1b.
BN_CTX_init() was removed in OpenSSL 1.1.0.
=head1 COPYRIGHT
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

15
doc/crypto/BN_CTX_start.pod
View File

@@ -17,7 +17,7 @@ BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables
=head1 DESCRIPTION
These functions are used to obtain temporary B<BIGNUM> variables from
a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)|BN_CTX_new(3)>)
a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)>)
in order to save the overhead of repeatedly creating and
freeing B<BIGNUM>s in functions that are called from inside a loop.
@@ -38,15 +38,20 @@ BN_CTX_get() returns a pointer to the B<BIGNUM>, or B<NULL> on error.
Once BN_CTX_get() has failed, the subsequent calls will return B<NULL>
as well, so it is sufficient to check the return value of the last
BN_CTX_get() call. In case of an error, an error code is set, which
can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<BN_CTX_new(3)|BN_CTX_new(3)>
L<BN_CTX_new(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_CTX_start(), BN_CTX_get() and BN_CTX_end() were added in OpenSSL 0.9.5.
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

29
doc/crypto/BN_add.pod
View File

@@ -49,10 +49,11 @@ BN_add() adds I<a> and I<b> and places the result in I<r> (C<r=a+b>).
I<r> may be the same B<BIGNUM> as I<a> or I<b>.
BN_sub() subtracts I<b> from I<a> and places the result in I<r> (C<r=a-b>).
I<r> may be the same B<BIGNUM> as I<a> or I<b>.
BN_mul() multiplies I<a> and I<b> and places the result in I<r> (C<r=a*b>).
I<r> may be the same B<BIGNUM> as I<a> or I<b>.
For multiplication by powers of 2, use L<BN_lshift(3)|BN_lshift(3)>.
For multiplication by powers of 2, use L<BN_lshift(3)>.
BN_sqr() takes the square of I<a> and places the result in I<r>
(C<r=a^2>). I<r> and I<a> may be the same B<BIGNUM>.
@@ -80,8 +81,8 @@ BN_mod_mul() multiplies I<a> by I<b> and finds the non-negative
remainder respective to modulus I<m> (C<r=(a*b) mod m>). I<r> may be
the same B<BIGNUM> as I<a> or I<b>. For more efficient algorithms for
repeated computations using the same modulus, see
L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)> and
L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>.
L<BN_mod_mul_montgomery(3)> and
L<BN_mod_mul_reciprocal(3)>.
BN_mod_sqr() takes the square of I<a> modulo B<m> and places the
result in I<r>.
@@ -98,7 +99,7 @@ places the result in I<r>. I<r> may be the same B<BIGNUM> as I<a> or
I<b>.
For all functions, I<ctx> is a previously allocated B<BN_CTX> used for
temporary variables; see L<BN_CTX_new(3)|BN_CTX_new(3)>.
temporary variables; see L<BN_CTX_new(3)>.
Unless noted otherwise, the result B<BIGNUM> must be different from
the arguments.
@@ -107,20 +108,20 @@ the arguments.
For all functions, 1 is returned for success, 0 on error. The return
value should always be checked (e.g., C<if (!BN_add(r,a,b)) goto err;>).
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>,
L<BN_add_word(3)|BN_add_word(3)>, L<BN_set_bit(3)|BN_set_bit(3)>
L<ERR_get_error(3)>, L<BN_CTX_new(3)>,
L<BN_add_word(3)>, L<BN_set_bit(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_add(), BN_sub(), BN_sqr(), BN_div(), BN_mod(), BN_mod_mul(),
BN_mod_exp() and BN_gcd() are available in all versions of SSLeay and
OpenSSL. The I<ctx> argument to BN_mul() was added in SSLeay
0.9.1b. BN_exp() appeared in SSLeay 0.9.0.
BN_nnmod(), BN_mod_add(), BN_mod_sub(), and BN_mod_sqr() were added in
OpenSSL 0.9.7.
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

16
doc/crypto/BN_add_word.pod
View File

@@ -40,22 +40,22 @@ For BN_div_word() and BN_mod_word(), B<w> must not be 0.
=head1 RETURN VALUES
BN_add_word(), BN_sub_word() and BN_mul_word() return 1 for success, 0
on error. The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
on error. The error codes can be obtained by L<ERR_get_error(3)>.
BN_mod_word() and BN_div_word() return B<a>%B<w> on success and
B<(BN_ULONG)-1> if an error occurred.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>
L<ERR_get_error(3)>, L<BN_add(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_add_word() and BN_mod_word() are available in all versions of
SSLeay and OpenSSL. BN_div_word() was added in SSLeay 0.8, and
BN_sub_word() and BN_mul_word() in SSLeay 0.9.0.
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
Before 0.9.8a the return value for BN_div_word() and BN_mod_word()
in case of an error was 0.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

55
doc/crypto/BN_bn2bin.pod
View File

@@ -2,16 +2,22 @@
=head1 NAME
BN_bn2bin, BN_bin2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn,
BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn - format conversions
BN_bn2binpad,
BN_bn2bin, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn, BN_bn2hex, BN_bn2dec,
BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp, BN_bn2mpi,
BN_mpi2bn - format conversions
=head1 SYNOPSIS
#include <openssl/bn.h>
int BN_bn2bin(const BIGNUM *a, unsigned char *to);
int BN_bn2binpad(const BIGNUM *a, unsigned char *to, int tolen);
BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret);
int BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen);
BIGNUM *BN_lebin2bn(const unsigned char *s, int len, BIGNUM *ret);
char *BN_bn2hex(const BIGNUM *a);
char *BN_bn2dec(const BIGNUM *a);
int BN_hex2bn(BIGNUM **a, const char *str);
@@ -29,20 +35,28 @@ BN_bn2bin() converts the absolute value of B<a> into big-endian form
and stores it at B<to>. B<to> must point to BN_num_bytes(B<a>) bytes of
memory.
BN_bn2binpad() also converts the absolute value of B<a> into big-endian form
and stores it at B<to>. B<tolen> indicates the length of the output buffer
B<to>. The result is padded with zeroes if necessary. If B<tolen> is less than
BN_num_bytes(B<a>) an error is returned.
BN_bin2bn() converts the positive integer in big-endian form of length
B<len> at B<s> into a B<BIGNUM> and places it in B<ret>. If B<ret> is
NULL, a new B<BIGNUM> is created.
BN_bn2lebinpad() and BN_bin2lbn() are identical to BN_bn2binpad() and
BN_bin2bn() except the buffer is in little-endian format.
BN_bn2hex() and BN_bn2dec() return printable strings containing the
hexadecimal and decimal encoding of B<a> respectively. For negative
numbers, the string is prefaced with a leading '-'. The string must be
freed later using OPENSSL_free().
BN_hex2bn() converts the string B<str> containing a hexadecimal number
to a B<BIGNUM> and stores it in **B<bn>. If *B<bn> is NULL, a new
B<BIGNUM> is created. If B<bn> is NULL, it only computes the number's
length in hexadecimal digits. If the string starts with '-', the
number is negative.
BN_hex2bn() takes as many characters as possible from the string B<str>,
including the leading character '-' which means negative, to form a valid
hexadecimal number representation and converts them to a B<BIGNUM> and
stores it in **B<bn>. If *B<bn> is NULL, a new B<BIGNUM> is created. If
B<bn> is NULL, it only computes the length of valid representation.
A "negative zero" is converted to zero.
BN_dec2bn() is the same using the decimal system.
@@ -69,29 +83,34 @@ if B<ret> is NULL.
BN_bn2bin() returns the length of the big-endian number placed at B<to>.
BN_bin2bn() returns the B<BIGNUM>, NULL on error.
BN_bn2binpad() returns the number of bytes written or -1 if the supplied
buffer is too small.
BN_bn2hex() and BN_bn2dec() return a null-terminated string, or NULL
on error. BN_hex2bn() and BN_dec2bn() return the number's length in
hexadecimal or decimal digits, and 0 on error.
on error. BN_hex2bn() and BN_dec2bn() return the the length of valid
representation in hexadecimal or decimal digits, and 0 on error, in which
case no new B<BIGNUM> will be created.
BN_print_fp() and BN_print() return 1 on success, 0 on write errors.
BN_bn2mpi() returns the length of the representation. BN_mpi2bn()
returns the B<BIGNUM>, and NULL on error.
The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>.
The error codes can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_zero(3)|BN_zero(3)>,
L<ASN1_INTEGER_to_BN(3)|ASN1_INTEGER_to_BN(3)>,
L<BN_num_bytes(3)|BN_num_bytes(3)>
L<ERR_get_error(3)>, L<BN_zero(3)>,
L<ASN1_INTEGER_to_BN(3)>,
L<BN_num_bytes(3)>
=head1 HISTORY
=head1 COPYRIGHT
BN_bn2bin(), BN_bin2bn(), BN_print_fp() and BN_print() are available
in all versions of SSLeay and OpenSSL.
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
BN_bn2hex(), BN_bn2dec(), BN_hex2bn(), BN_dec2bn(), BN_bn2mpi() and
BN_mpi2bn() were added in SSLeay 0.9.0.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

13
doc/crypto/BN_cmp.pod
View File

@@ -35,14 +35,13 @@ of B<a> and B<b>.
BN_is_zero(), BN_is_one() BN_is_word() and BN_is_odd() return 1 if
the condition is true, 0 otherwise.
=head1 SEE ALSO
=head1 COPYRIGHT
L<bn(3)|bn(3)>
Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
=head1 HISTORY
BN_cmp(), BN_ucmp(), BN_is_zero(), BN_is_one() and BN_is_word() are
available in all versions of SSLeay and OpenSSL.
BN_is_odd() was added in SSLeay 0.8.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

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