Latest update.

doc/internal/man3/evp_keymgmt_newdata.pod

@@ -18,12 +18,11 @@ evp_keymgmt_export, evp_keymgmt_export_types
  int evp_keymgmt_get_params(const EVP_KEYMGMT *keymgmt,
                             void *keydata, OSSL_PARAM params[]);
  const OSSL_PARAM *evp_keymgmt_gettable_params(const EVP_KEYMGMT *keymgmt);
- 
- 
+
  int evp_keymgmt_has(const EVP_KEYMGMT *keymgmt, void *keyddata, int selection);
  int evp_keymgmt_validate(const EVP_KEYMGMT *keymgmt, void *keydata,
                           int selection);
- 
+
  int evp_keymgmt_import(const EVP_KEYMGMT *keymgmt, void *keydata,
                         int selection, const OSSL_PARAM params[]);
  const OSSL_PARAM *evp_keymgmt_import_types(const EVP_KEYMGMT *keymgmt,

doc/internal/man3/evp_keymgmt_util_export_to_provider.pod

@@ -3,8 +3,10 @@
 =head1 NAME
 
 evp_keymgmt_util_export_to_provider,
-evp_keymgmt_util_clear_pkey_cache,
-evp_keymgmt_util_cache_pkey,
+evp_keymgmt_util_find_operation_cache_index,
+evp_keymgmt_util_clear_operation_cache,
+evp_keymgmt_util_cache_keydata,
+evp_keymgmt_util_cache_keyinfo,
 evp_keymgmt_util_fromdata
 - internal KEYMGMT utility functions
 
@@ -13,32 +15,41 @@ evp_keymgmt_util_fromdata
  #include "crypto/evp.h"
 
  void *evp_keymgmt_util_export_to_provider(EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);
- void evp_keymgmt_util_clear_pkey_cache(EVP_PKEY *pk);
- void evp_keymgmt_util_cache_pkey(EVP_PKEY *pk, size_t index,
-                                  EVP_KEYMGMT *keymgmt, void *keydata);
+ size_t evp_keymgmt_util_find_operation_cache_index(EVP_PKEY *pk,
+                                                    EVP_KEYMGMT *keymgmt);
+ void evp_keymgmt_util_clear_operation_cache(EVP_PKEY *pk);
+ void evp_keymgmt_util_cache_keydata(EVP_PKEY *pk, size_t index,
+                                     EVP_KEYMGMT *keymgmt, void *keydata);
+ void evp_keymgmt_util_cache_keyinfo(EVP_PKEY *pk);
  void *evp_keymgmt_util_fromdata(EVP_PKEY *target, EVP_KEYMGMT *keymgmt,
                                  int selection, const OSSL_PARAM params[]);
 
 =head1 DESCRIPTION
 
-evp_keymgmt_util_export_to_provider() exports the key material from
-the given key I<pk> to a provider via a B<EVP_KEYMGMT> interface, if
-this hasn't already been done.
+evp_keymgmt_util_export_to_provider() exports cached key material
+(provider side key material) from the given key I<pk> to a provider
+via a B<EVP_KEYMGMT> interface, if this hasn't already been done.
 It maintains a cache of provider key references in I<pk> to keep track
-of all such exports.
+of all provider side keys.
 
-If I<pk> has an assigned legacy key, a check is done to see if any of
-its key material has changed since last export, i.e. the legacy key's
-is_dirty() method returns 1.
-If it has, the cache of already exported keys is cleared, and a new
-export is made with the new key material.
+To export a legacy key, use L<evp_pkey_export_to_provider(3)> instead,
+as this function ignores any legacy key data.
 
-evp_keymgmt_util_clear_pkey_cache() can be used to explicitly clear
-the cache of provider key references.
+evp_keymgmt_util_find_operation_cache_index() finds the location if
+I<keymgmt> in I<pk>'s cache of provided keys for operations.  If
+I<keymgmt> is NULL or couldn't be found in the cache, it finds the
+first empty slot instead if there is any.
 
-evp_keymgmt_util_cache_pkey() can be used to assign a provider key
+evp_keymgmt_util_clear_operation_cache() can be used to explicitly
+clear the cache of operation key references.
+
+evp_keymgmt_util_cache_keydata() can be used to assign a provider key
 object to a specific cache slot in the given I<target>.
-I<Use with extreme care>.
+I<Use extreme care>.
+
+evp_keymgmt_util_cache_keyinfo() can be used to get all kinds of
+information from the provvider "origin" and save it in I<pk>'s
+information cache.
 
 evp_keymgmt_util_fromdata() can be used to add key object data to a
 given key I<target> via a B<EVP_KEYMGMT> interface.  This is used as a
@@ -50,6 +61,11 @@ evp_keymgmt_export_to_provider() and evp_keymgmt_util_fromdata()
 return a pointer to the appropriate provider side key (created or
 found again), or NULL on error.
 
+evp_keymgmt_util_find_operation_cache_index() returns the index of the
+operation cache slot.  If I<keymgmt> is NULL, or if there is no slot
+with a match for I<keymgmt>, the index of the first empty slot is
+returned, or the maximum number of slots if there isn't an empty one.
+
 =head1 NOTES
 
 "Legacy key" is the term used for any key that has been assigned to an

doc/internal/man3/evp_pkey_export_to_provider.pod

@@ -0,0 +1,75 @@
+=pod
+
+=head1 NAME
+
+evp_pkey_export_to_provider, evp_pkey_upgrade_to_provider
+- internal EVP_PKEY support functions for providers
+
+=head1 SYNOPSIS
+
+ /* Only for EVP source */
+ #include "evp_local.h"
+
+ void *evp_pkey_export_to_provider(EVP_PKEY *pk, OPENSSL_CTX *libctx,
+                                   EVP_KEYMGMT **keymgmt,
+                                   const char *propquery);
+ void *evp_pkey_upgrade_to_provider(EVP_PKEY *pk, OPENSSL_CTX *libctx,
+                                    EVP_KEYMGMT **keymgmt,
+                                    const char *propquery);
+
+=head1 DESCRIPTION
+
+This manual uses the term "origin", which is explained in internal
+L<EVP_PKEY(7)>.
+
+evp_pkey_export_to_provider() exports the "origin" key contained in I<pk>
+to its operation cache to make it suitable for an B<EVP_KEYMGMT> given either
+with I<*keymgmt> or with an implicit fetch using I<libctx> (NULL means the
+default context), the name of the legacy type of I<pk>, and the I<propquery>
+(NULL means the default property query settings).
+
+If I<keymgmt> isn't NULL but I<*keymgmt> is, and the "origin" was successfully
+exported, then I<*keymgmt> is assigned the implicitly fetched B<EVP_KEYMGMT>.
+
+evp_pkey_upgrade_to_provider() exports the legacy "origin" key contained in
+I<pk> to it's provider side counterpart, then clears the legacy "origin" key
+along with other legacy data, and resets all the caches.  Otherwise, it works
+like evp_pkey_export_to_provider().
+
+I<evp_pkey_upgrade_to_provider() must be used with great care, only if there's
+no other way.>
+Most of the time, it's sufficient to use evp_pkey_export_to_provider(), but in
+case the key needs modification with data coming from a provided key, the key
+will need an upgrade.
+
+=head1 RETURN VALUES
+
+evp_pkey_export_to_provider() and evp_pkey_upgrade_to_provider() both return
+the provider key data that was exported if the "origin" was successfully
+exported to its target.  Otherwise, NULL is returned.
+
+=head1 NOTES
+
+Some functions calling evp_pkey_export_to_provider() or
+evp_pkey_upgrade_to_provider() may have received a const key, and may
+therefore have to cast the key to non-const form to call this function.  Since
+B<EVP_PKEY> is always dynamically allocated, this is OK.
+
+=head1 SEE ALSO
+
+L<OPENSSL_CTX(3)>, L<EVP_KEYMGMT(3)>
+
+=head1 HISTORY
+
+The functions described here were all added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2020 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/internal/man3/evp_pkey_make_provided.pod

@@ -1,55 +0,0 @@
-=pod
-
-=head1 NAME
-
-evp_pkey_make_provided - internal EVP_PKEY support functions for providers
-
-=head1 SYNOPSIS
-
- /* Only for EVP source */
- #include "evp_local.h"
-
- void *evp_pkey_make_provided(EVP_PKEY *pk, OPENSSL_CTX *libctx,
-                              EVP_KEYMGMT **keymgmt, const char *propquery);
-
-=head1 DESCRIPTION
-
-evp_pkey_make_provided() ensures that the B<EVP_PKEY> I<pk> is provided within
-the library context I<libctx> (NULL means the default context).  I<keymgmt>
-may point at a reference to a B<EVP_KEYMGMT>, and works as an input/output
-parameter.
-As input to this function, it can be used to specify a B<EVP_KEYMGMT> to be
-used for exporting.  If not (I<*keymgmt> is NULL), then this function will
-fetch an B<EVP_KEYMGMT> implicitly, using I<propquery> as property query string.
-As output from this function, I<*keymgmt> will be assigned the B<EVP_KEYMGMT>
-that was used, if the export was successful, otherwise it will be assigned NULL.
-
-=head1 RETURN VALUES
-
-evp_pkey_make_provided() returns the provider key data that was exported if
-I<pk> was successfully provided.  Otherwise, NULL is returned.
-
-=head1 NOTES
-
-Some functions calling evp_pkey_make_provided() may have received a const
-key, and may therefore have to cast the key to non-const form to call this
-function.  Since B<EVP_PKEY> is always dynamically allocated, this is OK.
-
-=head1 SEE ALSO
-
-L<OPENSSL_CTX(3)>, L<EVP_KEYMGMT(3)>
-
-=head1 HISTORY
-
-The functions described here were all added in OpenSSL 3.0.
-
-=head1 COPYRIGHT
-
-Copyright 2020 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/internal/man3/ossl_cmp_print_log.pod

@@ -68,7 +68,7 @@ the variable pointed to by I<level> with the severity level or -1,
 the variable pointed to by I<func> with the function name string or NULL,
 the variable pointed to by I<file> with the filename string or NULL, and
 the variable pointed to by I<line> with the line number or -1.
-Any string returned via I<*func> and I<*file> must be freeed by the caller.
+Any string returned via I<*func> and I<*file> must be freed by the caller.
 
 ossl_cmp_add_error_data() is a macro calling
 L<ERR_add_error_txt(3)> with the separator being ":".

doc/internal/man3/ossl_param_bld_init.pod

@@ -75,7 +75,7 @@ I<val> is stored by value and an expression or auto variable can be used.
 
 ossl_param_bld_push_BN() is a function that will create an OSSL_PARAM object
 that holds the specified BIGNUM I<bn>.
-If I<bn> is marked as being securely allocated, it's OSSL_PARAM representation
+If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
 will also be securely allocated.
 The I<bn> argument is stored by reference and the underlying BIGNUM object
 must exist until after ossl_param_bld_to_param() has been called.
@@ -84,7 +84,7 @@ ossl_param_bld_push_BN_pad() is a function that will create an OSSL_PARAM object
 that holds the specified BIGNUM I<bn>.
 The object will be padded to occupy exactly I<sz> bytes, if insufficient space
 is specified an error results.
-If I<bn> is marked as being securely allocated, it's OSSL_PARAM representation
+If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
 will also be securely allocated.
 The I<bn> argument is stored by reference and the underlying BIGNUM object
 must exist until after ossl_param_bld_to_param() has been called.

doc/internal/man3/s2i_ASN1_UTF8STRING.pod

@@ -0,0 +1,45 @@
+=pod
+
+=head1 NAME
+
+i2s_ASN1_UTF8STRING,
+s2i_ASN1_UTF8STRING,
+- convert objects from/to ASN.1/string representation
+
+=head1 SYNOPSIS
+
+=for openssl generic
+
+ char *i2s_ASN1_UTF8STRING(X509V3_EXT_METHOD *method,
+                           ASN1_UTF8STRING *utf8);
+ ASN1_UTF8STRING *s2i_ASN1_UTF8STRING(X509V3_EXT_METHOD *method,
+                                      X509V3_CTX *ctx, const char *str);
+=head1 DESCRIPTION
+
+These functions convert OpenSSL objects to and from their ASN.1/string
+representation. This function is used for B<X509v3> extentions.
+
+=head1 NOTES
+
+The letters B<i> and B<s> in B<i2s_ASN1_UTF8STRING>() stand for
+"internal" (that is, an internal C structure) and string respectively.
+So B<i2s_ASN1_UTF8STRING>() converts from internal to string.
+
+=head1 RETURN VALUES
+
+B<s2i_ASN1_UTF8STRING>() return a valid
+B<ASN1_UTF8STRING> structure or NULL if an error occurs.
+
+B<i2s_ASN1_UTF8STRING>() returns the pointer to a UTF-8 string
+or NULL if an error occurs.
+
+=head1 COPYRIGHT
+
+Copyright 2020 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/internal/man7/EVP_PKEY.pod

@@ -0,0 +1,56 @@
+=pod
+
+=head1 NAME
+
+EVP_PKEY - an internal description
+
+=head1 SYNOPSIS
+
+ #include "crypto/evp.h"
+
+ struct evp_pkey_st;
+
+=head1 DESCRIPTION
+
+I<This is not a complete description yet>
+
+B<EVP_PKEY> is a complex type that's essentially a container for
+private/public key key pairs, but has had other uses as well.
+
+=for comment "uses" could as well be "abuses"...
+
+It can contain the legacy form of keys -- i.e. pointers to the low
+level key types, such as B<RSA>, B<DSA> and B<EC> --, but also the
+provided form of keys -- i.e. pointers to provider side key data.
+Those two forms are mutually exclusive; an B<EVP_PKEY> instance can't
+contain both a key in legacy form and in provided form.  Regardless of
+form, this key is commonly refered to as the "origin".
+
+An B<EVP_PKEY> also contains a cache of provider side copies of the
+key, each adapted for the provider that is going to use that copy to
+perform some operation.
+For a legacy "origin", the B<EVP_PKEY_ASN1_METHOD>'s functions
+export_to() and dirty_cnt() must be implemented for such caching to be
+possible.  For a provider side "origin", the B<EVP_KEYMGMT>'s function
+OP_keymgmt_export() must be implemented.  In all cases, the receiving
+B<EVP_KEYMGMT> must have an implemented OP_keygmt_import().
+
+If such caching isn't supported, the operations that can be performed
+with that key are limited to the same backend as the "origin" key
+(ENGINE for legacy "origin" keys, provider for provider side "origin"
+keys).
+
+=head1 SEE ALSO
+
+L<provider-keymgmt(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2020 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/internal/man7/build.info.pod

@@ -24,7 +24,7 @@ B<MODULES=> I<name> ...
 
 B<SCRIPTS=> I<name> ...
 
-B<DEPEND[>I<item>B<]=> I<otheritem> ...
+B<DEPEND[>I<items>B<]=> I<otheritem> ...
 
 B<GENERATE[>I<item>B<]=> I<generator> I<generator-args> ...
 
@@ -32,9 +32,9 @@ B<SOURCE[>I<item>B<]=> I<file> ...
 
 B<SHARED_SOURCE[>I<item>B<]=> I<file> ...
 
-B<DEFINE[>I<item>B<]=> I<name>[B<=>I<value>] ...
+B<DEFINE[>I<items>B<]=> I<name>[B<=>I<value>] ...
 
-B<INCLUDE[>I<item>B<]=> I<dir> ...
+B<INCLUDE[>I<items>B<]=> I<dir> ...
 
 B<$>I<VARIABLE>B<=>I<value>
 
@@ -122,7 +122,7 @@ syntax is one of:
 
 =item B<I<KEYWORD>> B<=> I<value> ...
 
-=item B<I<KEYWORD>[>I<item>B<]> B<=> I<value> ...
+=item B<I<KEYWORD>[>I<items>B<]> B<=> I<value> ...
 
 =back
 
@@ -154,8 +154,14 @@ F<foo.c> and F<details.c>, and that it depends on the library
 C<libcookie> (in other words, the library will be included when
 linking that program together).
 
-For any indexed statement for which the item hasn't been specified
-through any plain statement, or where the item exists but the indexed
+Multiple space separated items are allowed too:
+
+    SOURCE[foo]=foo.c
+    SOURCE[details]=details.c
+    DEPEND[foo details]=libcookie
+
+For any indexed statement for which the items haven't been specified
+through any plain statement, or where the items exists but the indexed
 statement does not apply, the value is simply ignored by the build
 file generators.
 
@@ -169,7 +175,7 @@ variations on how they are treated.
 =item B<I<KEYWORD>{> I<attrib> | I<attrib>B<=>I<attrib-value> [,...]B<}>
 B<=> I<value> ...
 
-=item B<I<KEYWORD>[>I<item>B<]{> I<attrib> | I<attrib>B<=>I<attrib-value>
+=item B<I<KEYWORD>[>I<items>B<]{> I<attrib> | I<attrib>B<=>I<attrib-value>
 [,...]B<}> B<=> I<value> ...
 
 =back
@@ -264,6 +270,22 @@ part of is tokenized>.
 
 I<Variable assignment values are not tokenized.>
 
+Variable references can be one of:
+
+=over 4
+
+=item B<$>I<NAME> or B<${>I<NAME>B<}>
+
+Simple reference; the variable reference is replaced with its value,
+verbatim.
+
+=item B<${>I<NAME>B</>I<str>B</>I<subst>B<}>
+
+Substitution reference; the variable reference is replaced with its
+value, modified by replacing all occurences of I<str> with I<subst>.
+
+=back
+
 =head2 Scope
 
 Most of the statement values are accumulated globally from all the
@@ -411,15 +433,15 @@ C<noinst>, while the script C<bar> will.
 
 =over 4
 
-=item B<DEPEND[>I<item>B<]> B<=> I<file> ...
+=item B<DEPEND[>I<items>B<]> B<=> I<file> ...
 
-Collects dependencies, where I<item> depends on the given I<file>s.
+Collects dependencies, where I<items> depend on the given I<file>s.
 
-As a special case, the I<item> may be empty, for which the build file
+As a special case, the I<items> may be empty, for which the build file
 generators should make the whole build depend on the given I<file>s,
-rather than some specific I<item>.
+rather than the specific I<items>.
 
-The I<item> may be any program, library, module, script, or any
+The I<items> may be any program, library, module, script, or any
 filename used as a value anywhere.
 
 B<DEPEND> statements may have attributes, which apply to each
@@ -473,19 +495,19 @@ given with B<LIBS> or B<MODULES>.  For libraries, the given filenames
 are only used for their shared form, so if the item is a library name
 ending with C<.a>, the filenames will be ignored.
 
-=item B<DEFINE[>I<item>B<]> B<=> I<name>[B<=>I<value>] ...
+=item B<DEFINE[>I<items>B<]> B<=> I<name>[B<=>I<value>] ...
 
 Collects I<name> / I<value> pairs (or just I<name> with no defined
-value if no I<value> is given) associated with I<item>.
+value if no I<value> is given) associated with I<items>.
 
 The build file generators will decide what to do with them.  For
 example, these pairs should become C macro definitions whenever a
 C<.c> file is built into an object file.
 
-=item B<INCLUDE[>I<item>B<]> B<=> I<dir> ...
+=item B<INCLUDE[>I<items>B<]> B<=> I<dir> ...
 
 Collects inclusion directories that will be used when building the
-I<item> components (object files and whatever else).  This is used at
+I<items> components (object files and whatever else).  This is used at
 the discretion of the build file generators.
 
 =back
@@ -568,7 +590,7 @@ the exception of conditional statements and variable assignments.
 
 =item "indexed statement"
 
-Any F<build.info> statement of the form B<I<KEYWORD>[>I<item>B<]=>I<values>,
+Any F<build.info> statement of the form B<I<KEYWORD>[>I<items>B<]=>I<values>,
 with the exception of conditional statements.
 
 =item "intermediate file"