From: kovan <xaum.io@gmail.com>
Date: Tue, 27 Jan 2026 10:05:00 +0000 (+0100)
Subject: doc: document provider/library context cleanup order requirement
X-Git-Tag: openssl-4.0.0-alpha1~67
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ce101e19abed882f8a66ec73f4f0c501435e4f1c;p=thirdparty%2Fopenssl.git

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 215db61820e..c5b85e26415 100644
--- 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 f90b5d7a9ef..14d637402a8 100644
--- 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.