aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorJung-uk Kim <jkim@FreeBSD.org>2015-12-03 17:22:58 +0000
committerJung-uk Kim <jkim@FreeBSD.org>2015-12-03 17:22:58 +0000
commit737d7e8d3945c206c037e139055821aa0c64bb8e (patch)
treeb0284af4e4144e27eb9f39e88c53868060774b16 /doc
parente9fcefce9bb70f20c272a996443928c5f6ab8cd8 (diff)
downloadsrc-737d7e8d3945c206c037e139055821aa0c64bb8e.tar.gz
src-737d7e8d3945c206c037e139055821aa0c64bb8e.zip
Import OpenSSL 1.0.2e.vendor/openssl/1.0.2e
Notes
Notes: svn path=/vendor-crypto/openssl/dist/; revision=291707 svn path=/vendor-crypto/openssl/1.0.2e/; revision=291708; tag=vendor/openssl/1.0.2e
Diffstat (limited to 'doc')
-rw-r--r--doc/HOWTO/keys.txt5
-rw-r--r--doc/README27
-rw-r--r--doc/apps/dgst.pod5
-rw-r--r--doc/apps/genrsa.pod6
-rw-r--r--doc/apps/pkcs12.pod2
-rw-r--r--doc/apps/req.pod13
-rw-r--r--doc/apps/x509.pod3
-rw-r--r--doc/crypto/BIO_read.pod6
-rw-r--r--doc/crypto/BN_rand.pod4
-rw-r--r--doc/crypto/DSA_generate_parameters.pod2
-rw-r--r--doc/crypto/EC_GROUP_copy.pod2
-rw-r--r--doc/crypto/EC_KEY_new.pod4
-rw-r--r--doc/crypto/EVP_DigestVerifyInit.pod9
-rw-r--r--doc/crypto/EVP_EncryptInit.pod2
-rw-r--r--doc/crypto/EVP_SealInit.pod2
-rw-r--r--doc/crypto/EVP_SignInit.pod3
-rw-r--r--doc/crypto/X509_check_host.pod2
-rw-r--r--doc/crypto/buffer.pod49
-rw-r--r--doc/crypto/d2i_X509_NAME.pod2
-rw-r--r--doc/crypto/engine.pod10
-rw-r--r--doc/dir-locals.example.el15
-rw-r--r--doc/openssl-c-indent.el62
-rw-r--r--doc/openssl_button.gifbin2063 -> 0 bytes
-rw-r--r--doc/openssl_button.html7
-rw-r--r--doc/ssl/SSL_CTX_add_extra_chain_cert.pod35
-rw-r--r--doc/ssl/SSL_CTX_get0_param.pod2
-rw-r--r--doc/ssl/SSL_check_chain.pod85
27 files changed, 266 insertions, 98 deletions
diff --git a/doc/HOWTO/keys.txt b/doc/HOWTO/keys.txt
index 7ae2a3a11833..ba0314fafce0 100644
--- a/doc/HOWTO/keys.txt
+++ b/doc/HOWTO/keys.txt
@@ -40,9 +40,8 @@ consider insecure or to be insecure pretty soon.
3. To generate a DSA key
-A DSA key can be used for signing only. This is important to keep
-in mind to know what kind of purposes a certificate request with a
-DSA key can really be used for.
+A DSA key can be used for signing only. It is important to
+know what a certificate request with a DSA key can really be used for.
Generating a key for the DSA algorithm is a two-step process. First,
you have to generate parameters from which to generate the key:
diff --git a/doc/README b/doc/README
index 6ecc14d99457..cc760402ae9b 100644
--- a/doc/README
+++ b/doc/README
@@ -1,12 +1,21 @@
- apps/openssl.pod .... Documentation of OpenSSL `openssl' command
- crypto/crypto.pod ... Documentation of OpenSSL crypto.h+libcrypto.a
- ssl/ssl.pod ......... Documentation of OpenSSL ssl.h+libssl.a
- openssl.txt ......... Assembled documentation files for OpenSSL [not final]
- ssleay.txt .......... Assembled documentation of ancestor SSLeay [obsolete]
- standards.txt ....... Assembled pointers to standards, RFCs or internet drafts
- that are related to OpenSSL.
+README This file
- An archive of HTML documents for the SSLeay library is available from
- http://www.columbia.edu/~ariel/ssleay/
+fingerprints.txt
+ PGP fingerprints of authoried release signers
+standards.txt
+ Pointers to standards, RFC's and IETF Drafts that are
+ related to OpenSSL. Incomplete.
+
+HOWTO/
+ A few how-to documents; not necessarily up-to-date
+apps/
+ The openssl command-line tools; start with openssl.pod
+ssl/
+ The SSL library; start with ssl.pod
+crypto/
+ The cryptographic library; start with crypto.pod
+
+Formatted versions of the manpages (apps,ssl,crypto) can be found at
+ https://www.openssl.org/docs/manpages.html
diff --git a/doc/apps/dgst.pod b/doc/apps/dgst.pod
index 9e15798d8279..b27bb946b1b2 100644
--- a/doc/apps/dgst.pod
+++ b/doc/apps/dgst.pod
@@ -13,7 +13,6 @@ B<openssl> B<dgst>
[B<-hex>]
[B<-binary>]
[B<-r>]
-[B<-hmac arg>]
[B<-non-fips-allow>]
[B<-out filename>]
[B<-sign filename>]
@@ -64,10 +63,6 @@ output the digest or signature in binary form.
output the digest in the "coreutils" format used by programs like B<sha1sum>.
-=item B<-hmac arg>
-
-set the HMAC key to "arg".
-
=item B<-non-fips-allow>
Allow use of non FIPS digest when in FIPS mode. This has no effect when not in
diff --git a/doc/apps/genrsa.pod b/doc/apps/genrsa.pod
index cb03d09b95eb..3dc9870f34b9 100644
--- a/doc/apps/genrsa.pod
+++ b/doc/apps/genrsa.pod
@@ -10,12 +10,6 @@ B<openssl> B<genrsa>
[B<-out filename>]
[B<-passout arg>]
[B<-aes128>]
-[B<-aes128>]
-[B<-aes192>]
-[B<-aes256>]
-[B<-camellia128>]
-[B<-camellia192>]
-[B<-camellia256>]
[B<-aes192>]
[B<-aes256>]
[B<-camellia128>]
diff --git a/doc/apps/pkcs12.pod b/doc/apps/pkcs12.pod
index 8e0d91798ac4..744984838dc7 100644
--- a/doc/apps/pkcs12.pod
+++ b/doc/apps/pkcs12.pod
@@ -216,7 +216,7 @@ key is encrypted using triple DES and the certificate using 40 bit RC2.
these options allow the algorithm used to encrypt the private key and
certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name
-can be used (see B<NOTES> section for more information). If a a cipher name
+can be used (see B<NOTES> section for more information). If a cipher name
(as output by the B<list-cipher-algorithms> command is specified then it
is used with PKCS#5 v2.0. For interoperability reasons it is advisable to only
use PKCS#12 algorithms.
diff --git a/doc/apps/req.pod b/doc/apps/req.pod
index df68cb0921fd..54a4d394d282 100644
--- a/doc/apps/req.pod
+++ b/doc/apps/req.pod
@@ -30,7 +30,6 @@ B<openssl> B<req>
[B<-keygen_engine id>]
[B<-[digest]>]
[B<-config filename>]
-[B<-subj arg>]
[B<-multivalue-rdn>]
[B<-x509>]
[B<-days n>]
@@ -490,7 +489,7 @@ be input by calling it "1.organizationName".
The actual permitted field names are any object identifier short or
long names. These are compiled into OpenSSL and include the usual
values such as commonName, countryName, localityName, organizationName,
-organizationUnitName, stateOrProvinceName. Additionally emailAddress
+organizationalUnitName, stateOrProvinceName. Additionally emailAddress
is include as well as name, surname, givenName initials and dnQualifier.
Additional object identifiers can be defined with the B<oid_file> or
@@ -506,16 +505,16 @@ Examine and verify certificate request:
Create a private key and then generate a certificate request from it:
- openssl genrsa -out key.pem 1024
+ openssl genrsa -out key.pem 2048
openssl req -new -key key.pem -out req.pem
The same but just using req:
- openssl req -newkey rsa:1024 -keyout key.pem -out req.pem
+ openssl req -newkey rsa:2048 -keyout key.pem -out req.pem
Generate a self signed root certificate:
- openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem
+ openssl req -x509 -newkey rsa:2048 -keyout key.pem -out req.pem
Example of a file pointed to by the B<oid_file> option:
@@ -531,7 +530,7 @@ expansion:
Sample configuration file prompting for field values:
[ req ]
- default_bits = 1024
+ default_bits = 2048
default_keyfile = privkey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
@@ -572,7 +571,7 @@ Sample configuration containing all field values:
RANDFILE = $ENV::HOME/.rnd
[ req ]
- default_bits = 1024
+ default_bits = 2048
default_keyfile = keyfile.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
diff --git a/doc/apps/x509.pod b/doc/apps/x509.pod
index a1326edeefb6..26f71c883295 100644
--- a/doc/apps/x509.pod
+++ b/doc/apps/x509.pod
@@ -539,7 +539,8 @@ very rare and their use is discouraged). The options ending in
"space" additionally place a space after the separator to make it
more readable. The B<sep_multiline> uses a linefeed character for
the RDN separator and a spaced B<+> for the AVA separator. It also
-indents the fields by four characters.
+indents the fields by four characters. If no field separator is specified
+then B<sep_comma_plus_space> is used by default.
=item B<dn_rev>
diff --git a/doc/crypto/BIO_read.pod b/doc/crypto/BIO_read.pod
index b34528104ddf..2c177f0b6d86 100644
--- a/doc/crypto/BIO_read.pod
+++ b/doc/crypto/BIO_read.pod
@@ -9,9 +9,9 @@ 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_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_puts(BIO *b, const char *buf);
=head1 DESCRIPTION
@@ -26,7 +26,7 @@ return the digest and other BIOs may not support BIO_gets() at all.
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 null terminated string B<buf> to BIO B<b>.
=head1 RETURN VALUES
diff --git a/doc/crypto/BN_rand.pod b/doc/crypto/BN_rand.pod
index bd6bc8632394..e8cbf658b47d 100644
--- a/doc/crypto/BN_rand.pod
+++ b/doc/crypto/BN_rand.pod
@@ -19,7 +19,7 @@ BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-r
=head1 DESCRIPTION
BN_rand() generates a cryptographically strong pseudo-random number of
-B<bits> bits in length and stores it in B<rnd>. If B<top> is -1, the
+B<bits> in length and stores it in B<rnd>. If B<top> is -1, the
most significant bit of the random number can be zero. If B<top> is 0,
it is set to 1, and if B<top> is 1, the two most significant bits of
the number will be set to 1, so that the product of two such random
@@ -33,7 +33,7 @@ non-cryptographic purposes and for certain purposes in cryptographic
protocols, but usually not for key generation etc.
BN_rand_range() generates a cryptographically strong pseudo-random
-number B<rnd> in the range 0 <lt>= B<rnd> E<lt> B<range>.
+number B<rnd> in the range 0 E<lt>= B<rnd> E<lt> B<range>.
BN_pseudo_rand_range() does the same, but is based on BN_pseudo_rand(),
and hence numbers generated by it are not necessarily unpredictable.
diff --git a/doc/crypto/DSA_generate_parameters.pod b/doc/crypto/DSA_generate_parameters.pod
index 16a67f22b0c4..b1a4d201b75c 100644
--- a/doc/crypto/DSA_generate_parameters.pod
+++ b/doc/crypto/DSA_generate_parameters.pod
@@ -29,7 +29,7 @@ maximum of 1024 bits.
If B<seed> is B<NULL> or B<seed_len> E<lt> 20, the primes will be
generated at random. Otherwise, the seed is used to generate
them. If the given seed does not yield a prime q, a new random
-seed is chosen and placed at B<seed>.
+seed is chosen.
DSA_generate_parameters_ex() places the iteration count in
*B<counter_ret> and a counter used for finding a generator in
diff --git a/doc/crypto/EC_GROUP_copy.pod b/doc/crypto/EC_GROUP_copy.pod
index 954af469d5aa..49dc01ced147 100644
--- a/doc/crypto/EC_GROUP_copy.pod
+++ b/doc/crypto/EC_GROUP_copy.pod
@@ -158,7 +158,7 @@ EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the p
specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified.
EC_GROUP_set_seed returns the length of the seed that has been set. If the supplied seed is NULL, or the supplied seed length is
-0, the the return value will be 1. On error 0 is returned.
+0, the return value will be 1. On error 0 is returned.
EC_GROUP_cmp returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.
diff --git a/doc/crypto/EC_KEY_new.pod b/doc/crypto/EC_KEY_new.pod
index e859689bcb50..0fa2de1721b7 100644
--- a/doc/crypto/EC_KEY_new.pod
+++ b/doc/crypto/EC_KEY_new.pod
@@ -70,8 +70,8 @@ The functions EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_K
The functions EC_KEY_get_conv_form and EC_KEY_set_conv_form get and set the point_conversion_form for the B<key>. For a description
of point_conversion_forms please refer to L<EC_POINT_new(3)|EC_POINT_new(3)>.
-EC_KEY_insert_key_method_data and EC_KEY_get_key_method_data enable the caller to associate arbitary additional data specific to the
-elliptic curve scheme being used with the EC_KEY object. This data is treated as a "black box" by the ec library. The data to be stored by EC_KEY_insert_key_method_data is provided in the B<data> parameter, which must have have associated functions for duplicating, freeing and "clear_freeing" the data item. If a subsequent EC_KEY_get_key_method_data call is issued, the functions for duplicating, freeing and "clear_freeing" the data item must be provided again, and they must be the same as they were when the data item was inserted.
+EC_KEY_insert_key_method_data and EC_KEY_get_key_method_data enable the caller to associate arbitrary additional data specific to the
+elliptic curve scheme being used with the EC_KEY object. This data is treated as a "black box" by the ec library. The data to be stored by EC_KEY_insert_key_method_data is provided in the B<data> parameter, which must have associated functions for duplicating, freeing and "clear_freeing" the data item. If a subsequent EC_KEY_get_key_method_data call is issued, the functions for duplicating, freeing and "clear_freeing" the data item must be provided again, and they must be the same as they were when the data item was inserted.
EC_KEY_set_flags sets the flags in the B<flags> parameter on the EC_KEY object. Any flags that are already set are left set. The currently defined standard flags are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH and is defined in ecdh.h. EC_KEY_get_flags returns the current flags that are set for this EC_KEY. EC_KEY_clear_flags clears the flags indicated by the B<flags> parameter. All other flags are left in their existing state.
diff --git a/doc/crypto/EVP_DigestVerifyInit.pod b/doc/crypto/EVP_DigestVerifyInit.pod
index e0217e40cba8..0ead2d2f8aa1 100644
--- a/doc/crypto/EVP_DigestVerifyInit.pod
+++ b/doc/crypto/EVP_DigestVerifyInit.pod
@@ -37,10 +37,11 @@ EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0
or a negative value for failure. In particular a return value of -2 indicates
the operation is not supported by the public key algorithm.
-Unlike other functions the return value 0 from EVP_DigestVerifyFinal() only
-indicates that the signature did not verify successfully (that is tbs did
-not match the original data or the signature was of invalid form) it is not an
-indication of a more serious error.
+EVP_DigestVerifyFinal() returns 1 for success; any other value indicates
+failure. A return value of zero indicates that the signature did not verify
+successfully (that is, tbs did not match the original data or the signature had
+an invalid form), while other values indicate a more serious error (and
+sometimes also indicate an invalid signature form).
The error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod
index fb6036f959ba..c69e6a6d700e 100644
--- a/doc/crypto/EVP_EncryptInit.pod
+++ b/doc/crypto/EVP_EncryptInit.pod
@@ -111,7 +111,7 @@ EVP_CIPHER_CTX_init() initializes cipher contex B<ctx>.
EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption
with cipher B<type> from ENGINE B<impl>. B<ctx> must be initialized
before calling this function. B<type> is normally supplied
-by a function such as EVP_des_cbc(). If B<impl> is NULL then the
+by a function such as EVP_aes_256_cbc(). If B<impl> is NULL then the
default implementation is used. B<key> is the symmetric key to use
and B<iv> is the IV to use (if necessary), the actual number of bytes
used for the key and IV depends on the cipher. It is possible to set
diff --git a/doc/crypto/EVP_SealInit.pod b/doc/crypto/EVP_SealInit.pod
index 7d793e19ef7a..19112a542d89 100644
--- a/doc/crypto/EVP_SealInit.pod
+++ b/doc/crypto/EVP_SealInit.pod
@@ -25,7 +25,7 @@ encrypted using this key.
EVP_SealInit() initializes a cipher context B<ctx> for encryption
with cipher B<type> using a random secret key and IV. B<type> is normally
-supplied by a function such as EVP_des_cbc(). The secret key is encrypted
+supplied by a function such as EVP_aes_256_cbc(). The secret key is encrypted
using one or more public keys, this allows the same encrypted data to be
decrypted using any of the corresponding private keys. B<ek> is an array of
buffers where the public key encrypted secret key will be written, each buffer
diff --git a/doc/crypto/EVP_SignInit.pod b/doc/crypto/EVP_SignInit.pod
index 14ecc775af6a..c63d6b339318 100644
--- a/doc/crypto/EVP_SignInit.pod
+++ b/doc/crypto/EVP_SignInit.pod
@@ -2,7 +2,8 @@
=head1 NAME
-EVP_SignInit, EVP_SignUpdate, EVP_SignFinal - EVP signing functions
+EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal - EVP signing
+functions
=head1 SYNOPSIS
diff --git a/doc/crypto/X509_check_host.pod b/doc/crypto/X509_check_host.pod
index 0def17aac1c5..521b9f535c7b 100644
--- a/doc/crypto/X509_check_host.pod
+++ b/doc/crypto/X509_check_host.pod
@@ -135,6 +135,6 @@ L<X509_VERIFY_PARAM_set1_ipasc(3)|X509_VERIFY_PARAM_set1_ipasc(3)>
=head1 HISTORY
-These functions were added in OpenSSL 1.1.0.
+These functions were added in OpenSSL 1.0.2.
=cut
diff --git a/doc/crypto/buffer.pod b/doc/crypto/buffer.pod
index 781f5b11ee54..52c5c841eb03 100644
--- a/doc/crypto/buffer.pod
+++ b/doc/crypto/buffer.pod
@@ -2,8 +2,11 @@
=head1 NAME
-BUF_MEM_new, BUF_MEM_free, BUF_MEM_grow, BUF_strdup - simple
-character arrays structure
+BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow - simple
+character array structure
+
+BUF_strdup, BUF_strndup, BUF_memdup, BUF_strlcpy, BUF_strlcat -
+standard C library equivalents
=head1 SYNOPSIS
@@ -15,25 +18,22 @@ character arrays structure
int BUF_MEM_grow(BUF_MEM *str, int len);
- char * BUF_strdup(const char *str);
+ char *BUF_strdup(const char *str);
-=head1 DESCRIPTION
+ char *BUF_strndup(const char *str, size_t siz);
-The buffer library handles simple character arrays. Buffers are used for
-various purposes in the library, most notably memory BIOs.
+ void *BUF_memdup(const void *data, size_t siz);
+
+ size_t BUF_strlcpy(char *dst, const char *src, size_t size);
-The library uses the BUF_MEM structure defined in buffer.h:
+ size_t BUF_strlcat(char *dst, const char *src, size_t size);
- typedef struct buf_mem_st
- {
- int length; /* current number of bytes */
- char *data;
- int max; /* size of buffer */
- } BUF_MEM;
+ size_t BUF_strnlen(const char *str, size_t maxlen);
-B<length> is the current size of the buffer in bytes, B<max> is the amount of
-memory allocated to the buffer. There are three functions which handle these
-and one "miscellaneous" function.
+=head1 DESCRIPTION
+
+The buffer library handles simple character arrays. Buffers are used for
+various purposes in the library, most notably memory BIOs.
BUF_MEM_new() allocates a new buffer of zero size.
@@ -44,14 +44,17 @@ BUF_MEM_grow() changes the size of an already existing buffer to
B<len>. Any data already in the buffer is preserved if it increases in
size.
-BUF_strdup() copies a null terminated string into a block of allocated
-memory and returns a pointer to the allocated block.
-Unlike the standard C library strdup() this function uses OPENSSL_malloc() and so
-should be used in preference to the standard library strdup() because it can
-be used for memory leak checking or replacing the malloc() function.
+BUF_strdup(), BUF_strndup(), BUF_memdup(), BUF_strlcpy(),
+BUF_strlcat() and BUF_strnlen are equivalents of the standard C
+library functions. The dup() functions use OPENSSL_malloc() underneath
+and so should be used in preference to the standard library for memory
+leak checking or replacing the malloc() function.
+
+Memory allocated from these functions should be freed up using the
+OPENSSL_free() function.
-The memory allocated from BUF_strdup() should be freed up using the OPENSSL_free()
-function.
+BUF_strndup makes the explicit guarantee that it will never read past
+the first B<siz> bytes of B<str>.
=head1 RETURN VALUES
diff --git a/doc/crypto/d2i_X509_NAME.pod b/doc/crypto/d2i_X509_NAME.pod
index 343ffe151914..b025de7b2ff6 100644
--- a/doc/crypto/d2i_X509_NAME.pod
+++ b/doc/crypto/d2i_X509_NAME.pod
@@ -14,7 +14,7 @@ d2i_X509_NAME, i2d_X509_NAME - X509_NAME encoding functions
=head1 DESCRIPTION
These functions decode and encode an B<X509_NAME> structure which is the
-the same as the B<Name> type defined in RFC2459 (and elsewhere) and used
+same as the B<Name> type defined in RFC2459 (and elsewhere) and used
for example in certificate subject and issuer names.
Othewise the functions behave in a similar way to d2i_X509() and i2d_X509()
diff --git a/doc/crypto/engine.pod b/doc/crypto/engine.pod
index f5ab1c3e50fd..48741ee30629 100644
--- a/doc/crypto/engine.pod
+++ b/doc/crypto/engine.pod
@@ -192,7 +192,7 @@ to use the pointer value at all, as this kind of reference is a guarantee
that the structure can not be deallocated until the reference is released.
However, a structural reference provides no guarantee that the ENGINE is
-initiliased and able to use any of its cryptographic
+initialised and able to use any of its cryptographic
implementations. Indeed it's quite possible that most ENGINEs will not
initialise at all in typical environments, as ENGINEs are typically used to
support specialised hardware. To use an ENGINE's functionality, you need a
@@ -201,8 +201,8 @@ specialised form of structural reference, because each functional reference
implicitly contains a structural reference as well - however to avoid
difficult-to-find programming bugs, it is recommended to treat the two
kinds of reference independently. If you have a functional reference to an
-ENGINE, you have a guarantee that the ENGINE has been initialised ready to
-perform cryptographic operations and will remain uninitialised
+ENGINE, you have a guarantee that the ENGINE has been initialised and
+is ready to perform cryptographic operations, and will remain initialised
until after you have released your reference.
I<Structural references>
@@ -370,7 +370,7 @@ I<Using a specific ENGINE implementation>
Here we'll assume an application has been configured by its user or admin
to want to use the "ACME" ENGINE if it is available in the version of
OpenSSL the application was compiled with. If it is available, it should be
-used by default for all RSA, DSA, and symmetric cipher operation, otherwise
+used by default for all RSA, DSA, and symmetric cipher operations, otherwise
OpenSSL should use its builtin software as per usual. The following code
illustrates how to approach this;
@@ -401,7 +401,7 @@ I<Automatically using builtin ENGINE implementations>
Here we'll assume we want to load and register all ENGINE implementations
bundled with OpenSSL, such that for any cryptographic algorithm required by
-OpenSSL - if there is an ENGINE that implements it and can be initialise,
+OpenSSL - if there is an ENGINE that implements it and can be initialised,
it should be used. The following code illustrates how this can work;
/* Load all bundled ENGINEs into memory and make them visible */
diff --git a/doc/dir-locals.example.el b/doc/dir-locals.example.el
new file mode 100644
index 000000000000..79d0b01108d4
--- /dev/null
+++ b/doc/dir-locals.example.el
@@ -0,0 +1,15 @@
+;;; This is an example of what a .dir-locals.el suitable for OpenSSL
+;;; development could look like.
+;;;
+;;; Apart from setting the CC mode style to "OpenSSL-II", it also
+;;; makes sure that tabs are never used for indentation in any file,
+;;; and that the fill column is 78.
+;;;
+;;; For more information see (info "(emacs) Directory Variables")
+
+((nil
+ (indent-tabs-mode . nil)
+ (fill-column . 78)
+ )
+ (c-mode
+ (c-file-style . "OpenSSL-II")))
diff --git a/doc/openssl-c-indent.el b/doc/openssl-c-indent.el
new file mode 100644
index 000000000000..144a915675ed
--- /dev/null
+++ b/doc/openssl-c-indent.el
@@ -0,0 +1,62 @@
+;;; This Emacs Lisp file defines a C indentation style for 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).
+;;;
+;;; Recommended use is to add this line in your .emacs:
+;;;
+;;; (load (expand-file-name "~/PATH/TO/openssl-c-indent.el"))
+;;;
+;;; 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.
+;;;
+;;; If you're a OpenSSL developer, you might find it more comfortable
+;;; to have this style be permanent in your OpenSSL development
+;;; directory. To have that, please perform this:
+;;;
+;;; M-x add-dir-local-variable <RET> c-mode <RET> c-file-style <RET>
+;;; "OpenSSL-II" <RET>
+;;;
+;;; A new buffer with .dir-locals.el will appear. Save it (C-x C-s).
+;;;
+;;; Alternatively, have a look at dir-locals.example.el
+
+;;; For suggesting improvements, please send e-mail to levitte@openssl.org.
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Note, it could be easy to inherit from the "gnu" style... however,
+;; one never knows if that style will change somewhere in the future,
+;; so I've chosen to copy the "gnu" style values explicitely instead
+;; and mark them with a comment. // RLevitte 2015-08-31
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(c-add-style "OpenSSL-II"
+ '((c-basic-offset . 4)
+ (indent-tabs-mode . nil)
+ (fill-column . 78)
+ (comment-column . 33)
+ (c-comment-only-line-offset 0 . 0) ; From "gnu" style
+ (c-hanging-braces-alist ; From "gnu" style
+ (substatement-open before after) ; From "gnu" style
+ (arglist-cont-nonempty)) ; From "gnu" style
+ (c-offsets-alist
+ (statement-block-intro . +) ; From "gnu" style
+ (knr-argdecl-intro . 0)
+ (knr-argdecl . 0)
+ (substatement-open . +) ; From "gnu" style
+ (substatement-label . 0) ; From "gnu" style
+ (label . 1)
+ (statement-case-open . +) ; From "gnu" style
+ (statement-cont . +) ; From "gnu" style
+ (arglist-intro . c-lineup-arglist-intro-after-paren) ; From "gnu" style
+ (arglist-close . c-lineup-arglist) ; From "gnu" style
+ (inline-open . 0) ; From "gnu" style
+ (brace-list-open . +) ; From "gnu" style
+ (topmost-intro-cont first c-lineup-topmost-intro-cont
+ c-lineup-gnu-DEFUN-intro-cont) ; From "gnu" style
+ )
+ (c-special-indent-hook . c-gnu-impose-minimum) ; From "gnu" style
+ (c-block-comment-prefix . "* ")
+ ))
diff --git a/doc/openssl_button.gif b/doc/openssl_button.gif
deleted file mode 100644
index 3d3c90c9f849..000000000000
--- a/doc/openssl_button.gif
+++ /dev/null
Binary files differ
diff --git a/doc/openssl_button.html b/doc/openssl_button.html
deleted file mode 100644
index 44c91bd3d068..000000000000
--- a/doc/openssl_button.html
+++ /dev/null
@@ -1,7 +0,0 @@
-
-<!-- the `Includes OpenSSL Cryptogaphy Software' button -->
-<!-- freely usable by any application linked against OpenSSL -->
-<a href="http://www.openssl.org/">
-<img src="openssl_button.gif"
- width=102 height=47 border=0></a>
-
diff --git a/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/doc/ssl/SSL_CTX_add_extra_chain_cert.pod
index 8e832a57eaac..04300fbe6f3f 100644
--- a/doc/ssl/SSL_CTX_add_extra_chain_cert.pod
+++ b/doc/ssl/SSL_CTX_add_extra_chain_cert.pod
@@ -2,29 +2,39 @@
=head1 NAME
-SSL_CTX_add_extra_chain_cert - add certificate to chain
+SSL_CTX_add_extra_chain_cert, SSL_CTX_clear_extra_chain_certs - add or clear
+extra chain certificates
=head1 SYNOPSIS
#include <openssl/ssl.h>
- long SSL_CTX_add_extra_chain_cert(SSL_CTX ctx, X509 *x509)
+ long SSL_CTX_add_extra_chain_cert(SSL_CTX *ctx, X509 *x509);
+ long SSL_CTX_clear_extra_chain_certs(SSL_CTX *ctx);
=head1 DESCRIPTION
-SSL_CTX_add_extra_chain_cert() adds the certificate B<x509> to the certificate
-chain presented together with the certificate. Several certificates
-can be added one after the other.
+SSL_CTX_add_extra_chain_cert() adds the certificate B<x509> to the extra chain
+certificates associated with B<ctx>. Several certificates can be added one
+after another.
+
+SSL_CTX_clear_extra_chain_certs() clears all extra chain certificates
+associated with B<ctx>.
+
+These functions are implemented as macros.
=head1 NOTES
-When constructing the certificate chain, the chain will be formed from
-these certificates explicitly specified. If no chain is specified,
-the library will try to complete the chain from the available CA
-certificates in the trusted CA storage, see
+When sending a certificate chain, extra chain certificates are sent in order
+following the end entity certificate.
+
+If no chain is specified, the library will try to complete the chain from the
+available CA certificates in the trusted CA storage, see
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>.
-The B<x509> certificate provided to SSL_CTX_add_extra_chain_cert() will be freed by the library when the B<SSL_CTX> is destroyed. An application B<should not> free the B<x509> object.
+The B<x509> certificate provided to SSL_CTX_add_extra_chain_cert() will be
+freed by the library when the B<SSL_CTX> is destroyed. An application
+B<should not> free the B<x509> object.
=head1 RESTRICTIONS
@@ -37,8 +47,9 @@ be used instead.
=head1 RETURN VALUES
-SSL_CTX_add_extra_chain_cert() returns 1 on success. Check out the
-error stack to find out the reason for failure otherwise.
+SSL_CTX_add_extra_chain_cert() and SSL_CTX_clear_extra_chain_certs() return
+1 on success and 0 for failure. Check out the error stack to find out the
+reason for failure.
=head1 SEE ALSO
diff --git a/doc/ssl/SSL_CTX_get0_param.pod b/doc/ssl/SSL_CTX_get0_param.pod
index 332f181187a8..ba16b50f0879 100644
--- a/doc/ssl/SSL_CTX_get0_param.pod
+++ b/doc/ssl/SSL_CTX_get0_param.pod
@@ -34,7 +34,7 @@ them to suit its needs: for example to add a hostname check.
Check hostname matches "www.foo.com" in peer certificate:
X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl);
- X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com");
+ X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0);
=head1 RETURN VALUES
diff --git a/doc/ssl/SSL_check_chain.pod b/doc/ssl/SSL_check_chain.pod
new file mode 100644
index 000000000000..d3b7601909e4
--- /dev/null
+++ b/doc/ssl/SSL_check_chain.pod
@@ -0,0 +1,85 @@
+=pod
+
+=head1 NAME
+
+SSL_check_chain - check certificate chain suitability
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ int SSL_check_chain(SSL *s, X509 *x, EVP_PKEY *pk, STACK_OF(X509) *chain);
+
+=head1 DESCRIPTION
+
+SSL_check_chain() checks whether certificate B<x>, private key B<pk> and
+certificate chain B<chain> is suitable for use with the current session
+B<s>.
+
+=head1 RETURN VALUES
+
+SSL_check_chain() returns a bitmap of flags indicating the validity of the
+chain.
+
+B<CERT_PKEY_VALID>: the chain can be used with the current session.
+If this flag is B<not> set then the certificate will never be used even
+if the application tries to set it because it is inconsistent with the
+peer preferences.
+
+B<CERT_PKEY_SIGN>: the EE key can be used for signing.
+
+B<CERT_PKEY_EE_SIGNATURE>: the signature algorithm of the EE certificate is
+acceptable.
+
+B<CERT_PKEY_CA_SIGNATURE>: the signature algorithms of all CA certificates
+are acceptable.
+
+B<CERT_PKEY_EE_PARAM>: the parameters of the end entity certificate are
+acceptable (e.g. it is a supported curve).
+
+B<CERT_PKEY_CA_PARAM>: the parameters of all CA certificates are acceptable.
+
+B<CERT_PKEY_EXPLICIT_SIGN>: the end entity certificate algorithm
+can be used explicitly for signing (i.e. it is mentioned in the signature
+algorithms extension).
+
+B<CERT_PKEY_ISSUER_NAME>: the issuer name is acceptable. This is only
+meaningful for client authentication.
+
+B<CERT_PKEY_CERT_TYPE>: the certificate type is acceptable. Only meaningful
+for client authentication.
+
+B<CERT_PKEY_SUITEB>: chain is suitable for Suite B use.
+
+=head1 NOTES
+
+SSL_check_chain() must be called in servers after a client hello message or in
+clients after a certificate request message. It will typically be called
+in the certificate callback.
+
+An application wishing to support multiple certificate chains may call this
+function on each chain in turn: starting with the one it considers the
+most secure. It could then use the chain of the first set which returns
+suitable flags.
+
+As a minimum the flag B<CERT_PKEY_VALID> must be set for a chain to be
+usable. An application supporting multiple chains with different CA signature
+algorithms may also wish to check B<CERT_PKEY_CA_SIGNATURE> too. If no
+chain is suitable a server should fall back to the most secure chain which
+sets B<CERT_PKEY_VALID>.
+
+The validity of a chain is determined by checking if it matches a supported
+signature algorithm, supported curves and in the case of client authentication
+certificate types and issuer names.
+
+Since the supported signature algorithms extension is only used in TLS 1.2
+and DTLS 1.2 the results for earlier versions of TLS and DTLS may not be
+very useful. Applications may wish to specify a different "legacy" chain
+for earlier versions of TLS or DTLS.
+
+=head1 SEE ALSO
+
+L<SSL_CTX_set_cert_cb(3)|SSL_CTX_set_cert_cb(3)>,
+L<ssl(3)|ssl(3)>
+
+=cut