Latest update

doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod

@@ -0,0 +1,120 @@
+=pod
+
+=head1 NAME
+
+DEFINE_SPARSE_ARRAY_OF, ossl_sa_TYPE_new, ossl_sa_TYPE_free,
+ossl_sa_TYPE_free_leaves, ossl_sa_TYPE_num, ossl_sa_TYPE_doall,
+ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set
+- sparse array container
+
+=head1 SYNOPSIS
+
+=for comment generic
+
+ #include "internal/sparse_array.h"
+
+ typedef struct sparse_array_st OPENSSL_SA;
+
+ SPARSE_ARRAY_OF(TYPE)
+ DEFINE_SPARSE_ARRAY_OF(TYPE)
+
+ SPARSE_ARRAY_OF(TYPE) *ossl_sa_TYPE_new(void);
+ void ossl_sa_TYPE_free(const SPARSE_ARRAY_OF(TYPE) *sa);
+ void ossl_sa_TYPE_free_leaves(const SPARSE_ARRAY_OF(TYPE) *sa);
+ int ossl_sa_TYPE_num(const SPARSE_ARRAY_OF(TYPE) *sa);
+ void ossl_sa_TYPE_doall(const OPENSSL_SA *sa, void (*leaf)(size_t, void *));
+ void ossl_sa_TYPE_doall_arg(const OPENSSL_SA *sa,
+                             void (*leaf)(size_t, void *, void *), void *arg);
+ TYPE *ossl_sa_TYPE_get(const SPARSE_ARRAY_OF(TYPE) *sa, size_t idx);
+ int ossl_sa_TYPE_set(SPARSE_ARRAY_OF(TYPE) *sa, size_t idx, TYPE *value);
+
+=head1 DESCRIPTION
+
+SPARSE_ARRAY_OF() returns the name for a sparse array of the specified
+B<TYPE>.  DEFINE_STACK_OF() creates set of functions for a sparse array of
+B<TYPE>. This will mean that a pointer to type B<TYPE> is stored in each
+element of a sparse array, the type is referenced by SPARSE_ARRAY_OF(TYPE) and
+each function name begins with I<ossl_sa_TYPE_>. For example:
+
+ TYPE *ossl_sa_TYPE_get(SPARSE_ARRAY_OF(TYPE) *sa, size_t idx);
+
+ossl_sa_TYPE_num() returns the number of elements in B<sa> or 0 if B<sa> is
+B<NULL>.
+
+ossl_sa_TYPE_get() returns element B<idx> in B<sa>, where B<idx> starts at
+zero. If B<idx> refers to a value that has not been set then B<NULL> is
+returned.
+
+ossl_sa_TYPE_set() sets element B<idx> in B<sa> to B<value>, where B<idx>
+starts at zero. The sparse array will be resized as required.
+
+ossl_sa_TYPE_new() allocates a new empty sparse array.
+
+ossl_sa_TYPE_free() frees up the B<sa> structure. It does B<not> free up any
+elements of B<sa>. After this call B<sa> is no longer valid.
+
+ossl_sa_TYPE_free_leaves() frees up the B<sa> structure and all of its
+elements.  After this call B<sa> is no longer valid.
+
+ossl_sa_TYPE_doall() calls the function B<leaf> for each element in B<sa>
+in ascending index order. The index position, within the sparse array,
+of each item is passed as the first argument to the leaf function and a
+pointer to the associated value is is passed as the second argument.
+
+ossl_sa_TYPE_doall_arg() calls the function B<leaf> for each element in
+B<sa> in ascending index order. The index position, within the sparse
+array, of each item is passed as the first argument to the leaf function,
+a pointer to the associated value is passed as the second argument and
+the third argument is the user supplied B<arg>.
+
+
+=head1 NOTES
+
+Sparse arrays are an internal data structure and should B<not> be used by user
+applications.
+
+Care should be taken when accessing sparse arrays in multi-threaded
+environments.  The ossl_sa_TYPE_set operation can cause the internal structure
+of the sparse array to change which causes race conditions if the sparse array
+is accessed in a different thread.
+
+SPARSE_ARRAY_OF() and DEFINE_SPARSE_ARRAY_OF() are implemented as macros.
+
+The underlying utility B<OPENSSL_SA_> API should not be used directly.  It
+defines these functions: OPENSSL_SA_doall, OPENSSL_SA_doall_arg,
+OPENSSL_SA_free, OPENSSL_SA_free_leaves, OPENSSL_SA_get, OPENSSL_SA_new,
+OPENSSL_SA_num and OPENSSL_SA_set.
+
+=head1 RETURN VALUES
+
+ossl_sa_TYPE_num() returns the number of elements in the sparse array or B<0>
+if the passed sparse array is B<NULL>.
+
+ossl_sa_TYPE_get() returns a pointer to a sparse array element or B<NULL> if
+the element has not be set.
+
+ossl_sa_TYPE_set() return B<1> on success and B<0> on error. In the latter
+case, the elements of the sparse array remain unchanged, although the internal
+structures might have.
+
+ossl_sa_TYPE_new() returns an empty sparse array or B<NULL> if an error
+occurs.
+
+ossl_sa_TYPE_doall, ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_free() and
+ossl_sa_TYPE_free_leaves() do not return values.
+
+=head1 HISTORY
+
+This functionality was added to OpenSSL 3.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.  Copyright
+(c) 2019, Oracle and/or its affiliates.  All rights reserved.
+
+Licensed under the Apache License 2.0 (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/internal/man3/OSSL_METHOD_STORE.pod

@@ -0,0 +1,116 @@
+=pod
+
+=head1 NAME
+
+OSSL_METHOD_STORE, ossl_method_store_new, ossl_method_store_free,
+ossl_method_store_init, ossl_method_store_cleanup,
+ossl_method_store_add, ossl_method_store_remove, ossl_method_store_fetch,
+ossl_method_store_set_global_properties,
+ossl_method_store_cache_get, ossl_method_store_cache_set
+- implementation method store and query
+
+=head1 SYNOPSIS
+
+ #include "internal/property.h"
+
+ typedef struct ossl_method_store_st OSSL_METHOD_STORE;
+
+ OSSL_METHOD_STORE *ossl_method_store_new(void);
+ void ossl_method_store_free(OSSL_METHOD_STORE *store);
+ int ossl_method_store_init(void);
+ void ossl_method_store_cleanup(void);
+ int ossl_method_store_add(OSSL_METHOD_STORE *store,
+                           int nid, const char *properties,
+                           void *method, void (*method_destruct)(void *));
+ int ossl_method_store_remove(OSSL_METHOD_STORE *store,
+                              int nid, const void *method);
+ int ossl_method_store_fetch(OSSL_METHOD_STORE *store,
+                             int nid, const char *properties,
+                             void **method);
+ int ossl_method_store_set_global_properties(OSSL_METHOD_STORE *store,
+                                            const char *prop_query);
+ int ossl_method_store_cache_get(OSSL_METHOD_STORE *store, int nid,
+                                 const char *prop_query, void **method);
+ int ossl_method_store_cache_set(OSSL_METHOD_STORE *store, int nid,
+                                 const char *prop_query, void *method);
+
+=head1 DESCRIPTION
+
+OSSL_METHOD_STORE stores methods that can be queried using properties and a
+numeric identity (nid).
+
+Methods are expected to be library internal structures.
+It's left to the caller to define the exact contents.
+
+Numeric identities are expected to be an algorithm identity for the methods.
+It's left to the caller to define exactly what an algorithm is, and to allocate
+these numeric identities accordingly.
+
+The B<OSSL_METHOD_STORE> also holds an internal query cache, which is accessed
+separately (see L</Cache Functions> below).
+
+=head2 Store Functions
+
+ossl_method_store_init() initialises the method store subsystem.
+
+ossl_method_store_cleanup() cleans up and shuts down the implementation method
+store subsystem.
+
+ossl_method_store_new() create a new empty method store.
+
+ossl_method_store_free() frees resources allocated to B<store>.
+
+ossl_method_store_add() adds the B<method> to the B<store> as an instance of an
+algorithm indicated by B<nid> and the property definition B<properties>.
+The optional B<method_destruct> function is called when B<method> is being
+released from B<store>.
+
+ossl_method_store_remove() removes the B<method> identified by B<nid> from the
+B<store>.
+
+ossl_method_store_fetch() queries B<store> for an method identified by B<nid>
+that matches the property query B<prop_query>.
+The result, if any, is returned in B<method>.
+
+ossl_method_store_set_global_properties() sets method B<store> wide query
+properties to B<prop_query>.
+All subsequent fetches will need to meet both these global query properties
+and the ones passed to the ossl_method_store_free().
+
+=head2 Cache Functions
+
+ossl_method_store_cache_get() queries the cache associated with the B<store>
+for an method identified by B<nid> that matches the property query
+B<prop_query>.
+The result, if any, is returned in B<method>.
+
+ossl_method_store_cache_set() sets a cache entry identified by B<nid> with the
+property query B<prop_query> in the B<store>.
+Future cache gets will return the specified B<method>.
+
+=head1 RETURN VALUES
+
+ossl_method_store_new() a new method store object or B<NULL> on failure.
+
+ossl_method_store_free(), ossl_method_store_add(),
+ossl_method_store_remove(), ossl_method_store_fetch(),
+ossl_method_store_set_global_properties(), ossl_method_store_cache_get()
+and ossl_method_store_cache_set() return B<1> on success and B<0> on error.
+
+ossl_method_store_free() and ossl_method_store_cleanup() do not return values.
+
+=head1 HISTORY
+
+This functionality was added to OpenSSL 3.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+Copyright (c) 2019, Oracle and/or its affiliates.  All rights reserved.
+
+Licensed under the Apache License 2.0 (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/internal/man3/openssl_ctx_get_data.pod

@@ -0,0 +1,112 @@
+=pod
+
+=head1 NAME
+
+openssl_ctx_new_index, openssl_ctx_get_data - internal OPENSSL_CTX routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/ossl_typ.h>
+ #include "internal/cryptlib.h"
+
+ typedef struct openssl_ctx_method {
+     void *(*new_func)(void);
+     void (*free_func)(void *);
+ } OPENSSL_CTX_METHOD;
+
+ int openssl_ctx_new_index(const OPENSSL_CTX_METHOD *meth);
+ void *openssl_ctx_get_data(OPENSSL_CTX *ctx, int index);
+
+=head1 DESCRIPTION
+
+Internally, the OpenSSL library context C<OPENSSL_CTX> is implemented
+as a C<CRYPTO_EX_DATA>, which allows data from diverse parts of the
+library to be added and removed dynamically.
+Each such data item must have a corresponding CRYPTO_EX_DATA index
+associated with it.
+See the example further down to see how that's done.
+
+openssl_ctx_new_index() allocates a new library context index, and
+associates it with the functions given through C<meth>.
+The functions given through that method are used to create or free
+items that are stored at that index whenever a library context is
+created or freed, meaning that the code that use a data item of that
+index doesn't have to worry about that, just use the data available.
+
+Deallocation of an index happens automatically when the library
+context is freed.
+
+openssl_ctx_get_data() is used to retrieve a pointer to the data in
+the library context C<ctx> associated with the given C<index>.
+
+=head1 EXAMPLES
+
+=head2 Initialization
+
+For a type C<FOO> that should end up in the OpenSSL library context, a
+small bit of initialization is needed, i.e. to associate a constructor
+and a destructor to a new index.
+
+ /* The index will always be entirely global, and dynamically allocated */
+ static int foo_index = -1;
+
+ typedef struct foo_st {
+     int i;
+     void *data;
+ } FOO;
+
+ static void *foo_new(void)
+ {
+     FOO *ptr = OPENSSL_zalloc(sizeof(*foo));
+     if (ptr != NULL)
+         ptr->i = 42;
+     return ptr;
+ }
+ static void foo_free(void *ptr)
+ {
+     OPENSSL_free(ptr);
+ }
+ static const OPENSSL_CTX_METHOD foo_method = {
+     foo_new,
+     foo_free
+ };
+
+ static int foo_init(void)
+ {
+     foo_index = openssl_ctx_new_index(foo_method);
+
+     return foo_index != -1;
+ }
+
+=head2 Usage
+
+To get and use the data stored in the library context, simply do this:
+
+ /*
+  * ctx is received from a caller,
+  * foo_index comes from the example above
+  */
+ FOO *data = openssl_ctx_get_data(ctx, foo_index);
+
+=head1 RETURN VALUES
+
+openssl_ctx_new_index() returns -1 on error, otherwise the allocated
+index number.
+
+openssl_ctx_get_data() returns a pointer on success, or C<NULL> on
+failure.
+
+=head1 SEE ALSO
+
+L<OPENSSL_CTX(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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/man1/ciphers.pod

@@ -411,7 +411,7 @@ based on client preferences. An equal-preference is specified with square
 brackets, combining multiple selectors separated by |. For example:
 
  [ECDHE-ECDSA-CHACHA20-POLY1305|ECDHE-ECDSA-AES128-GCM-SHA256]
-
+ 
  Once an equal-preference group is used, future directives must be
  opcode-less.
 

doc/man1/dgst.pod

@@ -230,8 +230,8 @@ prior to verification.
 
 =head1 HISTORY
 
-The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0
-The FIPS-related options were removed in OpenSSL 1.1.0
+The default digest was changed from MD5 to SHA256 in OpenSSL 1.1.0.
+The FIPS-related options were removed in OpenSSL 1.1.0.
 
 =head1 COPYRIGHT
 

doc/man1/s_client.pod

@@ -208,14 +208,17 @@ Use IPv6 only.
 =item B<-servername name>
 
 Set the TLS SNI (Server Name Indication) extension in the ClientHello message to
-the given value. If both this option and the B<-noservername> are not given, the
-TLS SNI extension is still set to the hostname provided to the B<-connect> option,
-or "localhost" if B<-connect> has not been supplied. This is default since OpenSSL
-1.1.1.
+the given value. 
+If B<-servername> is not provided, the TLS SNI extension will be populated with 
+the name given to B<-connect> if it follows a DNS name format. If B<-connect> is 
+not provided either, the SNI is set to "localhost".
+This is the default since OpenSSL 1.1.1.
 
-Even though SNI name should normally be a DNS name and not an IP address, this
-option will not make the distinction when parsing B<-connect> and will send
-IP address if one passed.
+Even though SNI should normally be a DNS name and not an IP address, if 
+B<-servername> is provided then that name will be sent, regardless of whether 
+it is a DNS name or not.
+
+This option cannot be used in conjuction with B<-noservername>.
 
 =item B<-noservername>
 

doc/man3/CRYPTO_get_ex_new_index.pod

@@ -3,8 +3,9 @@
 =head1 NAME
 
 CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup,
-CRYPTO_free_ex_index, CRYPTO_get_ex_new_index, CRYPTO_set_ex_data,
-CRYPTO_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data
+CRYPTO_free_ex_index, CRYPTO_get_ex_new_index,
+CRYPTO_alloc_ex_data, CRYPTO_set_ex_data, CRYPTO_get_ex_data,
+CRYPTO_free_ex_data, CRYPTO_new_ex_data
 - functions supporting application-specific data
 
 =head1 SYNOPSIS
@@ -26,6 +27,9 @@ CRYPTO_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data
 
  int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad)
 
+ int CRYPTO_alloc_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad,
+                          int idx);
+
  int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);
 
  void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);
