1=pod 2 3=head1 NAME 4 5openssl-threads - Overview of thread safety in OpenSSL 6 7=head1 DESCRIPTION 8 9In this man page, we use the term B<thread-safe> to indicate that an 10object or function can be used by multiple threads at the same time. 11 12OpenSSL can be built with or without threads support. The most important 13use of this support is so that OpenSSL itself can use a single consistent 14API, as shown in L<CRYPTO_THREAD_run_once(3)/EXAMPLES>. 15Multi-platform applications can also use this API. 16 17In particular, being configured for threads support does not imply that 18all OpenSSL objects are thread-safe. 19To emphasize: I<most objects are not safe for simultaneous use>. 20Exceptions to this should be documented on the specific manual pages, and 21some general high-level guidance is given here. 22 23One major use of the OpenSSL thread API is to implement reference counting. 24Many objects within OpenSSL are reference-counted, so resources are not 25released, until the last reference is removed. 26References are often increased automatically (such as when an B<X509> 27certificate object is added into an B<X509_STORE> trust store). 28There is often an B<I<object>_up_ref>() function that can be used to increase 29the reference count. 30Failure to match B<I<object>_up_ref>() calls with the right number of 31B<I<object>_free>() calls is a common source of memory leaks when a program 32exits. 33 34Many objects have set and get API's to set attributes in the object. 35A C<set0> passes ownership from the caller to the object and a 36C<get0> returns a pointer but the attribute ownership 37remains with the object and a reference to it is returned. 38A C<set1> or C<get1> function does not change the ownership, but instead 39updates the attribute's reference count so that the object is shared 40between the caller and the object; the caller must free the returned 41attribute when finished. 42Functions that involve attributes that have reference counts themselves, 43but are named with just C<set> or C<get> are historical; and the documentation 44must state how the references are handled. 45Get methods are often thread-safe as long as the ownership requirements are 46met and shared objects are not modified. 47Set methods, or modifying shared objects, are generally not thread-safe 48as discussed below. 49 50Objects are thread-safe 51as long as the API's being invoked don't modify the object; in this 52case the parameter is usually marked in the API as C<const>. 53Not all parameters are marked this way. 54Note that a C<const> declaration does not mean immutable; for example 55L<X509_cmp(3)> takes pointers to C<const> objects, but the implementation 56uses a C cast to remove that so it can lock objects, generate and cache 57a DER encoding, and so on. 58 59Another instance of thread-safety is when updates to an object's 60internal state, such as cached values, are done with locks. 61One example of this is the reference counting API's described above. 62 63In all cases, however, it is generally not safe for one thread to 64mutate an object, such as setting elements of a private or public key, 65while another thread is using that object, such as verifying a signature. 66 67The same API's can usually be used simultaneously on different objects 68without interference. 69For example, two threads can calculate a signature using two different 70B<EVP_PKEY_CTX> objects. 71 72For implicit global state or singletons, thread-safety depends on the facility. 73The L<CRYPTO_secure_malloc(3)> and related API's have their own lock, 74while L<CRYPTO_malloc(3)> assumes the underlying platform allocation 75will do any necessary locking. 76Some API's, such as L<NCONF_load(3)> and related, or L<OBJ_create(3)> 77do no locking at all; this can be considered a bug. 78 79A separate, although related, issue is modifying "factory" objects 80when other objects have been created from that. 81For example, an B<SSL_CTX> object created by L<SSL_CTX_new(3)> is used 82to create per-connection B<SSL> objects by calling L<SSL_new(3)>. 83In this specific case, and probably for factory methods in general, it is 84not safe to modify the factory object after it has been used to create 85other objects. 86 87=head1 SEE ALSO 88 89CRYPTO_THREAD_run_once(3), 90local system threads documentation. 91 92=head1 BUGS 93 94This page is admittedly very incomplete. 95 96=head1 COPYRIGHT 97 98Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. 99 100Licensed under the Apache License 2.0 (the "License"). You may not use 101this file except in compliance with the License. You can obtain a copy 102in the file LICENSE in the source distribution or at 103L<https://www.openssl.org/source/license.html>. 104 105=cut 106