159191Skris=pod 259191Skris 359191Skris=head1 NAME 459191Skris 5238405SjkimCRYPTO_THREADID_set_callback, CRYPTO_THREADID_get_callback, 6238405SjkimCRYPTO_THREADID_current, CRYPTO_THREADID_cmp, CRYPTO_THREADID_cpy, 7238405SjkimCRYPTO_THREADID_hash, CRYPTO_set_locking_callback, CRYPTO_num_locks, 868651SkrisCRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, 968651SkrisCRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, 1068651SkrisCRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support 1159191Skris 1259191Skris=head1 SYNOPSIS 1359191Skris 1459191Skris #include <openssl/crypto.h> 1559191Skris 16238405Sjkim /* Don't use this structure directly. */ 17238405Sjkim typedef struct crypto_threadid_st 18238405Sjkim { 19238405Sjkim void *ptr; 20238405Sjkim unsigned long val; 21238405Sjkim } CRYPTO_THREADID; 22238405Sjkim /* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */ 23238405Sjkim void CRYPTO_THREADID_set_numeric(CRYPTO_THREADID *id, unsigned long val); 24238405Sjkim void CRYPTO_THREADID_set_pointer(CRYPTO_THREADID *id, void *ptr); 25238405Sjkim int CRYPTO_THREADID_set_callback(void (*threadid_func)(CRYPTO_THREADID *)); 26238405Sjkim void (*CRYPTO_THREADID_get_callback(void))(CRYPTO_THREADID *); 27238405Sjkim void CRYPTO_THREADID_current(CRYPTO_THREADID *id); 28238405Sjkim int CRYPTO_THREADID_cmp(const CRYPTO_THREADID *a, 29238405Sjkim const CRYPTO_THREADID *b); 30238405Sjkim void CRYPTO_THREADID_cpy(CRYPTO_THREADID *dest, 31238405Sjkim const CRYPTO_THREADID *src); 32238405Sjkim unsigned long CRYPTO_THREADID_hash(const CRYPTO_THREADID *id); 3359191Skris 3459191Skris int CRYPTO_num_locks(void); 3559191Skris 3668651Skris /* struct CRYPTO_dynlock_value needs to be defined by the user */ 3768651Skris struct CRYPTO_dynlock_value; 3868651Skris 3968651Skris void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * 4068651Skris (*dyn_create_function)(char *file, int line)); 4168651Skris void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) 4268651Skris (int mode, struct CRYPTO_dynlock_value *l, 4368651Skris const char *file, int line)); 4468651Skris void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) 4568651Skris (struct CRYPTO_dynlock_value *l, const char *file, int line)); 4668651Skris 4768651Skris int CRYPTO_get_new_dynlockid(void); 4868651Skris 4968651Skris void CRYPTO_destroy_dynlockid(int i); 5068651Skris 5168651Skris void CRYPTO_lock(int mode, int n, const char *file, int line); 5268651Skris 5368651Skris #define CRYPTO_w_lock(type) \ 5468651Skris CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) 5568651Skris #define CRYPTO_w_unlock(type) \ 5668651Skris CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) 5768651Skris #define CRYPTO_r_lock(type) \ 5868651Skris CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__) 5968651Skris #define CRYPTO_r_unlock(type) \ 6068651Skris CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__) 6168651Skris #define CRYPTO_add(addr,amount,type) \ 6268651Skris CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__) 6368651Skris 6459191Skris=head1 DESCRIPTION 6559191Skris 6659191SkrisOpenSSL can safely be used in multi-threaded applications provided 67238405Sjkimthat at least two callback functions are set, locking_function and 68238405Sjkimthreadid_func. 6959191Skris 7059191Skrislocking_function(int mode, int n, const char *file, int line) is 71109998Smarkmneeded to perform locking on shared data structures. 7289837Skris(Note that OpenSSL uses a number of global data structures that 7389837Skriswill be implicitly shared whenever multiple threads use OpenSSL.) 7489837SkrisMulti-threaded applications will crash at random if it is not set. 7559191Skris 7659191Skrislocking_function() must be able to handle up to CRYPTO_num_locks() 7759191Skrisdifferent mutex locks. It sets the B<n>-th lock if B<mode> & 7859191SkrisB<CRYPTO_LOCK>, and releases it otherwise. 7959191Skris 8059191SkrisB<file> and B<line> are the file number of the function setting the 8159191Skrislock. They can be useful for debugging. 8259191Skris 83238405Sjkimthreadid_func(CRYPTO_THREADID *id) is needed to record the currently-executing 84238405Sjkimthread's identifier into B<id>. The implementation of this callback should not 85238405Sjkimfill in B<id> directly, but should use CRYPTO_THREADID_set_numeric() if thread 86238405SjkimIDs are numeric, or CRYPTO_THREADID_set_pointer() if they are pointer-based. 87238405SjkimIf the application does not register such a callback using 88238405SjkimCRYPTO_THREADID_set_callback(), then a default implementation is used - on 89238405SjkimWindows and BeOS this uses the system's default thread identifying APIs, and on 90238405Sjkimall other platforms it uses the address of B<errno>. The latter is satisfactory 91238405Sjkimfor thread-safety if and only if the platform has a thread-local error number 92238405Sjkimfacility. 9359191Skris 94238405SjkimOnce threadid_func() is registered, or if the built-in default implementation is 95238405Sjkimto be used; 96238405Sjkim 97238405Sjkim=over 4 98238405Sjkim 99238405Sjkim=item * 100238405SjkimCRYPTO_THREADID_current() records the currently-executing thread ID into the 101238405Sjkimgiven B<id> object. 102238405Sjkim 103238405Sjkim=item * 104238405SjkimCRYPTO_THREADID_cmp() compares two thread IDs (returning zero for equality, ie. 105238405Sjkimthe same semantics as memcmp()). 106238405Sjkim 107238405Sjkim=item * 108238405SjkimCRYPTO_THREADID_cpy() duplicates a thread ID value, 109238405Sjkim 110238405Sjkim=item * 111238405SjkimCRYPTO_THREADID_hash() returns a numeric value usable as a hash-table key. This 112238405Sjkimis usually the exact numeric or pointer-based thread ID used internally, however 113238405Sjkimthis also handles the unusual case where pointers are larger than 'long' 114238405Sjkimvariables and the platform's thread IDs are pointer-based - in this case, mixing 115238405Sjkimis done to attempt to produce a unique numeric value even though it is not as 116238405Sjkimwide as the platform's true thread IDs. 117238405Sjkim 118238405Sjkim=back 119238405Sjkim 12068651SkrisAdditionally, OpenSSL supports dynamic locks, and sometimes, some parts 12168651Skrisof OpenSSL need it for better performance. To enable this, the following 12268651Skrisis required: 12368651Skris 12468651Skris=over 4 12568651Skris 12668651Skris=item * 12768651SkrisThree additional callback function, dyn_create_function, dyn_lock_function 12868651Skrisand dyn_destroy_function. 12968651Skris 13068651Skris=item * 13168651SkrisA structure defined with the data that each lock needs to handle. 13268651Skris 13368651Skris=back 13468651Skris 13568651Skrisstruct CRYPTO_dynlock_value has to be defined to contain whatever structure 13668651Skrisis needed to handle locks. 13768651Skris 13868651Skrisdyn_create_function(const char *file, int line) is needed to create a 13968651Skrislock. Multi-threaded applications might crash at random if it is not set. 14068651Skris 14168651Skrisdyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line) 14268651Skrisis needed to perform locking off dynamic lock numbered n. Multi-threaded 14368651Skrisapplications might crash at random if it is not set. 14468651Skris 14568651Skrisdyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is 14668651Skrisneeded to destroy the lock l. Multi-threaded applications might crash at 14768651Skrisrandom if it is not set. 14868651Skris 14968651SkrisCRYPTO_get_new_dynlockid() is used to create locks. It will call 15068651Skrisdyn_create_function for the actual creation. 15168651Skris 15268651SkrisCRYPTO_destroy_dynlockid() is used to destroy locks. It will call 15368651Skrisdyn_destroy_function for the actual destruction. 15468651Skris 15568651SkrisCRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield 15668651Skrisdescribing what should be done with the lock. n is the number of the 15768651Skrislock as returned from CRYPTO_get_new_dynlockid(). mode can be combined 15868651Skrisfrom the following values. These values are pairwise exclusive, with 15968651Skrisundefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE 16068651Skrisshould not be used together): 16168651Skris 16268651Skris CRYPTO_LOCK 0x01 16368651Skris CRYPTO_UNLOCK 0x02 16468651Skris CRYPTO_READ 0x04 16568651Skris CRYPTO_WRITE 0x08 16668651Skris 16759191Skris=head1 RETURN VALUES 16859191Skris 16959191SkrisCRYPTO_num_locks() returns the required number of locks. 17068651Skris 17168651SkrisCRYPTO_get_new_dynlockid() returns the index to the newly created lock. 17268651Skris 17359191SkrisThe other functions return no values. 17459191Skris 175160814Ssimon=head1 NOTES 17659191Skris 17759191SkrisYou can find out if OpenSSL was configured with thread support: 17859191Skris 17959191Skris #define OPENSSL_THREAD_DEFINES 18059191Skris #include <openssl/opensslconf.h> 181160814Ssimon #if defined(OPENSSL_THREADS) 18259191Skris // thread support enabled 18359191Skris #else 18459191Skris // no thread support 18559191Skris #endif 18659191Skris 18768651SkrisAlso, dynamic locks are currently not used internally by OpenSSL, but 18868651Skrismay do so in the future. 18968651Skris 19059191Skris=head1 EXAMPLES 19159191Skris 19259191SkrisB<crypto/threads/mttest.c> shows examples of the callback functions on 19359191SkrisSolaris, Irix and Win32. 19459191Skris 19559191Skris=head1 HISTORY 19659191Skris 197238405SjkimCRYPTO_set_locking_callback() is 19859191Skrisavailable in all versions of SSLeay and OpenSSL. 19959191SkrisCRYPTO_num_locks() was added in OpenSSL 0.9.4. 20068651SkrisAll functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. 201238405SjkimB<CRYPTO_THREADID> and associated functions were introduced in OpenSSL 1.0.0 202238405Sjkimto replace (actually, deprecate) the previous CRYPTO_set_id_callback(), 203238405SjkimCRYPTO_get_id_callback(), and CRYPTO_thread_id() functions which assumed 204238405Sjkimthread IDs to always be represented by 'unsigned long'. 20559191Skris 20659191Skris=head1 SEE ALSO 20759191Skris 20859191SkrisL<crypto(3)|crypto(3)> 20959191Skris 21059191Skris=cut 211