Version bump

doc/man3/ADMISSIONS.pod

@@ -99,10 +99,10 @@ The B<PROFESSION_INFOS>, B<ADMISSION_SYNTAX>, B<ADMISSIONS>, and
 B<PROFESSION_INFO> types are opaque structures representing the
 analogous types defined in the Common PKI Specification published
 by L<https://www.t7ev.org>.
-Knowledge of those strutures and their semantics is assumed.
+Knowledge of those structures and their semantics is assumed.
 
 The conventional routines to convert between DER and the local format
-are desribed in L<d2i_X509(3)>.
+are described in L<d2i_X509(3)>.
 The conventional routines to allocate and free the types are defined
 in L<X509_dup(3)>.
 

doc/man3/ASN1_STRING_length.pod

@@ -71,8 +71,8 @@ utility functions should be used instead.
 In general it cannot be assumed that the data returned by ASN1_STRING_data()
 is null terminated or does not contain embedded nulls. The actual format
 of the data will depend on the actual string type itself: for example
-for and IA5String the data will be ASCII, for a BMPString two bytes per
-character in big endian format, UTF8String will be in UTF8 format.
+for an IA5String the data will be ASCII, for a BMPString two bytes per
+character in big endian format, and for an UTF8String it will be in UTF8 format.
 
 Similar care should be take to ensure the data is in the correct format
 when calling ASN1_STRING_set().

doc/man3/ASN1_TIME_set.pod

@@ -155,7 +155,7 @@ in the B<offset_sec> and B<offset_day> parameters instead of directly
 manipulating a time_t value.
 
 ASN1_TIME_adj() may change the type from ASN1_GENERALIZEDTIME to ASN1_UTCTIME,
-or vise-versa, based on the resulting year. The ASN1_GENERALIZEDTIME_adj() and
+or vice versa, based on the resulting year. The ASN1_GENERALIZEDTIME_adj() and
 ASN1_UTCTIME_adj() functions will not modify the type of the return structure.
 
 It is recommended that functions starting with ASN1_TIME be used instead of

doc/man3/BIO_s_mem.pod

@@ -56,14 +56,14 @@ zero then it will return B<v> when it is empty and it will set the read retry
 flag (that is BIO_read_retry(b) is true). To avoid ambiguity with a normal
 positive return value B<v> should be set to a negative value, typically -1.
 
-BIO_get_mem_data() sets B<pp> to a pointer to the start of the memory BIOs data
+BIO_get_mem_data() sets *B<pp> to a pointer to the start of the memory BIOs data
 and returns the total amount of data available. It is implemented as a macro.
 
 BIO_set_mem_buf() sets the internal BUF_MEM structure to B<bm> and sets the
 close flag to B<c>, that is B<c> should be either BIO_CLOSE or BIO_NOCLOSE.
 It is a macro.
 
-BIO_get_mem_ptr() places the underlying BUF_MEM structure in B<pp>. It is
+BIO_get_mem_ptr() places the underlying BUF_MEM structure in *B<pp>. It is
 a macro.
 
 BIO_new_mem_buf() creates a memory BIO using B<len> bytes of data at B<buf>,

doc/man3/DH_generate_parameters.pod

@@ -111,10 +111,10 @@ The parameter B<j> is invalid.
 
 =back
 
-DH_check_ex(), DH_check_params() and DH_check_pub_key_ex() are similiar with
-DH_check() and DH_check_params() respectively, but the error reasons are set
-to the OpenSSL error handling framework instead of returning by the function
-parameters.
+DH_check_ex(), DH_check_params() and DH_check_pub_key_ex() are similar to
+DH_check() and DH_check_params() respectively, but the error reasons are added
+to the thread's error queue instead of provided as return values from the
+function.
 
 =head1 RETURN VALUES
 

doc/man3/DTLSv1_listen.pod

@@ -64,10 +64,11 @@ does not support this), then B<*peer> will be cleared and the family set to
 AF_UNSPEC. Typically user code is expected to "connect" the underlying socket to
 the peer and continue the handshake in a connected state.
 
-Prior to calling these functions user code must ensure that cookie generation
+Prior to calling DTLSv1_listen() user code must ensure that cookie generation
 and verification callbacks have been set up using
 SSL_CTX_set_cookie_generate_cb() and SSL_CTX_set_cookie_verify_cb()
