openssl

History

Benjamin Kaduk 63ab5ea13b Revert the crypto "global lock" implementation Conceptually, this is a squashed version of: Revert "Address feedback" This reverts commit `75551e07bd`. and Revert "Add CRYPTO_thread_glock_new" This reverts commit `ed6b2c7938`. But there were some intervening commits that made neither revert apply cleanly, so instead do it all as one shot. The crypto global locks were an attempt to cope with the awkward POSIX semantics for pthread_atfork(); its documentation (the "RATIONALE" section) indicates that the expected usage is to have the prefork handler lock all "global" locks, and the parent and child handlers release those locks, to ensure that forking happens with a consistent (lock) state. However, the set of functions available in the child process is limited to async-signal-safe functions, and pthread_mutex_unlock() is not on the list of async-signal-safe functions! The only synchronization primitives that are async-signal-safe are the semaphore primitives, which are not really appropriate for general-purpose usage. However, the state consistency problem that the global locks were attempting to solve is not actually a serious problem, particularly for OpenSSL. That is, we can consider four cases of forking application that might use OpenSSL: (1) Single-threaded, does not call into OpenSSL in the child (e.g., the child calls exec() immediately) For this class of process, no locking is needed at all, since there is only ever a single thread of execution and the only reentrancy is due to signal handlers (which are themselves limited to async-signal-safe operation and should not be doing much work at all). (2) Single-threaded, calls into OpenSSL after fork() The application must ensure that it does not fork() with an unexpected lock held (that is, one that would get unlocked in the parent but accidentally remain locked in the child and cause deadlock). Since OpenSSL does not expose any of its internal locks to the application and the application is single-threaded, the OpenSSL internal locks will be unlocked for the fork(), and the state will be consistent. (OpenSSL will need to reseed its PRNG in the child, but that is an orthogonal issue.) If the application makes use of locks from libcrypto, proper handling for those locks is the responsibility of the application, as for any other locking primitive that is available for application programming. (3) Multi-threaded, does not call into OpenSSL after fork() As for (1), the OpenSSL state is only relevant in the parent, so no particular fork()-related handling is needed. The internal locks are relevant, but there is no interaction with the child to consider. (4) Multi-threaded, calls into OpenSSL after fork() This is the case where the pthread_atfork() hooks to ensure that all global locks are in a known state across fork() would come into play, per the above discussion. However, these "calls into OpenSSL after fork()" are still subject to the restriction to async-signal-safe functions. Since OpenSSL uses all sorts of locking and libc functions that are not on the list of safe functions (e.g., malloc()), this case is not currently usable and is unlikely to ever be usable, independently of the locking situation. So, there is no need to go through contortions to attempt to support this case in the one small area of locking interaction with fork(). In light of the above analysis (thanks @davidben and @achernya), go back to the simpler implementation that does not need to distinguish "library-global" locks or to have complicated atfork handling for locks. Reviewed-by: Kurt Roeckx <kurt@roeckx.be> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/5089)		2018-01-31 12:25:28 -06:00
..
build.info	unified build scheme: add build.info files	2016-02-01 12:46:58 +01:00
err.c	Revert the crypto "global lock" implementation	2018-01-31 12:25:28 -06:00
err_all.c	Remove the possibility to disable the UI module entirely	2017-07-03 07:51:04 +02:00
err_prn.c	Consistent formatting for sizeof(foo)	2017-12-07 19:11:49 -05:00
openssl.ec	Add the STORE module	2017-06-29 11:55:31 +02:00
openssl.txt	Add support for the TLS 1.3 signature_algorithms_cert extension	2018-01-25 12:57:22 -06:00
README	Clean up "generic" intro pod files.	2016-06-09 16:39:19 -04:00

README

Adding new libraries
--------------------

When adding a new sub-library to OpenSSL, assign it a library number
ERR_LIB_XXX, define a macro XXXerr() (both in err.h), add its
name to ERR_str_libraries[] (in crypto/err/err.c), and add
ERR_load_XXX_strings() to the ERR_load_crypto_strings() function
(in crypto/err/err_all.c). Finally, add an entry:

    L      XXX     xxx.h   xxx_err.c

to crypto/err/openssl.ec, and add xxx_err.c to the Makefile.
Running make errors will then generate a file xxx_err.c, and
add all error codes used in the library to xxx.h.

Additionally the library include file must have a certain form.
Typically it will initially look like this:

    #ifndef HEADER_XXX_H
    #define HEADER_XXX_H

    #ifdef __cplusplus
    extern "C" {
    #endif

    /* Include files */

    #include <openssl/bio.h>
    #include <openssl/x509.h>

    /* Macros, structures and function prototypes */


    /* BEGIN ERROR CODES */

The BEGIN ERROR CODES sequence is used by the error code
generation script as the point to place new error codes, any text
after this point will be overwritten when make errors is run.
The closing #endif etc will be automatically added by the script.

The generated C error code file xxx_err.c will load the header
files stdio.h, openssl/err.h and openssl/xxx.h so the
header file must load any additional header files containing any
definitions it uses.