1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks, 6*2175Sjp161948CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, 7*2175Sjp161948CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, 8*2175Sjp161948CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support 9*2175Sjp161948 10*2175Sjp161948=head1 SYNOPSIS 11*2175Sjp161948 12*2175Sjp161948 #include <openssl/crypto.h> 13*2175Sjp161948 14*2175Sjp161948 void CRYPTO_set_locking_callback(void (*locking_function)(int mode, 15*2175Sjp161948 int n, const char *file, int line)); 16*2175Sjp161948 17*2175Sjp161948 void CRYPTO_set_id_callback(unsigned long (*id_function)(void)); 18*2175Sjp161948 19*2175Sjp161948 int CRYPTO_num_locks(void); 20*2175Sjp161948 21*2175Sjp161948 22*2175Sjp161948 /* struct CRYPTO_dynlock_value needs to be defined by the user */ 23*2175Sjp161948 struct CRYPTO_dynlock_value; 24*2175Sjp161948 25*2175Sjp161948 void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * 26*2175Sjp161948 (*dyn_create_function)(char *file, int line)); 27*2175Sjp161948 void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) 28*2175Sjp161948 (int mode, struct CRYPTO_dynlock_value *l, 29*2175Sjp161948 const char *file, int line)); 30*2175Sjp161948 void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) 31*2175Sjp161948 (struct CRYPTO_dynlock_value *l, const char *file, int line)); 32*2175Sjp161948 33*2175Sjp161948 int CRYPTO_get_new_dynlockid(void); 34*2175Sjp161948 35*2175Sjp161948 void CRYPTO_destroy_dynlockid(int i); 36*2175Sjp161948 37*2175Sjp161948 void CRYPTO_lock(int mode, int n, const char *file, int line); 38*2175Sjp161948 39*2175Sjp161948 #define CRYPTO_w_lock(type) \ 40*2175Sjp161948 CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) 41*2175Sjp161948 #define CRYPTO_w_unlock(type) \ 42*2175Sjp161948 CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) 43*2175Sjp161948 #define CRYPTO_r_lock(type) \ 44*2175Sjp161948 CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__) 45*2175Sjp161948 #define CRYPTO_r_unlock(type) \ 46*2175Sjp161948 CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__) 47*2175Sjp161948 #define CRYPTO_add(addr,amount,type) \ 48*2175Sjp161948 CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__) 49*2175Sjp161948 50*2175Sjp161948=head1 DESCRIPTION 51*2175Sjp161948 52*2175Sjp161948OpenSSL can safely be used in multi-threaded applications provided 53*2175Sjp161948that at least two callback functions are set. 54*2175Sjp161948 55*2175Sjp161948locking_function(int mode, int n, const char *file, int line) is 56*2175Sjp161948needed to perform locking on shared data structures. 57*2175Sjp161948(Note that OpenSSL uses a number of global data structures that 58*2175Sjp161948will be implicitly shared whenever multiple threads use OpenSSL.) 59*2175Sjp161948Multi-threaded applications will crash at random if it is not set. 60*2175Sjp161948 61*2175Sjp161948locking_function() must be able to handle up to CRYPTO_num_locks() 62*2175Sjp161948different mutex locks. It sets the B<n>-th lock if B<mode> & 63*2175Sjp161948B<CRYPTO_LOCK>, and releases it otherwise. 64*2175Sjp161948 65*2175Sjp161948B<file> and B<line> are the file number of the function setting the 66*2175Sjp161948lock. They can be useful for debugging. 67*2175Sjp161948 68*2175Sjp161948id_function(void) is a function that returns a thread ID, for example 69*2175Sjp161948pthread_self() if it returns an integer (see NOTES below). It isn't 70*2175Sjp161948needed on Windows nor on platforms where getpid() returns a different 71*2175Sjp161948ID for each thread (see NOTES below). 72*2175Sjp161948 73*2175Sjp161948Additionally, OpenSSL supports dynamic locks, and sometimes, some parts 74*2175Sjp161948of OpenSSL need it for better performance. To enable this, the following 75*2175Sjp161948is required: 76*2175Sjp161948 77*2175Sjp161948=over 4 78*2175Sjp161948 79*2175Sjp161948=item * 80*2175Sjp161948Three additional callback function, dyn_create_function, dyn_lock_function 81*2175Sjp161948and dyn_destroy_function. 82*2175Sjp161948 83*2175Sjp161948=item * 84*2175Sjp161948A structure defined with the data that each lock needs to handle. 85*2175Sjp161948 86*2175Sjp161948=back 87*2175Sjp161948 88*2175Sjp161948struct CRYPTO_dynlock_value has to be defined to contain whatever structure 89*2175Sjp161948is needed to handle locks. 90*2175Sjp161948 91*2175Sjp161948dyn_create_function(const char *file, int line) is needed to create a 92*2175Sjp161948lock. Multi-threaded applications might crash at random if it is not set. 93*2175Sjp161948 94*2175Sjp161948dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line) 95*2175Sjp161948is needed to perform locking off dynamic lock numbered n. Multi-threaded 96*2175Sjp161948applications might crash at random if it is not set. 97*2175Sjp161948 98*2175Sjp161948dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is 99*2175Sjp161948needed to destroy the lock l. Multi-threaded applications might crash at 100*2175Sjp161948random if it is not set. 101*2175Sjp161948 102*2175Sjp161948CRYPTO_get_new_dynlockid() is used to create locks. It will call 103*2175Sjp161948dyn_create_function for the actual creation. 104*2175Sjp161948 105*2175Sjp161948CRYPTO_destroy_dynlockid() is used to destroy locks. It will call 106*2175Sjp161948dyn_destroy_function for the actual destruction. 107*2175Sjp161948 108*2175Sjp161948CRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield 109*2175Sjp161948describing what should be done with the lock. n is the number of the 110*2175Sjp161948lock as returned from CRYPTO_get_new_dynlockid(). mode can be combined 111*2175Sjp161948from the following values. These values are pairwise exclusive, with 112*2175Sjp161948undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE 113*2175Sjp161948should not be used together): 114*2175Sjp161948 115*2175Sjp161948 CRYPTO_LOCK 0x01 116*2175Sjp161948 CRYPTO_UNLOCK 0x02 117*2175Sjp161948 CRYPTO_READ 0x04 118*2175Sjp161948 CRYPTO_WRITE 0x08 119*2175Sjp161948 120*2175Sjp161948=head1 RETURN VALUES 121*2175Sjp161948 122*2175Sjp161948CRYPTO_num_locks() returns the required number of locks. 123*2175Sjp161948 124*2175Sjp161948CRYPTO_get_new_dynlockid() returns the index to the newly created lock. 125*2175Sjp161948 126*2175Sjp161948The other functions return no values. 127*2175Sjp161948 128*2175Sjp161948=head1 NOTES 129*2175Sjp161948 130*2175Sjp161948You can find out if OpenSSL was configured with thread support: 131*2175Sjp161948 132*2175Sjp161948 #define OPENSSL_THREAD_DEFINES 133*2175Sjp161948 #include <openssl/opensslconf.h> 134*2175Sjp161948 #if defined(OPENSSL_THREADS) 135*2175Sjp161948 // thread support enabled 136*2175Sjp161948 #else 137*2175Sjp161948 // no thread support 138*2175Sjp161948 #endif 139*2175Sjp161948 140*2175Sjp161948Also, dynamic locks are currently not used internally by OpenSSL, but 141*2175Sjp161948may do so in the future. 142*2175Sjp161948 143*2175Sjp161948Defining id_function(void) has it's own issues. Generally speaking, 144*2175Sjp161948pthread_self() should be used, even on platforms where getpid() gives 145*2175Sjp161948different answers in each thread, since that may depend on the machine 146*2175Sjp161948the program is run on, not the machine where the program is being 147*2175Sjp161948compiled. For instance, Red Hat 8 Linux and earlier used 148*2175Sjp161948LinuxThreads, whose getpid() returns a different value for each 149*2175Sjp161948thread. Red Hat 9 Linux and later use NPTL, which is 150*2175Sjp161948Posix-conformant, and has a getpid() that returns the same value for 151*2175Sjp161948all threads in a process. A program compiled on Red Hat 8 and run on 152*2175Sjp161948Red Hat 9 will therefore see getpid() returning the same value for 153*2175Sjp161948all threads. 154*2175Sjp161948 155*2175Sjp161948There is still the issue of platforms where pthread_self() returns 156*2175Sjp161948something other than an integer. This is a bit unusual, and this 157*2175Sjp161948manual has no cookbook solution for that case. 158*2175Sjp161948 159*2175Sjp161948=head1 EXAMPLES 160*2175Sjp161948 161*2175Sjp161948B<crypto/threads/mttest.c> shows examples of the callback functions on 162*2175Sjp161948Solaris, Irix and Win32. 163*2175Sjp161948 164*2175Sjp161948=head1 HISTORY 165*2175Sjp161948 166*2175Sjp161948CRYPTO_set_locking_callback() and CRYPTO_set_id_callback() are 167*2175Sjp161948available in all versions of SSLeay and OpenSSL. 168*2175Sjp161948CRYPTO_num_locks() was added in OpenSSL 0.9.4. 169*2175Sjp161948All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. 170*2175Sjp161948 171*2175Sjp161948=head1 SEE ALSO 172*2175Sjp161948 173*2175Sjp161948L<crypto(3)|crypto(3)> 174*2175Sjp161948 175*2175Sjp161948=cut 176