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_dynlock_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.

       locking_function(int mode, int n, const char *file, int line) is needed
       to perform locking on shared data structures.  (Note that OpenSSL uses
       a number of global data structures that will be implicitly shared when-
       ever multiple 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() dif-
       ferent 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 getpid() returns a different
       ID for each thread (most notably Linux).

       Additionally, OpenSSL supports dynamic locks, and sometimes, some parts
       of OpenSSL need it for better performance.  To enable this, the follow-
       ing is required:

       · Three additional callback function, dyn_create_function,
       dyn_lock_function and dyn_destroy_function.
       · A structure defined with the data that each lock needs to handle.

       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 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 avail-
       able in all versions of SSLeay and OpenSSL.  CRYPTO_num_locks() was
       added in OpenSSL 0.9.4.  All functions dealing with dynamic locks were
       added in OpenSSL 0.9.5b-dev.


SEE ALSO

       crypto(3)



3rd Berkeley Distribution           0.9.7d                          threads(3)