6.1.5 Thread safety

The GnuTLS library is thread safe by design, meaning that objects of the library such as TLS sessions, can be safely divided across threads as long as a single thread accesses a single object. This is sufficient to support a server which handles several sessions per thread. Read-only access to objects, for example the credentials holding structures, is also thread-safe.

A gnutls_session_t object could also be shared by two threads, one sending, the other receiving. However, care must be taken on the following use cases:

• The re-handshake process in TLS 1.2 or earlier must be handled only in a single thread and no other thread may be performing any operation.
• The flag GNUTLS_AUTO_REAUTH cannot be used safely in this mode of operation.
• Any other operation which may send or receive data, like key update (c.f., gnutls_session_key_update), must not be performed while threads are receiving or writing.
• The termination of a session should be handled, either by a single thread being active, or by the sender thread using gnutls_bye with GNUTLS_SHUT_WR and the receiving thread waiting for a return value of zero (or timeout on certain servers which do not respond).
• The functions gnutls_transport_set_errno and gnutls_record_get_direction should not be relied during parallel operation.

For several aspects of the library (e.g., the random generator, PKCS#11 operations), the library may utilize mutex locks (e.g., pthreads on GNU/Linux and CriticalSection on Windows) which are transparently setup on library initialization. Prior to version 3.3.0 these were setup by explicitly calling gnutls_global_init.¹⁷

Note that, on Glibc systems, unless the application is explicitly linked with the libpthread library, no mutex locks are used and setup by GnuTLS. It will use the Glibc mutex stubs.