@@ -114,7 +118,8 @@ new_func() is called for every defined index. There is no requirement
 that the entire parent, or containing, structure has been set up.
 The new_func() is typically used only to allocate memory to store the
 exdata, and perhaps an "initialized" flag within that memory.
-The exdata value should be set by calling CRYPTO_set_ex_data().
+The exdata value may be allocated later on with CRYPTO_alloc_ex_data(),
+or may be set by calling CRYPTO_set_ex_data().
 
 When a structure is free'd (such as SSL_CTX_free()) then the
 free_func() is called for every defined index.  Again, the state of the
@@ -147,14 +152,18 @@ will fail.
 
 CRYPTO_get_ex_new_index() returns a new index or -1 on failure.
 
-CRYPTO_free_ex_index() and
-CRYPTO_set_ex_data() return 1 on success or 0 on failure.
+CRYPTO_free_ex_index(), CRYPTO_alloc_ex_data() and CRYPTO_set_ex_data()
+return 1 on success or 0 on failure. 
 
 CRYPTO_get_ex_data() returns the application data or NULL on failure;
 note that NULL may be a valid value.
 
 dup_func() should return 0 for failure and 1 for success.
 
+=head1 HISTORY
+
+CRYPTO_alloc_ex_data() was added in OpenSSL 3.0.0.
+
 =head1 COPYRIGHT
 
 Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.

