From: Matt Caswell <matt@openssl.org>
Date: Tue, 11 May 2021 15:49:45 +0000 (+0100)
Subject: Documentation updates for mirroring of global properties
X-Git-Tag: openssl-3.0.0-alpha17~12
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=366bf9aedbbf719097a891dbf675f46dab8c9276;p=thirdparty%2Fopenssl.git

Documentation updates for mirroring of global properties

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

diff --git a/doc/internal/man3/ossl_global_properties_no_mirrored.pod b/doc/internal/man3/ossl_global_properties_no_mirrored.pod
new file mode 100644
index 00000000000..6c39ccbc0ff
--- /dev/null
+++ b/doc/internal/man3/ossl_global_properties_no_mirrored.pod
@@ -0,0 +1,56 @@
+=pod
+
+=head1 NAME
+
+ossl_property_list_to_string, ossl_global_properties_no_mirrored
+- internal property routines
+
+=head1 SYNOPSIS
+
+ #include "internal/property.h"
+
+ size_t ossl_property_list_to_string(OSSL_LIB_CTX *ctx,
+                                     const OSSL_PROPERTY_LIST *list, char *buf,
+                                     size_t bufsize);
+
+ int ossl_global_properties_no_mirrored(OSSL_LIB_CTX *libctx);
+ void ossl_global_properties_no_mirrored(OSSL_LIB_CTX *libctx);
+
+
+=head1 DESCRIPTION
+
+ossl_property_list_to_string() takes a given OSSL_PROPERTY_LIST in I<list> and
+converts it to a string. If I<buf> is non NULL then the string will be stored
+in I<buf>. The size of the buffer is provided in I<bufsize>. If I<bufsize> is
+too short then the string will be truncated. If I<buf> is NULL then the length
+of the string is still calculated and returned. If the property list has no
+properties in it then the empty string will be stored in I<buf>.
+
+ossl_global_properties_no_mirrored() checks whether mirroring of global
+properties from a parent library context is allowed for the current library
+context.
+
+ossl_global_properties_no_mirrored() prevents future mirroring of global
+properties from a parent library context for the current library context.
+
+=head1 RETURN VALUES
+
+ossl_property_list_to_string() returns the length of the string, or 0 on error.
+
+ossl_global_properties_no_mirrored() returns 1 if mirroring of global properties
+is not allowed, or 0 otherwise.
+
+=head1 HISTORY
+
+The functions described here were all added in OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2021 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
diff --git a/doc/man3/OSSL_LIB_CTX.pod b/doc/man3/OSSL_LIB_CTX.pod
index 57037e2ba65..d51816ead7c 100644
--- a/doc/man3/OSSL_LIB_CTX.pod
+++ b/doc/man3/OSSL_LIB_CTX.pod
@@ -69,6 +69,12 @@ reference count. L<OSSL_PROVIDER_unload(3)> must not be called for a provider in
 the child library context that did not have an earlier L<OSSL_PROVIDER_load(3)>
 call for that provider in that child library context.
 
+In addition to providers, a child library context will also mirror the default
+properties (set via L<EVP_set_default_properties(3)>) from the parent library
+context. If L<EVP_set_default_properties(3)> is called directly on a child
+library context then the new properties will override anything from the parent
+library context and mirroring of the properties will stop.
+
 OSSL_LIB_CTX_new_child() must only be called from within the scope of a
 provider's B<OSSL_provider_init> function (see L<provider-base(7)>). Calling it
 outside of that function may succeed but may not correctly mirror all providers