OLD | NEW |
1 =pod | 1 =pod |
2 | 2 |
3 =head1 NAME | 3 =head1 NAME |
4 | 4 |
5 CRYPTO_set_locking_callback, CRYPTO_set_id_callback, CRYPTO_num_locks, | 5 CRYPTO_THREADID_set_callback, CRYPTO_THREADID_get_callback, |
| 6 CRYPTO_THREADID_current, CRYPTO_THREADID_cmp, CRYPTO_THREADID_cpy, |
| 7 CRYPTO_THREADID_hash, CRYPTO_set_locking_callback, CRYPTO_num_locks, |
6 CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, | 8 CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, |
7 CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, | 9 CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, |
8 CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support | 10 CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support |
9 | 11 |
10 =head1 SYNOPSIS | 12 =head1 SYNOPSIS |
11 | 13 |
12 #include <openssl/crypto.h> | 14 #include <openssl/crypto.h> |
13 | 15 |
14 void CRYPTO_set_locking_callback(void (*locking_function)(int mode, | 16 /* Don't use this structure directly. */ |
15 int n, const char *file, int line)); | 17 typedef struct crypto_threadid_st |
16 | 18 { |
17 void CRYPTO_set_id_callback(unsigned long (*id_function)(void)); | 19 void *ptr; |
| 20 unsigned long val; |
| 21 } CRYPTO_THREADID; |
| 22 /* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */ |
| 23 void CRYPTO_THREADID_set_numeric(CRYPTO_THREADID *id, unsigned long val); |
| 24 void CRYPTO_THREADID_set_pointer(CRYPTO_THREADID *id, void *ptr); |
| 25 int CRYPTO_THREADID_set_callback(void (*threadid_func)(CRYPTO_THREADID *)); |
| 26 void (*CRYPTO_THREADID_get_callback(void))(CRYPTO_THREADID *); |
| 27 void CRYPTO_THREADID_current(CRYPTO_THREADID *id); |
| 28 int CRYPTO_THREADID_cmp(const CRYPTO_THREADID *a, |
| 29 const CRYPTO_THREADID *b); |
| 30 void CRYPTO_THREADID_cpy(CRYPTO_THREADID *dest, |
| 31 const CRYPTO_THREADID *src); |
| 32 unsigned long CRYPTO_THREADID_hash(const CRYPTO_THREADID *id); |
18 | 33 |
19 int CRYPTO_num_locks(void); | 34 int CRYPTO_num_locks(void); |
20 | 35 |
21 | |
22 /* struct CRYPTO_dynlock_value needs to be defined by the user */ | 36 /* struct CRYPTO_dynlock_value needs to be defined by the user */ |
23 struct CRYPTO_dynlock_value; | 37 struct CRYPTO_dynlock_value; |
24 | 38 |
25 void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * | 39 void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * |
26 (*dyn_create_function)(char *file, int line)); | 40 (*dyn_create_function)(char *file, int line)); |
27 void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) | 41 void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) |
28 (int mode, struct CRYPTO_dynlock_value *l, | 42 (int mode, struct CRYPTO_dynlock_value *l, |
29 const char *file, int line)); | 43 const char *file, int line)); |
30 void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) | 44 void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) |
31 (struct CRYPTO_dynlock_value *l, const char *file, int line)); | 45 (struct CRYPTO_dynlock_value *l, const char *file, int line)); |
(...skipping 11 matching lines...) Expand all Loading... |
43 #define CRYPTO_r_lock(type) \ | 57 #define CRYPTO_r_lock(type) \ |
44 CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__) | 58 CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__) |
45 #define CRYPTO_r_unlock(type) \ | 59 #define CRYPTO_r_unlock(type) \ |
46 CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__) | 60 CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__) |
47 #define CRYPTO_add(addr,amount,type) \ | 61 #define CRYPTO_add(addr,amount,type) \ |
48 CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__) | 62 CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__) |
49 | 63 |
50 =head1 DESCRIPTION | 64 =head1 DESCRIPTION |
51 | 65 |
52 OpenSSL can safely be used in multi-threaded applications provided | 66 OpenSSL can safely be used in multi-threaded applications provided |
53 that at least two callback functions are set. | 67 that at least two callback functions are set, locking_function and |
| 68 threadid_func. |
54 | 69 |
55 locking_function(int mode, int n, const char *file, int line) is | 70 locking_function(int mode, int n, const char *file, int line) is |
56 needed to perform locking on shared data structures. | 71 needed to perform locking on shared data structures. |
57 (Note that OpenSSL uses a number of global data structures that | 72 (Note that OpenSSL uses a number of global data structures that |
58 will be implicitly shared whenever multiple threads use OpenSSL.) | 73 will be implicitly shared whenever multiple threads use OpenSSL.) |
59 Multi-threaded applications will crash at random if it is not set. | 74 Multi-threaded applications will crash at random if it is not set. |
60 | 75 |
61 locking_function() must be able to handle up to CRYPTO_num_locks() | 76 locking_function() must be able to handle up to CRYPTO_num_locks() |
62 different mutex locks. It sets the B<n>-th lock if B<mode> & | 77 different mutex locks. It sets the B<n>-th lock if B<mode> & |
63 B<CRYPTO_LOCK>, and releases it otherwise. | 78 B<CRYPTO_LOCK>, and releases it otherwise. |
64 | 79 |
65 B<file> and B<line> are the file number of the function setting the | 80 B<file> and B<line> are the file number of the function setting the |
66 lock. They can be useful for debugging. | 81 lock. They can be useful for debugging. |
67 | 82 |
68 id_function(void) is a function that returns a thread ID, for example | 83 threadid_func(CRYPTO_THREADID *id) is needed to record the currently-executing |
69 pthread_self() if it returns an integer (see NOTES below). It isn't | 84 thread's identifier into B<id>. The implementation of this callback should not |
70 needed on Windows nor on platforms where getpid() returns a different | 85 fill in B<id> directly, but should use CRYPTO_THREADID_set_numeric() if thread |
71 ID for each thread (see NOTES below). | 86 IDs are numeric, or CRYPTO_THREADID_set_pointer() if they are pointer-based. |
| 87 If the application does not register such a callback using |
| 88 CRYPTO_THREADID_set_callback(), then a default implementation is used - on |
| 89 Windows and BeOS this uses the system's default thread identifying APIs, and on |
| 90 all other platforms it uses the address of B<errno>. The latter is satisfactory |
| 91 for thread-safety if and only if the platform has a thread-local error number |
| 92 facility. |
| 93 |
| 94 Once threadid_func() is registered, or if the built-in default implementation is |
| 95 to be used; |
| 96 |
| 97 =over 4 |
| 98 |
| 99 =item * |
| 100 CRYPTO_THREADID_current() records the currently-executing thread ID into the |
| 101 given B<id> object. |
| 102 |
| 103 =item * |
| 104 CRYPTO_THREADID_cmp() compares two thread IDs (returning zero for equality, ie. |
| 105 the same semantics as memcmp()). |
| 106 |
| 107 =item * |
| 108 CRYPTO_THREADID_cpy() duplicates a thread ID value, |
| 109 |
| 110 =item * |
| 111 CRYPTO_THREADID_hash() returns a numeric value usable as a hash-table key. This |
| 112 is usually the exact numeric or pointer-based thread ID used internally, however |
| 113 this also handles the unusual case where pointers are larger than 'long' |
| 114 variables and the platform's thread IDs are pointer-based - in this case, mixing |
| 115 is done to attempt to produce a unique numeric value even though it is not as |
| 116 wide as the platform's true thread IDs. |
| 117 |
| 118 =back |
72 | 119 |
73 Additionally, OpenSSL supports dynamic locks, and sometimes, some parts | 120 Additionally, OpenSSL supports dynamic locks, and sometimes, some parts |
74 of OpenSSL need it for better performance. To enable this, the following | 121 of OpenSSL need it for better performance. To enable this, the following |
75 is required: | 122 is required: |
76 | 123 |
77 =over 4 | 124 =over 4 |
78 | 125 |
79 =item * | 126 =item * |
80 Three additional callback function, dyn_create_function, dyn_lock_function | 127 Three additional callback function, dyn_create_function, dyn_lock_function |
81 and dyn_destroy_function. | 128 and dyn_destroy_function. |
(...skipping 51 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
133 #include <openssl/opensslconf.h> | 180 #include <openssl/opensslconf.h> |
134 #if defined(OPENSSL_THREADS) | 181 #if defined(OPENSSL_THREADS) |
135 // thread support enabled | 182 // thread support enabled |
136 #else | 183 #else |
137 // no thread support | 184 // no thread support |
138 #endif | 185 #endif |
139 | 186 |
140 Also, dynamic locks are currently not used internally by OpenSSL, but | 187 Also, dynamic locks are currently not used internally by OpenSSL, but |
141 may do so in the future. | 188 may do so in the future. |
142 | 189 |
143 Defining id_function(void) has it's own issues. Generally speaking, | |
144 pthread_self() should be used, even on platforms where getpid() gives | |
145 different answers in each thread, since that may depend on the machine | |
146 the program is run on, not the machine where the program is being | |
147 compiled. For instance, Red Hat 8 Linux and earlier used | |
148 LinuxThreads, whose getpid() returns a different value for each | |
149 thread. Red Hat 9 Linux and later use NPTL, which is | |
150 Posix-conformant, and has a getpid() that returns the same value for | |
151 all threads in a process. A program compiled on Red Hat 8 and run on | |
152 Red Hat 9 will therefore see getpid() returning the same value for | |
153 all threads. | |
154 | |
155 There is still the issue of platforms where pthread_self() returns | |
156 something other than an integer. This is a bit unusual, and this | |
157 manual has no cookbook solution for that case. | |
158 | |
159 =head1 EXAMPLES | 190 =head1 EXAMPLES |
160 | 191 |
161 B<crypto/threads/mttest.c> shows examples of the callback functions on | 192 B<crypto/threads/mttest.c> shows examples of the callback functions on |
162 Solaris, Irix and Win32. | 193 Solaris, Irix and Win32. |
163 | 194 |
164 =head1 HISTORY | 195 =head1 HISTORY |
165 | 196 |
166 CRYPTO_set_locking_callback() and CRYPTO_set_id_callback() are | 197 CRYPTO_set_locking_callback() is |
167 available in all versions of SSLeay and OpenSSL. | 198 available in all versions of SSLeay and OpenSSL. |
168 CRYPTO_num_locks() was added in OpenSSL 0.9.4. | 199 CRYPTO_num_locks() was added in OpenSSL 0.9.4. |
169 All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. | 200 All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. |
| 201 B<CRYPTO_THREADID> and associated functions were introduced in OpenSSL 1.0.0 |
| 202 to replace (actually, deprecate) the previous CRYPTO_set_id_callback(), |
| 203 CRYPTO_get_id_callback(), and CRYPTO_thread_id() functions which assumed |
| 204 thread IDs to always be represented by 'unsigned long'. |
170 | 205 |
171 =head1 SEE ALSO | 206 =head1 SEE ALSO |
172 | 207 |
173 L<crypto(3)|crypto(3)> | 208 L<crypto(3)|crypto(3)> |
174 | 209 |
175 =cut | 210 =cut |
OLD | NEW |