doc/man3/EC_GROUP_copy.pod

@@ -11,7 +11,7 @@ EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed,
 EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree,
 EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp,
 EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis,
-EC_GROUP_get_pentanomial_basis
+EC_GROUP_get_pentanomial_basis, EC_GROUP_get0_field
 - Functions for manipulating EC_GROUP objects
 
 =head1 SYNOPSIS
@@ -32,6 +32,7 @@ EC_GROUP_get_pentanomial_basis
  int EC_GROUP_order_bits(const EC_GROUP *group);
  int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx);
  const BIGNUM *EC_GROUP_get0_cofactor(const EC_GROUP *group);
+ const BIGNUM *EC_GROUP_get0_field(const EC_GROUP *group);
 
  void EC_GROUP_set_curve_name(EC_GROUP *group, int nid);
  int EC_GROUP_get_curve_name(const EC_GROUP *group);
@@ -177,6 +178,8 @@ specified curve respectively. If there is no curve name associated with a curve
 EC_GROUP_get0_order() returns an internal pointer to the group order.
 EC_GROUP_order_bits() returns the number of bits in the group order.
 EC_GROUP_get0_cofactor() returns an internal pointer to the group cofactor.
+EC_GROUP_get0_field() returns an internal pointer to the group field. For curves over GF(p), this is the modulus; for curves
+over GF(2^m), this is the irreducible polynomial defining the field.
 
 EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not
 specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified.

doc/man3/EVP_KDF_CTX.pod