-respectively.
+respectively. For SSL_stateless(), SSL_CTX_set_stateless_cookie_generate_cb()
+and SSL_CTX_set_stateless_cookie_verify_cb() must be used instead.
 
 Since DTLSv1_listen() operates entirely statelessly whilst processing incoming
 ClientHellos it is unable to process fragmented messages (since this would
@@ -88,8 +89,9 @@ start.
 =head1 RETURN VALUES
 
 For SSL_stateless() a return value of 1 indicates success and the B<ssl> object
-will be set up ready to continue the handshake. A return value of 0 indicates
-failure. User code may retry the SSL_stateless() call.
+will be set up ready to continue the handshake. A return value of 0 or -1
+indicates failure. If the value is 0 then a HelloRetryRequest was sent. A value
+of -1 indicates any other error. User code may retry the SSL_stateless() call.
 
 For DTLSv1_listen() a return value of >= 1 indicates success. The B<ssl> object
 will be set up ready to continue the handshake.  the B<peer> value will also be

doc/man3/EVP_CIPHER_meth_new.pod

@@ -73,7 +73,7 @@ EVP_CIPHER_meth_dup() creates a copy of B<cipher>.
 
 EVP_CIPHER_meth_free() destroys a B<EVP_CIPHER> structure.
 
-EVP_CIPHER_meth_iv_length() sets the length of the IV.
+EVP_CIPHER_meth_set_iv_length() sets the length of the IV.
 This is only needed when the implemented cipher mode requires it.
 
 EVP_CIPHER_meth_set_flags() sets the flags to describe optional

doc/man3/EVP_DigestInit.pod

@@ -217,8 +217,8 @@ preference to the low level interfaces. This is because the code then becomes
 transparent to the digest used and much more flexible.
 
 New applications should use the SHA-2 (such as L<EVP_sha256(3)>) or the SHA-3
-digest algorithms (such as L<EVP_sha3_512>). The other digest algorithms are
-still in common use.
+digest algorithms (such as L<EVP_sha3_512(3)>). The other digest algorithms
+are still in common use.
 
 For most applications the B<impl> parameter to EVP_DigestInit_ex() will be
 set to NULL to use the default digest implementation.

doc/man3/EVP_EncryptInit.pod

@@ -59,33 +59,33 @@ EVP_enc_null
  void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx);
 
  int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
-                        ENGINE *impl, unsigned char *key, unsigned char *iv);
+                        ENGINE *impl, const unsigned char *key, const unsigned char *iv);
  int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
                        int *outl, const unsigned char *in, int inl);
  int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
 
  int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
-                        ENGINE *impl, unsigned char *key, unsigned char *iv);
+                        ENGINE *impl, const unsigned char *key, const unsigned char *iv);
  int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
                        int *outl, const unsigned char *in, int inl);
  int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
 
  int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
-                       ENGINE *impl, unsigned char *key, unsigned char *iv, int enc);
+                       ENGINE *impl, const unsigned char *key, const unsigned char *iv, int enc);
  int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
-                      int *outl, unsigned char *in, int inl);
+                      int *outl, const unsigned char *in, int inl);
  int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
 
  int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
-                     unsigned char *key, unsigned char *iv);
+                     const unsigned char *key, const unsigned char *iv);
  int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
 
  int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
-                     unsigned char *key, unsigned char *iv);
+                     const unsigned char *key, const unsigned char *iv);
  int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
 
  int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
-                    unsigned char *key, unsigned char *iv, int enc);
+                    const unsigned char *key, const unsigned char *iv, int enc);
  int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
 
  int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
@@ -457,6 +457,20 @@ This call is only valid when decrypting data.
 
 =back
 
+=head1 Random numbers
+
+The following can be used to select the DRBG that is used to generate the random
+numbers:
+
+EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_SET_DRBG, 0, drbg)
+
+The following can be used to get the DRBG:
+
+EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GET_DRBG, 0, &drbg)
+
+By default it's set to NULL which results in RAND_bytes() being used.
+
+
 =head1 NOTES
 
 Where possible the B<EVP> interface to symmetric ciphers should be used in

doc/man3/EVP_md5.pod

@@ -16,7 +16,7 @@ EVP_md5
 MD5 is a cryptographic hash function standardized in RFC 1321 and designed by
 Ronald Rivest.
 
-The CMU Software Engieneering Institute considers MD5 unsuitable for further
+The CMU Software Engineering Institute considers MD5 unsuitable for further
 use since its security has been severely compromised.
 
 =over 4

doc/man3/OSSL_STORE_LOADER.pod

@@ -162,7 +162,7 @@ It is otherwise expected to return 0.
 =item B<OSSL_STORE_error_fn>
 
 This function takes a B<OSSL_STORE_LOADER_CTX> pointer and is expected to
-return 1 to indicate that an error occured in a previous call to the
+return 1 to indicate that an error occurred in a previous call to the
 B<OSSL_STORE_load_fn> function.
 It is otherwise expected to return 0.
 

doc/man3/OSSL_STORE_SEARCH.pod

@@ -45,7 +45,7 @@ OSSL_STORE_SEARCH_get0_digest
 
 =head1 DESCRIPTION
 
-These functions are use to specify search criteria to help search for specific
+These functions are used to specify search criteria to help search for specific
 objects through other names than just the URI that's given to OSSL_STORE_open().
 For example, this can be useful for an application that has received a URI
 and then wants to add on search criteria in a uniform and supported manner.
@@ -122,7 +122,7 @@ accordingly.
 A criterion of this type is created with OSSL_STORE_SEARCH_by_key_fingerprint()
 and the actual fingerprint and its length can be retrieved with
 OSSL_STORE_SEARCH_get0_bytes().
-The digest can be retreived with OSSL_STORE_SEARCH_get0_digest().
+The digest can be retrieved with OSSL_STORE_SEARCH_get0_digest().
 
 =item OSSL_STORE_SEARCH_BY_ALIAS
 

