1threads(3)                          OpenSSL                         threads(3)
2
3
4

NAME

6       CRYPTO_THREADID_set_callback, CRYPTO_THREADID_get_callback,
7       CRYPTO_THREADID_current, CRYPTO_THREADID_cmp, CRYPTO_THREADID_cpy,
8       CRYPTO_THREADID_hash, CRYPTO_set_locking_callback, CRYPTO_num_locks,
9       CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback,
10       CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid,
11       CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support
12

SYNOPSIS

14        #include <openssl/crypto.h>
15
16        /* Don't use this structure directly. */
17        typedef struct crypto_threadid_st
18                {
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);
33
34        int CRYPTO_num_locks(void);
35
36        /* struct CRYPTO_dynlock_value needs to be defined by the user */
37        struct CRYPTO_dynlock_value;
38
39        void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value *
40               (*dyn_create_function)(char *file, int line));
41        void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function)
42               (int mode, struct CRYPTO_dynlock_value *l,
43               const char *file, int line));
44        void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function)
45               (struct CRYPTO_dynlock_value *l, const char *file, int line));
46
47        int CRYPTO_get_new_dynlockid(void);
48
49        void CRYPTO_destroy_dynlockid(int i);
50
51        void CRYPTO_lock(int mode, int n, const char *file, int line);
52
53        #define CRYPTO_w_lock(type)    \
54               CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
55        #define CRYPTO_w_unlock(type)  \
56               CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
57        #define CRYPTO_r_lock(type)    \
58               CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__)
59        #define CRYPTO_r_unlock(type)  \
60               CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__)
61        #define CRYPTO_add(addr,amount,type)   \
62               CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__)
63

DESCRIPTION

65       OpenSSL can generally be used safely in multi-threaded applications
66       provided that at least two callback functions are set, the
67       locking_function and threadid_func.  Note that OpenSSL is not
68       completely thread-safe, and unfortunately not all global resources have
69       the necessary locks.  Further, the thread-safety does not extend to
70       things like multiple threads using the same SSL object at the same
71       time.
72
73       locking_function(int mode, int n, const char *file, int line) is needed
74       to perform locking on shared data structures.  (Note that OpenSSL uses
75       a number of global data structures that will be implicitly shared
76       whenever multiple threads use OpenSSL.)  Multi-threaded applications
77       will crash at random if it is not set.
78
79       locking_function() must be able to handle up to CRYPTO_num_locks()
80       different mutex locks. It sets the n-th lock if mode & CRYPTO_LOCK, and
81       releases it otherwise.
82
83       file and line are the file number of the function setting the lock.
84       They can be useful for debugging.
85
86       threadid_func(CRYPTO_THREADID *id) is needed to record the currently-
87       executing thread's identifier into id. The implementation of this
88       callback should not fill in id directly, but should use
89       CRYPTO_THREADID_set_numeric() if thread IDs are numeric, or
90       CRYPTO_THREADID_set_pointer() if they are pointer-based.  If the
91       application does not register such a callback using
92       CRYPTO_THREADID_set_callback(), then a default implementation is used -
93       on Windows and BeOS this uses the system's default thread identifying
94       APIs, and on all other platforms it uses the address of errno. The
95       latter is satisfactory for thread-safety if and only if the platform
96       has a thread-local error number facility.
97
98       Once threadid_func() is registered, or if the built-in default
99       implementation is to be used;
100
101       ·   CRYPTO_THREADID_current() records the currently-executing thread ID
102           into the given id object.
103
104       ·   CRYPTO_THREADID_cmp() compares two thread IDs (returning zero for
105           equality, ie.  the same semantics as memcmp()).
106
107       ·   CRYPTO_THREADID_cpy() duplicates a thread ID value,
108
109       ·   CRYPTO_THREADID_hash() returns a numeric value usable as a hash-
110           table key. This is usually the exact numeric or pointer-based
111           thread ID used internally, however this also handles the unusual
112           case where pointers are larger than 'long' variables and the
113           platform's thread IDs are pointer-based - in this case, mixing is
114           done to attempt to produce a unique numeric value even though it is
115           not as wide as the platform's true thread IDs.
116
117       Additionally, OpenSSL supports dynamic locks, and sometimes, some parts
118       of OpenSSL need it for better performance.  To enable this, the
119       following is required:
120
121       ·   Three additional callback function, dyn_create_function,
122           dyn_lock_function and dyn_destroy_function.
123
124       ·   A structure defined with the data that each lock needs to handle.
125
126       struct CRYPTO_dynlock_value has to be defined to contain whatever
127       structure is needed to handle locks.
128
129       dyn_create_function(const char *file, int line) is needed to create a
130       lock.  Multi-threaded applications might crash at random if it is not
131       set.
132
133       dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int
134       line) is needed to perform locking off dynamic lock numbered n. Multi-
135       threaded applications might crash at random if it is not set.
136
137       dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is
138       needed to destroy the lock l. Multi-threaded applications might crash
139       at random if it is not set.
140
141       CRYPTO_get_new_dynlockid() is used to create locks.  It will call
142       dyn_create_function for the actual creation.
143
144       CRYPTO_destroy_dynlockid() is used to destroy locks.  It will call
145       dyn_destroy_function for the actual destruction.
146
147       CRYPTO_lock() is used to lock and unlock the locks.  mode is a bitfield
148       describing what should be done with the lock.  n is the number of the
149       lock as returned from CRYPTO_get_new_dynlockid().  mode can be combined
150       from the following values.  These values are pairwise exclusive, with
151       undefined behaviour if misused (for example, CRYPTO_READ and
152       CRYPTO_WRITE should not be used together):
153
154               CRYPTO_LOCK     0x01
155               CRYPTO_UNLOCK   0x02
156               CRYPTO_READ     0x04
157               CRYPTO_WRITE    0x08
158

RETURN VALUES

160       CRYPTO_num_locks() returns the required number of locks.
161
162       CRYPTO_get_new_dynlockid() returns the index to the newly created lock.
163
164       The other functions return no values.
165

NOTES

167       You can find out if OpenSSL was configured with thread support:
168
169        #define OPENSSL_THREAD_DEFINES
170        #include <openssl/opensslconf.h>
171        #if defined(OPENSSL_THREADS)
172          // thread support enabled
173        #else
174          // no thread support
175        #endif
176
177       Also, dynamic locks are currently not used internally by OpenSSL, but
178       may do so in the future.
179

EXAMPLES

181       crypto/threads/mttest.c shows examples of the callback functions on
182       Solaris, Irix and Win32.
183

HISTORY

185       CRYPTO_set_locking_callback() is available in all versions of SSLeay
186       and OpenSSL.  CRYPTO_num_locks() was added in OpenSSL 0.9.4.  All
187       functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev.
188       CRYPTO_THREADID and associated functions were introduced in OpenSSL
189       1.0.0 to replace (actually, deprecate) the previous
190       CRYPTO_set_id_callback(), CRYPTO_get_id_callback(), and
191       CRYPTO_thread_id() functions which assumed thread IDs to always be
192       represented by 'unsigned long'.
193

SEE ALSO

195       crypto(3)
196
197
198
1991.0.2o                            2020-01-28                        threads(3)
Impressum