@@ -0,0 +1,217 @@
+=pod
+
+=head1 NAME
+
+EVP_KDF_CTX, EVP_KDF_CTX_new_id, EVP_KDF_CTX_free, EVP_KDF_reset,
+EVP_KDF_ctrl, EVP_KDF_vctrl, EVP_KDF_ctrl_str, EVP_KDF_size,
+EVP_KDF_derive - EVP KDF routines
+
+=head1 SYNOPSIS
+
+ #include <openssl/kdf.h>
+
+ typedef struct evp_kdf_ctx_st EVP_KDF_CTX;
+
+ EVP_KDF_CTX *EVP_KDF_CTX_new_id(int id);
+ void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx);
+ void EVP_KDF_reset(EVP_KDF_CTX *ctx);
+ int EVP_KDF_ctrl(EVP_KDF_CTX *ctx, int cmd, ...);
+ int EVP_KDF_vctrl(EVP_KDF_CTX *ctx, int cmd, va_list args);
+ int EVP_KDF_ctrl_str(EVP_KDF_CTX *ctx, const char *type, const char *value);
+ size_t EVP_KDF_size(EVP_KDF_CTX *ctx);
+ int EVP_KDF_derive(EVP_KDF_CTX *ctx, unsigned char *key, size_t keylen);
+
+=head1 DESCRIPTION
+
+The EVP KDF routines are a high level interface to Key Derivation Function
+algorithms and should be used instead of algorithm-specific functions.
+
+After creating a C<EVP_KDF_CTX> for the required algorithm using
+EVP_KDF_CTX_new_id(), inputs to the algorithm are supplied using calls to
+EVP_KDF_ctrl(), EVP_KDF_vctrl() or EVP_KDF_ctrl_str() before calling
+EVP_KDF_derive() to derive the key.
+
+=head2 Types
+
+B<EVP_KDF_CTX> is a context type that holds the algorithm inputs.
+
+=head2 Context manipulation functions
+
+EVP_KDF_CTX_new_id() creates a KDF context for the algorithm identified by the
+specified NID.
+
+EVP_KDF_CTX_free() frees up the context C<ctx>.  If C<ctx> is C<NULL>, nothing
+is done.
+
+=head2 Computing functions
+
+EVP_KDF_reset() resets the context to the default state as if the context
+had just been created.
+
+EVP_KDF_ctrl() is used to provide inputs to the KDF algorithm prior to
+EVP_KDF_derive() being called.  The inputs that may be provided will vary
+depending on the KDF algorithm or its implementation.  This functions takes
+variable arguments, the exact expected arguments depend on C<cmd>.
+See L</CONTROLS> below for a description of standard controls.
+
+EVP_KDF_vctrl() is the variant of EVP_KDF_ctrl() that takes a C<va_list>
+argument instead of variadic arguments.
+
+EVP_KDF_ctrl_str() allows an application to send an algorithm specific control
+operation to a context C<ctx> in string form.  This is intended to be used for
+options specified on the command line or in text files.
+
+EVP_KDF_size() returns the output size if the algorithm produces a fixed amount
+of output and C<SIZE_MAX> otherwise.  If an error occurs then 0 is returned.
+For some algorithms an error may result if input parameters necessary to
+calculate a fixed output size have not yet been supplied.
+
+EVP_KDF_derive() derives C<keylen> bytes of key material and places it in the
+C<key> buffer.  If the algorithm produces a fixed amount of output then an
+error will occur unless the C<keylen> parameter is equal to that output size,
+as returned by EVP_KDF_size().
+
+=head1 CONTROLS
+
+The standard controls are:
+
+=over 4
+
+=item B<EVP_KDF_CTRL_SET_PASS>
+
+This control expects two arguments: C<unsigned char *pass>, C<size_t passlen>
+
+Some KDF implementations require a password.  For those KDF implementations
+that support it, this control sets the password.
+
+EVP_KDF_ctrl_str() takes two type strings for this control:
+
+=over 4
+
+=item "pass"
+
+The value string is used as is.
+
+=item "hexpass"
+
+The value string is expected to be a hexadecimal number, which will be
+decoded before being passed on as the control value.
+
+=back
+
+=item B<EVP_KDF_CTRL_SET_SALT>
+
+This control expects two arguments: C<unsigned char *salt>, C<size_t saltlen>
+
+Some KDF implementations can take a salt.  For those KDF implementations that
+support it, this control sets the salt.
+
+The default value, if any, is implementation dependent.
+
+EVP_KDF_ctrl_str() takes two type strings for this control:
+
+=over 4
+
+=item "salt"
+
+The value string is used as is.
+
+=item "hexsalt"
+
+The value string is expected to be a hexadecimal number, which will be
+decoded before being passed on as the control value.
+
+=back
+
+=item B<EVP_KDF_CTRL_SET_ITER>
+
+This control expects one argument: C<int iter>
+
+Some KDF implementations require an iteration count. For those KDF implementations that support it, this control sets the iteration count.
+
+The default value, if any, is implementation dependent.
+
+EVP_KDF_ctrl_str() type string: "iter"
+
+The value string is expected to be a decimal number.
+
+=item B<EVP_KDF_CTRL_SET_MD>
+
+This control expects one argument: C<EVP_MD *md>
+
+For MAC implementations that use a message digest as an underlying computation
+algorithm, this control set what the digest algorithm should be.
+
+EVP_KDF_ctrl_str() type string: "md"
+
+The value string is expected to be the name of a digest.
+
+=item B<EVP_KDF_CTRL_SET_KEY>
+
+This control expects two arguments: C<unsigned char *key>, C<size_t keylen>
+
+Some KDF implementations require a key.  For those KDF implementations that
+support it, this control sets the key.
+
+EVP_KDF_ctrl_str() takes two type strings for this control:
+
+=over 4
+
+=item "key"
+
+The value string is used as is.
+
+=item "hexkey"
+
+The value string is expected to be a hexadecimal number, which will be
+decoded before being passed on as the control value.
+
+=back
+
+=item B<EVP_KDF_CTRL_SET_MAXMEM_BYTES>
+
+This control expects one argument: C<uint64_t maxmem_bytes>
+
+Memory-hard password-based KDF algorithms, such as scrypt, use an amount of
+memory that depends on the load factors provided as input.  For those KDF
+implementations that support it, this control sets an upper limit on the amount
+of memory that may be consumed while performing a key derivation.  If this
+memory usage limit is exceeded because the load factors are chosen too high,
+the key derivation will fail.
+
+The default value is implementation dependent.
+
+EVP_KDF_ctrl_str() type string: "maxmem_bytes"
+
+The value string is expected to be a decimal number.
+
+=back
+
+=head1 RETURN VALUES
+
+EVP_KDF_CTX_new_id() returns either the newly allocated C<EVP_KDF_CTX>
+structure or C<NULL> if an error occurred.
+
+EVP_KDF_CTX_free() and EVP_KDF_reset() do not return a value.
+
+EVP_KDF_size() returns the output size.  C<SIZE_MAX> is returned to indicate
+that the algorithm produces a variable amount of output; 0 to indicate failure.
+
+The remaining functions return 1 for success and 0 or a negative value for
+failure.  In particular, a return value of -2 indicates the operation is not
+supported by the KDF algorithm.
+
+=head1 SEE ALSO
+
+L<EVP_KDF_SCRYPT(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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/OPENSSL_CTX.pod

@@ -0,0 +1,48 @@
+=pod
+
+=head1 NAME
+
+OPENSSL_CTX, OPENSSL_CTX_new, OPENSSL_CTX_free - OpenSSL library context
+
+=head1 SYNOPSIS
+
+ #include <openssl/crypto.h>
+
+ typedef struct openssl_ctx_st OPENSSL_CTX;
+
+ OPENSSL_CTX *OPENSSL_CTX_new(void);
+ void OPENSSL_CTX_free(OPENSSL_CTX *ctx);
+
+=head1 DESCRIPTION
+
+C<OPENSSL_CTX> is an internal OpenSSL library context type.
+Applications may allocate their own, but may also use C<NULL> to use
+the internal default context with functions that take a C<OPENSSL_CTX>
+argument.
+
+OPENSSL_CTX_new() creates a new OpenSSL library context.
+
+OPENSSL_CTX_free() frees the given C<ctx>.
+
+=head1 RETURN VALUES
+
+OPENSSL_CTX_new() return a library context pointer on success, or
+C<NULL> on error.
+
+OPENSSL_CTX_free() doesn't return any value.
+
+=head1 HISTORY
+
+OPENSSL_CTX, OPENSSL_CTX_new() and OPENSSL_CTX_free()
+were added in OpenSSL 3.0.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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/OPENSSL_LH_COMPFUNC.pod

@@ -6,7 +6,7 @@ LHASH, DECLARE_LHASH_OF,
 OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DOALL_FUNC,
 LHASH_DOALL_ARG_FN_TYPE,
 IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN,
-lh_TYPE_new, lh_TYPE_free,
+lh_TYPE_new, lh_TYPE_free, lh_TYPE_flush,
 lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve,
 lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table
 
@@ -20,6 +20,7 @@ lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table
 
  LHASH *lh_TYPE_new(OPENSSL_LH_HASHFUNC hash, OPENSSL_LH_COMPFUNC compare);
  void lh_TYPE_free(LHASH_OF(TYPE) *table);
+ void lh_TYPE_flush(LHASH_OF(TYPE) *table);
 
  TYPE *lh_TYPE_insert(LHASH_OF(TYPE) *table, TYPE *data);
  TYPE *lh_TYPE_delete(LHASH_OF(TYPE) *table, TYPE *data);
@@ -95,6 +96,11 @@ B<table>. Allocated hash table entries will not be freed; consider
 using lh_TYPE_doall() to deallocate any remaining entries in the
 hash table (see below).
 
+lh_TYPE_flush() empties the B<LHASH_OF(TYPE)> structure B<table>. New
+entries can be added to the flushed table.  Allocated hash table entries
+will not be freed; consider using lh_TYPE_doall() to deallocate any
+remaining entries in the hash table (see below).
+
 lh_TYPE_insert() inserts the structure pointed to by B<data> into
 B<table>.  If there already is an entry with the same key, the old
 value is replaced. Note that lh_TYPE_insert() stores pointers, the
@@ -173,7 +179,8 @@ B<NULL> otherwise.
 lh_TYPE_error() returns 1 if an error occurred in the last operation, 0
 otherwise. It's meaningful only after non-retrieve operations.
 
-lh_TYPE_free(), lh_TYPE_doall() and lh_TYPE_doall_arg() return no values.
+lh_TYPE_free(), lh_TYPE_flush, lh_TYPE_doall() and lh_TYPE_doall_arg()
+return no values.
 
 =head1 NOTE
 

doc/man3/RIPEMD160_Init.pod

@@ -13,7 +13,7 @@ RIPEMD-160 hash function
                           unsigned char *md);
 
  int RIPEMD160_Init(RIPEMD160_CTX *c);
