EVP_get_default_properties - documentation

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25434)

diff --git a/doc/man3/EVP_set_default_properties.pod b/doc/man3/EVP_set_default_properties.pod
index d27dc67cc8eef3a6ffbc821691365dd5138ee372..0c0f67c7cbc3e2683e9fabf8ebc62ab604975ab3 100644 (file)
--- a/doc/man3/EVP_set_default_properties.pod
+++ b/doc/man3/EVP_set_default_properties.pod
@@ -3,14 +3,15 @@
 =head1 NAME
 
 EVP_set_default_properties, EVP_default_properties_enable_fips,
-EVP_default_properties_is_fips_enabled
-- Set default properties for future algorithm fetches
+EVP_default_properties_is_fips_enabled, EVP_get1_default_properties
+- manage default properties for future algorithm fetches
 
 =head1 SYNOPSIS
 
  #include <openssl/evp.h>
 
  int EVP_set_default_properties(OSSL_LIB_CTX *libctx, const char *propq);
+ char *EVP_get1_default_properties(OSSL_LIB_CTX *libctx);
  int EVP_default_properties_enable_fips(OSSL_LIB_CTX *libctx, int enable);
  int EVP_default_properties_is_fips_enabled(OSSL_LIB_CTX *libctx);
 
@@ -28,6 +29,10 @@ given with I<libctx> (NULL signifies the default library context).
 Any previous default property for the specified library context will
 be dropped.
 
+EVP_get1_default_properties() gets the default properties set for all future EVP
+algorithm fetches, implicit as well as explicit, for the specific library
+context.
+
 EVP_default_properties_enable_fips() sets the 'fips=yes' to be a default property
 if I<enable> is non zero, otherwise it clears 'fips' from the default property
 query for the given I<libctx>. It merges the fips default property query with any
@@ -42,6 +47,10 @@ EVP_set_default_properties() and  EVP_default_properties_enable_fips() are not
 thread safe. They are intended to be called only during the initialisation
 phase of a I<libctx>.
 
+EVP_get1_default_properties() is not thread safe. The application must ensure
+that the context reference is valid and default fetching properties are not
+being modified by a different thread.
+
 =head1 RETURN VALUES
 
 EVP_set_default_properties() and  EVP_default_properties_enable_fips() return 1
@@ -51,13 +60,20 @@ failure occurs.
 EVP_default_properties_is_fips_enabled() returns 1 if the 'fips=yes' default
 property is set for the given I<libctx>, otherwise it returns 0.
 
+EVP_get1_default_properties() returns allocated memory that must be freed by
+L<OPENSSL_free(3)> on success and NULL on failure.
+
 =head1 SEE ALSO
 
 L<EVP_MD_fetch(3)>
 
 =head1 HISTORY
 
-The functions described here were added in OpenSSL 3.0.
+The functions EVP_set_default_properties(), EVP_default_properties_enable_fips(),
+EVP_default_properties_is_fips_enabled() were added in OpenSSL 3.0.
+
+The function EVP_get1_default_properties() was added in OpenSSL 3.5.
+
 
 =head1 COPYRIGHT