159191Skris=pod 259191Skris 359191Skris=head1 NAME 459191Skris 568651SkrisCRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks, 668651SkrisCRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, 768651SkrisCRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, 868651SkrisCRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support 959191Skris 1059191Skris=head1 SYNOPSIS 1159191Skris 1259191Skris #include <openssl/crypto.h> 1359191Skris 1459191Skris void CRYPTO_set_locking_callback(void (*locking_function)(int mode, 1559191Skris int n, const char *file, int line)); 1659191Skris 1759191Skris void CRYPTO_set_id_callback(unsigned long (*id_function)(void)); 1859191Skris 1959191Skris int CRYPTO_num_locks(void); 2059191Skris 2168651Skris 2268651Skris /* struct CRYPTO_dynlock_value needs to be defined by the user */ 2368651Skris struct CRYPTO_dynlock_value; 2468651Skris 2568651Skris void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * 2668651Skris (*dyn_create_function)(char *file, int line)); 2768651Skris void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) 2868651Skris (int mode, struct CRYPTO_dynlock_value *l, 2968651Skris const char *file, int line)); 3068651Skris void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) 3168651Skris (struct CRYPTO_dynlock_value *l, const char *file, int line)); 3268651Skris 3368651Skris int CRYPTO_get_new_dynlockid(void); 3468651Skris 3568651Skris void CRYPTO_destroy_dynlockid(int i); 3668651Skris 3768651Skris void CRYPTO_lock(int mode, int n, const char *file, int line); 3868651Skris 3968651Skris #define CRYPTO_w_lock(type) \ 4068651Skris CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) 4168651Skris #define CRYPTO_w_unlock(type) \ 4268651Skris CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) 4368651Skris #define CRYPTO_r_lock(type) \ 4468651Skris CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__) 4568651Skris #define CRYPTO_r_unlock(type) \ 4668651Skris CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__) 4768651Skris #define CRYPTO_add(addr,amount,type) \ 4868651Skris CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__) 4968651Skris 5059191Skris=head1 DESCRIPTION 5159191Skris 5259191SkrisOpenSSL can safely be used in multi-threaded applications provided 5368651Skristhat at least two callback functions are set. 5459191Skris 5559191Skrislocking_function(int mode, int n, const char *file, int line) is 56109998Smarkmneeded to perform locking on shared data structures. 5789837Skris(Note that OpenSSL uses a number of global data structures that 5889837Skriswill be implicitly shared whenever multiple threads use OpenSSL.) 5989837SkrisMulti-threaded applications will crash at random if it is not set. 6059191Skris 6159191Skrislocking_function() must be able to handle up to CRYPTO_num_locks() 6259191Skrisdifferent mutex locks. It sets the B<n>-th lock if B<mode> & 6359191SkrisB<CRYPTO_LOCK>, and releases it otherwise. 6459191Skris 6559191SkrisB<file> and B<line> are the file number of the function setting the 6659191Skrislock. They can be useful for debugging. 6759191Skris 68160814Ssimonid_function(void) is a function that returns a thread ID, for example 69160814Ssimonpthread_self() if it returns an integer (see NOTES below). It isn't 7059191Skrisneeded on Windows nor on platforms where getpid() returns a different 71160814SsimonID for each thread (see NOTES below). 7259191Skris 7368651SkrisAdditionally, OpenSSL supports dynamic locks, and sometimes, some parts 7468651Skrisof OpenSSL need it for better performance. To enable this, the following 7568651Skrisis required: 7668651Skris 7768651Skris=over 4 7868651Skris 7968651Skris=item * 8068651SkrisThree additional callback function, dyn_create_function, dyn_lock_function 8168651Skrisand dyn_destroy_function. 8268651Skris 8368651Skris=item * 8468651SkrisA structure defined with the data that each lock needs to handle. 8568651Skris 8668651Skris=back 8768651Skris 8868651Skrisstruct CRYPTO_dynlock_value has to be defined to contain whatever structure 8968651Skrisis needed to handle locks. 9068651Skris 9168651Skrisdyn_create_function(const char *file, int line) is needed to create a 9268651Skrislock. Multi-threaded applications might crash at random if it is not set. 9368651Skris 9468651Skrisdyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line) 9568651Skrisis needed to perform locking off dynamic lock numbered n. Multi-threaded 9668651Skrisapplications might crash at random if it is not set. 9768651Skris 9868651Skrisdyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is 9968651Skrisneeded to destroy the lock l. Multi-threaded applications might crash at 10068651Skrisrandom if it is not set. 10168651Skris 10268651SkrisCRYPTO_get_new_dynlockid() is used to create locks. It will call 10368651Skrisdyn_create_function for the actual creation. 10468651Skris 10568651SkrisCRYPTO_destroy_dynlockid() is used to destroy locks. It will call 10668651Skrisdyn_destroy_function for the actual destruction. 10768651Skris 10868651SkrisCRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield 10968651Skrisdescribing what should be done with the lock. n is the number of the 11068651Skrislock as returned from CRYPTO_get_new_dynlockid(). mode can be combined 11168651Skrisfrom the following values. These values are pairwise exclusive, with 11268651Skrisundefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE 11368651Skrisshould not be used together): 11468651Skris 11568651Skris CRYPTO_LOCK 0x01 11668651Skris CRYPTO_UNLOCK 0x02 11768651Skris CRYPTO_READ 0x04 11868651Skris CRYPTO_WRITE 0x08 11968651Skris 12059191Skris=head1 RETURN VALUES 12159191Skris 12259191SkrisCRYPTO_num_locks() returns the required number of locks. 12368651Skris 12468651SkrisCRYPTO_get_new_dynlockid() returns the index to the newly created lock. 12568651Skris 12659191SkrisThe other functions return no values. 12759191Skris 128160814Ssimon=head1 NOTES 12959191Skris 13059191SkrisYou can find out if OpenSSL was configured with thread support: 13159191Skris 13259191Skris #define OPENSSL_THREAD_DEFINES 13359191Skris #include <openssl/opensslconf.h> 134160814Ssimon #if defined(OPENSSL_THREADS) 13559191Skris // thread support enabled 13659191Skris #else 13759191Skris // no thread support 13859191Skris #endif 13959191Skris 14068651SkrisAlso, dynamic locks are currently not used internally by OpenSSL, but 14168651Skrismay do so in the future. 14268651Skris 143160814SsimonDefining id_function(void) has it's own issues. Generally speaking, 144160814Ssimonpthread_self() should be used, even on platforms where getpid() gives 145160814Ssimondifferent answers in each thread, since that may depend on the machine 146160814Ssimonthe program is run on, not the machine where the program is being 147160814Ssimoncompiled. For instance, Red Hat 8 Linux and earlier used 148160814SsimonLinuxThreads, whose getpid() returns a different value for each 149160814Ssimonthread. Red Hat 9 Linux and later use NPTL, which is 150160814SsimonPosix-conformant, and has a getpid() that returns the same value for 151160814Ssimonall threads in a process. A program compiled on Red Hat 8 and run on 152160814SsimonRed Hat 9 will therefore see getpid() returning the same value for 153160814Ssimonall threads. 154160814Ssimon 155160814SsimonThere is still the issue of platforms where pthread_self() returns 156160814Ssimonsomething other than an integer. This is a bit unusual, and this 157160814Ssimonmanual has no cookbook solution for that case. 158160814Ssimon 15959191Skris=head1 EXAMPLES 16059191Skris 16159191SkrisB<crypto/threads/mttest.c> shows examples of the callback functions on 16259191SkrisSolaris, Irix and Win32. 16359191Skris 16459191Skris=head1 HISTORY 16559191Skris 16659191SkrisCRYPTO_set_locking_callback() and CRYPTO_set_id_callback() are 16759191Skrisavailable in all versions of SSLeay and OpenSSL. 16859191SkrisCRYPTO_num_locks() was added in OpenSSL 0.9.4. 16968651SkrisAll functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. 17059191Skris 17159191Skris=head1 SEE ALSO 17259191Skris 17359191SkrisL<crypto(3)|crypto(3)> 17459191Skris 17559191Skris=cut 176