| blob | 70518c7453d5c154834670c6e72e795cb8d6ac34 |
1 .\" $OpenBSD: CRYPTO_set_locking_callback.3,v 1.5 2016/11/23 16:28:23 schwarze Exp $
2 .\" OpenSSL doc/crypto/threads.pod fb552ac6 Sep 30 23:43:01 2009 +0000
3 .\"
4 .\" This file was written by Ulf Moeller <ulf@openssl.org>,
5 .\" Richard Levitte <levitte@openssl.org>, Bodo Moeller <bodo@openssl.org>,
6 .\" and Geoff Thorpe <geoff@openssl.org>.
7 .\" Copyright (c) 2000, 2001, 2005, 2006, 2008, 2009 The OpenSSL Project.
8 .\" All rights reserved.
9 .\"
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
12 .\" are met:
13 .\"
14 .\" 1. Redistributions of source code must retain the above copyright
15 .\" notice, this list of conditions and the following disclaimer.
16 .\"
17 .\" 2. Redistributions in binary form must reproduce the above copyright
18 .\" notice, this list of conditions and the following disclaimer in
19 .\" the documentation and/or other materials provided with the
20 .\" distribution.
21 .\"
22 .\" 3. All advertising materials mentioning features or use of this
23 .\" software must display the following acknowledgment:
24 .\" "This product includes software developed by the OpenSSL Project
25 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
26 .\"
27 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
28 .\" endorse or promote products derived from this software without
29 .\" prior written permission. For written permission, please contact
30 .\" openssl-core@openssl.org.
31 .\"
32 .\" 5. Products derived from this software may not be called "OpenSSL"
33 .\" nor may "OpenSSL" appear in their names without prior written
34 .\" permission of the OpenSSL Project.
35 .\"
36 .\" 6. Redistributions of any form whatsoever must retain the following
37 .\" acknowledgment:
38 .\" "This product includes software developed by the OpenSSL Project
39 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
40 .\"
41 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
42 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
43 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
44 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
45 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
46 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
47 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
48 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
49 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
50 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
51 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
52 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
53 .\"
54 .Dd $Mdocdate: November 23 2016 $
55 .Dt CRYPTO_SET_LOCKING_CALLBACK 3
56 .Os
57 .Sh NAME
58 .Nm CRYPTO_THREADID_set_numeric ,
59 .Nm CRYPTO_THREADID_set_pointer ,
60 .Nm CRYPTO_THREADID_set_callback ,
61 .Nm CRYPTO_THREADID_get_callback ,
62 .Nm CRYPTO_THREADID_current ,
63 .Nm CRYPTO_THREADID_cmp ,
64 .Nm CRYPTO_THREADID_cpy ,
65 .Nm CRYPTO_THREADID_hash ,
66 .Nm CRYPTO_num_locks ,
67 .Nm CRYPTO_set_dynlock_create_callback ,
68 .Nm CRYPTO_set_dynlock_lock_callback ,
69 .Nm CRYPTO_set_dynlock_destroy_callback ,
70 .Nm CRYPTO_get_new_dynlockid ,
71 .Nm CRYPTO_destroy_dynlockid ,
72 .Nm CRYPTO_lock ,
73 .Nm CRYPTO_w_lock ,
74 .Nm CRYPTO_w_unlock ,
75 .Nm CRYPTO_r_lock ,
76 .Nm CRYPTO_r_unlock ,
77 .Nm CRYPTO_add
78 .Nd OpenSSL thread support
79 .Sh SYNOPSIS
80 .In openssl/crypto.h
81 .Bd -literal
82 /* Don't use this structure directly. */
83 typedef struct crypto_threadid_st {
84 void *ptr;
85 unsigned long val;
86 } CRYPTO_THREADID;
87 /* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */
88 .Ed
89 .Pp
90 .Ft void
91 .Fo CRYPTO_THREADID_set_numeric
92 .Fa "CRYPTO_THREADID *id"
93 .Fa "unsigned long val"
94 .Fc
95 .Ft void
96 .Fo CRYPTO_THREADID_set_pointer
97 .Fa "CRYPTO_THREADID *id"
98 .Fa "void *ptr"
99 .Fc
100 .Ft int
101 .Fo CRYPTO_THREADID_set_callback
102 .Fa "void (*threadid_func)(CRYPTO_THREADID *)"
103 .Fc
104 .Ft void
105 .Fo "(*CRYPTO_THREADID_get_callback(void))"
106 .Fa "CRYPTO_THREADID *"
107 .Fc
108 .Ft void
109 .Fo CRYPTO_THREADID_current
110 .Fa "CRYPTO_THREADID *id"
111 .Fc
112 .Ft int
113 .Fo CRYPTO_THREADID_cmp
114 .Fa "const CRYPTO_THREADID *a"
115 .Fa "const CRYPTO_THREADID *b"
116 .Fc
117 .Ft void
118 .Fo CRYPTO_THREADID_cpy
119 .Fa "CRYPTO_THREADID *dest"
120 .Fa "const CRYPTO_THREADID *src"
121 .Fc
122 .Ft unsigned long
123 .Fo CRYPTO_THREADID_hash
124 .Fa "const CRYPTO_THREADID *id"
125 .Fc
126 .Ft int
127 .Fo CRYPTO_num_locks
128 .Fa void
129 .Fc
130 .Bd -literal
131 /* struct CRYPTO_dynlock_value needs to be defined by the user */
132 struct CRYPTO_dynlock_value;
133 .Ed
134 .Pp
135 .Ft void
136 .Fo CRYPTO_set_dynlock_create_callback
137 .Fa "struct CRYPTO_dynlock_value *"
138 .Fa "(*dyn_create_function)(char *file, int line)"
139 .Fc
140 .Ft void
141 .Fo CRYPTO_set_dynlock_lock_callback
142 .Fa "void (*dyn_lock_function)(int mode, struct CRYPTO_dynlock_value *l,\
143 const char *file, int line)"
144 .Fc
145 .Ft void
146 .Fo CRYPTO_set_dynlock_destroy_callback
147 .Fa "void (*dyn_destroy_function)(struct CRYPTO_dynlock_value *l,\
148 const char *file, int line)"
149 .Fc
150 .Ft int
151 .Fo CRYPTO_get_new_dynlockid
152 .Fa void
153 .Fc
154 .Ft void
155 .Fo CRYPTO_destroy_dynlockid
156 .Fa "int i"
157 .Fc
158 .Ft void
159 .Fo CRYPTO_lock
160 .Fa "int mode"
161 .Fa "int n"
162 .Fa "const char *file"
163 .Fa "int line"
164 .Fc
165 .Bd -literal
166 #define CRYPTO_w_lock(type) \e
167 CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE, type, __FILE__, __LINE__)
168 #define CRYPTO_w_unlock(type) \e
169 CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE, type, __FILE__, __LINE__)
170 #define CRYPTO_r_lock(type) \e
171 CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ, type, __FILE__, __LINE__)
172 #define CRYPTO_r_unlock(type) \e
173 CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ, type, __FILE__, __LINE__)
174 #define CRYPTO_add(addr,amount,type) \e
175 CRYPTO_add_lock(addr, amount, type, __FILE__, __LINE__)
176 .Ed
177 .Sh DESCRIPTION
178 OpenSSL can safely be used in multi-threaded applications provided that
179 at least two callback functions are set,
180 .Fn locking_function
181 and
182 .Fn threadid_func .
183 .Pp
184 .Fo locking_function
185 .Fa "int mode"
186 .Fa "int n"
187 .Fa "const char *file"
188 .Fa "int line"
189 .Fc
190 is needed to perform locking on shared data structures.
191 Note that OpenSSL uses a number of global data structures that will be
192 implicitly shared whenever multiple threads use OpenSSL.
193 Multi-threaded applications will crash at random if it is not set.
194 .Pp
195 .Fn locking_function
196 must be able to handle up to
197 .Fn CRYPTO_num_locks
198 different mutex locks.
199 It sets the
200 .Fa n Ns -th
201 lock if
202 .Fa mode
203 includes
204 .Dv CRYPTO_LOCK ,
205 and releases it otherwise.
206 .Pp
207 .Fa file
208 and
209 .Fa line
210 are the file number of the function setting the lock.
211 They can be useful for debugging.
212 .Pp
213 .Fo threadid_func
214 .Fa "CRYPTO_THREADID *id"
215 .Fc
216 is needed to record the currently-executing thread's identifier into
217 .Fa id .
218 The implementation of this callback should not fill in
219 .Fa id
220 directly, but should use
221 .Fn CRYPTO_THREADID_set_numeric
222 if thread IDs are numeric, or
223 .Fn CRYPTO_THREADID_set_pointer
224 if they are pointer-based.
225 If the application does not register such a callback using
226 .Fn CRYPTO_THREADID_set_callback ,
227 then a default implementation is used - on Windows and BeOS this uses
228 the system's default thread identifying APIs, and on all other platforms
229 it uses the address of
230 .Va errno .
231 The latter is satisfactory for thread-safety if and only if the platform
232 has a thread-local error number facility.
233 .Pp
234 Once
235 .Fn threadid_func
236 is registered, or if the built-in default implementation is to be used,
237 .Bl -bullet
238 .It
239 .Fn CRYPTO_THREADID_current
240 records the currently-executing thread ID into the given
241 .Fa id
242 object.
243 .It
244 .Fn CRYPTO_THREADID_cmp
245 compares two thread IDs (returning zero for equality, i.e. the same
246 semantics as
247 .Xr memcmp 3 ) .
248 .It
249 .Fn CRYPTO_THREADID_cpy
250 duplicates a thread ID value.
251 .It
252 .Fn CRYPTO_THREADID_hash
253 returns a numeric value usable as a hash-table key.
254 This is usually the exact numeric or pointer-based thread ID used
255 internally, however this also handles the unusual case where pointers
256 are larger than
257 .Vt long
258 variables and the platform's thread IDs are pointer-based \(em in
259 this case, mixing is done to attempt to produce a unique numeric
260 value even though it is not as wide as the platform's true thread
261 IDs.
262 .El
263 .Pp
264 Additionally, OpenSSL supports dynamic locks and, sometimes, some parts
265 of OpenSSL need it for better performance.
266 To enable this, the following is required:
267 .Bl -bullet
268 .It
269 Three additional callback functions,
270 .Fn dyn_create_function ,
271 .Fn dyn_lock_function ,
272 and
273 .Fn dyn_destroy_function .
274 .It
275 A structure defined with the data that each lock needs to handle.
276 .El
277 .Pp
278 .Vt struct CRYPTO_dynlock_value
279 has to be defined to contain whatever structure is needed to handle locks.
280 .Pp
281 .Fo dyn_create_function
282 .Fa "const char *file"
283 .Fa "int line"
284 .Fc
285 is needed to create a lock.
286 Multi-threaded applications might crash at random if it is not set.
287 .Pp
288 .Fo dyn_lock_function
289 .Fa "int mode"
290 .Fa "CRYPTO_dynlock *l"
291 .Fa "const char *file"
292 .Fa "int line"
293 .Fc
294 is needed to perform locking off dynamic lock numbered n.
295 Multi-threaded applications might crash at random if it is not set.
296 .Pp
297 .Fo dyn_destroy_function
298 .Fa "CRYPTO_dynlock *l"
299 .Fa "const char *file"
300 .Fa "int line"
301 .Fc
302 is needed to destroy the lock
303 .Fa l .
304 Multi-threaded applications might crash at random if it is not set.
305 .Pp
306 .Fn CRYPTO_get_new_dynlockid
307 is used to create locks.
308 It will call
309 .Fn dyn_create_function
310 for the actual creation.
311 .Pp
312 .Fn CRYPTO_destroy_dynlockid
313 is used to destroy locks.
314 It will call
315 .Fn dyn_destroy_function
316 for the actual destruction.
317 .Pp
318 .Fn CRYPTO_lock
319 is used to lock and unlock the locks.
320 .Fa mode
321 is a bitfield describing what should be done with the lock.
322 .Fa n
323 is the number of the lock as returned from
324 .Fn CRYPTO_get_new_dynlockid .
325 .Fa mode
326 can be combined from the following values.
327 These values are pairwise exclusive, with undefined behaviour if misused
328 (for example,
329 .Dv CRYPTO_READ
330 and
331 .Dv CRYPTO_WRITE
332 should not be used together):
333 .Bd -literal -offset indent
334 CRYPTO_LOCK 0x01
335 CRYPTO_UNLOCK 0x02
336 CRYPTO_READ 0x04
337 CRYPTO_WRITE 0x08
338 .Ed
339 .Pp
340 You can find out if OpenSSL was configured with thread support:
341 .Bd -literal -offset indent
342 #define OPENSSL_THREAD_DEFINES
343 #include <openssl/opensslconf.h>
344 #if defined(OPENSSL_THREADS)
345 /* thread support enabled */
346 #else
347 /* no thread support */
348 #endif
349 .Ed
350 .Pp
351 Also, dynamic locks are currently not used internally by OpenSSL, but
352 may do so in the future.
353 .Sh RETURN VALUES
354 .Fn CRYPTO_num_locks
355 returns the required number of locks.
356 .Pp
357 .Fn CRYPTO_get_new_dynlockid
358 returns the index to the newly created lock.
359 .Pp
360 The other functions return no values.
361 .Sh EXAMPLES
362 .Pa crypto/threads/mttest.c
363 shows examples of the callback functions on Solaris, Irix and Win32.
364 .Sh SEE ALSO
365 .Xr crypto 3
366 .Sh HISTORY
367 .Fn CRYPTO_set_locking_callback
368 is available in all versions of SSLeay and OpenSSL.
369 .Fn CRYPTO_num_locks
370 was added in OpenSSL 0.9.4.
371 All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev.
372 .Vt CRYPTO_THREADID
373 and associated functions were introduced in OpenSSL 1.0.0 to replace
374 (actually, deprecate) the previous
375 .Fn CRYPTO_set_id_callback ,
376 .Fn CRYPTO_get_id_callback ,
377 and
378 .Fn CRYPTO_thread_id
379 functions which assumed thread IDs to always be represented by
380 .Vt unsigned long .