doc/man3/OSSL_STORE_expect.pod

@@ -14,7 +14,7 @@ OSSL_STORE_find
  int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type);
 
  int OSSL_STORE_supports_search(OSSL_STORE_CTX *ctx, int criterion_type);
- 
+
  int OSSL_STORE_find(OSSL_STORE_CTX *ctx, OSSL_STORE_SEARCH *search);
 
 =head1 DESCRIPTION

doc/man3/OSSL_STORE_open.pod

@@ -86,7 +86,7 @@ object and return it wrapped with  B<OSSL_STORE_INFO>.
 OSSL_STORE_eof() takes a B<OSSL_STORE_CTX> and checks if we've reached the end
 of data.
 
-OSSL_STORE_error() takes a B<OSSL_STORE_CTX> and checks if an error occured in
+OSSL_STORE_error() takes a B<OSSL_STORE_CTX> and checks if an error occurred in
 the last OSSL_STORE_load() call.
 Note that it may still be meaningful to try and load more objects, unless
 OSSL_STORE_eof() shows that the end of data has been reached.
@@ -125,7 +125,7 @@ returned B<NULL>.
 OSSL_STORE_eof() returns 1 if the end of data has been reached, otherwise
 0.
 
-OSSL_STORE_error() returns 1 if an error occured in a OSSL_STORE_load() call,
+OSSL_STORE_error() returns 1 if an error occurred in an OSSL_STORE_load() call,
 otherwise 0.
 
 OSSL_STORE_ctrl() and OSSL_STORE_close() returns 1 on success, or 0 on failure.

doc/man3/SSL_CTX_set_psk_client_callback.pod

@@ -14,48 +14,33 @@ SSL_set_psk_use_session_callback
 
  #include <openssl/ssl.h>
 
+ typedef int (*SSL_psk_use_session_cb_func)(SSL *ssl, const EVP_MD *md,
+                                            const unsigned char **id,
+                                            size_t *idlen,
+                                            SSL_SESSION **sess);
+
+
+ void SSL_CTX_set_psk_use_session_callback(SSL_CTX *ctx,
+                                           SSL_psk_use_session_cb_func cb);
+ void SSL_set_psk_use_session_callback(SSL *s, SSL_psk_use_session_cb_func cb);
+
+
  typedef unsigned int (*SSL_psk_client_cb_func)(SSL *ssl,
                                                 const char *hint,
                                                 char *identity,
                                                 unsigned int max_identity_len,
                                                 unsigned char *psk,
                                                 unsigned int max_psk_len);
- typedef int (*SSL_psk_use_session_cb_func)(SSL *ssl, const EVP_MD *md,
-                                            const unsigned char **id,
-                                            size_t *idlen,
-                                            SSL_SESSION **sess);
 
  void SSL_CTX_set_psk_client_callback(SSL_CTX *ctx, SSL_psk_client_cb_func cb);
  void SSL_set_psk_client_callback(SSL *ssl, SSL_psk_client_cb_func cb);
 
- void SSL_CTX_set_psk_use_session_callback(SSL_CTX *ctx,
-                                           SSL_psk_use_session_cb_func cb);
- void SSL_set_psk_use_session_callback(SSL *s, SSL_psk_use_session_cb_func cb);
 
 =head1 DESCRIPTION
 
-TLSv1.3 Pre-Shared Keys (PSKs) and PSKs for TLSv1.2 and below are not
-compatible.
-
-A client application wishing to use PSK ciphersuites for TLSv1.2 and below must
-provide a callback function. This function will be called when the client is
-sending the ClientKeyExchange message to the server.
-
-The purpose of the callback function is to select the PSK identity and
-the pre-shared key to use during the connection setup phase.
-
-The callback is set using functions SSL_CTX_set_psk_client_callback()
-or SSL_set_psk_client_callback(). The callback function is given the
-connection in parameter B<ssl>, a B<NULL>-terminated PSK identity hint
-sent by the server in parameter B<hint>, a buffer B<identity> of
-length B<max_identity_len> bytes where the resulting
-B<NULL>-terminated identity is to be stored, and a buffer B<psk> of
-length B<max_psk_len> bytes where the resulting pre-shared key is to
-be stored.
-
-A client application wishing to use TLSv1.3 PSKs must set a different callback
-using either SSL_CTX_set_psk_use_session_callback() or
-SSL_set_psk_use_session_callback() as appropriate.
+A client application wishing to use TLSv1.3 PSKs should use either
+SSL_CTX_set_psk_use_session_callback() or SSL_set_psk_use_session_callback() as
+appropriate. These functions cannot be used for TLSv1.2 and below PSKs.
 
 The callback function is given a pointer to the SSL connection in B<ssl>.
 
@@ -113,6 +98,33 @@ case no PSK will be sent to the server but the handshake will continue. To do
 this the callback should return successfully and ensure that B<*sess> is
 NULL. The contents of B<*id> and B<*idlen> will be ignored.
 
