Debian Codegraph @

upstream/debian-unstable/man7/openssl-threads.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OPENSSL-THREADS 7SSL"
58 .TH OPENSSL-THREADS 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 openssl\-threads \- Overview of thread safety in OpenSSL
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 In this man page, we use the term \fBthread-safe\fR to indicate that an
68 object or function can be used by multiple threads at the same time.
69 .PP
70 OpenSSL can be built with or without threads support. The most important
71 use of this support is so that OpenSSL itself can use a single consistent
72 API, as shown in "EXAMPLES" in \fBCRYPTO_THREAD_run_once\fR\|(3).
73 Multi-platform applications can also use this API.
74 .PP
75 In particular, being configured for threads support does not imply that
76 all OpenSSL objects are thread-safe.
77 To emphasize: \fImost objects are not safe for simultaneous use\fR.
78 Exceptions to this should be documented on the specific manual pages, and
79 some general high-level guidance is given here.
80 .PP
81 One major use of the OpenSSL thread API is to implement reference counting.
82 Many objects within OpenSSL are reference-counted, so resources are not
83 released, until the last reference is removed.
84 References are often increased automatically (such as when an \fBX509\fR
85 certificate object is added into an \fBX509_STORE\fR trust store).
86 There is often an \fR\f(BIobject\fR\fB_up_ref\fR() function that can be used to increase
87 the reference count.
88 Failure to match \fB\fR\f(BIobject\fR\fB_up_ref\fR() calls with the right number of
89 \&\fB\fR\f(BIobject\fR\fB_free\fR() calls is a common source of memory leaks when a program
90 exits.
91 .PP
92 Many objects have set and get API's to set attributes in the object.
93 A \f(CW\*(C`set0\*(C'\fR passes ownership from the caller to the object and a
94 \&\f(CW\*(C`get0\*(C'\fR returns a pointer but the attribute ownership
95 remains with the object and a reference to it is returned.
96 A \f(CW\*(C`set1\*(C'\fR or \f(CW\*(C`get1\*(C'\fR function does not change the ownership, but instead
97 updates the attribute's reference count so that the object is shared
98 between the caller and the object; the caller must free the returned
99 attribute when finished.
100 Functions that involve attributes that have reference counts themselves,
101 but are named with just \f(CW\*(C`set\*(C'\fR or \f(CW\*(C`get\*(C'\fR are historical; and the documentation
102 must state how the references are handled.
103 Get methods are often thread-safe as long as the ownership requirements are
104 met and shared objects are not modified.
105 Set methods, or modifying shared objects, are generally not thread-safe
106 as discussed below.
107 .PP
108 Objects are thread-safe
109 as long as the API's being invoked don't modify the object; in this
110 case the parameter is usually marked in the API as \f(CW\*(C`const\*(C'\fR.
111 Not all parameters are marked this way.
112 Note that a \f(CW\*(C`const\*(C'\fR declaration does not mean immutable; for example
113 \&\fBX509_cmp\fR\|(3) takes pointers to \f(CW\*(C`const\*(C'\fR objects, but the implementation
114 uses a C cast to remove that so it can lock objects, generate and cache
115 a DER encoding, and so on.
116 .PP
117 Another instance of thread-safety is when updates to an object's
118 internal state, such as cached values, are done with locks.
119 One example of this is the reference counting API's described above.
120 .PP
121 In all cases, however, it is generally not safe for one thread to
122 mutate an object, such as setting elements of a private or public key,
123 while another thread is using that object, such as verifying a signature.
124 .PP
125 The same API's can usually be used simultaneously on different objects
126 without interference.
127 For example, two threads can calculate a signature using two different
128 \&\fBEVP_PKEY_CTX\fR objects.
129 .PP
130 For implicit global state or singletons, thread-safety depends on the facility.
131 The \fBCRYPTO_secure_malloc\fR\|(3) and related API's have their own lock,
132 while \fBCRYPTO_malloc\fR\|(3) assumes the underlying platform allocation
133 will do any necessary locking.
134 Some API's, such as \fBNCONF_load\fR\|(3) and related do no locking at all;
135 this can be considered a bug.
136 .PP
137 A separate, although related, issue is modifying "factory" objects
138 when other objects have been created from that.
139 For example, an \fBSSL_CTX\fR object created by \fBSSL_CTX_new\fR\|(3) is used
140 to create per-connection \fBSSL\fR objects by calling \fBSSL_new\fR\|(3).
141 In this specific case, and probably for factory methods in general, it is
142 not safe to modify the factory object after it has been used to create
143 other objects.
144 .SH "SEE ALSO"
145 .IX Header "SEE ALSO"
146 \&\fBCRYPTO_THREAD_run_once\fR\|(3),
147 local system threads documentation.
148 .SH BUGS
149 .IX Header "BUGS"
150 This page is admittedly very incomplete.
151 .SH COPYRIGHT
152 .IX Header "COPYRIGHT"
153 Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.
154 .PP
155 Licensed under the Apache License 2.0 (the "License"). You may not use
156 this file except in compliance with the License. You can obtain a copy
157 in the file LICENSE in the source distribution or at
158 <https://www.openssl.org/source/license.html>.