INSTALL: document shared library pinning for static builds

The libcrypto library uses shared library pinning to prevent its
cleanup handlers from crashing at program termination because of a
premature unloading of the shared library.

However, shared library pinning is enabled also for static builds,
which may lead to surpising behaviour if libcrypto is linked
statically to a shared third-party library, because in this case
the third-party library gets pinned.

This surprising behaviour is caused by the fact that the `no-shared`
configure option does not imply `no-pinshared`. Since this quirk
can't be changed without potentially breaking existing code, we just
document it here and provide a workaround.

Fixes #20977

Reviewed-by: Todd Short <todd.short@me.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20985)

diff --git a/INSTALL.md b/INSTALL.md
index 0fb8b27fe33354a0a054d53ad323e349540b7d8f..44e4a2a15aea2bf9605f19ecdd01471b1e0283d0 100644 (file)
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -856,14 +856,22 @@ By default OpenSSL will attempt to stay in memory until the process exits.
 This is so that libcrypto and libssl can be properly cleaned up automatically
 via an `atexit()` handler.  The handler is registered by libcrypto and cleans
 up both libraries.  On some platforms the `atexit()` handler will run on unload of
-libcrypto (if it has been dynamically loaded) rather than at process exit.  This
-option can be used to stop OpenSSL from attempting to stay in memory until the
+libcrypto (if it has been dynamically loaded) rather than at process exit.
+
+This option can be used to stop OpenSSL from attempting to stay in memory until the
 process exits.  This could lead to crashes if either libcrypto or libssl have
 already been unloaded at the point that the atexit handler is invoked, e.g.  on a
 platform which calls `atexit()` on unload of the library, and libssl is unloaded
-before libcrypto then a crash is likely to happen.  Applications can suppress
-running of the `atexit()` handler at run time by using the
-`OPENSSL_INIT_NO_ATEXIT` option to `OPENSSL_init_crypto()`.
+before libcrypto then a crash is likely to happen.
+
+Note that shared library pinning is not automatically disabled for static builds,
+i.e., `no-shared` does not imply `no-pinshared`. This may come as a surprise when
+linking libcrypto statically into a shared third-party library, because in this
+case the shared library will be pinned. To prevent this behaviour, you need to
+configure the static build using `no-shared` and `no-pinshared` together.
+
+Applications can suppress running of the `atexit()` handler at run time by
+using the `OPENSSL_INIT_NO_ATEXIT` option to `OPENSSL_init_crypto()`.
 See the man page for it for further details.
 
 ### no-posix-io