+A client application wishing to use PSK ciphersuites for TLSv1.2 and below must
+provide a different callback function. This function will be called when the
+client is sending the ClientKeyExchange message to the server.
+
+The purpose of the callback function is to select the PSK identity and
+the pre-shared key to use during the connection setup phase.
+
+The callback is set using functions SSL_CTX_set_psk_client_callback()
+or SSL_set_psk_client_callback(). The callback function is given the
+connection in parameter B<ssl>, a B<NULL>-terminated PSK identity hint
+sent by the server in parameter B<hint>, a buffer B<identity> of
+length B<max_identity_len> bytes where the resulting
+B<NUL>-terminated identity is to be stored, and a buffer B<psk> of
+length B<max_psk_len> bytes where the resulting pre-shared key is to
+be stored.
+
+The callback for use in TLSv1.2 will also work in TLSv1.3 although it is
+recommended to use SSL_CTX_set_psk_use_session_callback()
+or SSL_set_psk_use_session_callback() for this purpose instead. If TLSv1.3 has
+been negotiated then OpenSSL will first check to see if a callback has been set
+via SSL_CTX_set_psk_use_session_callback() or SSL_set_psk_use_session_callback()
+and it will use that in preference. If no such callback is present then it will
+check to see if a callback has been set via SSL_CTX_set_psk_client_callback() or
+SSL_set_psk_client_callback() and use that. In this case the B<hint> value will
+always be NULL and the handshake digest will default to SHA-256 for any returned
+PSK.
+
 =head1 NOTES
 
 Note that parameter B<hint> given to the callback may be B<NULL>.

doc/man3/SSL_CTX_set_session_ticket_cb.pod

@@ -0,0 +1,149 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_session_ticket_cb,
+SSL_SESSION_get0_ticket_appdata,
+SSL_SESSION_set1_ticket_appdata,
+SSL_CTX_generate_session_ticket_fn,
+SSL_CTX_decrypt_session_ticket_fn - manage session ticket application data
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ typedef int (*SSL_CTX_generate_session_ticket_fn)(SSL *s, void *arg);
+ typedef SSL_TICKET_RETURN (*SSL_CTX_decrypt_session_ticket_fn)(SSL *s, SSL_SESSION *ss,
+                                                                const unsigned char *keyname,
+                                                                size_t keyname_len,
+                                                                SSL_TICKET_RETURN retv,
+                                                                void *arg);
+ int SSL_CTX_set_session_ticket_cb(SSL_CTX *ctx,
+                                   SSL_CTX_generate_session_ticket_fn gen_cb,
+                                   SSL_CTX_decrypt_session_ticket_fn dec_cb,
+                                   void *arg);
+ int SSL_SESSION_set1_ticket_appdata(SSL_SESSION *ss, const void *data, size_t len);
+ int SSL_SESSION_get0_ticket_appdata(SSL_SESSION *ss, void **data, size_t *len);
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_set_session_ticket_cb() sets the application callbacks B<gen_cb>
+and B<dec_cb> that are used by a server to set and get application data stored
+with a session, and placed into a session ticket. Either callback function may
+be set to NULL. The value of B<arg> is passed to the callbacks.
+
+B<gen_cb> is the application defined callback invoked when a session ticket is
+about to be created. The application can call SSL_SESSION_set1_ticket_appdata()
+at this time to add application data to the session ticket. The value of B<arg>
+is the same as that given to SSL_CTX_set_session_ticket_cb(). The B<gen_cb>
+callback is defined as type B<SSL_CTX_generate_session_ticket_fn>.
+
+B<dec_cb> is the application defined callback invoked after session ticket
+decryption has been attempted and any session ticket application data is available.
+The application can call SSL_SESSION_get_ticket_appdata() at this time to retrieve
+the application data. The value of B<arg> is the same as that given to
+SSL_CTX_set_session_ticket_cb(). The B<retv> arguement is the result of the ticket
+decryption. The B<keyname> and B<keyname_len> identify the key used to decrypt the
+session ticket. The B<dec_cb> callback is defined as type
+B<SSL_CTX_decrypt_session_ticket_fn>.
+
+SSL_SESSION_set1_ticket_appdata() sets the application data specified by
+B<data> and B<len> into B<ss> which is then placed into any generated session
+tickets. It can be called at any time before a session ticket is created to
+update the data placed into the session ticket. However, given that sessions
+and tickets are created by the handshake, the B<gen_cb> is provided to notify
+the application that a session ticket is about to be generated.
+
+SSL_SESSION_get0_ticket_appdata() assigns B<data> to the session ticket
+application data and assigns B<len> to the length of the session ticket
+application data from B<ss>. The application data can be set via
+SSL_SESSION_set1_ticket_appdata() or by a session ticket. NULL will be assigned
+to B<data> and 0 will be assigned to B<len> if there is no session ticket
+application data. SSL_SESSION_get0_ticket_appdata() can be called any time
+after a session has been created. The B<dec_cb> is provided to notify the
+application that a session ticket has just been decrypted.
+
+=head1 NOTES
+
+When the B<dec_cb> callback is invoked, the SSL_SESSION B<ss> has not yet been
+assigned to the SSL B<s>. The B<retv> indicates the result of the ticket
+decryption which can be modified by the callback before being returned. The
+callback must check the B<retv> value before performing any action, as it's
+called even if ticket decryption fails.
+
+The B<keyname> and B<keyname_len> arguments to B<dec_cb> may be used to identify
+the key that was used to encrypt the session ticket.
+
+When the B<gen_cb> callback is invoked, the SSL_get_session() function can be
+used to retrieve the SSL_SESSION for SSL_SESSION_set1_ticket_appdata().
+
+=head1 RETURN VALUES
+
+The SSL_CTX_set_session_ticket_cb(), SSL_SESSION_set1_ticket_appdata() and
+SSL_SESSION_get0_ticket_appdata() functions return 1 on success and 0 on
+failure.
+
+The B<gen_cb> callback must return 1 to continue the connection. A return of 0
+will terminate the connection with an INTERNAL_ERROR alert.
+
+The B<dec_cb> callback must return one of the following B<SSL_TICKET_RETURN>
+values. Under normal circumstances the B<retv> value is returned unmodified,
+but the callback can change the behavior of the post-ticket decryption code
+by returning something different. The B<dec_cb> callback must check the B<retv>
+value before performing any action.
+
+ typedef int SSL_TICKET_RETURN;
+
+=over 4
+
+=item SSL_TICKET_FATAL_ERR_MALLOC
+
+Fatal error, malloc failure.
+
+=item SSL_TICKET_FATAL_ERR_OTHER
+
+Fatal error, either from parsing or decrypting the ticket.
+
+=item SSL_TICKET_NONE
+
+No ticket present.
+
+=item SSL_TICKET_EMPTY
+
+Empty ticket present.
+
+=item SSL_TICKET_NO_DECRYPT
+
+The ticket couldn't be decrypted.
+
+=item SSL_TICKET_SUCCESS
+
+A ticket was successfully decrypted, any session ticket application data should
+be available.
+
+=item TICKET_SUCCESS_RENEW
+
+Same as B<TICKET_SUCCESS>, but the ticket needs to be renewed.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(7)>,
+L<SSL_get_session(3)>
+
+=head1 HISTORY
+
+SSL_CTX_set_session_ticket_cb(), SSSL_SESSION_set1_ticket_appdata() and
+SSL_SESSION_get_ticket_appdata() were added to OpenSSL 1.1.1.
+
+=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