- int RIPEMD160_Update(RIPEMD_CTX *c, const void *data, unsigned long len);
+ int RIPEMD160_Update(RIPEMD160_CTX *c, const void *data, unsigned long len);
  int RIPEMD160_Final(unsigned char *md, RIPEMD160_CTX *c);
 
 =head1 DESCRIPTION

doc/man3/SSL_CONF_cmd.pod

@@ -308,11 +308,6 @@ Attempts to pad TLSv1.3 records so that they are a multiple of B<value> in
 length on send. A B<value> of 0 or 1 turns off padding. Otherwise, the
 B<value> must be >1 or <=16384.
 
-=item B<NoRenegotiation>
-
-Disables all attempts at renegotiation in TLSv1.2 and earlier, same as setting
-B<SSL_OP_NO_RENEGOTIATION>.
-
 =item B<SignatureAlgorithms>
 
 This sets the supported signature algorithms for TLSv1.2 and TLSv1.3.
@@ -456,6 +451,9 @@ Only used by servers.
 B<NoResumptionOnRenegotiation>: set
 B<SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION> flag. Only used by servers.
 
+B<NoRenegotiation>: disables all attempts at renegotiation in TLSv1.2 and
+earlier, same as setting B<SSL_OP_NO_RENEGOTIATION>.
+
 B<UnsafeLegacyRenegotiation>: permits the use of unsafe legacy renegotiation.
 Equivalent to B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>.
 
@@ -486,6 +484,10 @@ specification. Some applications may be able to mitigate the replay risks in
 other ways and in such cases the built-in OpenSSL functionality is not required.
 Disabling anti-replay is equivalent to setting B<SSL_OP_NO_ANTI_REPLAY>.
 
+B<ExtendedMasterSecret>: use extended master secret extension, enabled by
+default. Inverse of B<SSL_OP_NO_EXTENDED_MASTER_SECRET>: that is,
+B<-ExtendedMasterSecret> is the same as setting B<SSL_OP_NO_EXTENDED_MASTER_SECRET>.
+
 =item B<VerifyMode>
 
 The B<value> argument is a comma separated list of flags to set.

doc/man3/SSL_CTX_set_info_callback.pod

@@ -92,17 +92,13 @@ Callback has been called due to an alert being sent or received.
 
 =item SSL_CB_HANDSHAKE_START
 
-Callback has been called because a new handshake is started. In TLSv1.3 this is
-also used for the start of post-handshake message exchanges such as for the
-exchange of session tickets, or for key updates. It also occurs when resuming a
-handshake following a pause to handle early data.
+Callback has been called because a new handshake is started. It also occurs when
+resuming a handshake following a pause to handle early data.
 
-=item SSL_CB_HANDSHAKE_DONE           0x20
+=item SSL_CB_HANDSHAKE_DONE
 
-Callback has been called because a handshake is finished. In TLSv1.3 this is
-also used at the end of an exchange of post-handshake messages such as for
-session tickets or key updates. It also occurs if the handshake is paused to
-allow the exchange of early data.
+Callback has been called because a handshake is finished.  It also occurs if the
+handshake is paused to allow the exchange of early data.
 
 =back
 

doc/man3/SSL_CTX_set_options.pod

@@ -198,6 +198,14 @@ RFC7366 Encrypt-then-MAC option on TLS and DTLS connection.
 If this option is set, Encrypt-then-MAC is disabled. Clients will not
 propose, and servers will not accept the extension.
 
