From: Matthias St. Pierre Date: Wed, 17 May 2023 09:54:07 +0000 (+0200) Subject: INSTALL: document shared library pinning for static builds X-Git-Tag: openssl-3.1.2~69 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=986eda314ef37d166c6f143282395fddba6dd33f;p=thirdparty%2Fopenssl.git 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 Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/20985) (cherry picked from commit ce451fb86141fedad607bd68840639b06616047e) --- diff --git a/INSTALL.md b/INSTALL.md index a0194d49396..d13517873c9 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -797,14 +797,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