doc/man3/SSL_CTX_set_stateless_cookie_generate_cb.pod

@@ -0,0 +1,58 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_stateless_cookie_generate_cb,
+SSL_CTX_set_stateless_cookie_verify_cb
+- Callback functions for stateless TLS1.3 cookies
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_stateless_cookie_generate_cb(
+     SSL_CTX *ctx,
+     int (*gen_stateless_cookie_cb) (SSL *ssl,
+                                     unsigned char *cookie,
+                                     size_t *cookie_len));
+ void SSL_CTX_set_stateless_cookie_verify_cb(
+     SSL_CTX *ctx,
+     int (*verify_stateless_cookie_cb) (SSL *ssl,
+                                        const unsigned char *cookie,
+                                        size_t cookie_len));
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_cookie_generate_cb() sets the callback used by L<SSL_stateless(3)>
+to generate the application-controlled portion of the cookie provided to clients
+in the HelloRetryRequest transmitted as a response to a ClientHello with a
+missing or invalid cookie. gen_stateless_cookie_cb() must write at most
+SSL_COOKIE_LENGTH bytes into B<cookie>, and must write the number of bytes
+written to B<cookie_len>. If a cookie cannot be generated, a zero return value
+can be used to abort the handshake.
+
+SSL_CTX_set_cookie_verify_cb() sets the callback used by L<SSL_stateless(3)> to
+determine whether the application-controlled portion of a ClientHello cookie is
+valid. A nonzero return value from app_verify_cookie_cb() communicates that the
+cookie is valid. The integrity of the entire cookie, including the
+application-controlled portion, is automatically verified by HMAC before
+verify_stateless_cookie_cb() is called.
+
+=head1 RETURN VALUES
+
+Neither function returns a value.
+
+=head1 SEE ALSO
+
+L<SSL_stateless(3)>
+
+=head1 COPYRIGHT
+
+Copyright 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

doc/man3/SSL_CTX_set_tlsext_use_srtp.pod

@@ -75,7 +75,7 @@ SSL_get_selected_srtp_profile(). This function will return NULL if no SRTP
 protection profile was negotiated. The memory returned from this function should
 not be freed by the caller.
 
-If an SRTP protection profile has been sucessfully negotiated then the SRTP
+If an SRTP protection profile has been successfully negotiated then the SRTP
 keying material (on both the client and server) should be obtained via a call to
 L<SSL_export_keying_material(3)>. This call should provide a label value of
 "EXTRACTOR-dtls_srtp" and a NULL context value (use_context is 0). The total

doc/man3/SSL_CTX_use_certificate.pod

@@ -11,7 +11,8 @@ SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey,
 SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file,
 SSL_use_PrivateKey_file, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey,
 SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1,
-SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key
+SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key,
+SSL_CTX_use_cert_and_key, SSL_use_cert_and_key
 - load certificate and key data
 
 =head1 SYNOPSIS
@@ -45,6 +46,9 @@ SSL_use_RSAPrivateKey_file, SSL_CTX_check_private_key, SSL_check_private_key
  int SSL_CTX_check_private_key(const SSL_CTX *ctx);
  int SSL_check_private_key(const SSL *ssl);
 
+ int SSL_CTX_use_cert_and_key(SSL_CTX *ctx, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);
+ int SSL_use_cert_and_key(SSL *ssl, X509 *x, EVP_PKEY *pkey, STACK_OF(X509) *chain, int override);
+
 =head1 DESCRIPTION
 
 These functions load the certificates and private keys into the SSL_CTX
@@ -94,6 +98,19 @@ key pair the new certificate needs to be set with SSL_use_certificate()
 or SSL_CTX_use_certificate() before setting the private key with
 SSL_CTX_use_PrivateKey() or SSL_use_PrivateKey().
 
+SSL_CTX_use_cert_and_key() and SSL_use_cert_and_key() assign the X.509
+certificate B<x>, private key B<key>, and certificate B<chain> onto the
+corresponding B<ssl> or B<ctx>. The B<pkey> argument must be the private
+key of the X.509 certificate B<x>. If the B<override> argument is 0, then
+B<x>, B<pkey> and B<chain> are set only if all were not previously set.
+If B<override> is non-0, then the certificate, private key and chain certs
+are always set. If B<pkey> is NULL, then the public key of B<x> is used as
+the private key. This is intended to be used with hardware (via the ENGINE
+inteface) that stores the private key securely, such that it cannot be
+accessed by OpenSSL. The reference count of the public key is incremented
+(twice if there is no private key); it is not copied nor duplicated. This
+allows all private key validations checks to succeed without an actual
+private key being assigned via SSL_CTX_use_PrivateKey(), etc.
 
 SSL_CTX_use_PrivateKey_ASN1() adds the private key of type B<pk>
 stored at memory location B<d> (length B<len>) to B<ctx>.