+=item SSL_OP_NO_EXTENDED_MASTER_SECRET
+
+Normally clients and servers will transparently attempt to negotiate the
+RFC7627 Extended Master Secret option on TLS and DTLS connection.
+
+If this option is set, Extended Master Secret is disabled. Clients will
+not propose, and servers will not accept the extension.
+
 =item SSL_OP_NO_RENEGOTIATION
 
 Disable all renegotiation in TLSv1.2 and earlier. Do not send HelloRequest
@@ -366,9 +374,11 @@ OpenSSL 0.9.8m.
 The B<SSL_OP_PRIORITIZE_CHACHA> and B<SSL_OP_NO_RENEGOTIATION> options
 were added in OpenSSL 1.1.1.
 
+The B<SSL_OP_NO_EXTENDED_MASTER_SECRET> option was added in OpenSSL 3.0.0.
+
 =head1 COPYRIGHT
 
-Copyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2019 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy

doc/man7/EVP_KDF_HKDF.pod

@@ -0,0 +1,180 @@
+=pod
+
+=head1 NAME
+
+EVP_KDF_HKDF - The HKDF EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+Support for computing the B<HKDF> KDF through the B<EVP_KDF> API.
+
+The EVP_KDF_HKDF algorithm implements the HKDF key derivation function.
+HKDF follows the "extract-then-expand" paradigm, where the KDF logically
+consists of two modules. The first stage takes the input keying material
+and "extracts" from it a fixed-length pseudorandom key K. The second stage
+"expands" the key K into several additional pseudorandom keys (the output
+of the KDF).
+
+=head2 Numeric identity
+
+B<EVP_KDF_HKDF> is the numeric identity for this implementation; it
+can be used with the EVP_KDF_CTX_new_id() function.
+
+=head2 Supported controls
+
+The supported controls are:
+
+=over 4
+
+=item B<EVP_KDF_CTRL_SET_SALT>
+
+=item B<EVP_KDF_CTRL_SET_MD>
+
+=item B<EVP_KDF_CTRL_SET_KEY>
+
+These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
+
+=item B<EVP_KDF_CTRL_RESET_HKDF_INFO>
+
+This control does not expect any arguments.
+
+Resets the context info buffer to zero length.
+
+=item B<EVP_KDF_CTRL_ADD_HKDF_INFO>
+
+This control expects two arguments: C<unsigned char *info>, C<size_t infolen>
+
+Sets the info value to the first B<infolen> bytes of the buffer B<info>.  If a
+value is already set, the contents of the buffer are appended to the existing
+value.
+
+The total length of the context info buffer cannot exceed 1024 bytes;
+this should be more than enough for any normal use of HKDF.
+
+EVP_KDF_ctrl_str() takes two type strings for this control:
+
+=over 4
+
+=item "info"
+
+The value string is used as is.
+
+=item "hexinfo"
+
+The value string is expected to be a hexadecimal number, which will be
+decoded before being passed on as the control value.
+
+=back
+
+=item B<EVP_KDF_CTRL_SET_HKDF_MODE>
+
+This control expects one argument: C<int mode>
+
+Sets the mode for the HKDF operation. There are three modes that are currently
+defined:
+
+=over 4
+
+=item EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND
+
+This is the default mode.  Calling L<EVP_KDF_derive(3)> on an EVP_KDF_CTX set
+up for HKDF will perform an extract followed by an expand operation in one go.
+The derived key returned will be the result after the expand operation. The
+intermediate fixed-length pseudorandom key K is not returned.
+
+In this mode the digest, key, salt and info values must be set before a key is
+derived otherwise an error will occur.
+
+=item EVP_KDF_HKDF_MODE_EXTRACT_ONLY
+
+In this mode calling L<EVP_KDF_derive(3)> will just perform the extract
+operation. The value returned will be the intermediate fixed-length pseudorandom
+key K.  The C<keylen> parameter must match the size of K, which can be looked
+up by calling EVP_KDF_size() after setting the mode and digest.
+
+The digest, key and salt values must be set before a key is derived otherwise
+an error will occur.
+
+=item EVP_KDF_HKDF_MODE_EXPAND_ONLY
+
+In this mode calling L<EVP_KDF_derive(3)> will just perform the expand
+operation. The input key should be set to the intermediate fixed-length
+pseudorandom key K returned from a previous extract operation.
+
+The digest, key and info values must be set before a key is derived otherwise
+an error will occur.
+
+=back
+
+EVP_KDF_ctrl_str() type string: "mode"
+
+The value string is expected to be one of: "EXTRACT_AND_EXPAND", "EXTRACT_ONLY"
+or "EXPAND_ONLY".
+
+=back
+
+=head1 NOTES
+
+A context for HKDF can be obtained by calling:
+
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
+
+The output length of an HKDF expand operation is specified via the C<keylen>
+parameter to the L<EVP_KDF_derive(3)> function.  When using
+EVP_KDF_HKDF_MODE_EXTRACT_ONLY the C<keylen> parameter must equal the size of
+the intermediate fixed-length pseudorandom key otherwise an error will occur.
+For that mode, the fixed output size can be looked up by calling EVP_KDF_size()
+after setting the mode and digest on the C<EVP_KDF_CTX>.
+
+=head1 EXAMPLE
+
+This example derives 10 bytes using SHA-256 with the secret key "secret",
+salt value "salt" and info value "label":
+
+ EVP_KDF_CTX *kctx;
+ unsigned char out[10];
+
+ kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
+
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
+     error("EVP_KDF_CTRL_SET_MD");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
+     error("EVP_KDF_CTRL_SET_SALT");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
+     error("EVP_KDF_CTRL_SET_KEY");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_HKDF_INFO, "label", (size_t)5) <= 0) {
+     error("EVP_KDF_CTRL_ADD_HKDF_INFO");
+ }
+ if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+     error("EVP_KDF_derive");
+ }
+
+ EVP_KDF_CTX_free(kctx);
+
+=head1 CONFORMING TO
+
+RFC 5869
+
+=head1 SEE ALSO
+
+L<EVP_KDF_CTX>,
+L<EVP_KDF_CTX_new_id(3)>,
+L<EVP_KDF_CTX_free(3)>,
+L<EVP_KDF_ctrl(3)>,
+L<EVP_KDF_size(3)>,
+L<EVP_KDF_derive(3)>,
+L<EVP_KDF_CTX(3)/CONTROLS>
+
+=head1 COPYRIGHT
+
+Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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/man7/EVP_KDF_PBKDF2.pod

