1.\" $OpenBSD: CRYPTO_set_ex_data.3,v 1.12 2019/08/16 12:16:22 schwarze Exp $
2.\" full merge up to:
3.\" OpenSSL CRYPTO_get_ex_new_index 9e183d22 Mar 11 08:56:44 2017 -0500
4.\" selective merge up to: 72a7a702 Feb 26 14:05:09 2019 +0000
5.\"
6.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
7.\" and by Rich Salz <rsalz@akamai.com>.
8.\" Copyright (c) 2000, 2006, 2015, 2016 The OpenSSL Project.
9.\" All rights reserved.
10.\"
11.\" Redistribution and use in source and binary forms, with or without
12.\" modification, are permitted provided that the following conditions
13.\" are met:
14.\"
15.\" 1. Redistributions of source code must retain the above copyright
16.\"    notice, this list of conditions and the following disclaimer.
17.\"
18.\" 2. Redistributions in binary form must reproduce the above copyright
19.\"    notice, this list of conditions and the following disclaimer in
20.\"    the documentation and/or other materials provided with the
21.\"    distribution.
22.\"
23.\" 3. All advertising materials mentioning features or use of this
24.\"    software must display the following acknowledgment:
25.\"    "This product includes software developed by the OpenSSL Project
26.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
27.\"
28.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
29.\"    endorse or promote products derived from this software without
30.\"    prior written permission. For written permission, please contact
31.\"    openssl-core@openssl.org.
32.\"
33.\" 5. Products derived from this software may not be called "OpenSSL"
34.\"    nor may "OpenSSL" appear in their names without prior written
35.\"    permission of the OpenSSL Project.
36.\"
37.\" 6. Redistributions of any form whatsoever must retain the following
38.\"    acknowledgment:
39.\"    "This product includes software developed by the OpenSSL Project
40.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
41.\"
42.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
43.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
44.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
45.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
46.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
47.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
48.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
49.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
50.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
51.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
52.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
53.\" OF THE POSSIBILITY OF SUCH DAMAGE.
54.\"
55.Dd $Mdocdate: August 16 2019 $
56.Dt CRYPTO_SET_EX_DATA 3
57.Os
58.Sh NAME
59.Nm CRYPTO_EX_new ,
60.Nm CRYPTO_EX_free ,
61.Nm CRYPTO_EX_dup ,
62.Nm CRYPTO_get_ex_new_index ,
63.Nm CRYPTO_set_ex_data ,
64.Nm CRYPTO_get_ex_data ,
65.Nm CRYPTO_free_ex_data ,
66.Nm CRYPTO_new_ex_data
67.Nd functions supporting application-specific data
68.Sh SYNOPSIS
69.In openssl/crypto.h
70.Ft int
71.Fo CRYPTO_get_ex_new_index
72.Fa "int class_index"
73.Fa "long argl"
74.Fa "void *argp"
75.Fa "CRYPTO_EX_new *new_func"
76.Fa "CRYPTO_EX_dup *dup_func"
77.Fa "CRYPTO_EX_free *free_func"
78.Fc
79.Ft typedef int
80.Fo CRYPTO_EX_new
81.Fa "void *parent"
82.Fa "void *ptr"
83.Fa "CRYPTO_EX_DATA *ad"
84.Fa "int idx"
85.Fa "long argl"
86.Fa "void *argp"
87.Fc
88.Ft typedef void
89.Fo CRYPTO_EX_free
90.Fa "void *parent"
91.Fa "void *ptr"
92.Fa "CRYPTO_EX_DATA *ad"
93.Fa "int idx"
94.Fa "long argl"
95.Fa "void *argp"
96.Fc
97.Ft typedef int
98.Fo CRYPTO_EX_dup
99.Fa "CRYPTO_EX_DATA *to"
100.Fa "const CRYPTO_EX_DATA *from"
101.Fa "void *from_d"
102.Fa "int idx"
103.Fa "long argl"
104.Fa "void *argp"
105.Fc
106.Ft int
107.Fo CRYPTO_new_ex_data
108.Fa "int class_index"
109.Fa "void *obj"
110.Fa "CRYPTO_EX_DATA *ad"
111.Fc
112.Ft int
113.Fo CRYPTO_set_ex_data
114.Fa "CRYPTO_EX_DATA *r"
115.Fa "int idx"
116.Fa "void *arg"
117.Fc
118.Ft void *
119.Fo CRYPTO_get_ex_data
120.Fa "CRYPTO_EX_DATA *r"
121.Fa "int idx"
122.Fc
123.Ft void
124.Fo CRYPTO_free_ex_data
125.Fa "int class_index"
126.Fa "void *obj"
127.Fa "CRYPTO_EX_DATA *r"
128.Fc
129.Sh DESCRIPTION
130Several OpenSSL structures can have application specific data attached
131to them, known as "exdata".
132The specific structures are:
133.Bd -literal
134    BIO
135    DH
136    DSA
137    EC_KEY
138    ECDH
139    ECDSA
140    ENGINE
141    RSA
142    SSL
143    SSL_CTX
144    SSL_SESSION
145    UI
146    X509
147    X509_STORE
148    X509_STORE_CTX
149.Ed
150.Pp
151Each is identified by a
152.Dv CRYPTO_EX_INDEX_*
153constant defined in the
154.In openssl/crypto.h
155header file.
156.Pp
157The API described here is used by OpenSSL to manipulate exdata for
158specific structures.
159Since the application data can be anything at all it is passed and
160retrieved as a
161.Vt void *
162type.
163.Pp
164The
165.Vt CRYPTO_EX_DATA
166type is opaque.
167To initialize the exdata part of a structure, call
168.Fn CRYPTO_new_ex_data .
169.Pp
170Exdata types are identified by an index, an integer guaranteed to
171be unique within structures for the lifetime of the program.
172Applications using exdata typically call
173.Fn CRYPTO_get_ex_new_index
174at startup and store the result in a global variable, or write a
175wrapper function to provide lazy evaluation.
176The
177.Fa class_index
178should be one of the
179.Dv CRYPTO_EX_INDEX_*
180values.
181The
182.Fa argl
183and
184.Fa argp
185parameters are saved to be passed to the callbacks but are otherwise not
186used.
187In order to transparently manipulate exdata, three callbacks must be
188provided.
189The semantics of those callbacks are described below.
190.Pp
191When copying or releasing objects with exdata, the callback functions
192are called in increasing order of their index value.
193.Pp
194To set or get the exdata on an object, the appropriate type-specific
195routine must be used.
196This is because the containing structure is opaque and the
197.Vt CRYPTO_EX_DATA
198field is not accessible.
199In both APIs, the
200.Fa idx
201parameter should be an already-created index value.
202.Pp
203When setting exdata, the pointer specified with a particular index is
204saved, and returned on a subsequent "get" call.
205If the application is going to release the data, it must make sure to
206set a
207.Dv NULL
208value at the index, to avoid likely double-free crashes.
209.Pp
210The function
211.Fn CRYPTO_free_ex_data
212is used to free all exdata attached to a structure.
213The appropriate type-specific routine must be used.
214The
215.Fa class_index
216identifies the structure type, the
217.Fa obj
218is a pointer to the actual structure, and
219.Fa r
220is a pointer to the structure's exdata field.
221.Pp
222The callback functions are used as follows.
223.Pp
224When a structure is initially allocated (such as by
225.Xr RSA_new 3 ) ,
226then
227.Fa new_func
228is called for every defined index.
229There is no requirement that the entire parent, or containing, structure
230has been set up.
231The
232.Fa new_func
233is typically used only to allocate memory to store the
234exdata, and perhaps an "initialized" flag within that memory.
235The exdata value should be set by calling
236.Fn CRYPTO_set_ex_data .
237.Pp
238When a structure is free'd (such as by
239.Xr SSL_CTX_free 3 ) ,
240then the
241.Fa free_func
242is called for every defined index.
243Again, the state of the parent structure is not guaranteed.
244The
245.Fa free_func
246may be called with a
247.Dv NULL
248pointer.
249.Pp
250Both
251.Fa new_func
252and
253.Fa free_func
254take the same parameters.
255The
256.Fa parent
257is the pointer to the structure that contains the exdata.
258The
259.Fa ptr
260is the current exdata item; for
261.Fa new_func
262this will typically be
263.Dv NULL .
264The
265.Fa r
266parameter is a pointer to the exdata field of the object.
267The
268.Fa idx
269is the index and is the value returned when the callbacks were initially
270registered via
271.Fn CRYPTO_get_ex_new_index
272and can be used if the same callback handles different types of exdata.
273.Pp
274.Fa dup_func
275is called when a structure is being copied.
276This is only done for
277.Vt SSL
278and
279.Vt SSL_SESSION
280objects.
281The
282.Fa to
283and
284.Fa from
285parameters are pointers to the destination and source
286.Vt CRYPTO_EX_DATA
287structures, respectively.
288The
289.Fa from_d
290parameter is a pointer to the source exdata.
291When
292.Fa dup_func
293returns, the value in
294.Fa from_d
295is copied to the destination ex_data.
296If the pointer contained in
297.Fa from_d
298is not modified by the
299.Fa dup_func ,
300then both
301.Fa to
302and
303.Fa from
304will point to the same data.
305The
306.Fa idx ,
307.Fa argl
308and
309.Fa argp
310parameters are as described for the other two callbacks.
311.Pp
312.Fn CRYPTO_set_ex_data
313is used to set application specific data.
314The data is supplied in the
315.Fa arg
316parameter and its precise meaning is up to the application.
317.Pp
318.Fn CRYPTO_get_ex_data
319is used to retrieve application specific data.
320The data is returned to the application; this will be the same value as
321supplied to a previous
322.Fn CRYPTO_set_ex_data
323call.
324.Sh RETURN VALUES
325.Fn CRYPTO_get_ex_new_index
326returns a new index or -1 on failure; the value 0 is reserved for
327the legacy "app_data" APIs.
328.Pp
329.Fn CRYPTO_set_ex_data
330returns 1 on success or 0 on failure.
331.Pp
332.Fn CRYPTO_get_ex_data
333returns the application data or
334.Dv NULL
335on failure; note that
336.Dv NULL
337may be a valid value.
338.Pp
339.Fa dup_func
340should return 0 for failure and 1 for success.
341.Pp
342On failure an error code can be obtained from
343.Xr ERR_get_error 3 .
344.Sh SEE ALSO
345.Xr BIO_get_ex_new_index 3 ,
346.Xr DH_get_ex_new_index 3 ,
347.Xr DSA_get_ex_new_index 3 ,
348.Xr RSA_get_ex_new_index 3 ,
349.Xr SSL_CTX_get_ex_new_index 3 ,
350.Xr SSL_get_ex_new_index 3 ,
351.Xr SSL_SESSION_get_ex_new_index 3 ,
352.Xr X509_STORE_CTX_get_ex_new_index 3 ,
353.Xr X509_STORE_get_ex_new_index 3
354.Sh HISTORY
355.Fn CRYPTO_get_ex_new_index ,
356.Fn CRYPTO_set_ex_data ,
357.Fn CRYPTO_get_ex_data ,
358.Fn CRYPTO_free_ex_data ,
359and
360.Fn CRYPTO_new_ex_data
361first appeared in SSLeay 0.9.0 and have been available since
362.Ox 2.4 .
363.Pp
364.Fn CRYPTO_EX_new ,
365.Fn CRYPTO_EX_free ,
366and
367.Fn CRYPTO_EX_dup
368first appeared in OpenSSL 0.9.5 and have been available since
369.Ox 2.7 .
370