aboutsummaryrefslogtreecommitdiffstats
path: root/doc/man3
diff options
context:
space:
mode:
authorJung-uk Kim <jkim@FreeBSD.org>2018-11-20 18:59:41 +0000
committerJung-uk Kim <jkim@FreeBSD.org>2018-11-20 18:59:41 +0000
commit8c3f9abd70b3f447a4795c1b00b386b044fb322d (patch)
tree884976f2693f42bade35b92edc3c1f7f8c53825b /doc/man3
parenta43ce912fc025d11e1395506111f75fc194d7ba5 (diff)
downloadsrc-8c3f9abd70b3f447a4795c1b00b386b044fb322d.tar.gz
src-8c3f9abd70b3f447a4795c1b00b386b044fb322d.zip
Import OpenSSL 1.1.1a.vendor/openssl/1.1.1a
Notes
Notes: svn path=/vendor-crypto/openssl/dist/; revision=340690 svn path=/vendor-crypto/openssl/1.1.1a/; revision=340691; tag=vendor/openssl/1.1.1a
Diffstat (limited to 'doc/man3')
-rw-r--r--doc/man3/DES_random_key.pod28
-rw-r--r--doc/man3/EVP_DigestInit.pod5
-rw-r--r--doc/man3/EVP_PKEY_CTX_ctrl.pod283
-rw-r--r--doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod4
-rw-r--r--doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod4
-rw-r--r--doc/man3/EVP_PKEY_set1_RSA.pod35
-rw-r--r--doc/man3/EVP_aes.pod8
-rw-r--r--doc/man3/EVP_aria.pod8
-rw-r--r--doc/man3/EVP_bf_cbc.pod5
-rw-r--r--doc/man3/EVP_camellia.pod8
-rw-r--r--doc/man3/EVP_cast5_cbc.pod5
-rw-r--r--doc/man3/EVP_des.pod32
-rw-r--r--doc/man3/EVP_idea_cbc.pod5
-rw-r--r--doc/man3/EVP_md5.pod4
-rw-r--r--doc/man3/EVP_rc2_cbc.pod5
-rw-r--r--doc/man3/EVP_rc5_32_12_16_cbc.pod5
-rw-r--r--doc/man3/EVP_seed_cbc.pod5
-rw-r--r--doc/man3/EVP_sm4_cbc.pod3
-rw-r--r--doc/man3/OPENSSL_VERSION_NUMBER.pod7
-rw-r--r--doc/man3/RSA_meth_new.pod4
-rw-r--r--doc/man3/SSL_CTX_set0_CA_list.pod148
-rw-r--r--doc/man3/SSL_CTX_set1_curves.pod5
-rw-r--r--doc/man3/SSL_CTX_set_client_CA_list.pod103
-rw-r--r--doc/man3/SSL_CTX_set_quiet_shutdown.pod6
-rw-r--r--doc/man3/SSL_get_client_CA_list.pod62
-rw-r--r--doc/man3/SSL_get_error.pod2
-rw-r--r--doc/man3/SSL_get_peer_signature_nid.pod12
-rw-r--r--doc/man3/SSL_get_peer_tmp_key.pod53
-rw-r--r--doc/man3/SSL_get_server_tmp_key.pod43
-rw-r--r--doc/man3/SSL_set_bio.pod4
-rw-r--r--doc/man3/SSL_set_shutdown.pod10
-rw-r--r--doc/man3/SSL_shutdown.pod78
32 files changed, 630 insertions, 359 deletions
diff --git a/doc/man3/DES_random_key.pod b/doc/man3/DES_random_key.pod
index f543bea1ee7b..6e0394d637b2 100644
--- a/doc/man3/DES_random_key.pod
+++ b/doc/man3/DES_random_key.pod
@@ -99,7 +99,7 @@ algorithm.
There are two phases to the use of DES encryption. The first is the
generation of a I<DES_key_schedule> from a key, the second is the
-actual encryption. A DES key is of type I<DES_cblock>. This type is
+actual encryption. A DES key is of type I<DES_cblock>. This type
consists of 8 bytes with odd parity. The least significant bit in
each byte is the parity bit. The key schedule is an expanded form of
the key; it is used to speed the encryption process.
@@ -170,42 +170,42 @@ of 24 bytes. This is much better than CBC DES.
DES_ede3_cbc_encrypt() implements outer triple CBC DES encryption with
three keys. This means that each DES operation inside the CBC mode is
-an C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL.
+C<C=E(ks3,D(ks2,E(ks1,M)))>. This mode is used by SSL.
The DES_ede2_cbc_encrypt() macro implements two-key Triple-DES by
reusing I<ks1> for the final encryption. C<C=E(ks1,D(ks2,E(ks1,M)))>.
This form of Triple-DES is used by the RSAREF library.
-DES_pcbc_encrypt() encrypt/decrypts using the propagating cipher block
+DES_pcbc_encrypt() encrypts/decrypts using the propagating cipher block
chaining mode used by Kerberos v4. Its parameters are the same as
DES_ncbc_encrypt().
-DES_cfb_encrypt() encrypt/decrypts using cipher feedback mode. This
-method takes an array of characters as input and outputs and array of
+DES_cfb_encrypt() encrypts/decrypts using cipher feedback mode. This
+method takes an array of characters as input and outputs an array of
characters. It does not require any padding to 8 character groups.
Note: the I<ivec> variable is changed and the new changed value needs to
be passed to the next call to this function. Since this function runs
a complete DES ECB encryption per I<numbits>, this function is only
-suggested for use when sending small numbers of characters.
+suggested for use when sending a small number of characters.
DES_cfb64_encrypt()
-implements CFB mode of DES with 64bit feedback. Why is this
+implements CFB mode of DES with 64-bit feedback. Why is this
useful you ask? Because this routine will allow you to encrypt an
-arbitrary number of bytes, no 8 byte padding. Each call to this
+arbitrary number of bytes, without 8 byte padding. Each call to this
routine will encrypt the input bytes to output and then update ivec
and num. num contains 'how far' we are though ivec. If this does
-not make much sense, read more about cfb mode of DES :-).
+not make much sense, read more about CFB mode of DES.
DES_ede3_cfb64_encrypt() and DES_ede2_cfb64_encrypt() is the same as
DES_cfb64_encrypt() except that Triple-DES is used.
DES_ofb_encrypt() encrypts using output feedback mode. This method
-takes an array of characters as input and outputs and array of
+takes an array of characters as input and outputs an array of
characters. It does not require any padding to 8 character groups.
Note: the I<ivec> variable is changed and the new changed value needs to
be passed to the next call to this function. Since this function runs
-a complete DES ECB encryption per numbits, this function is only
-suggested for use when sending small numbers of characters.
+a complete DES ECB encryption per I<numbits>, this function is only
+suggested for use when sending a small number of characters.
DES_ofb64_encrypt() is the same as DES_cfb64_encrypt() using Output
Feed Back mode.
@@ -232,10 +232,10 @@ The following are DES-based transformations:
DES_fcrypt() is a fast version of the Unix crypt(3) function. This
version takes only a small amount of space relative to other fast
-crypt() implementations. This is different to the normal crypt in
+crypt() implementations. This is different to the normal crypt() in
that the third parameter is the buffer that the return value is
written into. It needs to be at least 14 bytes long. This function
-is thread safe, unlike the normal crypt.
+is thread safe, unlike the normal crypt().
DES_crypt() is a faster replacement for the normal system crypt().
This function calls DES_fcrypt() with a static array passed as the
diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index 0fedd17ce6c6..5ecbcc5e8992 100644
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -310,16 +310,17 @@ This example digests the data "Test Message\n" and "Hello World\n", using the
digest name passed on the command line.
#include <stdio.h>
+ #include <string.h>
#include <openssl/evp.h>
- main(int argc, char *argv[])
+ int main(int argc, char *argv[])
{
EVP_MD_CTX *mdctx;
const EVP_MD *md;
char mess1[] = "Test Message\n";
char mess2[] = "Hello World\n";
unsigned char md_value[EVP_MAX_MD_SIZE];
- int md_len, i;
+ unsigned int md_len, i;
if (argv[1] == NULL) {
printf("Usage: mdtest digestname\n");
diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod
index e1a107c06e3c..4982e9205305 100644
--- a/doc/man3/EVP_PKEY_CTX_ctrl.pod
+++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod
@@ -4,20 +4,55 @@
EVP_PKEY_CTX_ctrl,
EVP_PKEY_CTX_ctrl_str,
+EVP_PKEY_CTX_ctrl_uint64,
+EVP_PKEY_CTX_md,
EVP_PKEY_CTX_set_signature_md,
EVP_PKEY_CTX_get_signature_md,
EVP_PKEY_CTX_set_mac_key,
EVP_PKEY_CTX_set_rsa_padding,
+EVP_PKEY_CTX_get_rsa_padding,
EVP_PKEY_CTX_set_rsa_pss_saltlen,
+EVP_PKEY_CTX_get_rsa_pss_saltlen,
EVP_PKEY_CTX_set_rsa_keygen_bits,
EVP_PKEY_CTX_set_rsa_keygen_pubexp,
+EVP_PKEY_CTX_set_rsa_keygen_primes,
+EVP_PKEY_CTX_set_rsa_mgf1_md,
+EVP_PKEY_CTX_get_rsa_mgf1_md,
+EVP_PKEY_CTX_set_rsa_oaep_md,
+EVP_PKEY_CTX_get_rsa_oaep_md,
+EVP_PKEY_CTX_set0_rsa_oaep_label,
+EVP_PKEY_CTX_get0_rsa_oaep_label,
EVP_PKEY_CTX_set_dsa_paramgen_bits,
EVP_PKEY_CTX_set_dh_paramgen_prime_len,
+EVP_PKEY_CTX_set_dh_paramgen_subprime_len,
EVP_PKEY_CTX_set_dh_paramgen_generator,
+EVP_PKEY_CTX_set_dh_paramgen_type,
+EVP_PKEY_CTX_set_dh_rfc5114,
+EVP_PKEY_CTX_set_dhx_rfc5114,
EVP_PKEY_CTX_set_dh_pad,
EVP_PKEY_CTX_set_dh_nid,
+EVP_PKEY_CTX_set_dh_kdf_type,
+EVP_PKEY_CTX_get_dh_kdf_type,
+EVP_PKEY_CTX_set0_dh_kdf_oid,
+EVP_PKEY_CTX_get0_dh_kdf_oid,
+EVP_PKEY_CTX_set_dh_kdf_md,
+EVP_PKEY_CTX_get_dh_kdf_md,
+EVP_PKEY_CTX_set_dh_kdf_outlen,
+EVP_PKEY_CTX_get_dh_kdf_outlen,
+EVP_PKEY_CTX_set0_dh_kdf_ukm,
+EVP_PKEY_CTX_get0_dh_kdf_ukm,
EVP_PKEY_CTX_set_ec_paramgen_curve_nid,
EVP_PKEY_CTX_set_ec_param_enc,
+EVP_PKEY_CTX_set_ecdh_cofactor_mode,
+EVP_PKEY_CTX_get_ecdh_cofactor_mode,
+EVP_PKEY_CTX_set_ecdh_kdf_type,
+EVP_PKEY_CTX_get_ecdh_kdf_type,
+EVP_PKEY_CTX_set_ecdh_kdf_md,
+EVP_PKEY_CTX_get_ecdh_kdf_md,
+EVP_PKEY_CTX_set_ecdh_kdf_outlen,
+EVP_PKEY_CTX_get_ecdh_kdf_outlen,
+EVP_PKEY_CTX_set0_ecdh_kdf_ukm,
+EVP_PKEY_CTX_get0_ecdh_kdf_ukm,
EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
- algorithm specific control operations
@@ -27,9 +62,13 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype,
int cmd, int p1, void *p2);
+ int EVP_PKEY_CTX_ctrl_uint64(EVP_PKEY_CTX *ctx, int keytype, int optype,
+ int cmd, uint64_t value);
int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type,
const char *value);
+ int EVP_PKEY_CTX_md(EVP_PKEY_CTX *ctx, int optype, int cmd, const char *md);
+
int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd);
@@ -38,22 +77,58 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
#include <openssl/rsa.h>
int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad);
+ int EVP_PKEY_CTX_get_rsa_padding(EVP_PKEY_CTX *ctx, int *pad);
int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len);
+ int EVP_PKEY_CTX_get_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int *len);
int EVP_PKEY_CTX_set_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits);
int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp);
+ int EVP_PKEY_CTX_set_rsa_keygen_primes(EVP_PKEY_CTX *ctx, int primes);
+ int EVP_PKEY_CTX_set_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
+ int EVP_PKEY_CTX_get_rsa_mgf1_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
+ int EVP_PKEY_CTX_set_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
+ int EVP_PKEY_CTX_get_rsa_oaep_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
+ int EVP_PKEY_CTX_set0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char *label, int len);
+ int EVP_PKEY_CTX_get0_rsa_oaep_label(EVP_PKEY_CTX *ctx, unsigned char **label);
#include <openssl/dsa.h>
+
int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits);
#include <openssl/dh.h>
+
int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len);
+ int EVP_PKEY_CTX_set_dh_paramgen_subprime_len(EVP_PKEY_CTX *ctx, int len);
int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen);
+ int EVP_PKEY_CTX_set_dh_paramgen_type(EVP_PKEY_CTX *ctx, int type);
int EVP_PKEY_CTX_set_dh_pad(EVP_PKEY_CTX *ctx, int pad);
int EVP_PKEY_CTX_set_dh_nid(EVP_PKEY_CTX *ctx, int nid);
+ int EVP_PKEY_CTX_set_dh_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114);
+ int EVP_PKEY_CTX_set_dhx_rfc5114(EVP_PKEY_CTX *ctx, int rfc5114);
+ int EVP_PKEY_CTX_set_dh_kdf_type(EVP_PKEY_CTX *ctx, int kdf);
+ int EVP_PKEY_CTX_get_dh_kdf_type(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_CTX_set0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT *oid);
+ int EVP_PKEY_CTX_get0_dh_kdf_oid(EVP_PKEY_CTX *ctx, ASN1_OBJECT **oid);
+ int EVP_PKEY_CTX_set_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
+ int EVP_PKEY_CTX_get_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
+ int EVP_PKEY_CTX_set_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int len);
+ int EVP_PKEY_CTX_get_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len);
+ int EVP_PKEY_CTX_set0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len);
+ int EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);
#include <openssl/ec.h>
+
int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid);
int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc);
+ int EVP_PKEY_CTX_set_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx, int cofactor_mode);
+ int EVP_PKEY_CTX_get_ecdh_cofactor_mode(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_CTX_set_ecdh_kdf_type(EVP_PKEY_CTX *ctx, int kdf);
+ int EVP_PKEY_CTX_get_ecdh_kdf_type(EVP_PKEY_CTX *ctx);
+ int EVP_PKEY_CTX_set_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
+ int EVP_PKEY_CTX_get_ecdh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
+ int EVP_PKEY_CTX_set_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int len);
+ int EVP_PKEY_CTX_get_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len);
+ int EVP_PKEY_CTX_set0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len);
+ int EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);
int EVP_PKEY_CTX_set1_id(EVP_PKEY_CTX *ctx, void *id, size_t id_len);
int EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id);
@@ -73,6 +148,9 @@ and B<p2> is MAC key. This is used by Poly1305, SipHash, HMAC and CMAC.
Applications will not normally call EVP_PKEY_CTX_ctrl() directly but will
instead call one of the algorithm specific macros below.
+The function EVP_PKEY_CTX_ctrl_uint64() is a wrapper that directly passes a
+uint64 value as B<p2> to EVP_PKEY_CTX_ctrl().
+
The function EVP_PKEY_CTX_ctrl_str() allows an application to send an algorithm
specific control operation to a context B<ctx> in string form. This is
intended to be used for options specified on the command line or in text
@@ -80,6 +158,9 @@ files. The commands supported are documented in the openssl utility
command line pages for the option B<-pkeyopt> which is supported by the
B<pkeyutl>, B<genpkey> and B<req> commands.
+The function EVP_PKEY_CTX_md() sends a message digest control operation
+to the context B<ctx>. The message digest is specified by its name B<md>.
+
All the remaining "functions" are implemented as macros.
The EVP_PKEY_CTX_set_signature_md() macro sets the message digest type used
@@ -99,12 +180,14 @@ L<EVP_PKEY_new_raw_private_key(3)> or similar functions instead of this macro.
The EVP_PKEY_CTX_set_mac_key() macro can be used with any of the algorithms
supported by the L<EVP_PKEY_new_raw_private_key(3)> function.
-The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B<ctx>.
-The B<pad> parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding,
-RSA_SSLV23_PADDING for SSLv23 padding, RSA_NO_PADDING for no padding,
-RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only),
-RSA_X931_PADDING for X9.31 padding (signature operations only) and
-RSA_PKCS1_PSS_PADDING (sign and verify only).
+=head2 RSA parameters
+
+The EVP_PKEY_CTX_set_rsa_padding() macro sets the RSA padding mode for B<ctx>.
+The B<pad> parameter can take the value B<RSA_PKCS1_PADDING> for PKCS#1
+padding, B<RSA_SSLV23_PADDING> for SSLv23 padding, B<RSA_NO_PADDING> for
+no padding, B<RSA_PKCS1_OAEP_PADDING> for OAEP padding (encrypt and
+decrypt only), B<RSA_X931_PADDING> for X9.31 padding (signature operations
+only) and B<RSA_PKCS1_PSS_PADDING> (sign and verify only).
Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md()
is used. If this macro is called for PKCS#1 padding the plaintext buffer is
@@ -116,41 +199,154 @@ padding for RSA the algorithm identifier byte is added or checked and removed
if this control is called. If it is not called then the first byte of the plaintext
buffer is expected to be the algorithm identifier byte.
+The EVP_PKEY_CTX_get_rsa_padding() macro gets the RSA padding mode for B<ctx>.
+
The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to
-B<len> as its name implies it is only supported for PSS padding. Three special
-values are supported: RSA_PSS_SALTLEN_DIGEST sets the salt length to the
-digest length, RSA_PSS_SALTLEN_MAX sets the salt length to the maximum
-permissible value. When verifying RSA_PSS_SALTLEN_AUTO causes the salt length
+B<len>. As its name implies it is only supported for PSS padding. Three special
+values are supported: B<RSA_PSS_SALTLEN_DIGEST> sets the salt length to the
+digest length, B<RSA_PSS_SALTLEN_MAX> sets the salt length to the maximum
+permissible value. When verifying B<RSA_PSS_SALTLEN_AUTO> causes the salt length
to be automatically determined based on the B<PSS> block structure. If this
macro is not called maximum salt length is used when signing and auto detection
when verifying is used by default.
+The EVP_PKEY_CTX_get_rsa_pss_saltlen() macro gets the RSA PSS salt length
+for B<ctx>. The padding mode must have been set to B<RSA_PKCS1_PSS_PADDING>.
+
The EVP_PKEY_CTX_set_rsa_keygen_bits() macro sets the RSA key length for
RSA key generation to B<bits>. If not specified 1024 bits is used.
The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value
-for RSA key generation to B<pubexp> currently it should be an odd integer. The
+for RSA key generation to B<pubexp>. Currently it should be an odd integer. The
B<pubexp> pointer is used internally by this function so it should not be
-modified or free after the call. If this macro is not called then 65537 is used.
+modified or freed after the call. If not specified 65537 is used.
+
+The EVP_PKEY_CTX_set_rsa_keygen_primes() macro sets the number of primes for
+RSA key generation to B<primes>. If not specified 2 is used.
+
+The EVP_PKEY_CTX_set_rsa_mgf1_md() macro sets the MGF1 digest for RSA padding
+schemes to B<md>. If not explicitly set the signing digest is used. The
+padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING>
+or B<RSA_PKCS1_PSS_PADDING>.
+
+The EVP_PKEY_CTX_get_rsa_mgf1_md() macro gets the MGF1 digest for B<ctx>.
+If not explicitly set the signing digest is used. The padding mode must have
+been set to B<RSA_PKCS1_OAEP_PADDING> or B<RSA_PKCS1_PSS_PADDING>.
+
+The EVP_PKEY_CTX_set_rsa_oaep_md() macro sets the message digest type used
+in RSA OAEP to B<md>. The padding mode must have been set to
+B<RSA_PKCS1_OAEP_PADDING>.
+
+The EVP_PKEY_CTX_get_rsa_oaep_md() macro gets the message digest type used
+in RSA OAEP to B<md>. The padding mode must have been set to
+B<RSA_PKCS1_OAEP_PADDING>.
+
+The EVP_PKEY_CTX_set0_rsa_oaep_label() macro sets the RSA OAEP label to
+B<label> and its length to B<len>. If B<label> is NULL or B<len> is 0,
+the label is cleared. The library takes ownership of the label so the
+caller should not free the original memory pointed to by B<label>.
+The padding mode must have been set to B<RSA_PKCS1_OAEP_PADDING>.
+
+The EVP_PKEY_CTX_get0_rsa_oaep_label() macro gets the RSA OAEP label to
+B<label>. The return value is the label length. The padding mode
+must have been set to B<RSA_PKCS1_OAEP_PADDING>. The resulting pointer is owned
+by the library and should not be freed by the caller.
+
+=head2 DSA parameters
-The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used
+The EVP_PKEY_CTX_set_dsa_paramgen_bits() macro sets the number of bits used
for DSA parameter generation to B<bits>. If not specified 1024 is used.
-The macro EVP_PKEY_CTX_set_dh_paramgen_prime_len() sets the length of the DH
+=head2 DH parameters
+
+The EVP_PKEY_CTX_set_dh_paramgen_prime_len() macro sets the length of the DH
prime parameter B<p> for DH parameter generation. If this macro is not called
-then 1024 is used.
+then 1024 is used. Only accepts lengths greater than or equal to 256.
+
+The EVP_PKEY_CTX_set_dh_paramgen_subprime_len() macro sets the length of the DH
+optional subprime parameter B<q> for DH parameter generation. The default is
+256 if the prime is at least 2048 bits long or 160 otherwise. The DH
+paramgen type must have been set to x9.42.
The EVP_PKEY_CTX_set_dh_paramgen_generator() macro sets DH generator to B<gen>
for DH parameter generation. If not specified 2 is used.
+The EVP_PKEY_CTX_set_dh_paramgen_type() macro sets the key type for DH
+parameter generation. Use 0 for PKCS#3 DH and 1 for X9.42 DH.
+The default is 0.
+
The EVP_PKEY_CTX_set_dh_pad() macro sets the DH padding mode. If B<pad> is
1 the shared secret is padded with zeroes up to the size of the DH prime B<p>.
If B<pad> is zero (the default) then no padding is performed.
EVP_PKEY_CTX_set_dh_nid() sets the DH parameters to values corresponding to
-B<nid>. The B<nid> parameter must be B<NID_ffdhe2048>, B<NID_ffdhe3072>,
-B<NID_ffdhe4096>, B<NID_ffdhe6144> or B<NID_ffdhe8192>. This macro can be
-called during parameter or key generation.
+B<nid> as defined in RFC7919. The B<nid> parameter must be B<NID_ffdhe2048>,
+B<NID_ffdhe3072>, B<NID_ffdhe4096>, B<NID_ffdhe6144>, B<NID_ffdhe8192>
+or B<NID_undef> to clear the stored value. This macro can be called during
+parameter or key generation.
+The nid parameter and the rfc5114 parameter are mutually exclusive.
+
+The EVP_PKEY_CTX_set_dh_rfc5114() and EVP_PKEY_CTX_set_dhx_rfc5114() macros are
+synonymous. They set the DH parameters to the values defined in RFC5114. The
+B<rfc5114> parameter must be 1, 2 or 3 corresponding to RFC5114 sections
+2.1, 2.2 and 2.3. or 0 to clear the stored value. This macro can be called
+during parameter generation. The B<ctx> must have a key type of
+B<EVP_PKEY_DHX>.
+The rfc5114 parameter and the nid parameter are mutually exclusive.
+
+=head2 DH key derivation function parameters
+
+Note that all of the following functions require that the B<ctx> parameter has
+a private key type of B<EVP_PKEY_DHX>. When using key derivation, the output of
+EVP_PKEY_derive() is the output of the KDF instead of the DH shared secret.
+The KDF output is typically used as a Key Encryption Key (KEK) that in turn
+encrypts a Content Encryption Key (CEK).
+
+The EVP_PKEY_CTX_set_dh_kdf_type() macro sets the key derivation function type
+to B<kdf> for DH key derivation. Possible values are B<EVP_PKEY_DH_KDF_NONE>
+and B<EVP_PKEY_DH_KDF_X9_42> which uses the key derivation specified in RFC2631
+(based on the keying algorithm described in X9.42). When using key derivation,
+the B<kdf_oid>, B<kdf_md> and B<kdf_outlen> parameters must also be specified.
+
+The EVP_PKEY_CTX_get_dh_kdf_type() macro gets the key derivation function type
+for B<ctx> used for DH key derivation. Possible values are B<EVP_PKEY_DH_KDF_NONE>
+and B<EVP_PKEY_DH_KDF_X9_42>.
+
+The EVP_PKEY_CTX_set0_dh_kdf_oid() macro sets the key derivation function
+object identifier to B<oid> for DH key derivation. This OID should identify
+the algorithm to be used with the Content Encryption Key.
+The library takes ownership of the object identifier so the caller should not
+free the original memory pointed to by B<oid>.
+
+The EVP_PKEY_CTX_get0_dh_kdf_oid() macro gets the key derivation function oid
+for B<ctx> used for DH key derivation. The resulting pointer is owned by the
+library and should not be freed by the caller.
+
+The EVP_PKEY_CTX_set_dh_kdf_md() macro sets the key derivation function
+message digest to B<md> for DH key derivation. Note that RFC2631 specifies
+that this digest should be SHA1 but OpenSSL tolerates other digests.
+
+The EVP_PKEY_CTX_get_dh_kdf_md() macro gets the key derivation function
+message digest for B<ctx> used for DH key derivation.
+
+The EVP_PKEY_CTX_set_dh_kdf_outlen() macro sets the key derivation function
+output length to B<len> for DH key derivation.
+
+The EVP_PKEY_CTX_get_dh_kdf_outlen() macro gets the key derivation function
+output length for B<ctx> used for DH key derivation.
+
+The EVP_PKEY_CTX_set0_dh_kdf_ukm() macro sets the user key material to
+B<ukm> and its length to B<len> for DH key derivation. This parameter is optional
+and corresponds to the partyAInfo field in RFC2631 terms. The specification
+requires that it is 512 bits long but this is not enforced by OpenSSL.
+The library takes ownership of the user key material so the caller should not
+free the original memory pointed to by B<ukm>.
+
+The EVP_PKEY_CTX_get0_dh_kdf_ukm() macro gets the user key material for B<ctx>.
+The return value is the user key material length. The resulting pointer is owned
+by the library and should not be freed by the caller.
+
+=head2 EC parameters
The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter
generation to B<nid>. For EC parameter generation this macro must be called
@@ -158,7 +354,7 @@ or an error occurs because there is no default curve.
This function can also be called to set the curve explicitly when
generating an EC key.
-The EVP_PKEY_CTX_set_ec_param_enc() sets the EC parameter encoding to
+The EVP_PKEY_CTX_set_ec_param_enc() macro sets the EC parameter encoding to
B<param_enc> when generating EC parameters or an EC key. The encoding can be
B<OPENSSL_EC_EXPLICIT_CURVE> for explicit parameters (the default in versions
of OpenSSL before 1.1.0) or B<OPENSSL_EC_NAMED_CURVE> to use named curve form.
@@ -166,6 +362,53 @@ For maximum compatibility the named curve form should be used. Note: the
B<OPENSSL_EC_NAMED_CURVE> value was only added to OpenSSL 1.1.0; previous
versions should use 0 instead.
+=head2 ECDH parameters
+
+The EVP_PKEY_CTX_set_ecdh_cofactor_mode() macro sets the cofactor mode to
+B<cofactor_mode> for ECDH key derivation. Possible values are 1 to enable
+cofactor key derivation, 0 to disable it and -1 to clear the stored cofactor
+mode and fallback to the private key cofactor mode.
+
+The EVP_PKEY_CTX_get_ecdh_cofactor_mode() macro returns the cofactor mode for
+B<ctx> used for ECDH key derivation. Possible values are 1 when cofactor key
+derivation is enabled and 0 otherwise.
+
+=head2 ECDH key derivation function parameters
+
+The EVP_PKEY_CTX_set_ecdh_kdf_type() macro sets the key derivation function type
+to B<kdf> for ECDH key derivation. Possible values are B<EVP_PKEY_ECDH_KDF_NONE>
+and B<EVP_PKEY_ECDH_KDF_X9_63> which uses the key derivation specified in X9.63.
+When using key derivation, the B<kdf_md> and B<kdf_outlen> parameters must
+also be specified.
+
+The EVP_PKEY_CTX_get_ecdh_kdf_type() macro returns the key derivation function
+type for B<ctx> used for ECDH key derivation. Possible values are
+B<EVP_PKEY_ECDH_KDF_NONE> and B<EVP_PKEY_ECDH_KDF_X9_63>.
+
+The EVP_PKEY_CTX_set_ecdh_kdf_md() macro sets the key derivation function
+message digest to B<md> for ECDH key derivation. Note that X9.63 specifies
+that this digest should be SHA1 but OpenSSL tolerates other digests.
+
+The EVP_PKEY_CTX_get_ecdh_kdf_md() macro gets the key derivation function
+message digest for B<ctx> used for ECDH key derivation.
+
+The EVP_PKEY_CTX_set_ecdh_kdf_outlen() macro sets the key derivation function
+output length to B<len> for ECDH key derivation.
+
+The EVP_PKEY_CTX_get_ecdh_kdf_outlen() macro gets the key derivation function
+output length for B<ctx> used for ECDH key derivation.
+
+The EVP_PKEY_CTX_set0_ecdh_kdf_ukm() macro sets the user key material to B<ukm>
+for ECDH key derivation. This parameter is optional and corresponds to the
+shared info in X9.63 terms. The library takes ownership of the user key material
+so the caller should not free the original memory pointed to by B<ukm>.
+
+The EVP_PKEY_CTX_get0_ecdh_kdf_ukm() macro gets the user key material for B<ctx>.
+The return value is the user key material length. The resulting pointer is owned
+by the library and should not be freed by the caller.
+
+=head2 Other parameters
+
The EVP_PKEY_CTX_set1_id(), EVP_PKEY_CTX_get1_id() and EVP_PKEY_CTX_get1_id_len()
macros are used to manipulate the special identifier field for specific signature
algorithms such as SM2. The EVP_PKEY_CTX_set1_id() sets an ID pointed by B<id> with
@@ -191,7 +434,7 @@ L<EVP_PKEY_decrypt(3)>,
L<EVP_PKEY_sign(3)>,
L<EVP_PKEY_verify(3)>,
L<EVP_PKEY_verify_recover(3)>,
-L<EVP_PKEY_derive(3)>
+L<EVP_PKEY_derive(3)>,
L<EVP_PKEY_keygen(3)>
=head1 HISTORY
diff --git a/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod b/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
index 1433a50a6ffe..e8f19cfc9980 100644
--- a/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
+++ b/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
@@ -68,12 +68,12 @@ error occurs.
=back
-EVP_PKEY_set_hkdf_md() sets the message digest associated with the HKDF.
+EVP_PKEY_CTX_set_hkdf_md() sets the message digest associated with the HKDF.
EVP_PKEY_CTX_set1_hkdf_salt() sets the salt to B<saltlen> bytes of the
buffer B<salt>. Any existing value is replaced.
-EVP_PKEY_CTX_set_hkdf_key() sets the key to B<keylen> bytes of the buffer
+EVP_PKEY_CTX_set1_hkdf_key() sets the key to B<keylen> bytes of the buffer
B<key>. Any existing value is replaced.
EVP_PKEY_CTX_add1_hkdf_info() sets the info value to B<infolen> bytes of the
diff --git a/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod b/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod
index bd1193e24a5b..7578278a6cfc 100644
--- a/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod
+++ b/doc/man3/EVP_PKEY_CTX_set_rsa_pss_keygen_md.pod
@@ -32,7 +32,7 @@ The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro is used to set the salt length.
If the key has usage restrictions then an error is returned if an attempt is
made to set the salt length below the minimum value. It is otherwise similar
to the B<RSA> operation except detection of the salt length (using
-RSA_PSS_SALTLEN_AUTO is not supported for verification if the key has
+RSA_PSS_SALTLEN_AUTO) is not supported for verification if the key has
usage restrictions.
The EVP_PKEY_CTX_set_signature_md() and EVP_PKEY_CTX_set_rsa_mgf1_md() macros
@@ -43,7 +43,7 @@ similar to the B<RSA> versions.
=head2 Key Generation
-As with RSA key generation the EVP_PKEY_CTX_set_rsa_rsa_keygen_bits()
+As with RSA key generation the EVP_PKEY_CTX_set_rsa_keygen_bits()
and EVP_PKEY_CTX_set_rsa_keygen_pubexp() macros are supported for RSA-PSS:
they have exactly the same meaning as for the RSA algorithm.
diff --git a/doc/man3/EVP_PKEY_set1_RSA.pod b/doc/man3/EVP_PKEY_set1_RSA.pod
index 749c52c375af..d10fc59d8bcc 100644
--- a/doc/man3/EVP_PKEY_set1_RSA.pod
+++ b/doc/man3/EVP_PKEY_set1_RSA.pod
@@ -6,8 +6,10 @@ EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY,
EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY,
EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY,
EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH,
-EVP_PKEY_assign_EC_KEY, EVP_PKEY_get0_hmac, EVP_PKEY_type, EVP_PKEY_id,
-EVP_PKEY_base_id, EVP_PKEY_set_alias_type, EVP_PKEY_set1_engine - EVP_PKEY assignment functions
+EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH,
+EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash,
+EVP_PKEY_type, EVP_PKEY_id, EVP_PKEY_base_id, EVP_PKEY_set_alias_type,
+EVP_PKEY_set1_engine - EVP_PKEY assignment functions
=head1 SYNOPSIS
@@ -24,6 +26,8 @@ EVP_PKEY_base_id, EVP_PKEY_set_alias_type, EVP_PKEY_set1_engine - EVP_PKEY assig
EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);
const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len);
+ const unsigned char *EVP_PKEY_get0_poly1305(const EVP_PKEY *pkey, size_t *len);
+ const unsigned char *EVP_PKEY_get0_siphash(const EVP_PKEY *pkey, size_t *len);
RSA *EVP_PKEY_get0_RSA(EVP_PKEY *pkey);
DSA *EVP_PKEY_get0_DSA(EVP_PKEY *pkey);
DH *EVP_PKEY_get0_DH(EVP_PKEY *pkey);
@@ -33,6 +37,8 @@ EVP_PKEY_base_id, EVP_PKEY_set_alias_type, EVP_PKEY_set1_engine - EVP_PKEY assig
int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key);
int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key);
int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
+ int EVP_PKEY_assign_POLY1305(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
+ int EVP_PKEY_assign_SIPHASH(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
int EVP_PKEY_id(const EVP_PKEY *pkey);
int EVP_PKEY_base_id(const EVP_PKEY *pkey);
@@ -50,14 +56,15 @@ EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or
B<NULL> if the key is not of the correct type.
-EVP_PKEY_get0_hmac(), EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(),
-EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() also return the
-referenced key in B<pkey> or B<NULL> if the key is not of the
-correct type but the reference count of the returned key is
-B<not> incremented and so must not be freed up after use.
+EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(),
+EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH()
+and EVP_PKEY_get0_EC_KEY() also return the referenced key in B<pkey> or B<NULL>
+if the key is not of the correct type but the reference count of the
+returned key is B<not> incremented and so must not be freed up after use.
-EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
-and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key>
+EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(),
+EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() and
+EVP_PKEY_assign_SIPHASH() also set the referenced key to B<key>
however these use the supplied B<key> internally and so B<key>
will be freed when the parent B<pkey> is freed.
@@ -89,8 +96,9 @@ In accordance with the OpenSSL naming convention the key obtained
from or assigned to the B<pkey> using the B<1> functions must be
freed as well as B<pkey>.
-EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
-and EVP_PKEY_assign_EC_KEY() are implemented as macros.
+EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(),
+EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305()
+and EVP_PKEY_assign_SIPHASH() are implemented as macros.
Most applications wishing to know a key type will simply call
EVP_PKEY_base_id() and will not care about the actual type:
@@ -119,8 +127,9 @@ EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and
EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if
an error occurred.
-EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH()
-and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure.
+EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(),
+EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305()
+and EVP_PKEY_assign_SIPHASH() return 1 for success and 0 for failure.
EVP_PKEY_base_id(), EVP_PKEY_id() and EVP_PKEY_type() return a key
type or B<NID_undef> (equivalently B<EVP_PKEY_NONE>) on error.
diff --git a/doc/man3/EVP_aes.pod b/doc/man3/EVP_aes.pod
index 6a893993c6a8..4192a9ec369f 100644
--- a/doc/man3/EVP_aes.pod
+++ b/doc/man3/EVP_aes.pod
@@ -14,6 +14,9 @@ EVP_aes_256_cfb1,
EVP_aes_128_cfb8,
EVP_aes_192_cfb8,
EVP_aes_256_cfb8,
+EVP_aes_128_cfb128,
+EVP_aes_192_cfb128,
+EVP_aes_256_cfb128,
EVP_aes_128_ctr,
EVP_aes_192_ctr,
EVP_aes_256_ctr,
@@ -75,6 +78,9 @@ EVP_aes_256_cfb1(),
EVP_aes_128_cfb8(),
EVP_aes_192_cfb8(),
EVP_aes_256_cfb8(),
+EVP_aes_128_cfb128(),
+EVP_aes_192_cfb128(),
+EVP_aes_256_cfb128(),
EVP_aes_128_ctr(),
EVP_aes_192_ctr(),
EVP_aes_256_ctr(),
@@ -170,7 +176,7 @@ L<EVP_CIPHER_meth_new(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2018 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
diff --git a/doc/man3/EVP_aria.pod b/doc/man3/EVP_aria.pod
index 3b6ad3576ed1..fbb79187546c 100644
--- a/doc/man3/EVP_aria.pod
+++ b/doc/man3/EVP_aria.pod
@@ -14,6 +14,9 @@ EVP_aria_256_cfb1,
EVP_aria_128_cfb8,
EVP_aria_192_cfb8,
EVP_aria_256_cfb8,
+EVP_aria_128_cfb128,
+EVP_aria_192_cfb128,
+EVP_aria_256_cfb128,
EVP_aria_128_ctr,
EVP_aria_192_ctr,
EVP_aria_256_ctr,
@@ -60,6 +63,9 @@ EVP_aria_256_cfb1(),
EVP_aria_128_cfb8(),
EVP_aria_192_cfb8(),
EVP_aria_256_cfb8(),
+EVP_aria_128_cfb128(),
+EVP_aria_192_cfb128(),
+EVP_aria_256_cfb128(),
EVP_aria_128_ctr(),
EVP_aria_192_ctr(),
EVP_aria_256_ctr(),
@@ -100,7 +106,7 @@ L<EVP_CIPHER_meth_new(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2018 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
diff --git a/doc/man3/EVP_bf_cbc.pod b/doc/man3/EVP_bf_cbc.pod
index 4a9d3a9f5e76..505d41b4943f 100644
--- a/doc/man3/EVP_bf_cbc.pod
+++ b/doc/man3/EVP_bf_cbc.pod
@@ -4,6 +4,7 @@
EVP_bf_cbc,
EVP_bf_cfb,
+EVP_bf_cfb64,
EVP_bf_ecb,
EVP_bf_ofb
- EVP Blowfish cipher
@@ -14,6 +15,7 @@ EVP_bf_ofb
const EVP_CIPHER *EVP_bf_cbc(void)
const EVP_CIPHER *EVP_bf_cfb(void)
+ const EVP_CIPHER *EVP_bf_cfb64(void)
const EVP_CIPHER *EVP_bf_ecb(void)
const EVP_CIPHER *EVP_bf_ofb(void)
@@ -27,6 +29,7 @@ This is a variable key length cipher.
=item EVP_bf_cbc(),
EVP_bf_cfb(),
+EVP_bf_cfb64(),
EVP_bf_ecb(),
EVP_bf_ofb()
@@ -48,7 +51,7 @@ L<EVP_CIPHER_meth_new(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2018 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
diff --git a/doc/man3/EVP_camellia.pod b/doc/man3/EVP_camellia.pod
index 75602cf64573..6ad59f84b110 100644
--- a/doc/man3/EVP_camellia.pod
+++ b/doc/man3/EVP_camellia.pod
@@ -14,6 +14,9 @@ EVP_camellia_256_cfb1,
EVP_camellia_128_cfb8,
EVP_camellia_192_cfb8,
EVP_camellia_256_cfb8,
+EVP_camellia_128_cfb128,
+EVP_camellia_192_cfb128,
+EVP_camellia_256_cfb128,
EVP_camellia_128_ctr,
EVP_camellia_192_ctr,
EVP_camellia_256_ctr,
@@ -54,6 +57,9 @@ EVP_camellia_256_cfb1(),
EVP_camellia_128_cfb8(),
EVP_camellia_192_cfb8(),
EVP_camellia_256_cfb8(),
+EVP_camellia_128_cfb128(),
+EVP_camellia_192_cfb128(),
+EVP_camellia_256_cfb128(),
EVP_camellia_128_ctr(),
EVP_camellia_192_ctr(),
EVP_camellia_256_ctr(),
@@ -83,7 +89,7 @@ L<EVP_CIPHER_meth_new(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2018 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
diff --git a/doc/man3/EVP_cast5_cbc.pod b/doc/man3/EVP_cast5_cbc.pod
index 01c38414698b..0be07279259f 100644
--- a/doc/man3/EVP_cast5_cbc.pod
+++ b/doc/man3/EVP_cast5_cbc.pod
@@ -4,6 +4,7 @@
EVP_cast5_cbc,
EVP_cast5_cfb,
+EVP_cast5_cfb64,
EVP_cast5_ecb,
EVP_cast5_ofb
- EVP CAST cipher
@@ -14,6 +15,7 @@ EVP_cast5_ofb
const EVP_CIPHER *EVP_cast5_cbc(void)
const EVP_CIPHER *EVP_cast5_cfb(void)
+ const EVP_CIPHER *EVP_cast5_cfb64(void)
const EVP_CIPHER *EVP_cast5_ecb(void)
const EVP_CIPHER *EVP_cast5_ofb(void)
@@ -28,6 +30,7 @@ This is a variable key length cipher.
=item EVP_cast5_cbc(),
EVP_cast5_ecb(),
EVP_cast5_cfb(),
+EVP_cast5_cfb64(),
EVP_cast5_ofb()
CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively.
@@ -48,7 +51,7 @@ L<EVP_CIPHER_meth_new(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2018 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
diff --git a/doc/man3/EVP_des.pod b/doc/man3/EVP_des.pod
index 836c399c849e..a05149ff8586 100644
--- a/doc/man3/EVP_des.pod
+++ b/doc/man3/EVP_des.pod
@@ -6,19 +6,24 @@ EVP_des_cbc,
EVP_des_cfb,
EVP_des_cfb1,
EVP_des_cfb8,
+EVP_des_cfb64,
EVP_des_ecb,
+EVP_des_ofb,
EVP_des_ede,
+EVP_des_ede_cbc,
EVP_des_ede_cfb,
+EVP_des_ede_cfb64,
+EVP_des_ede_ecb,
EVP_des_ede_ofb,
-EVP_des_ofb,
EVP_des_ede3,
EVP_des_ede3_cbc,
EVP_des_ede3_cfb,
EVP_des_ede3_cfb1,
EVP_des_ede3_cfb8,
+EVP_des_ede3_cfb64,
+EVP_des_ede3_ecb,
EVP_des_ede3_ofb,
-EVP_des_ede3_wrap,
-EVP_des_ede_cbc
+EVP_des_ede3_wrap
- EVP DES cipher
=head1 SYNOPSIS
@@ -43,27 +48,32 @@ EVP_des_ecb(),
EVP_des_cfb(),
EVP_des_cfb1(),
EVP_des_cfb8(),
+EVP_des_cfb64(),
EVP_des_ofb()
-DES in CBC, ECB, CFB with 128-bit shift, CFB with 1-bit shift, CFB with 8-bit
-shift and OFB modes respectively.
+DES in CBC, ECB, CFB with 64-bit shift, CFB with 1-bit shift, CFB with 8-bit
+shift and OFB modes.
=item EVP_des_ede(),
EVP_des_ede_cbc(),
-EVP_des_ede_ofb(),
-EVP_des_ede_cfb()
+EVP_des_ede_cfb(),
+EVP_des_ede_cfb64(),
+EVP_des_ede_ecb(),
+EVP_des_ede_ofb()
-Two key triple DES in ECB, CBC, CFB and OFB modes respectively.
+Two key triple DES in ECB, CBC, CFB with 64-bit shift and OFB modes.
=item EVP_des_ede3(),
EVP_des_ede3_cbc(),
EVP_des_ede3_cfb(),
EVP_des_ede3_cfb1(),
EVP_des_ede3_cfb8(),
+EVP_des_ede3_cfb64(),
+EVP_des_ede3_ecb(),
EVP_des_ede3_ofb()
-Three-key triple DES in ECB, CBC, CFB with 128-bit shift, CFB with 1-bit shift,
-CFB with 8-bit shift and OFB modes respectively.
+Three-key triple DES in ECB, CBC, CFB with 64-bit shift, CFB with 1-bit shift,
+CFB with 8-bit shift and OFB modes.
=item EVP_des_ede3_wrap()
@@ -85,7 +95,7 @@ L<EVP_CIPHER_meth_new(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2018 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
diff --git a/doc/man3/EVP_idea_cbc.pod b/doc/man3/EVP_idea_cbc.pod
index ace79885e9a3..14dcc903b525 100644
--- a/doc/man3/EVP_idea_cbc.pod
+++ b/doc/man3/EVP_idea_cbc.pod
@@ -4,6 +4,7 @@
EVP_idea_cbc,
EVP_idea_cfb,
+EVP_idea_cfb64,
EVP_idea_ecb,
EVP_idea_ofb
- EVP IDEA cipher
@@ -14,6 +15,7 @@ EVP_idea_ofb
const EVP_CIPHER *EVP_idea_cbc(void)
const EVP_CIPHER *EVP_idea_cfb(void)
+ const EVP_CIPHER *EVP_idea_cfb64(void)
const EVP_CIPHER *EVP_idea_ecb(void)
const EVP_CIPHER *EVP_idea_ofb(void)
@@ -25,6 +27,7 @@ The IDEA encryption algorithm for EVP.
=item EVP_idea_cbc(),
EVP_idea_cfb(),
+EVP_idea_cfb64(),
EVP_idea_ecb(),
EVP_idea_ofb()
@@ -46,7 +49,7 @@ L<EVP_CIPHER_meth_new(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2018 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
diff --git a/doc/man3/EVP_md5.pod b/doc/man3/EVP_md5.pod
index 8101143b54ec..725fcbf5e227 100644
--- a/doc/man3/EVP_md5.pod
+++ b/doc/man3/EVP_md5.pod
@@ -2,7 +2,8 @@
=head1 NAME
-EVP_md5
+EVP_md5,
+EVP_md5_sha1
- MD5 For EVP
=head1 SYNOPSIS
@@ -10,6 +11,7 @@ EVP_md5
#include <openssl/evp.h>
const EVP_MD *EVP_md5(void);
+ const EVP_MD *EVP_md5_sha1(void);
=head1 DESCRIPTION
diff --git a/doc/man3/EVP_rc2_cbc.pod b/doc/man3/EVP_rc2_cbc.pod
index 0958e930537e..79769b82635a 100644
--- a/doc/man3/EVP_rc2_cbc.pod
+++ b/doc/man3/EVP_rc2_cbc.pod
@@ -4,6 +4,7 @@
EVP_rc2_cbc,
EVP_rc2_cfb,
+EVP_rc2_cfb64,
EVP_rc2_ecb,
EVP_rc2_ofb,
EVP_rc2_40_cbc,
@@ -16,6 +17,7 @@ EVP_rc2_64_cbc
const EVP_CIPHER *EVP_rc2_cbc(void)
const EVP_CIPHER *EVP_rc2_cfb(void)
+ const EVP_CIPHER *EVP_rc2_cfb64(void)
const EVP_CIPHER *EVP_rc2_ecb(void)
const EVP_CIPHER *EVP_rc2_ofb(void)
const EVP_CIPHER *EVP_rc2_40_cbc(void)
@@ -29,6 +31,7 @@ The RC2 encryption algorithm for EVP.
=item EVP_rc2_cbc(),
EVP_rc2_cfb(),
+EVP_rc2_cfb64(),
EVP_rc2_ecb(),
EVP_rc2_ofb()
@@ -62,7 +65,7 @@ L<EVP_CIPHER_meth_new(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2018 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
diff --git a/doc/man3/EVP_rc5_32_12_16_cbc.pod b/doc/man3/EVP_rc5_32_12_16_cbc.pod
index 56175e99c44b..442a114ea9ce 100644
--- a/doc/man3/EVP_rc5_32_12_16_cbc.pod
+++ b/doc/man3/EVP_rc5_32_12_16_cbc.pod
@@ -4,6 +4,7 @@
EVP_rc5_32_12_16_cbc,
EVP_rc5_32_12_16_cfb,
+EVP_rc5_32_12_16_cfb64,
EVP_rc5_32_12_16_ecb,
EVP_rc5_32_12_16_ofb
- EVP RC5 cipher
@@ -14,6 +15,7 @@ EVP_rc5_32_12_16_ofb
const EVP_CIPHER *EVP_rc5_32_12_16_cbc(void)
const EVP_CIPHER *EVP_rc5_32_12_16_cfb(void)
+ const EVP_CIPHER *EVP_rc5_32_12_16_cfb64(void)
const EVP_CIPHER *EVP_rc5_32_12_16_ecb(void)
const EVP_CIPHER *EVP_rc5_32_12_16_ofb(void)
@@ -25,6 +27,7 @@ The RC5 encryption algorithm for EVP.
=item EVP_rc5_32_12_16_cbc(),
EVP_rc5_32_12_16_cfb(),
+EVP_rc5_32_12_16_cfb64(),
EVP_rc5_32_12_16_ecb(),
EVP_rc5_32_12_16_ofb()
@@ -53,7 +56,7 @@ L<EVP_CIPHER_meth_new(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2018 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
diff --git a/doc/man3/EVP_seed_cbc.pod b/doc/man3/EVP_seed_cbc.pod
index e9f1f695a915..0d2329510d5e 100644
--- a/doc/man3/EVP_seed_cbc.pod
+++ b/doc/man3/EVP_seed_cbc.pod
@@ -4,6 +4,7 @@
EVP_seed_cbc,
EVP_seed_cfb,
+EVP_seed_cfb128,
EVP_seed_ecb,
EVP_seed_ofb
- EVP SEED cipher
@@ -14,6 +15,7 @@ EVP_seed_ofb
const EVP_CIPHER *EVP_seed_cbc(void)
const EVP_CIPHER *EVP_seed_cfb(void)
+ const EVP_CIPHER *EVP_seed_cfb128(void)
const EVP_CIPHER *EVP_seed_ecb(void)
const EVP_CIPHER *EVP_seed_ofb(void)
@@ -27,6 +29,7 @@ All modes below use a key length of 128 bits and acts on blocks of 128-bits.
=item EVP_seed_cbc(),
EVP_seed_cfb(),
+EVP_seed_cfb128(),
EVP_seed_ecb(),
EVP_seed_ofb()
@@ -48,7 +51,7 @@ L<EVP_CIPHER_meth_new(3)>
=head1 COPYRIGHT
-Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2017-2018 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
diff --git a/doc/man3/EVP_sm4_cbc.pod b/doc/man3/EVP_sm4_cbc.pod
index 4e0240919836..ecd51f09d41f 100644
--- a/doc/man3/EVP_sm4_cbc.pod
+++ b/doc/man3/EVP_sm4_cbc.pod
@@ -5,6 +5,7 @@
EVP_sm4_cbc,
EVP_sm4_ecb,
EVP_sm4_cfb,
+EVP_sm4_cfb128,
EVP_sm4_ofb,
EVP_sm4_ctr
- EVP SM4 cipher
@@ -16,6 +17,7 @@ EVP_sm4_ctr
const EVP_CIPHER *EVP_sm4_cbc(void);
const EVP_CIPHER *EVP_sm4_ecb(void);
const EVP_CIPHER *EVP_sm4_cfb(void);
+ const EVP_CIPHER *EVP_sm4_cfb128(void);
const EVP_CIPHER *EVP_sm4_ofb(void);
const EVP_CIPHER *EVP_sm4_ctr(void);
@@ -30,6 +32,7 @@ All modes below use a key length of 128 bits and acts on blocks of 128 bits.
=item EVP_sm4_cbc(),
EVP_sm4_ecb(),
EVP_sm4_cfb(),
+EVP_sm4_cfb128(),
EVP_sm4_ofb(),
EVP_sm4_ctr()
diff --git a/doc/man3/OPENSSL_VERSION_NUMBER.pod b/doc/man3/OPENSSL_VERSION_NUMBER.pod
index 6eca1134b161..55a55c706a51 100644
--- a/doc/man3/OPENSSL_VERSION_NUMBER.pod
+++ b/doc/man3/OPENSSL_VERSION_NUMBER.pod
@@ -2,13 +2,14 @@
=head1 NAME
-OPENSSL_VERSION_NUMBER, OpenSSL_version,
+OPENSSL_VERSION_NUMBER, OPENSSL_VERSION_TEXT, OpenSSL_version,
OpenSSL_version_num - get OpenSSL version number
=head1 SYNOPSIS
#include <openssl/opensslv.h>
#define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL
+ #define OPENSSL_VERSION_TEXT "OpenSSL x.y.z xx XXX xxxx"
#include <openssl/crypto.h>
@@ -45,6 +46,10 @@ Version 0.9.5a had an interim interpretation that is like the current one,
except the patch level got the highest bit set, to keep continuity. The
number was therefore 0x0090581f.
+OPENSSL_VERSION_TEXT is the text variant of the version number and the
+release date. For example,
+"OpenSSL 1.0.1a 15 Oct 2015".
+
OpenSSL_version_num() returns the version number.
OpenSSL_version() returns different strings depending on B<t>:
diff --git a/doc/man3/RSA_meth_new.pod b/doc/man3/RSA_meth_new.pod
index 69ba9dfc5ac3..f21095156c0f 100644
--- a/doc/man3/RSA_meth_new.pod
+++ b/doc/man3/RSA_meth_new.pod
@@ -64,10 +64,10 @@ RSA_meth_get_multi_prime_keygen, RSA_meth_set_multi_prime_keygen
unsigned char *to, RSA *rsa, int padding));
/* Can be null */
- int (*RSA_meth_get_mod_exp(const RSA_METHOD *meth))(BIGNUM *r0, const BIGNUM *I,
+ int (*RSA_meth_get_mod_exp(const RSA_METHOD *meth))(BIGNUM *r0, const BIGNUM *i,
RSA *rsa, BN_CTX *ctx);
int RSA_meth_set_mod_exp(RSA_METHOD *rsa,
- int (*mod_exp)(BIGNUM *r0, const BIGNUM *I, RSA *rsa,
+ int (*mod_exp)(BIGNUM *r0, const BIGNUM *i, RSA *rsa,
BN_CTX *ctx));
/* Can be null */
diff --git a/doc/man3/SSL_CTX_set0_CA_list.pod b/doc/man3/SSL_CTX_set0_CA_list.pod
index 618bd73e0420..d7ed89775b2e 100644
--- a/doc/man3/SSL_CTX_set0_CA_list.pod
+++ b/doc/man3/SSL_CTX_set0_CA_list.pod
@@ -2,14 +2,32 @@
=head1 NAME
-SSL_set0_CA_list, SSL_CTX_set0_CA_list, SSL_get0_CA_list,
-SSL_CTX_get0_CA_list, SSL_add1_to_CA_list, SSL_CTX_add1_to_CA_list,
-SSL_get0_peer_CA_list - get or set CA list
+SSL_CTX_set_client_CA_list,
+SSL_set_client_CA_list,
+SSL_get_client_CA_list,
+SSL_CTX_get_client_CA_list,
+SSL_CTX_add_client_CA,
+SSL_add_client_CA,
+SSL_set0_CA_list,
+SSL_CTX_set0_CA_list,
+SSL_get0_CA_list,
+SSL_CTX_get0_CA_list,
+SSL_add1_to_CA_list,
+SSL_CTX_add1_to_CA_list,
+SSL_get0_peer_CA_list
+- get or set CA list
=head1 SYNOPSIS
#include <openssl/ssl.h>
+ void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
+ void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
+ STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
+ STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
+ int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
+ int SSL_add_client_CA(SSL *ssl, X509 *cacert);
+
void SSL_CTX_set0_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *name_list);
void SSL_set0_CA_list(SSL *s, STACK_OF(X509_NAME) *name_list);
const STACK_OF(X509_NAME) *SSL_CTX_get0_CA_list(const SSL_CTX *ctx);
@@ -21,6 +39,70 @@ SSL_get0_peer_CA_list - get or set CA list
=head1 DESCRIPTION
+The functions described here set and manage the list of CA names that are sent
+between two communicating peers.
+
+For TLS versions 1.2 and earlier the list of CA names is only sent from the
+server to the client when requesting a client certificate. So any list of CA
+names set is never sent from client to server and the list of CA names retrieved
+by SSL_get0_peer_CA_list() is always B<NULL>.
+
+For TLS 1.3 the list of CA names is sent using the B<certificate_authorities>
+extension and may be sent by a client (in the ClientHello message) or by
+a server (when requesting a certificate).
+
+In most cases it is not necessary to set CA names on the client side. The list
+of CA names that are acceptable to the client will be sent in plaintext to the
+server. This has privacy implications and may also have performance implications
+if the list is large. This optional capability was introduced as part of TLSv1.3
+and therefore setting CA names on the client side will have no impact if that
+protocol version has been disabled. Most servers do not need this and so this
+should be avoided unless required.
+
+The "client CA list" functions below only have an effect when called on the
+server side.
+
+SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
+requesting a client certificate for B<ctx>. Ownership of B<list> is transferred
+to B<ctx> and it should not be freed by the caller.
+
+SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when
+requesting a client certificate for the chosen B<ssl>, overriding the
+setting valid for B<ssl>'s SSL_CTX object. Ownership of B<list> is transferred
+to B<s> and it should not be freed by the caller.
+
+SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for
+B<ctx> using SSL_CTX_set_client_CA_list(). The returned list should not be freed
+by the caller.
+
+SSL_get_client_CA_list() returns the list of client CAs explicitly
+set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with
+SSL_CTX_set_client_CA_list(), when in server mode. In client mode,
+SSL_get_client_CA_list returns the list of client CAs sent from the server, if
+any. The returned list should not be freed by the caller.
+
+SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the
+list of CAs sent to the client when requesting a client certificate for
+B<ctx>.
+
+SSL_add_client_CA() adds the CA name extracted from B<cacert> to the
+list of CAs sent to the client when requesting a client certificate for
+the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.
+
+SSL_get0_peer_CA_list() retrieves the list of CA names (if any) the peer
+has sent. This can be called on either the server or the client side. The
+returned list should not be freed by the caller.
+
+The "generic CA list" functions below are very similar to the "client CA
+list" functions except that they have an effect on both the server and client
+sides. The lists of CA names managed are separate - so you cannot (for example)
+set CA names using the "client CA list" functions and then get them using the
+"generic CA list" functions. Where a mix of the two types of functions has been
+used on the server side then the "client CA list" functions take precedence.
+Typically, on the server side, the "client CA list " functions should be used in
+preference. As noted above in most cases it is not necessary to set CA names on
+the client side.
+
SSL_CTX_set0_CA_list() sets the list of CAs to be sent to the peer to
B<name_list>. Ownership of B<name_list> is transferred to B<ctx> and
it should not be freed by the caller.
@@ -30,10 +112,11 @@ overriding any list set in the parent B<SSL_CTX> of B<s>. Ownership of
B<name_list> is transferred to B<s> and it should not be freed by the caller.
SSL_CTX_get0_CA_list() retrieves any previously set list of CAs set for
-B<ctx>.
+B<ctx>. The returned list should not be freed by the caller.
-SSL_CTX_get0_CA_list() retrieves any previously set list of CAs set for
-B<s> or if none are set the list from the parent B<SSL_CTX> is retrieved.
+SSL_get0_CA_list() retrieves any previously set list of CAs set for
+B<s> or if none are set the list from the parent B<SSL_CTX> is retrieved. The
+returned list should not be freed by the caller.
SSL_CTX_add1_to_CA_list() appends the CA subject name extracted from B<x> to the
list of CAs sent to peer for B<ctx>.
@@ -42,47 +125,60 @@ SSL_add1_to_CA_list() appends the CA subject name extracted from B<x> to the
list of CAs sent to the peer for B<s>, overriding the setting in the parent
B<SSL_CTX>.
-SSL_get0_peer_CA_list() retrieves the list of CA names (if any) the peer
-has sent.
-
=head1 NOTES
-These functions are generalised versions of the client authentication
-CA list functions such as L<SSL_CTX_set_client_CA_list(3)>.
+When a TLS/SSL server requests a client certificate (see
+B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which it will accept
+certificates, to the client.
-For TLS versions before 1.3 the list of CA names is only sent from the server
-to client when requesting a client certificate. So any list of CA names set
-is never sent from client to server and the list of CA names retrieved by
-SSL_get0_peer_CA_list() is always B<NULL>.
+This list must explicitly be set using SSL_CTX_set_client_CA_list() or
+SSL_CTX_set0_CA_list() for B<ctx> and SSL_set_client_CA_list() or
+SSL_set0_CA_list() for the specific B<ssl>. The list specified
+overrides the previous setting. The CAs listed do not become trusted (B<list>
+only contains the names, not the complete certificates); use
+L<SSL_CTX_load_verify_locations(3)> to additionally load them for verification.
-For TLS 1.3 the list of CA names is sent using the B<certificate_authorities>
-extension and will be sent by a client (in the ClientHello message) or by
-a server (when requesting a certificate).
+If the list of acceptable CAs is compiled in a file, the
+L<SSL_load_client_CA_file(3)> function can be used to help to import the
+necessary data.
+
+SSL_CTX_add_client_CA(), SSL_CTX_add1_to_CA_list(), SSL_add_client_CA() and
+SSL_add1_to_CA_list() can be used to add additional items the list of CAs. If no
+list was specified before using SSL_CTX_set_client_CA_list(),
+SSL_CTX_set0_CA_list(), SSL_set_client_CA_list() or SSL_set0_CA_list(), a
+new CA list for B<ctx> or B<ssl> (as appropriate) is opened.
=head1 RETURN VALUES
-SSL_CTX_set0_CA_list() and SSL_set0_CA_list() do not return a value.
+SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(),
+SSL_CTX_set_client_CA_list(), SSL_set_client_CA_list(), SSL_CTX_set0_CA_list()
+and SSL_set0_CA_list() do not return a value.
-SSL_CTX_get0_CA_list() and SSL_get0_CA_list() return a stack of CA names
-or B<NULL> is no CA names are set.
+SSL_CTX_get_client_CA_list(), SSL_get_client_CA_list(), SSL_CTX_get0_CA_list()
+and SSL_get0_CA_list() return a stack of CA names or B<NULL> is no CA names are
+set.
-SSL_CTX_add1_to_CA_list() and SSL_add1_to_CA_list() return 1 for success and 0
-for failure.
+SSL_CTX_add_client_CA(),SSL_add_client_CA(), SSL_CTX_add1_to_CA_list() and
+SSL_add1_to_CA_list() return 1 for success and 0 for failure.
SSL_get0_peer_CA_list() returns a stack of CA names sent by the peer or
B<NULL> or an empty stack if no list was sent.
+=head1 EXAMPLES
+
+Scan all certificates in B<CAfile> and list them as acceptable CAs:
+
+ SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
+
=head1 SEE ALSO
L<ssl(7)>,
-L<SSL_CTX_set_client_CA_list(3)>,
-L<SSL_get_client_CA_list(3)>,
L<SSL_load_client_CA_file(3)>,
L<SSL_CTX_load_verify_locations(3)>
=head1 COPYRIGHT
-Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2018 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
diff --git a/doc/man3/SSL_CTX_set1_curves.pod b/doc/man3/SSL_CTX_set1_curves.pod
index a250f20c2206..7dca0e0161d9 100644
--- a/doc/man3/SSL_CTX_set1_curves.pod
+++ b/doc/man3/SSL_CTX_set1_curves.pod
@@ -32,6 +32,9 @@ SSL_set1_curves_list, SSL_get1_curves, SSL_get_shared_curve
=head1 DESCRIPTION
+For all of the functions below that set the supported groups there must be at
+least one group in the list.
+
SSL_CTX_set1_groups() sets the supported groups for B<ctx> to B<glistlen>
groups in the array B<glist>. The array consist of all NIDs of groups in
preference order. For a TLS client the groups are used directly in the
@@ -99,7 +102,7 @@ functions were first added to OpenSSL 1.1.1.
=head1 COPYRIGHT
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2013-2018 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
diff --git a/doc/man3/SSL_CTX_set_client_CA_list.pod b/doc/man3/SSL_CTX_set_client_CA_list.pod
deleted file mode 100644
index 76fd65e6fcaa..000000000000
--- a/doc/man3/SSL_CTX_set_client_CA_list.pod
+++ /dev/null
@@ -1,103 +0,0 @@
-=pod
-
-=head1 NAME
-
-SSL_CTX_set_client_CA_list, SSL_set_client_CA_list, SSL_CTX_add_client_CA,
-SSL_add_client_CA - set list of CAs sent to the client when requesting a
-client certificate
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
- void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
- int SSL_CTX_add_client_CA(SSL_CTX *ctx, X509 *cacert);
- int SSL_add_client_CA(SSL *ssl, X509 *cacert);
-
-=head1 DESCRIPTION
-
-SSL_CTX_set_client_CA_list() sets the B<list> of CAs sent to the client when
-requesting a client certificate for B<ctx>.
-
-SSL_set_client_CA_list() sets the B<list> of CAs sent to the client when
-requesting a client certificate for the chosen B<ssl>, overriding the
-setting valid for B<ssl>'s SSL_CTX object.
-
-SSL_CTX_add_client_CA() adds the CA name extracted from B<cacert> to the
-list of CAs sent to the client when requesting a client certificate for
-B<ctx>.
-
-SSL_add_client_CA() adds the CA name extracted from B<cacert> to the
-list of CAs sent to the client when requesting a client certificate for
-the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.
-
-=head1 NOTES
-
-When a TLS/SSL server requests a client certificate (see
-B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which
-it will accept certificates, to the client.
-
-This list must explicitly be set using SSL_CTX_set_client_CA_list() for
-B<ctx> and SSL_set_client_CA_list() for the specific B<ssl>. The list
-specified overrides the previous setting. The CAs listed do not become
-trusted (B<list> only contains the names, not the complete certificates); use
-L<SSL_CTX_load_verify_locations(3)>
-to additionally load them for verification.
-
-If the list of acceptable CAs is compiled in a file, the
-L<SSL_load_client_CA_file(3)>
-function can be used to help importing the necessary data.
-
-SSL_CTX_add_client_CA() and SSL_add_client_CA() can be used to add additional
-items the list of client CAs. If no list was specified before using
-SSL_CTX_set_client_CA_list() or SSL_set_client_CA_list(), a new client
-CA list for B<ctx> or B<ssl> (as appropriate) is opened.
-
-These functions are only useful for TLS/SSL servers.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
-diagnostic information.
-
-SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
-values:
-
-=over 4
-
-=item Z<>0
-
-A failure while manipulating the STACK_OF(X509_NAME) object occurred or
-the X509_NAME could not be extracted from B<cacert>. Check the error stack
-to find out the reason.
-
-=item Z<>1
-
-The operation succeeded.
-
-=back
-
-=head1 EXAMPLES
-
-Scan all certificates in B<CAfile> and list them as acceptable CAs:
-
- SSL_CTX_set_client_CA_list(ctx, SSL_load_client_CA_file(CAfile));
-
-=head1 SEE ALSO
-
-L<ssl(7)>,
-L<SSL_get_client_CA_list(3)>,
-L<SSL_load_client_CA_file(3)>,
-L<SSL_CTX_load_verify_locations(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
diff --git a/doc/man3/SSL_CTX_set_quiet_shutdown.pod b/doc/man3/SSL_CTX_set_quiet_shutdown.pod
index 99922eb5bf8d..8ed9315df5c4 100644
--- a/doc/man3/SSL_CTX_set_quiet_shutdown.pod
+++ b/doc/man3/SSL_CTX_set_quiet_shutdown.pod
@@ -33,7 +33,7 @@ SSL_get_quiet_shutdown() returns the "quiet shutdown" setting of B<ssl>.
=head1 NOTES
Normally when a SSL connection is finished, the parties must send out
-"close notify" alert messages using L<SSL_shutdown(3)>
+close_notify alert messages using L<SSL_shutdown(3)>
for a clean shutdown.
When setting the "quiet shutdown" flag to 1, L<SSL_shutdown(3)>
@@ -41,7 +41,7 @@ will set the internal flags to SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.
(L<SSL_shutdown(3)> then behaves like
L<SSL_set_shutdown(3)> called with
SSL_SENT_SHUTDOWN|SSL_RECEIVED_SHUTDOWN.)
-The session is thus considered to be shutdown, but no "close notify" alert
+The session is thus considered to be shutdown, but no close_notify alert
is sent to the peer. This behaviour violates the TLS standard.
The default is normal shutdown behaviour as described by the TLS standard.
@@ -62,7 +62,7 @@ L<SSL_clear(3)>, L<SSL_free(3)>
=head1 COPYRIGHT
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2018 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
diff --git a/doc/man3/SSL_get_client_CA_list.pod b/doc/man3/SSL_get_client_CA_list.pod
deleted file mode 100644
index 40c3561efcee..000000000000
--- a/doc/man3/SSL_get_client_CA_list.pod
+++ /dev/null
@@ -1,62 +0,0 @@
-=pod
-
-=head1 NAME
-
-SSL_get_client_CA_list, SSL_CTX_get_client_CA_list - get list of client CAs
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- STACK_OF(X509_NAME) *SSL_get_client_CA_list(const SSL *s);
- STACK_OF(X509_NAME) *SSL_CTX_get_client_CA_list(const SSL_CTX *ctx);
-
-=head1 DESCRIPTION
-
-SSL_CTX_get_client_CA_list() returns the list of client CAs explicitly set for
-B<ctx> using L<SSL_CTX_set_client_CA_list(3)>.
-
-SSL_get_client_CA_list() returns the list of client CAs explicitly
-set for B<ssl> using SSL_set_client_CA_list() or B<ssl>'s SSL_CTX object with
-L<SSL_CTX_set_client_CA_list(3)>, when in
-server mode. In client mode, SSL_get_client_CA_list returns the list of
-client CAs sent from the server, if any.
-
-=head1 RETURN VALUES
-
-SSL_CTX_set_client_CA_list() and SSL_set_client_CA_list() do not return
-diagnostic information.
-
-SSL_CTX_add_client_CA() and SSL_add_client_CA() have the following return
-values:
-
-=over 4
-
-=item STACK_OF(X509_NAMES)
-
-List of CA names explicitly set (for B<ctx> or in server mode) or send
-by the server (client mode).
-
-=item NULL
-
-No client CA list was explicitly set (for B<ctx> or in server mode) or
-the server did not send a list of CAs (client mode).
-
-=back
-
-=head1 SEE ALSO
-
-L<ssl(7)>,
-L<SSL_CTX_set_client_CA_list(3)>,
-L<SSL_CTX_set_client_cert_cb(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
diff --git a/doc/man3/SSL_get_error.pod b/doc/man3/SSL_get_error.pod
index 01446a24a1e1..b3ab50568731 100644
--- a/doc/man3/SSL_get_error.pod
+++ b/doc/man3/SSL_get_error.pod
@@ -39,7 +39,7 @@ if and only if B<ret E<gt> 0>.
=item SSL_ERROR_ZERO_RETURN
The TLS/SSL peer has closed the connection for writing by sending the
-"close notify" alert.
+close_notify alert.
No more data can be read.
Note that B<SSL_ERROR_ZERO_RETURN> does not necessarily
indicate that the underlying transport has been closed.
diff --git a/doc/man3/SSL_get_peer_signature_nid.pod b/doc/man3/SSL_get_peer_signature_nid.pod
index ce6ab61f5e11..dbca8cffb920 100644
--- a/doc/man3/SSL_get_peer_signature_nid.pod
+++ b/doc/man3/SSL_get_peer_signature_nid.pod
@@ -2,8 +2,9 @@
=head1 NAME
-SSL_get_peer_signature_nid, SSL_get_peer_signature_type_nid - get TLS
-message signing types
+SSL_get_peer_signature_nid, SSL_get_peer_signature_type_nid,
+SSL_get_signature_nid, SSL_get_signature_type_nid - get TLS message signing
+types
=head1 SYNOPSIS
@@ -11,6 +12,8 @@ message signing types
int SSL_get_peer_signature_nid(SSL *ssl, int *psig_nid);
int SSL_get_peer_signature_type_nid(const SSL *ssl, int *psigtype_nid);
+ int SSL_get_signature_nid(SSL *ssl, int *psig_nid);
+ int SSL_get_signature_type_nid(const SSL *ssl, int *psigtype_nid);
=head1 DESCRIPTION
@@ -24,12 +27,15 @@ where it is B<EVP_PKEY_RSA_PSS>. To differentiate between
B<rsa_pss_rsae_*> and B<rsa_pss_pss_*> signatures, it's necessary to check
the type of public key in the peer's certificate.
+SSL_get_signature_nid() and SSL_get_signature_type_nid() return the equivalent
+information for the local end of the connection.
+
=head1 RETURN VALUES
These functions return 1 for success and 0 for failure. There are several
possible reasons for failure: the cipher suite has no signature (e.g. it
uses RSA key exchange or is anonymous), the TLS version is below 1.2 or
-the functions were called before the peer signed a message.
+the functions were called too early, e.g. before the peer signed a message.
=head1 SEE ALSO
diff --git a/doc/man3/SSL_get_peer_tmp_key.pod b/doc/man3/SSL_get_peer_tmp_key.pod
new file mode 100644
index 000000000000..a722a813bff8
--- /dev/null
+++ b/doc/man3/SSL_get_peer_tmp_key.pod
@@ -0,0 +1,53 @@
+=pod
+
+=head1 NAME
+
+SSL_get_peer_tmp_key, SSL_get_server_tmp_key, SSL_get_tmp_key - get information
+about temporary keys used during a handshake
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ long SSL_get_peer_tmp_key(SSL *ssl, EVP_PKEY **key);
+ long SSL_get_server_tmp_key(SSL *ssl, EVP_PKEY **key);
+ long SSL_get_tmp_key(SSL *ssl, EVP_PKEY **key);
+
+=head1 DESCRIPTION
+
+SSL_get_peer_tmp_key() returns the temporary key provided by the peer and
+used during key exchange. For example, if ECDHE is in use, then this represents
+the peer's public ECDHE key. On success a pointer to the key is stored in
+B<*key>. It is the caller's responsibility to free this key after use using
+L<EVP_PKEY_free(3)>.
+
+SSL_get_server_tmp_key() is a backwards compatibility alias for
+SSL_get_peer_tmp_key().
+Under that name it worked just on the client side of the connection, its
+behaviour on the server end is release-dependent.
+
+SSL_get_tmp_key() returns the equivalent information for the local
+end of the connection.
+
+=head1 RETURN VALUES
+
+All these functions return 1 on success and 0 otherwise.
+
+=head1 NOTES
+
+This function is implemented as a macro.
+
+=head1 SEE ALSO
+
+L<ssl(7)>, L<EVP_PKEY_free(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2017-2018 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
diff --git a/doc/man3/SSL_get_server_tmp_key.pod b/doc/man3/SSL_get_server_tmp_key.pod
deleted file mode 100644
index fda891b7a837..000000000000
--- a/doc/man3/SSL_get_server_tmp_key.pod
+++ /dev/null
@@ -1,43 +0,0 @@
-=pod
-
-=head1 NAME
-
-SSL_get_server_tmp_key - get information about the server's temporary key used
-during a handshake
-
-=head1 SYNOPSIS
-
- #include <openssl/ssl.h>
-
- long SSL_get_server_tmp_key(SSL *ssl, EVP_PKEY **key);
-
-=head1 DESCRIPTION
-
-SSL_get_server_tmp_key() returns the temporary key provided by the server and
-used during key exchange. For example, if ECDHE is in use, then this represents
-the server's public ECDHE key. On success a pointer to the key is stored in
-B<*key>. It is the caller's responsibility to free this key after use using
-L<EVP_PKEY_free(3)>. This function may only be called by the client.
-
-=head1 RETURN VALUES
-
-SSL_get_server_tmp_key() returns 1 on success or 0 otherwise.
-
-=head1 NOTES
-
-This function is implemented as a macro.
-
-=head1 SEE ALSO
-
-L<ssl(7)>, L<EVP_PKEY_free(3)>
-
-=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
diff --git a/doc/man3/SSL_set_bio.pod b/doc/man3/SSL_set_bio.pod
index 01617521bf52..1fa0d3492600 100644
--- a/doc/man3/SSL_set_bio.pod
+++ b/doc/man3/SSL_set_bio.pod
@@ -90,7 +90,7 @@ use SSL_set0_rbio() and SSL_set0_wbio() instead.
=head1 RETURN VALUES
-SSL_set_bio(), SSL_set_rbio() and SSL_set_wbio() cannot fail.
+SSL_set_bio(), SSL_set0_rbio() and SSL_set0_wbio() cannot fail.
=head1 SEE ALSO
@@ -104,7 +104,7 @@ SSL_set0_rbio() and SSL_set0_wbio() were added in OpenSSL 1.1.0.
=head1 COPYRIGHT
-Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2018 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
diff --git a/doc/man3/SSL_set_shutdown.pod b/doc/man3/SSL_set_shutdown.pod
index 04bcc47814e3..b1cf58920be4 100644
--- a/doc/man3/SSL_set_shutdown.pod
+++ b/doc/man3/SSL_set_shutdown.pod
@@ -30,12 +30,12 @@ No shutdown setting, yet.
=item SSL_SENT_SHUTDOWN
-A "close notify" shutdown alert was sent to the peer, the connection is being
+A close_notify shutdown alert was sent to the peer, the connection is being
considered closed and the session is closed and correct.
=item SSL_RECEIVED_SHUTDOWN
-A shutdown alert was received form the peer, either a normal "close notify"
+A shutdown alert was received form the peer, either a normal close_notify
or a fatal error.
=back
@@ -47,13 +47,13 @@ the ssl session. If the session is still open, when
L<SSL_clear(3)> or L<SSL_free(3)> is called,
it is considered bad and removed according to RFC2246.
The actual condition for a correctly closed session is SSL_SENT_SHUTDOWN
-(according to the TLS RFC, it is acceptable to only send the "close notify"
+(according to the TLS RFC, it is acceptable to only send the close_notify
alert but to not wait for the peer's answer, when the underlying connection
is closed).
SSL_set_shutdown() can be used to set this state without sending a
close alert to the peer (see L<SSL_shutdown(3)>).
-If a "close notify" was received, SSL_RECEIVED_SHUTDOWN will be set,
+If a close_notify was received, SSL_RECEIVED_SHUTDOWN will be set,
for setting SSL_SENT_SHUTDOWN the application must however still call
L<SSL_shutdown(3)> or SSL_set_shutdown() itself.
@@ -71,7 +71,7 @@ L<SSL_clear(3)>, L<SSL_free(3)>
=head1 COPYRIGHT
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2018 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
diff --git a/doc/man3/SSL_shutdown.pod b/doc/man3/SSL_shutdown.pod
index 453853d672fc..0a3d6d370d8b 100644
--- a/doc/man3/SSL_shutdown.pod
+++ b/doc/man3/SSL_shutdown.pod
@@ -13,27 +13,36 @@ SSL_shutdown - shut down a TLS/SSL connection
=head1 DESCRIPTION
SSL_shutdown() shuts down an active TLS/SSL connection. It sends the
-"close notify" shutdown alert to the peer.
+close_notify shutdown alert to the peer.
=head1 NOTES
-SSL_shutdown() tries to send the "close notify" shutdown alert to the peer.
+SSL_shutdown() tries to send the close_notify shutdown alert to the peer.
Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and
a currently open session is considered closed and good and will be kept in the
session cache for further reuse.
-The shutdown procedure consists of 2 steps: the sending of the "close notify"
-shutdown alert and the reception of the peer's "close notify" shutdown
-alert. According to the TLS standard, it is acceptable for an application
-to only send its shutdown alert and then close the underlying connection
-without waiting for the peer's response (this way resources can be saved,
-as the process can already terminate or serve another connection).
-When the underlying connection shall be used for more communications, the
-complete shutdown procedure (bidirectional "close notify" alerts) must be
-performed, so that the peers stay synchronized.
+The shutdown procedure consists of two steps: sending of the close_notify
+shutdown alert, and reception of the peer's close_notify shutdown alert.
+The order of those two steps depends on the application.
+
+It is acceptable for an application to only send its shutdown alert and
+then close the underlying connection without waiting for the peer's response.
+This way resources can be saved, as the process can already terminate or
+serve another connection.
+This should only be done when it is known that the other side will not send more
+data, otherwise there is a risk of a truncation attack.
-SSL_shutdown() supports both uni- and bidirectional shutdown by its 2 step
-behaviour.
+When a client only writes and never reads from the connection, and the server
+has sent a session ticket to establish a session, the client might not be able
+to resume the session because it did not received and process the session ticket
+from the server.
+In case the application wants to be able to resume the session, it is recommended to
+do a complete shutdown procedure (bidirectional close_notify alerts).
+
+When the underlying connection shall be used for more communications, the
+complete shutdown procedure must be performed, so that the peers stay
+synchronized.
SSL_shutdown() only closes the write direction.
It is not possible to call SSL_write() after calling SSL_shutdown().
@@ -41,45 +50,43 @@ The read direction is closed by the peer.
=head2 First to close the connection
-When the application is the first party to send the "close notify"
+When the application is the first party to send the close_notify
alert, SSL_shutdown() will only send the alert and then set the
SSL_SENT_SHUTDOWN flag (so that the session is considered good and will
be kept in the cache).
-SSL_shutdown() will then return with 0.
+If successful, SSL_shutdown() will return 0.
+
If a unidirectional shutdown is enough (the underlying connection shall be
-closed anyway), this first call to SSL_shutdown() is sufficient.
+closed anyway), this first successful call to SSL_shutdown() is sufficient.
In order to complete the bidirectional shutdown handshake, the peer needs
-to send back a "close notify" alert.
+to send back a close_notify alert.
The SSL_RECEIVED_SHUTDOWN flag will be set after receiving and processing
it.
-SSL_shutdown() will return 1 when it has been received.
-The peer is still allowed to send data after receiving the "close notify"
+The peer is still allowed to send data after receiving the close_notify
event.
-If the peer did send data it needs to be processed by calling SSL_read()
-before calling SSL_shutdown() a second time.
+When it is done sending data, it will send the close_notify alert.
+SSL_read() should be called until all data is received.
SSL_read() will indicate the end of the peer data by returning <= 0
and SSL_get_error() returning SSL_ERROR_ZERO_RETURN.
-It is recommended to call SSL_read() between SSL_shutdown() calls.
=head2 Peer closes the connection
-If the peer already sent the "close notify" alert B<and> it was
+If the peer already sent the close_notify alert B<and> it was
already processed implicitly inside another function
(L<SSL_read(3)>), the SSL_RECEIVED_SHUTDOWN flag is set.
SSL_read() will return <= 0 in that case, and SSL_get_error() will return
SSL_ERROR_ZERO_RETURN.
-SSL_shutdown() will send the "close notify" alert, set the SSL_SENT_SHUTDOWN
-flag and will immediately return with 1.
+SSL_shutdown() will send the close_notify alert, set the SSL_SENT_SHUTDOWN
+flag.
+If successful, SSL_shutdown() will return 1.
+
Whether SSL_RECEIVED_SHUTDOWN is already set can be checked using the
SSL_get_shutdown() (see also L<SSL_set_shutdown(3)> call.
=head1 NOTES
-It is recommended to do a bidirectional shutdown by checking the return value
-of SSL_shutdown() and call it again until it returns 1 or a fatal error.
-
The behaviour of SSL_shutdown() additionally depends on the underlying BIO.
If the underlying BIO is B<blocking>, SSL_shutdown() will only return once the
handshake step has been finished or an error occurred.
@@ -95,8 +102,13 @@ nothing is to be done, but select() can be used to check for the required
condition. When using a buffering BIO, like a BIO pair, data must be written
into or retrieved out of the BIO before being able to continue.
+After SSL_shutdown() returned 0, it is possible to call SSL_shutdown() again
+to wait for the peer's close_notify alert.
+SSL_shutdown() will return 1 in that case.
+However, it is recommended to wait for it using SSL_read() instead.
+
SSL_shutdown() can be modified to only set the connection to "shutdown"
-state but not actually send the "close notify" alert messages,
+state but not actually send the close_notify alert messages,
see L<SSL_CTX_set_quiet_shutdown(3)>.
When "quiet shutdown" is enabled, SSL_shutdown() will always succeed
and return 1.
@@ -109,16 +121,16 @@ The following return values can occur:
=item Z<>0
-The shutdown is not yet finished: the "close notify" was send but the peer
+The shutdown is not yet finished: the close_notify was sent but the peer
did not send it back yet.
-Call SSL_shutdown() again to do a bidirectional shutdown.
+Call SSL_read() to do a bidirectional shutdown.
The output of L<SSL_get_error(3)> may be misleading, as an
erroneous SSL_ERROR_SYSCALL may be flagged even though no error occurred.
=item Z<>1
-The shutdown was successfully completed. The "close notify" alert was sent
-and the peer's "close notify" alert was received.
+The shutdown was successfully completed. The close_notify alert was sent
+and the peer's close_notify alert was received.
=item E<lt>0