@@ -170,7 +187,7 @@ L<SSL_CTX_add_extra_chain_cert(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy

doc/man3/SSL_CTX_use_psk_identity_hint.pod

@@ -16,52 +16,30 @@ SSL_set_psk_find_session_callback
 
  #include <openssl/ssl.h>
 
- typedef unsigned int (*SSL_psk_server_cb_func)(SSL *ssl,
-                                                const char *identity,
-                                                unsigned char *psk,
-                                                unsigned int max_psk_len);
-
  typedef int (*SSL_psk_find_session_cb_func)(SSL *ssl,
                                              const unsigned char *identity,
                                              size_t identity_len,
                                              SSL_SESSION **sess);
 
+
+ void SSL_CTX_set_psk_find_session_callback(SSL_CTX *ctx,
+                                            SSL_psk_find_session_cb_func cb);
+ void SSL_set_psk_find_session_callback(SSL *s, SSL_psk_find_session_cb_func cb);
+
+ typedef unsigned int (*SSL_psk_server_cb_func)(SSL *ssl,
+                                                const char *identity,
+                                                unsigned char *psk,
+                                                unsigned int max_psk_len);
+
  int SSL_CTX_use_psk_identity_hint(SSL_CTX *ctx, const char *hint);
  int SSL_use_psk_identity_hint(SSL *ssl, const char *hint);
 
  void SSL_CTX_set_psk_server_callback(SSL_CTX *ctx, SSL_psk_server_cb_func cb);
  void SSL_set_psk_server_callback(SSL *ssl, SSL_psk_server_cb_func cb);
 
- void SSL_CTX_set_psk_find_session_callback(SSL_CTX *ctx,
-                                            SSL_psk_find_session_cb_func cb);
- void SSL_set_psk_find_session_callback(SSL *s, SSL_psk_find_session_cb_func cb);
-
 =head1 DESCRIPTION
 
-TLSv1.3 Pre-Shared Keys (PSKs) and PSKs for TLSv1.2 and below are not
-compatible.
-
-Identity hints are not relevant for TLSv1.3. A server application wishing to use
-PSK ciphersuites for TLSv1.2 and below may call SSL_CTX_use_psk_identity_hint()
-to set the given B<NUL>-terminated PSK identity hint B<hint> for SSL context
-object B<ctx>. SSL_use_psk_identity_hint() sets the given B<NUL>-terminated PSK
-identity hint B<hint> for the SSL connection object B<ssl>. If B<hint> is
-B<NULL> the current hint from B<ctx> or B<ssl> is deleted.
-
-In the case where PSK identity hint is B<NULL>, the server does not send the
-ServerKeyExchange message to the client.
-
-A server application for TLSv1.2 and below must provide a callback function
-which is called when the server receives the ClientKeyExchange message from the
-client. The purpose of the callback function is to validate the
-received PSK identity and to fetch the pre-shared key used during the
-connection setup phase. The callback is set using the functions
-SSL_CTX_set_psk_server_callback() or SSL_set_psk_server_callback(). The callback
-function is given the connection in parameter B<ssl>, B<NUL>-terminated PSK
-identity sent by the client in parameter B<identity>, and a buffer B<psk> of
-length B<max_psk_len> bytes where the pre-shared key is to be stored.
-
-A client application wishing to use TLSv1.3 PSKs must set a different callback
+A client application wishing to use TLSv1.3 PSKs should set a callback
 using either SSL_CTX_set_psk_use_session_callback() or
 SSL_set_psk_use_session_callback() as appropriate.
 
@@ -77,6 +55,36 @@ case no PSK will be used but the handshake will continue. To do this the
 callback should return successfully and ensure that B<*sess> is
 NULL.
 
+Identity hints are not relevant for TLSv1.3. A server application wishing to use
+PSK ciphersuites for TLSv1.2 and below may call SSL_CTX_use_psk_identity_hint()
+to set the given B<NUL>-terminated PSK identity hint B<hint> for SSL context
+object B<ctx>. SSL_use_psk_identity_hint() sets the given B<NUL>-terminated PSK
+identity hint B<hint> for the SSL connection object B<ssl>. If B<hint> is
+B<NULL> the current hint from B<ctx> or B<ssl> is deleted.
+
+In the case where PSK identity hint is B<NULL>, the server does not send the
+ServerKeyExchange message to the client.
+
+A server application wishing to use PSKs for TLSv1.2 and below must provide a
+callback function which is called when the server receives the
+ClientKeyExchange message from the client. The purpose of the callback function
+is to validate the received PSK identity and to fetch the pre-shared key used
+during the connection setup phase. The callback is set using the functions
+SSL_CTX_set_psk_server_callback() or SSL_set_psk_server_callback(). The callback
+function is given the connection in parameter B<ssl>, B<NUL>-terminated PSK
+identity sent by the client in parameter B<identity>, and a buffer B<psk> of
+length B<max_psk_len> bytes where the pre-shared key is to be stored.
+
+The callback for use in TLSv1.2 will also work in TLSv1.3 although it is
+recommended to use SSL_CTX_set_psk_find_session_callback()
+or SSL_set_psk_find_session_callback() for this purpose instead. If TLSv1.3 has
+been negotiated then OpenSSL will first check to see if a callback has been set
+via SSL_CTX_set_psk_find_session_callback() or SSL_set_psk_find_session_callback()
+and it will use that in preference. If no such callback is present then it will
+check to see if a callback has been set via SSL_CTX_set_psk_server_callback() or
+SSL_set_psk_server_callback() and use that. In this case the handshake digest
+will default to SHA-256 for any returned PSK.
+
 =head1 NOTES
 
 A connection established via a TLSv1.3 PSK will appear as if session resumption

doc/man3/SSL_read_early_data.pod

@@ -101,7 +101,9 @@ was rejected or SSL_EARLY_DATA_NOT_SENT if no early data was sent. This function
 may be called by either the client or the server.
 
 A server uses the SSL_read_early_data() function to receive early data on a
-connection. As for SSL_write_early_data() this must be the first IO function
+connection for which early data has been enabled using
+SSL_CTX_set_max_early_data() or SSL_set_max_early_data(). As for
+SSL_write_early_data(), this must be the first IO function
 called on a connection, i.e. it must occur before any calls to
 L<SSL_write_ex(3)>, L<SSL_read_ex(3)>, L<SSL_accept(3)>, L<SSL_do_handshake(3)>,
 or other similar functions.
@@ -165,12 +167,16 @@ further action taken.
 
 When a session is created between a server and a client the server will specify
 the maximum amount of any early data that it will accept on any future
-connection attempt. By default this is approximately 16k. A server may override
-this default value by calling SSL_CTX_set_max_early_data() or
+connection attempt. By default the server does not accept early data; a
+server may indicate support for early data by calling
+SSL_CTX_set_max_early_data() or
 SSL_set_max_early_data() to set it for the whole SSL_CTX or an individual SSL
 object respectively. Similarly the SSL_CTX_get_max_early_data() and
 SSL_get_max_early_data() functions can be used to obtain the current maximum
 early data settings for the SSL_CTX and SSL objects respectively.
+Generally a server application will either use both of SSL_read_early_data()
+and SSL_CTX_set_max_early_data() (or SSL_set_max_early_data()), or neither
+of them, since there is no practical benefit from using only one of them.
 
 In the event that the current maximum early data setting for the server is
 different to that originally specified in a session that a client is resuming

doc/man3/UI_STRING.pod

@@ -120,11 +120,11 @@ UI_get0_test_string() returns the UI string action description
 string for B<UIT_VERIFY> type UI strings, NULL for any other type.
 
 UI_get_result_minsize() returns the minimum allowed result size for
-the UI string for  for B<UIT_PROMPT> and B<UIT_VERIFY> type strings,
+the UI string for B<UIT_PROMPT> and B<UIT_VERIFY> type strings,
 -1 for any other type.
 
 UI_get_result_maxsize() returns the minimum allowed result size for
-the UI string for  for B<UIT_PROMPT> and B<UIT_VERIFY> type strings,
+the UI string for B<UIT_PROMPT> and B<UIT_VERIFY> type strings,
 -1 for any other type.
 
 UI_set_result() returns 0 on success or when the UI string is of any

doc/man3/X509_STORE_add_cert.pod

@@ -0,0 +1,100 @@
+=pod
+
+=head1 NAME
+
+X509_STORE_add_cert, X509_STORE_add_crl, X509_STORE_set_depth,
+X509_STORE_set_flags, X509_STORE_set_purpose, X509_STORE_set_trust,
+X509_STORE_load_locations,
+X509_STORE_set_default_paths
+- X509_STORE manipulation
+
+=head1 SYNOPSIS
+
+ #include <openssl/x509_vfy.h>
+
+ int X509_STORE_add_cert(X509_STORE *ctx, X509 *x);
+ int X509_STORE_add_crl(X509_STORE *ctx, X509_CRL *x);
+ int X509_STORE_set_depth(X509_STORE *store, int depth);
+ int X509_STORE_set_flags(X509_STORE *ctx, unsigned long flags);
+ int X509_STORE_set_purpose(X509_STORE *ctx, int purpose);
+ int X509_STORE_set_trust(X509_STORE *ctx, int trust);
+
+ int X509_STORE_load_locations(X509_STORE *ctx,
+                               const char *file, const char *dir);
+ int X509_STORE_set_default_paths(X509_STORE *ctx);
+
+=head1 DESCRIPTION
+
+The B<X509_STORE> structure is intended to be a consolidated mechanism for
+holding information about X.509 certificates and CRLs, and constructing
+and validating chains of certificates terminating in trusted roots.
+It admits multiple lookup mechanisms and efficient scaling performance
+with large numbers of certificates, and a great deal of flexibility in
+how validation and policy checks are performed.
+
+L<X509_STORE_new(3)> creates an empty B<X509_STORE> structure, which contains
+no information about trusted certificates or where such certificates
+are located on disk, and is generally not usable.  Normally, trusted
+certificates will be added to the B<X509_STORE> to prepare it for use,
+via mechanisms such as X509_STORE_add_lookup() and X509_LOOKUP_file(), or
+PEM_read_bio_X509_AUX() and X509_STORE_add_cert().  CRLs can also be added,
+and many behaviors configured as desired.
+
+Once the B<X509_STORE> is suitably configured, X509_STORE_CTX_new() is
+used to instantiate a single-use B<X509_STORE_CTX> for each chain-building
+and verification operation.  That process includes providing the end-entity
+certificate to be verified and an additional set of untrusted certificates
+that may be used in chain-building.  As such, it is expected that the
+certificates included in the B<X509_STORE> are certificates that represent
+trusted entities such as root certificate authorities (CAs).
+OpenSSL represents these trusted certificates internally as B<X509> objects
+with an associated B<X509_CERT_AUX>, as are produced by
+PEM_read_bio_X509_AUX() and similar routines that refer to X509_AUX.
+The public interfaces that operate on such trusted certificates still
+operate on pointers to B<X509> objects, though.
+
+X509_STORE_add_cert() and X509_STORE_add_crl() add the respective object
+to the B<X509_STORE>'s local storage.  Untrusted objects should not be
+added in this way.
+
+X509_STORE_set_depth(), X509_STORE_set_flags(), X509_STORE_set_purpose(),
+X509_STORE_set_trust(), and X509_STORE_set1_param() set the default values
+for the corresponding values used in certificate chain validation.  Their
+behavior is documented in the corresponding B<X509_VERIFY_PARAM> manual
+pages, e.g., L<X509_VERIFY_PARAM_set_depth(3)>.
+
+X509_STORE_load_locations() loads trusted certificate(s) into an
+B<X509_STORE> from a given file and/or directory path.  It is permitted
+to specify just a file, just a directory, or both paths.  The certificates
+in the directory must be in hashed form, as documented in
+L<X509_LOOKUP_hash_dir(3)>.
+
+X509_STORE_set_default_paths() is somewhat misnamed, in that it does not
+set what default paths should be used for loading certificates.  Instead,
+it loads certificates into the B<X509_STORE> from the hardcoded default
+paths.
+
+=head1 RETURN VALUES
+
+X509_STORE_add_cert(), X509_STORE_add_crl(), X509_STORE_set_depth(),
+X509_STORE_set_flags(), X509_STORE_set_purpose(),
+X509_STORE_set_trust(), X509_STORE_load_locations(), and
+X509_STORE_set_default_paths() return 1 on success or 0 on failure.
+
+=head1 SEE ALSO
+
+L<X509_LOOKUP_hash_dir(3)>.
+L<X509_VERIFY_PARAM_set_depth(3)>.
+L<X509_STORE_new(3)>,
+L<X509_STORE_get0_param(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

doc/man3/d2i_X509.pod

@@ -461,7 +461,7 @@ Represents a PKCS#3 DH parameters structure.
 
 =item B<DHparamx>
 
-Represents a ANSI X9.42 DH parameters structure.
+Represents an ANSI X9.42 DH parameters structure.
 
 =item B<DSA_PUBKEY>