Improve documentation about duplicate algorithm registrations

Reviewed-by: Tom Cosgrove <tom.cosgrove@arm.com>
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Paul Dale <ppzgs1@gmail.com>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25624)

3 files changed, 21 insertions, 2 deletions

diff --git a/doc/man7/fips_module.pod b/doc/man7/fips_module.pod
index fc89f89e00..6e0af8edab 100644
--- a/doc/man7/fips_module.pod
+++ b/doc/man7/fips_module.pod
@@ -212,7 +212,7 @@ application. If any OpenSSL functions get called that require the use of
 cryptographic functions before this occurs then, if no provider has yet been
 loaded, then the default provider will be automatically loaded. If you then
 later explicitly load the FIPS provider then you will have both the FIPS and the
-default provider loaded at the same time. It is undefined which implementation
+default provider loaded at the same time. It is unspecified which implementation
 of an algorithm will be used if multiple implementations are available and you
 have not explicitly specified via a property query (see below) which one should
 be used.
@@ -244,7 +244,7 @@ standards you can specify the property query C<fips=yes> like this:
     sha256 = EVP_MD_fetch(NULL, "SHA2-256", "fips=yes");
 
 If no property query is specified, or more than one implementation matches the
-property query then it is undefined which implementation of a particular
+property query then it is unspecified which implementation of a particular
 algorithm will be returned.
 
 This example shows an explicit request for an implementation of SHA256 from the
diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod
index 5dcbbed221..a27d948b08 100644
--- a/doc/man7/provider-base.pod
+++ b/doc/man7/provider-base.pod
@@ -581,6 +581,11 @@ The name of the group as known by the provider. This could be the same as the
 
 The TLS group id value as given in the IANA TLS Supported Groups registry.
 
+It is possible to register the same group id from within different
+providers. Users should note that if no property query is specified, or
+more than one implementation matches the property query then it is
+unspecified which implementation for a particular group id will be used.
+
 =item "tls-group-alg" (B<OSSL_CAPABILITY_TLS_GROUP_ALG>) <UTF8 string>
 
 The name of a Key Management algorithm that the provider offers and that should
@@ -667,6 +672,11 @@ This value must be supplied.
 The TLS algorithm ID value as given in the IANA TLS SignatureScheme registry.
 This value must be supplied.
 
+It is possible to register the same code point from within different
+providers. Users should note that if no property query is specified, or
+more than one implementation matches the property query then it is
+unspecified which implementation for a particular code point will be used.
+
 =item "sigalg-name" (B<OSSL_CAPABILITY_TLS_SIGALG_NAME>) <UTF8 string>
 
 A name for the full (possibly composite hash-and-signature) signature
diff --git a/doc/man7/provider.pod b/doc/man7/provider.pod
index 08ac1d0290..0754a0912b 100644
--- a/doc/man7/provider.pod
+++ b/doc/man7/provider.pod
@@ -239,6 +239,15 @@ e.g., when no provider implementing the required functionality has been
 activated. In particular, provider initialization should not depend on other
 providers already having been initialized.
 
+=head3 Note on naming clashes
+
+It is possible to register the same algorithm name from within different
+providers. Users should note that if no property query is specified, or
+more than one implementation matches the property query then it is
+unspecified which implementation of a particular algorithm will be returned.
+Such naming clashes may also occur if algorithms only differ in
+capitalization as L</Algorithm naming> is case insensitive.
+
 =head1 OPENSSL PROVIDERS
 
 OpenSSL provides a number of its own providers. These are the default, base,