@@ -0,0 +1,78 @@
+=pod
+
+=head1 NAME
+
+EVP_KDF_PBKDF2 - The PBKDF2 EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+Support for computing the B<PBKDF2> password-based KDF through the B<EVP_KDF>
+API.
+
+The EVP_KDF_PBKDF2 algorithm implements the PBKDF2 password-based key
+derivation function, as described in RFC 2898; it derives a key from a password
+using a salt and iteration count.
+
+=head2 Numeric identity
+
+B<EVP_KDF_PBKDF2> is the numeric identity for this implementation; it
+can be used with the EVP_KDF_CTX_new_id() function.
+
+=head2 Supported controls
+
+The supported controls are:
+
+=over 4
+
+=item B<EVP_KDF_CTRL_SET_PASS>
+
+=item B<EVP_KDF_CTRL_SET_SALT>
+
+=item B<EVP_KDF_CTRL_SET_ITER>
+
+=item B<EVP_KDF_CTRL_SET_MD>
+
+These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
+
+B<iter> is the iteration count and its value should be greater than or equal to
+1. RFC 2898 suggests an iteration count of at least 1000.  The default value is
+2048.  Any B<iter> less than 1 is treated as a single iteration.
+
+=back
+
+=head1 NOTES
+
+A typical application of this algorithm is to derive keying material for an
+encryption algorithm from a password in the B<pass>, a salt in B<salt>,
+and an iteration count.
+
+Increasing the B<iter> parameter slows down the algorithm which makes it
+harder for an attacker to perform a brute force attack using a large number
+of candidate passwords.
+
+No assumption is made regarding the given password; it is simply treated as a
+byte sequence.
+
+=head1 CONFORMING TO
+
+RFC 2898
+
+=head1 SEE ALSO
+
+L<EVP_KDF_CTX>,
+L<EVP_KDF_CTX_new_id(3)>,
+L<EVP_KDF_CTX_free(3)>,
+L<EVP_KDF_ctrl(3)>,
+L<EVP_KDF_derive(3)>,
+L<EVP_KDF_CTX(3)/CONTROLS>
+
+=head1 COPYRIGHT
+
+Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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/man7/EVP_KDF_SCRYPT.pod

@@ -2,11 +2,14 @@
 
 =head1 NAME
 
-scrypt - EVP_PKEY scrypt KDF support
+EVP_KDF_SCRYPT - The scrypt EVP_KDF implementation
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_SCRYPT algorithm implements the scrypt password based key
+Support for computing the B<scrypt> password-based KDF through the B<EVP_KDF>
+API.
+
+The EVP_KDF_SCRYPT algorithm implements the scrypt password-based key
 derivation function, as described in RFC 7914.  It is memory-hard in the sense
 that it deliberately requires a significant amount of RAM for efficient
 computation. The intention of this is to render brute forcing of passwords on
@@ -26,49 +29,82 @@ computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N =
 2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for
 this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5
 GHz), this computation takes about 3 seconds. When N, r or p are not specified,
-they default to 1048576, 8, and 1, respectively. The default amount of RAM that
+they default to 1048576, 8, and 1, respectively. The maximum amount of RAM that
 may be used by scrypt defaults to 1025 MiB.
 
+=head2 Numeric identity
+
+B<EVP_KDF_SCRYPT> is the numeric identity for this implementation; it
+can be used with the EVP_KDF_CTX_new_id() function.
+
+=head2 Supported controls
+
+The supported controls are:
+
+=over 4
+
+=item B<EVP_KDF_CTRL_SET_PASS>
+
+=item B<EVP_KDF_CTRL_SET_SALT>
+
+These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
+
+=item B<EVP_KDF_CTRL_SET_SCRYPT_N>
+
+=item B<EVP_KDF_CTRL_SET_SCRYPT_R>
+
+=item B<EVP_KDF_CTRL_SET_SCRYPT_P>
+
+B<EVP_KDF_CTRL_SET_SCRYPT_N> expects one argument: C<uint64_t N>
+
+B<EVP_KDF_CTRL_SET_SCRYPT_R> expects one argument: C<uint32_t r>
+
+B<EVP_KDF_CTRL_SET_SCRYPT_P> expects one argument: C<uint32_t p>
+
+These controls configure the scrypt work factors N, r and p.
+
+EVP_KDF_ctrl_str() type strings: "N", "r" and "p", respectively.
+
+The corresponding value strings are expected to be decimal numbers.
+
+=back
+
 =head1 NOTES
 
 A context for scrypt can be obtained by calling:
 
- EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL);
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SCRYPT);
 
 The output length of an scrypt key derivation is specified via the
-length parameter to the L<EVP_PKEY_derive(3)> function.
+B<keylen> parameter to the L<EVP_KDF_derive(3)> function.
 
 =head1 EXAMPLE
 
-This example derives a 64-byte long test vector using scrypt using the password
+This example derives a 64-byte long test vector using scrypt with the password
 "password", salt "NaCl" and N = 1024, r = 8, p = 16.
 
- EVP_PKEY_CTX *pctx;
+ EVP_KDF_CTX *kctx;
  unsigned char out[64];
 
- size_t outlen = sizeof(out);
- pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_SCRYPT, NULL);
+ kctx = EVP_KDF_CTX_new_id(EVP_KDF_SCRYPT);
 
- if (EVP_PKEY_derive_init(pctx) <= 0) {
-     error("EVP_PKEY_derive_init");
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_PASS, "password", (size_t)8) <= 0) {
+     error("EVP_KDF_CTRL_SET_PASS");
  }
- if (EVP_PKEY_CTX_set1_pbe_pass(pctx, "password", 8) <= 0) {
-     error("EVP_PKEY_CTX_set1_pbe_pass");
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "NaCl", (size_t)4) <= 0) {
+     error("EVP_KDF_CTRL_SET_SALT");
  }
- if (EVP_PKEY_CTX_set1_scrypt_salt(pctx, "NaCl", 4) <= 0) {
-     error("EVP_PKEY_CTX_set1_scrypt_salt");
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_N, (uint64_t)1024) <= 0) {
+     error("EVP_KDF_CTRL_SET_SCRYPT_N");
  }
- if (EVP_PKEY_CTX_set_scrypt_N(pctx, 1024) <= 0) {
-     error("EVP_PKEY_CTX_set_scrypt_N");
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_R, (uint32_t)8) <= 0) {
+     error("EVP_KDF_CTRL_SET_SCRYPT_R");
  }
- if (EVP_PKEY_CTX_set_scrypt_r(pctx, 8) <= 0) {
-     error("EVP_PKEY_CTX_set_scrypt_r");
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_P, (uint32_t)16) <= 0) {
+     error("EVP_KDF_CTRL_SET_SCRYPT_P");
  }
