diff options
| author | Matthias St. Pierre <matthias.st.pierre@ncp-e.com> | 2023-05-17 11:54:07 +0200 |
|---|---|---|
| committer | Tomas Mraz <tomas@openssl.org> | 2023-06-12 08:33:00 +0200 |
| commit | ce451fb86141fedad607bd68840639b06616047e (patch) | |
| tree | b79ca2634da49c3015f378b8821d4f1bb1c6b56b /INSTALL.md | |
| parent | 959c150a1dcc4535c2d94ac6f3310566723911f1 (diff) | |
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)
Diffstat (limited to 'INSTALL.md')
| -rw-r--r-- | INSTALL.md | 18 |
1 files changed, 13 insertions, 5 deletions
diff --git a/INSTALL.md b/INSTALL.md index 0fb8b27fe3..44e4a2a15a 100644 --- 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 |