openssl_threads(3)
- NetBSD Manual Pages
threads(3) OpenSSL threads(3)
NAME
CRYPTO_set_locking_callback, CRYPTO_set_id_callback,
CRYPTO_num_locks, CRYPTO_set_dynlock_create_callback,
CRYPTO_set_dynlock_lock_callback, CRYPTO_set_dyn-
lock_destroy_callback, CRYPTO_get_new_dynlockid,
CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread
support
LIBRARY
libcrypto, -lcrypto
SYNOPSIS
#include <openssl/crypto.h>
void CRYPTO_set_locking_callback(void (*locking_function)(int mode,
int n, const char *file, int line));
void CRYPTO_set_id_callback(unsigned long (*id_function)(void));
int CRYPTO_num_locks(void);
/* struct CRYPTO_dynlock_value needs to be defined by the user */
struct CRYPTO_dynlock_value;
void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value *
(*dyn_create_function)(char *file, int line));
void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function)
(int mode, struct CRYPTO_dynlock_value *l,
const char *file, int line));
void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function)
(struct CRYPTO_dynlock_value *l, const char *file, int line));
int CRYPTO_get_new_dynlockid(void);
void CRYPTO_destroy_dynlockid(int i);
void CRYPTO_lock(int mode, int n, const char *file, int line);
#define CRYPTO_w_lock(type) \
CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
#define CRYPTO_w_unlock(type) \
CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__)
#define CRYPTO_r_lock(type) \
CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__)
#define CRYPTO_r_unlock(type) \
CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__)
#define CRYPTO_add(addr,amount,type) \
CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__)
DESCRIPTION
OpenSSL can safely be used in multi-threaded applications
provided that at least two callback functions are set.
2002-06-10 0.9.6g 1
threads(3) OpenSSL threads(3)
locking_function(int mode, int n, const char *file, int
line) is needed to perform locking on shared data struc-
tures. (Note that OpenSSL uses a number of global data
structures that will be implicitly shared whenever multi-
ple threads use OpenSSL.) Multi-threaded applications
will crash at random if it is not set.
locking_function() must be able to handle up to
CRYPTO_num_locks() different mutex locks. It sets the n-th
lock if mode & CRYPTO_LOCK, and releases it otherwise.
file and line are the file number of the function setting
the lock. They can be useful for debugging.
id_function(void) is a function that returns a thread ID.
It is not needed on Windows nor on platforms where get-
pid() returns a different ID for each thread (most notably
Linux).
Additionally, OpenSSL supports dynamic locks, and some-
times, some parts of OpenSSL need it for better perfor-
mance. To enable this, the following is required:
o Three additional callback function, dyn_create_function,
dyn_lock_function and dyn_destroy_function.
o A structure defined with the data that each lock needs
to han- dle.
struct CRYPTO_dynlock_value has to be defined to contain
whatever structure is needed to handle locks.
dyn_create_function(const char *file, int line) is needed
to create a lock. Multi-threaded applications might crash
at random if it is not set.
dyn_lock_function(int mode, CRYPTO_dynlock *l, const char
*file, int line) is needed to perform locking off dynamic
lock numbered n. Multi-threaded applications might crash
at random if it is not set.
dyn_destroy_function(CRYPTO_dynlock *l, const char *file,
int line) is needed to destroy the lock l. Multi-threaded
applications might crash at random if it is not set.
CRYPTO_get_new_dynlockid() is used to create locks. It
will call dyn_create_function for the actual creation.
CRYPTO_destroy_dynlockid() is used to destroy locks. It
will call dyn_destroy_function for the actual destruction.
CRYPTO_lock() is used to lock and unlock the locks. mode
is a bitfield describing what should be done with the
lock. n is the number of the lock as returned from
2002-06-10 0.9.6g 2
threads(3) OpenSSL threads(3)
CRYPTO_get_new_dynlockid(). mode can be combined from the
following values. These values are pairwise exclusive,
with undefined behaviour if misused (for example,
CRYPTO_READ and CRYPTO_WRITE should not be used together):
CRYPTO_LOCK 0x01
CRYPTO_UNLOCK 0x02
CRYPTO_READ 0x04
CRYPTO_WRITE 0x08
RETURN VALUES
CRYPTO_num_locks() returns the required number of locks.
CRYPTO_get_new_dynlockid() returns the index to the newly
created lock.
The other functions return no values.
NOTE
You can find out if OpenSSL was configured with thread
support:
#define OPENSSL_THREAD_DEFINES
#include <openssl/opensslconf.h>
#if defined(THREADS)
// thread support enabled
#else
// no thread support
#endif
Also, dynamic locks are currently not used internally by
OpenSSL, but may do so in the future.
EXAMPLES
crypto/threads/mttest.c shows examples of the callback
functions on Solaris, Irix and Win32.
HISTORY
CRYPTO_set_locking_callback() and CRYPTO_set_id_callback()
are available in all versions of SSLeay and OpenSSL.
CRYPTO_num_locks() was added in OpenSSL 0.9.4. All func-
tions dealing with dynamic locks were added in OpenSSL
0.9.5b-dev.
SEE ALSO
crypto(3)
2002-06-10 0.9.6g 3
Powered by man-cgi (2024-03-20).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.