doc/man7/openssl-threads.pod - third_party/openssl - Git at Google

 =pod

 =head1 NAME

 openssl-threads - Overview of thread safety in OpenSSL

 =head1 DESCRIPTION

 In this man page, we use the term B<thread-safe> to indicate that an
 object or function can be used by multiple threads at the same time.

 OpenSSL can be built with or without threads support. The most important
 use of this support is so that OpenSSL itself can use a single consistent
 API, as shown in L<CRYPTO_THREAD_run_once(3)/EXAMPLES>.
 Multi-platform applications can also use this API.

 In particular, being configured for threads support does not imply that
 all OpenSSL objects are thread-safe.
 To emphasize: I<most objects are not safe for simultaneous use>.
 Exceptions to this should be documented on the specific manual pages, and
 some general high-level guidance is given here.

 One major use of the OpenSSL thread API is to implement reference counting.
 Many objects within OpenSSL are reference-counted, so resources are not
 released, until the last reference is removed.
 References are often increased automatically (such as when an B<X509>
 certificate object is added into an B<X509_STORE> trust store).
 There is often an B<I<object>_up_ref>() function that can be used to increase
 the reference count.
 Failure to match B<I<object>_up_ref>() calls with the right number of
 B<I<object>_free>() calls is a common source of memory leaks when a program
 exits.

 Many objects have set and get API's to set attributes in the object.
 A C<set0> passes ownership from the caller to the object and a
 C<get0> returns a pointer but the attribute ownership
 remains with the object and a reference to it is returned.
 A C<set1> or C<get1> function does not change the ownership, but instead
 updates the attribute's reference count so that the object is shared
 between the caller and the object; the caller must free the returned
 attribute when finished.
 Functions that involve attributes that have reference counts themselves,
 but are named with just C<set> or C<get> are historical; and the documentation
 must state how the references are handled.
 Get methods are often thread-safe as long as the ownership requirements are
 met and shared objects are not modified.
 Set methods, or modifying shared objects, are generally not thread-safe
 as discussed below.

 Objects are thread-safe
 as long as the API's being invoked don't modify the object; in this
 case the parameter is usually marked in the API as C<const>.
 Not all parameters are marked this way.
 Note that a C<const> declaration does not mean immutable; for example
 L<X509_cmp(3)> takes pointers to C<const> objects, but the implementation
 uses a C cast to remove that so it can lock objects, generate and cache
 a DER encoding, and so on.

 Another instance of thread-safety is when updates to an object's
 internal state, such as cached values, are done with locks.
 One example of this is the reference counting API's described above.

 In all cases, however, it is generally not safe for one thread to
 mutate an object, such as setting elements of a private or public key,
 while another thread is using that object, such as verifying a signature.

 The same API's can usually be used simultaneously on different objects
 without interference.
 For example, two threads can calculate a signature using two different
 B<EVP_PKEY_CTX> objects.

 For implicit global state or singletons, thread-safety depends on the facility.
 The L<CRYPTO_secure_malloc(3)> and related API's have their own lock,
 while L<CRYPTO_malloc(3)> assumes the underlying platform allocation
 will do any necessary locking.
 Some API's, such as L<NCONF_load(3)> and related do no locking at all;
 this can be considered a bug.

 A separate, although related, issue is modifying "factory" objects
 when other objects have been created from that.
 For example, an B<SSL_CTX> object created by L<SSL_CTX_new(3)> is used
 to create per-connection B<SSL> objects by calling L<SSL_new(3)>.
 In this specific case, and probably for factory methods in general, it is
 not safe to modify the factory object after it has been used to create
 other objects.

 =head1 SEE ALSO

 CRYPTO_THREAD_run_once(3),
 local system threads documentation.

 =head1 BUGS

 This page is admittedly very incomplete.

 =head1 COPYRIGHT

 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.

 =cut
	=pod

	=head1 NAME

	openssl-threads - Overview of thread safety in OpenSSL

	=head1 DESCRIPTION

	In this man page, we use the term B<thread-safe> to indicate that an
	object or function can be used by multiple threads at the same time.

	OpenSSL can be built with or without threads support. The most important
	use of this support is so that OpenSSL itself can use a single consistent
	API, as shown in L<CRYPTO_THREAD_run_once(3)/EXAMPLES>.
	Multi-platform applications can also use this API.

	In particular, being configured for threads support does not imply that
	all OpenSSL objects are thread-safe.
	To emphasize: I<most objects are not safe for simultaneous use>.
	Exceptions to this should be documented on the specific manual pages, and
	some general high-level guidance is given here.

	One major use of the OpenSSL thread API is to implement reference counting.
	Many objects within OpenSSL are reference-counted, so resources are not
	released, until the last reference is removed.
	References are often increased automatically (such as when an B<X509>
	certificate object is added into an B<X509_STORE> trust store).
	There is often an B<I<object>_up_ref>() function that can be used to increase
	the reference count.
	Failure to match B<I<object>_up_ref>() calls with the right number of
	B<I<object>_free>() calls is a common source of memory leaks when a program
	exits.

	Many objects have set and get API's to set attributes in the object.
	A C<set0> passes ownership from the caller to the object and a
	C<get0> returns a pointer but the attribute ownership
	remains with the object and a reference to it is returned.
	A C<set1> or C<get1> function does not change the ownership, but instead
	updates the attribute's reference count so that the object is shared
	between the caller and the object; the caller must free the returned
	attribute when finished.
	Functions that involve attributes that have reference counts themselves,
	but are named with just C<set> or C<get> are historical; and the documentation
	must state how the references are handled.
	Get methods are often thread-safe as long as the ownership requirements are
	met and shared objects are not modified.
	Set methods, or modifying shared objects, are generally not thread-safe
	as discussed below.

	Objects are thread-safe
	as long as the API's being invoked don't modify the object; in this
	case the parameter is usually marked in the API as C<const>.
	Not all parameters are marked this way.
	Note that a C<const> declaration does not mean immutable; for example
	L<X509_cmp(3)> takes pointers to C<const> objects, but the implementation
	uses a C cast to remove that so it can lock objects, generate and cache
	a DER encoding, and so on.

	Another instance of thread-safety is when updates to an object's
	internal state, such as cached values, are done with locks.
	One example of this is the reference counting API's described above.

	In all cases, however, it is generally not safe for one thread to
	mutate an object, such as setting elements of a private or public key,
	while another thread is using that object, such as verifying a signature.

	The same API's can usually be used simultaneously on different objects
	without interference.
	For example, two threads can calculate a signature using two different
	B<EVP_PKEY_CTX> objects.

	For implicit global state or singletons, thread-safety depends on the facility.
	The L<CRYPTO_secure_malloc(3)> and related API's have their own lock,
	while L<CRYPTO_malloc(3)> assumes the underlying platform allocation
	will do any necessary locking.
	Some API's, such as L<NCONF_load(3)> and related do no locking at all;
	this can be considered a bug.

	A separate, although related, issue is modifying "factory" objects
	when other objects have been created from that.
	For example, an B<SSL_CTX> object created by L<SSL_CTX_new(3)> is used
	to create per-connection B<SSL> objects by calling L<SSL_new(3)>.
	In this specific case, and probably for factory methods in general, it is
	not safe to modify the factory object after it has been used to create
	other objects.

	=head1 SEE ALSO

	CRYPTO_THREAD_run_once(3),
	local system threads documentation.

	=head1 BUGS

	This page is admittedly very incomplete.

	=head1 COPYRIGHT

	Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

	Licensed under the Apache License 2.0 (the "License"). You may not use
	this file except in compliance with the License. You can obtain a copy
	in the file LICENSE in the source distribution or at
	L<https://www.openssl.org/source/license.html>.

	=cut