xref: /openbsd-src/lib/libcrypto/man/CRYPTO_set_ex_data.3 (revision 5e3c7963eb248119b7dfd4b0defad58a7d9cd306) 
1.\" $OpenBSD: CRYPTO_set_ex_data.3,v 1.10 2018/04/08 01:00:15 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: a73d990e Feb 27 19:02:24 2018 +0100
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: April 8 2018 $
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    ECDH
138    ECDSA
139    ENGINE
140    RSA
141    SSL
142    SSL_CTX
143    SSL_SESSION
144    UI
145    X509
146    X509_STORE
147    X509_STORE_CTX
148.Ed
149.Pp
150Each is identified by a
151.Dv CRYPTO_EX_INDEX_*
152constant defined in the
153.In openssl/crypto.h
154header file.
155.Pp
156The API described here is used by OpenSSL to manipulate exdata for
157specific structures.
158Since the application data can be anything at all it is passed and
159retrieved as a
160.Vt void *
161type.
162.Pp
163The
164.Vt CRYPTO_EX_DATA
165type is opaque.
166To initialize the exdata part of a structure, call
167.Fn CRYPTO_new_ex_data .
168.Pp
169Exdata types are identified by an index, an integer guaranteed to
170be unique within structures for the lifetime of the program.
171Applications using exdata typically call
172.Fn CRYPTO_get_ex_new_index
173at startup and store the result in a global variable, or write a
174wrapper function to provide lazy evaluation.
175The
176.Fa class_index
177should be one of the
178.Dv CRYPTO_EX_INDEX_*
179values.
180The
181.Fa argl
182and
183.Fa argp
184parameters are saved to be passed to the callbacks but are otherwise not
185used.
186In order to transparently manipulate exdata, three callbacks must be
187provided.
188The semantics of those callbacks are described below.
189.Pp
190When copying or releasing objects with exdata, the callback functions
191are called in increasing order of their index value.
192.Pp
193To set or get the exdata on an object, the appropriate type-specific
194routine must be used.
195This is because the containing structure is opaque and the
196.Vt CRYPTO_EX_DATA
197field is not accessible.
198In both APIs, the
199.Fa idx
200parameter should be an already-created index value.
201.Pp
202When setting exdata, the pointer specified with a particular index is
203saved, and returned on a subsequent "get" call.
204If the application is going to release the data, it must make sure to
205set a
206.Dv NULL
207value at the index, to avoid likely double-free crashes.
208.Pp
209The function
210.Fn CRYPTO_free_ex_data
211is used to free all exdata attached to a structure.
212The appropriate type-specific routine must be used.
213The
214.Fa class_index
215identifies the structure type, the
216.Fa obj
217is be the pointer to the actual structure, and
218.Fa r
219is a pointer to the structure's exdata field.
220.Pp
221The callback functions are used as follows.
222.Pp
223When a structure is initially allocated (such as by
224.Xr RSA_new 3 ) ,
225then
226.Fa new_func
227is called for every defined index.
228There is no requirement that the entire parent, or containing, structure
229has been set up.
230The
231.Fa new_func
232is typically used only to allocate memory to store the
233exdata, and perhaps an "initialized" flag within that memory.
234The exdata value should be set by calling
235.Fn CRYPTO_set_ex_data .
236.Pp
237When a structure is free'd (such as by
238.Xr SSL_CTX_free 3 ) ,
239then the
240.Fa free_func
241is called for every defined index.
242Again, the state of the parent structure is not guaranteed.
243The
244.Fa free_func
245may be called with a
246.Dv NULL
247pointer.
248.Pp
249Both
250.Fa new_func
251and
252.Fa free_func
253take the same parameters.
254The
255.Fa parent
256is the pointer to the structure that contains the exdata.
257The
258.Fa ptr
259is the current exdata item; for
260.Fa new_func
261this will typically be
262.Dv NULL .
263The
264.Fa r
265parameter is a pointer to the exdata field of the object.
266The
267.Fa idx
268is the index and is the value returned when the callbacks were initially
269registered via
270.Fn CRYPTO_get_ex_new_index
271and can be used if the same callback handles different types of exdata.
272.Pp
273.Fa dup_func
274is called when a structure is being copied.
275This is only done for
276.Vt SSL
277and
278.Vt SSL_SESSION
279objects.
280The
281.Fa to
282and
283.Fa from
284parameters are pointers to the destination and source
285.Vt CRYPTO_EX_DATA
286structures, respectively.
287The
288.Fa from_d
289parameter is a pointer to the source exdata.
290When
291.Fa dup_func
292returns, the value in
293.Fa from_d
294is copied to the destination ex_data.
295If the pointer contained in
296.Fa from_d
297is not modified by the
298.Fa dup_func ,
299then both
300.Fa to
301and
302.Fa from
303will point to the same data.
304The
305.Fa idx ,
306.Fa argl
307and
308.Fa argp
309parameters are as described for the other two callbacks.
310.Pp
311.Fn CRYPTO_set_ex_data
312is used to set application specific data.
313The data is supplied in the
314.Fa arg
315parameter and its precise meaning is up to the application.
316.Pp
317.Fn CRYPTO_get_ex_data
318is used to retrieve application specific data.
319The data is returned to the application; this will be the same value as
320supplied to a previous
321.Fn CRYPTO_set_ex_data
322call.
323.Sh RETURN VALUES
324.Fn CRYPTO_get_ex_new_index
325returns a new index or -1 on failure; the value 0 is reserved for
326the legacy "app_data" APIs.
327.Pp
328.Fn CRYPTO_set_ex_data
329returns 1 on success or 0 on failure.
330.Pp
331.Fn CRYPTO_get_ex_data
332returns the application data or
333.Dv NULL
334on failure; note that
335.Dv NULL
336may be a valid value.
337.Pp
338.Fa dup_func
339should return 0 for failure and 1 for success.
340.Pp
341On failure an error code can be obtained from
342.Xr ERR_get_error 3 .
343.Sh SEE ALSO
344.Xr BIO_get_ex_new_index 3 ,
345.Xr DH_get_ex_new_index 3 ,
346.Xr DSA_get_ex_new_index 3 ,
347.Xr RSA_get_ex_new_index 3 ,
348.Xr X509_STORE_CTX_get_ex_new_index 3
349.Sh HISTORY
350.Fn CRYPTO_get_ex_new_index ,
351.Fn CRYPTO_set_ex_data ,
352.Fn CRYPTO_get_ex_data ,
353.Fn CRYPTO_free_ex_data ,
354and
355.Fn CRYPTO_new_ex_data
356first appeared in SSLeay 0.9.0 and have been available since
357.Ox 2.4 .
358.Pp
359.Fn CRYPTO_EX_new ,
360.Fn CRYPTO_EX_free ,
361and
362.Fn CRYPTO_EX_dup
363first appeared in OpenSSL 0.9.5 and have been available since
364.Ox 2.7 .
365