- if (EVP_PKEY_CTX_set_scrypt_p(pctx, 16) <= 0) {
-     error("EVP_PKEY_CTX_set_scrypt_p");
- }
- if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) {
-     error("EVP_PKEY_derive");
+ if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+     error("EVP_KDF_derive");
  }
 
  {
@@ -86,7 +122,7 @@ This example derives a 64-byte long test vector using scrypt using the password
      assert(!memcmp(out, expected, sizeof(out)));
  }
 
- EVP_PKEY_CTX_free(pctx);
+ EVP_KDF_CTX_free(kctx);
 
 =head1 CONFORMING TO
 
@@ -94,14 +130,12 @@ RFC 7914
 
 =head1 SEE ALSO
 
-L<EVP_PKEY_CTX_set1_scrypt_salt(3)>,
-L<EVP_PKEY_CTX_set_scrypt_N(3)>,
-L<EVP_PKEY_CTX_set_scrypt_r(3)>,
-L<EVP_PKEY_CTX_set_scrypt_p(3)>,
-L<EVP_PKEY_CTX_set_scrypt_maxmem_bytes(3)>,
-L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_CTX_ctrl_str(3)>,
-L<EVP_PKEY_derive(3)>
+L<EVP_KDF_CTX>,
+L<EVP_KDF_CTX_new_id(3)>,
+L<EVP_KDF_CTX_free(3)>,
+L<EVP_KDF_ctrl(3)>,
+L<EVP_KDF_derive(3)>,
+L<EVP_KDF_CTX(3)/CONTROLS>
 
 =head1 COPYRIGHT
 

doc/man7/EVP_KDF_TLS1_PRF.pod

@@ -0,0 +1,142 @@
+=pod
+
+=head1 NAME
+
+EVP_KDF_TLS1_PRF - The TLS1 PRF EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+Support for computing the B<TLS1> PRF through the B<EVP_KDF> API.
+
+The EVP_KDF_TLS1_PRF algorithm implements the PRF used by TLS versions up to
+and including TLS 1.2.
+
+=head2 Numeric identity
+
+B<EVP_KDF_TLS1_PRF> is the numeric identity for this implementation; it
+can be used with the EVP_KDF_CTX_new_id() function.
+
+=head2 Supported controls
+
+The supported controls are:
+
+=over 4
+
+=item B<EVP_KDF_CTRL_SET_MD>
+
+This control works as described in L<EVP_KDF_CTX(3)/CONTROLS>.
+
+The C<EVP_KDF_CTRL_SET_MD> control is used to set the message digest associated
+with the TLS PRF.  EVP_md5_sha1() is treated as a special case which uses the
+PRF algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1.
+
+=item B<EVP_KDF_CTRL_SET_TLS_SECRET>
+
+This control expects two arguments: C<unsigned char *sec>, C<size_t seclen>
+
+Sets the secret value of the TLS PRF to B<seclen> bytes of the buffer B<sec>.
+Any existing secret value is replaced.
+
+EVP_KDF_ctrl_str() takes two type strings for this control:
+
+=over 4
+
+=item "secret"
+
+The value string is used as is.
+
+=item "hexsecret"
+
+The value string is expected to be a hexadecimal number, which will be
+decoded before being passed on as the control value.
+
+=back
+
+=item B<EVP_KDF_CTRL_RESET_TLS_SEED>
+
+This control does not expect any arguments.
+
+Resets the context seed buffer to zero length.
+
+=item B<EVP_KDF_CTRL_ADD_TLS_SEED>
+
+This control expects two arguments: C<unsigned char *seed>, C<size_t seedlen>
+
+Sets the seed to B<seedlen> bytes of B<seed>.  If a seed is already set it is
+appended to the existing value.
+
+The total length of the context seed buffer cannot exceed 1024 bytes;
+this should be more than enough for any normal use of the TLS PRF.
+
+EVP_KDF_ctrl_str() takes two type strings for this control:
+
+=over 4
+
+=item "seed"
+
+The value string is used as is.
+
+=item "hexseed"
+
+The value string is expected to be a hexadecimal number, which will be
+decoded before being passed on as the control value.
+
+=back
+
+=back
+
+=head1 NOTES
+
+A context for the TLS PRF can be obtained by calling:
+
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF, NULL);
+
+The digest, secret value and seed must be set before a key is derived otherwise
+an error will occur.
+
+The output length of the PRF is specified by the C<keylen> parameter to the
+EVP_KDF_derive() function.
+
+=head1 EXAMPLE
+
+This example derives 10 bytes using SHA-256 with the secret key "secret"
+and seed value "seed":
+
+ EVP_KDF_CTX *kctx;
+ unsigned char out[10];
+
+ kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF);
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
+     error("EVP_KDF_CTRL_SET_MD");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_TLS_SECRET,
+                  "secret", (size_t)6) <= 0) {
+     error("EVP_KDF_CTRL_SET_TLS_SECRET");
+ }
+ if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_TLS_SEED, "seed", (size_t)4) <= 0) {
+     error("EVP_KDF_CTRL_ADD_TLS_SEED");
+ }
+ if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+     error("EVP_KDF_derive");
+ }
+ EVP_KDF_CTX_free(kctx);
+
+=head1 SEE ALSO
+
+L<EVP_KDF_CTX>,
+L<EVP_KDF_CTX_new_id(3)>,
+L<EVP_KDF_CTX_free(3)>,
+L<EVP_KDF_ctrl(3)>,
+L<EVP_KDF_derive(3)>,
+L<EVP_KDF_CTX(3)/CONTROLS>
+
+=head1 COPYRIGHT
+
+Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (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/man7/openssl_user_macros.pod.in

@@ -19,7 +19,7 @@ user defined macros.
 
 =head2 The macros
 
-=over
+=over 4
 
 =item B<OPENSSL_API_COMPAT>
 
@@ -30,7 +30,7 @@ be declared.
 
 The version number assigned to this macro can take one of two forms:
 
-=over
+=over 4
 
 =item C<0xMNNFF000L>
 
@@ -43,7 +43,7 @@ Any version number may be given, but these numbers are
 the current known major deprecation points, making them the most
 meaningful:
 
-=over
+=over 4
 
 =item C<0x00908000L> (version 0.9.8)
 
@@ -63,7 +63,7 @@ This form is a simple number that represents the major version number
 and is supported for version 3.0.0 and up.  For extra convenience,
 these numbers are also available:
 
-=over
+=over 4
 
 =item Z<>0 (C<0x00908000L>, i.e. version 0.9.8)