Debian Codegraph @

upstream/debian-unstable/man3/CRYPTO_get_ex_new_index.3ssl

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 "CRYPTO_GET_EX_NEW_INDEX 3SSL"
58 .TH CRYPTO_GET_EX_NEW_INDEX 3SSL 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 CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup,
65 CRYPTO_free_ex_index, CRYPTO_get_ex_new_index,
66 CRYPTO_alloc_ex_data, CRYPTO_set_ex_data, CRYPTO_get_ex_data,
67 CRYPTO_free_ex_data, CRYPTO_new_ex_data
68 \&\- functions supporting application\-specific data
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 1
72 \& #include <openssl/crypto.h>
73 \&
74 \& int CRYPTO_get_ex_new_index(int class_index,
75 \& long argl, void *argp,
76 \& CRYPTO_EX_new *new_func,
77 \& CRYPTO_EX_dup *dup_func,
78 \& CRYPTO_EX_free *free_func);
79 \&
80 \& typedef void CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
81 \& int idx, long argl, void *argp);
82 \& typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
83 \& int idx, long argl, void *argp);
84 \& typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from,
85 \& void **from_d, int idx, long argl, void *argp);
86 \&
87 \& int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad);
88 \&
89 \& int CRYPTO_alloc_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad,
90 \& int idx);
91 \&
92 \& int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);
93 \&
94 \& void *CRYPTO_get_ex_data(const CRYPTO_EX_DATA *r, int idx);
95 \&
96 \& void CRYPTO_free_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *r);
97 \&
98 \& int CRYPTO_free_ex_index(int class_index, int idx);
99 .Ve
100 .SH DESCRIPTION
101 .IX Header "DESCRIPTION"
102 Several OpenSSL structures can have application-specific data attached to them,
103 known as "exdata."
104 The specific structures are:
105 .PP
106 .Vb 10
107 \& BIO
108 \& DH
109 \& DSA
110 \& EC_KEY
111 \& ENGINE
112 \& EVP_PKEY
113 \& RSA
114 \& SSL
115 \& SSL_CTX
116 \& SSL_SESSION
117 \& UI
118 \& UI_METHOD
119 \& X509
120 \& X509_STORE
121 \& X509_STORE_CTX
122 .Ve
123 .PP
124 In addition, the \fBAPP\fR name is reserved for use by application code.
125 .PP
126 Each is identified by an \fBCRYPTO_EX_INDEX_xxx\fR define in the header file
127 \&\fI<openssl/crypto.h>\fR. In addition, \fBCRYPTO_EX_INDEX_APP\fR is reserved for
128 applications to use this facility for their own structures.
129 .PP
130 The API described here is used by OpenSSL to manipulate exdata for specific
131 structures. Since the application data can be anything at all it is passed
132 and retrieved as a \fBvoid *\fR type.
133 .PP
134 The \fBCRYPTO_EX_DATA\fR type is opaque. To initialize the exdata part of
135 a structure, call \fBCRYPTO_new_ex_data()\fR. This is only necessary for
136 \&\fBCRYPTO_EX_INDEX_APP\fR objects.
137 .PP
138 Exdata types are identified by an \fBindex\fR, an integer guaranteed to be
139 unique within structures for the lifetime of the program. Applications
140 using exdata typically call \fBCRYPTO_get_ex_new_index\fR at startup, and
141 store the result in a global variable, or write a wrapper function to
142 provide lazy evaluation. The \fBclass_index\fR should be one of the
143 \&\fBCRYPTO_EX_INDEX_xxx\fR values. The \fBargl\fR and \fBargp\fR parameters are saved
144 to be passed to the callbacks but are otherwise not used. In order to
145 transparently manipulate exdata, three callbacks must be provided. The
146 semantics of those callbacks are described below.
147 .PP
148 When copying or releasing objects with exdata, the callback functions
149 are called in increasing order of their \fBindex\fR value.
150 .PP
151 If a dynamic library can be unloaded, it should call \fBCRYPTO_free_ex_index()\fR
152 when this is done.
153 This will replace the callbacks with no-ops
154 so that applications don't crash. Any existing exdata will be leaked.
155 .PP
156 To set or get the exdata on an object, the appropriate type-specific
157 routine must be used. This is because the containing structure is opaque
158 and the \fBCRYPTO_EX_DATA\fR field is not accessible. In both API's, the
159 \&\fBidx\fR parameter should be an already-created index value.
160 .PP
161 When setting exdata, the pointer specified with a particular index is saved,
162 and returned on a subsequent "get" call. If the application is going to
163 release the data, it must make sure to set a \fBNULL\fR value at the index,
164 to avoid likely double-free crashes.
165 .PP
166 The function \fBCRYPTO_free_ex_data\fR is used to free all exdata attached
167 to a structure. The appropriate type-specific routine must be used.
168 The \fBclass_index\fR identifies the structure type, the \fBobj\fR is
169 a pointer to the actual structure, and \fBr\fR is a pointer to the
170 structure's exdata field.
171 .SS "Callback Functions"
172 .IX Subsection "Callback Functions"
173 This section describes how the callback functions are used. Applications
174 that are defining their own exdata using \fBCYPRTO_EX_INDEX_APP\fR must
175 call them as described here.
176 .PP
177 When a structure is initially allocated (such as \fBRSA_new()\fR) then the
178 \&\fBnew_func()\fR is called for every defined index. There is no requirement
179 that the entire parent, or containing, structure has been set up.
180 The \fBnew_func()\fR is typically used only to allocate memory to store the
181 exdata, and perhaps an "initialized" flag within that memory.
182 The exdata value may be allocated later on with \fBCRYPTO_alloc_ex_data()\fR,
183 or may be set by calling \fBCRYPTO_set_ex_data()\fR.
184 .PP
185 When a structure is free'd (such as \fBSSL_CTX_free()\fR) then the
186 \&\fBfree_func()\fR is called for every defined index. Again, the state of the
187 parent structure is not guaranteed. The \fBfree_func()\fR may be called with a
188 NULL pointer.
189 .PP
190 Both \fBnew_func()\fR and \fBfree_func()\fR take the same parameters.
191 The \fBparent\fR is the pointer to the structure that contains the exdata.
192 The \fBptr\fR is the current exdata item; for \fBnew_func()\fR this will typically
193 be NULL. The \fBr\fR parameter is a pointer to the exdata field of the object.
194 The \fBidx\fR is the index and is the value returned when the callbacks were
195 initially registered via \fBCRYPTO_get_ex_new_index()\fR and can be used if
196 the same callback handles different types of exdata.
197 .PP
198 \&\fBdup_func()\fR is called when a structure is being copied. This is only done
199 for \fBSSL\fR, \fBSSL_SESSION\fR, \fBEC_KEY\fR objects and \fBBIO\fR chains via
200 \&\fBBIO_dup_chain()\fR. The \fBto\fR and \fBfrom\fR parameters
201 are pointers to the destination and source \fBCRYPTO_EX_DATA\fR structures,
202 respectively. The \fB*from_d\fR parameter is a pointer to the source exdata.
203 When the \fBdup_func()\fR returns, the value in \fB*from_d\fR is copied to the
204 destination ex_data. If the pointer contained in \fB*pptr\fR is not modified
205 by the \fBdup_func()\fR, then both \fBto\fR and \fBfrom\fR will point to the same data.
206 The \fBidx\fR, \fBargl\fR and \fBargp\fR parameters are as described for the other
207 two callbacks. If the \fBdup_func()\fR returns \fB0\fR the whole \fBCRYPTO_dup_ex_data()\fR
208 will fail.
209 .SH "RETURN VALUES"
210 .IX Header "RETURN VALUES"
211 \&\fBCRYPTO_get_ex_new_index()\fR returns a new index or \-1 on failure.
212 .PP
213 \&\fBCRYPTO_free_ex_index()\fR, \fBCRYPTO_alloc_ex_data()\fR and \fBCRYPTO_set_ex_data()\fR
214 return 1 on success or 0 on failure.
215 .PP
216 \&\fBCRYPTO_get_ex_data()\fR returns the application data or NULL on failure;
217 note that NULL may be a valid value.
218 .PP
219 \&\fBdup_func()\fR should return 0 for failure and 1 for success.
220 .SH HISTORY
221 .IX Header "HISTORY"
222 \&\fBCRYPTO_alloc_ex_data()\fR was added in OpenSSL 3.0.
223 .PP
224 The signature of the \fBdup_func()\fR callback was changed in OpenSSL 3.0 to use the
225 type \fBvoid **\fR for \fBfrom_d\fR. Previously this parameter was of type \fBvoid *\fR.
226 .PP
227 Support for ENGINE "exdata" was deprecated in OpenSSL 3.0.
228 .SH COPYRIGHT
229 .IX Header "COPYRIGHT"
230 Copyright 2015\-2021 The OpenSSL Project Authors. All Rights Reserved.
231 .PP
232 Licensed under the Apache License 2.0 (the "License"). You may not use
233 this file except in compliance with the License. You can obtain a copy
234 in the file LICENSE in the source distribution or at
235 <https://www.openssl.org/source/license.html>.