threads(3) OpenSSL threads(3)
NAME
CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks, CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, CRYPTO_set_dyn- lock_destroy_callback, CRYPTO_get_new_dynlockid, CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support
LIBRARY
libcrypto, -lcrypto
SYNOPSIS
#include <openssl/crypto.h> void CRYPTO_set_locking_callback(void (*locking_function)(int mode, int n, const char *file, int line)); void CRYPTO_set_id_callback(unsigned long (*id_function)(void)); int CRYPTO_num_locks(void); /* struct CRYPTO_dynlock_value needs to be defined by the user */ struct CRYPTO_dynlock_value; void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * (*dyn_create_function)(char *file, int line)); void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) (int mode, struct CRYPTO_dynlock_value *l, const char *file, int line)); void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) (struct CRYPTO_dynlock_value *l, const char *file, int line)); int CRYPTO_get_new_dynlockid(void); void CRYPTO_destroy_dynlockid(int i); void CRYPTO_lock(int mode, int n, const char *file, int line); #define CRYPTO_w_lock(type) \ CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) #define CRYPTO_w_unlock(type) \ CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) #define CRYPTO_r_lock(type) \ CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__) #define CRYPTO_r_unlock(type) \ CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__) #define CRYPTO_add(addr,amount,type) \ CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__)
DESCRIPTION
OpenSSL can safely be used in multi-threaded applications provided that at least two callback functions are set. 2002-06-10 0.9.6g 1 threads(3) OpenSSL threads(3) locking_function(int mode, int n, const char *file, int line) is needed to perform locking on shared data struc- tures. (Note that OpenSSL uses a number of global data structures that will be implicitly shared whenever multi- ple threads use OpenSSL.) Multi-threaded applications will crash at random if it is not set. locking_function() must be able to handle up to CRYPTO_num_locks() different mutex locks. It sets the n-th lock if mode & CRYPTO_LOCK, and releases it otherwise. file and line are the file number of the function setting the lock. They can be useful for debugging. id_function(void) is a function that returns a thread ID. It is not needed on Windows nor on platforms where get- pid() returns a different ID for each thread (most notably Linux). Additionally, OpenSSL supports dynamic locks, and some- times, some parts of OpenSSL need it for better perfor- mance. To enable this, the following is required: o Three additional callback function, dyn_create_function, dyn_lock_function and dyn_destroy_function. o A structure defined with the data that each lock needs to han- dle. struct CRYPTO_dynlock_value has to be defined to contain whatever structure is needed to handle locks. dyn_create_function(const char *file, int line) is needed to create a lock. Multi-threaded applications might crash at random if it is not set. dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line) is needed to perform locking off dynamic lock numbered n. Multi-threaded applications might crash at random if it is not set. dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is needed to destroy the lock l. Multi-threaded applications might crash at random if it is not set. CRYPTO_get_new_dynlockid() is used to create locks. It will call dyn_create_function for the actual creation. CRYPTO_destroy_dynlockid() is used to destroy locks. It will call dyn_destroy_function for the actual destruction. CRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield describing what should be done with the lock. n is the number of the lock as returned from 2002-06-10 0.9.6g 2 threads(3) OpenSSL threads(3) CRYPTO_get_new_dynlockid(). mode can be combined from the following values. These values are pairwise exclusive, with undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE should not be used together): CRYPTO_LOCK 0x01 CRYPTO_UNLOCK 0x02 CRYPTO_READ 0x04 CRYPTO_WRITE 0x08
RETURN VALUES
CRYPTO_num_locks() returns the required number of locks. CRYPTO_get_new_dynlockid() returns the index to the newly created lock. The other functions return no values.
NOTE
You can find out if OpenSSL was configured with thread support: #define OPENSSL_THREAD_DEFINES #include <openssl/opensslconf.h> #if defined(THREADS) // thread support enabled #else // no thread support #endif Also, dynamic locks are currently not used internally by OpenSSL, but may do so in the future.
EXAMPLES
crypto/threads/mttest.c shows examples of the callback functions on Solaris, Irix and Win32.
HISTORY
CRYPTO_set_locking_callback() and CRYPTO_set_id_callback() are available in all versions of SSLeay and OpenSSL. CRYPTO_num_locks() was added in OpenSSL 0.9.4. All func- tions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev.
SEE ALSO
crypto(3) 2002-06-10 0.9.6g 3
Powered by man-cgi (2024-08-26). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.