doc: document provider/library context cleanup order requirement

Document that providers must be unloaded with OSSL_PROVIDER_unload()
before their associated library context is freed with OSSL_LIB_CTX_free().
Calling OSSL_PROVIDER_unload() after the library context has been freed
results in undefined behavior (heap-use-after-free).

The warning is added to both OSSL_PROVIDER(3) and OSSL_LIB_CTX(3) man pages
to ensure users encounter it regardless of which documentation they consult.

Fixes #27522

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Reviewed-by: Neil Horman <nhorman@openssl.org>
Reviewed-by: Frederik Wedel-Heinen <fwh.openssl@gmail.com>
MergeDate: Sun Mar  1 19:03:43 2026
(Merged from https://github.com/openssl/openssl/pull/29785)

diff --git a/doc/man3/OSSL_LIB_CTX.pod b/doc/man3/OSSL_LIB_CTX.pod
index 215db61820e5556b25e6058894c81c1e5d5ef394..c5b85e26415352b7a4d563f71a8b8e538403b3f6 100644 (file)
--- a/doc/man3/OSSL_LIB_CTX.pod
+++ b/doc/man3/OSSL_LIB_CTX.pod
@@ -92,6 +92,10 @@ multiple threads on a single I<ctx>.
 
 OSSL_LIB_CTX_free() frees the given I<ctx>, unless it happens to be the
 default OpenSSL library context. If the argument is NULL, nothing is done.
+Any providers loaded into I<ctx> are automatically deactivated and freed
+as part of the library context cleanup.
+Any B<OSSL_PROVIDER> pointers obtained from I<ctx> must not be used after
+this call.
 
 OSSL_LIB_CTX_get0_global_default() returns a concrete (non NULL) reference to
 the global default library context.

diff --git a/doc/man3/OSSL_PROVIDER.pod b/doc/man3/OSSL_PROVIDER.pod
index f90b5d7a9efe97c12347e31879d037186990a239..14d637402a847afb39d195775c3112d8bac733a6 100644 (file)
--- a/doc/man3/OSSL_PROVIDER.pod
+++ b/doc/man3/OSSL_PROVIDER.pod
@@ -124,6 +124,11 @@ configuration file.
 OSSL_PROVIDER_unload() unloads the given provider.
 For a provider added with OSSL_PROVIDER_add_builtin(), this simply
 runs its teardown function.
+It is not necessary to explicitly unload providers before calling
+L<OSSL_LIB_CTX_free(3)>, as freeing a library context automatically
+deactivates and frees all providers associated with it.
+OSSL_PROVIDER_unload() must not be called after L<OSSL_LIB_CTX_free(3)>
+has been called on the associated library context.
 
 OSSL_PROVIDER_available() checks if a named provider is available
 for use.