]>
Commit | Line | Data |
---|---|---|
e6390aca RS |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c952780c | 5 | CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup, |
e17f5b6a RL |
6 | CRYPTO_free_ex_index, CRYPTO_get_ex_new_index, |
7 | CRYPTO_alloc_ex_data, CRYPTO_set_ex_data, CRYPTO_get_ex_data, | |
8 | CRYPTO_free_ex_data, CRYPTO_new_ex_data | |
e6390aca RS |
9 | - functions supporting application-specific data |
10 | ||
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/crypto.h> | |
14 | ||
15 | int CRYPTO_get_ex_new_index(int class_index, | |
e9b77246 BB |
16 | long argl, void *argp, |
17 | CRYPTO_EX_new *new_func, | |
18 | CRYPTO_EX_dup *dup_func, | |
19 | CRYPTO_EX_free *free_func); | |
e6390aca | 20 | |
1ee21259 TS |
21 | typedef void CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad, |
22 | int idx, long argl, void *argp); | |
e6390aca RS |
23 | typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, |
24 | int idx, long argl, void *argp); | |
3c853776 | 25 | typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from, |
e6390aca RS |
26 | void *from_d, int idx, long argl, void *argp); |
27 | ||
c952780c RS |
28 | int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad) |
29 | ||
e17f5b6a RL |
30 | int CRYPTO_alloc_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad, |
31 | int idx); | |
32 | ||
e6390aca RS |
33 | int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); |
34 | ||
35 | void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx); | |
36 | ||
37 | void CRYPTO_free_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *r); | |
38 | ||
39 | int CRYPTO_free_ex_index(int class_index, int idx); | |
40 | ||
41 | =head1 DESCRIPTION | |
42 | ||
43 | Several OpenSSL structures can have application-specific data attached to them, | |
44 | known as "exdata." | |
45 | The specific structures are: | |
46 | ||
a73d990e | 47 | BIO |
e6390aca RS |
48 | DH |
49 | DSA | |
3aef36ff | 50 | EC_KEY |
e6390aca | 51 | ENGINE |
ff1f7cde | 52 | EVP_PKEY |
d318389e | 53 | RAND_DRBG |
a73d990e DMSP |
54 | RSA |
55 | SSL | |
56 | SSL_CTX | |
57 | SSL_SESSION | |
e6390aca | 58 | UI |
18cfc668 | 59 | UI_METHOD |
a73d990e DMSP |
60 | X509 |
61 | X509_STORE | |
62 | X509_STORE_CTX | |
e6390aca | 63 | |
d318389e RS |
64 | In addition, the B<APP> name is reserved for use by application code. |
65 | ||
e6390aca RS |
66 | Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h> |
67 | header file. In addition, B<CRYPTO_EX_INDEX_APP> is reserved for | |
68 | applications to use this facility for their own structures. | |
69 | ||
70 | The API described here is used by OpenSSL to manipulate exdata for specific | |
71 | structures. Since the application data can be anything at all it is passed | |
72 | and retrieved as a B<void *> type. | |
73 | ||
c952780c RS |
74 | The B<CRYPTO_EX_DATA> type is opaque. To initialize the exdata part of |
75 | a structure, call CRYPTO_new_ex_data(). This is only necessary for | |
76 | B<CRYPTO_EX_INDEX_APP> objects. | |
77 | ||
e6390aca RS |
78 | Exdata types are identified by an B<index>, an integer guaranteed to be |
79 | unique within structures for the lifetime of the program. Applications | |
80 | using exdata typically call B<CRYPTO_get_ex_new_index> at startup, and | |
81 | store the result in a global variable, or write a wrapper function to | |
82 | provide lazy evaluation. The B<class_index> should be one of the | |
83 | B<CRYPTO_EX_INDEX_xxx> values. The B<argl> and B<argp> parameters are saved | |
84 | to be passed to the callbacks but are otherwise not used. In order to | |
85 | transparently manipulate exdata, three callbacks must be provided. The | |
86 | semantics of those callbacks are described below. | |
87 | ||
88 | When copying or releasing objects with exdata, the callback functions | |
89 | are called in increasing order of their B<index> value. | |
90 | ||
91 | If a dynamic library can be unloaded, it should call CRYPTO_free_ex_index() | |
92 | when this is done. | |
93 | This will replace the callbacks with no-ops | |
94 | so that applications don't crash. Any existing exdata will be leaked. | |
95 | ||
96 | To set or get the exdata on an object, the appropriate type-specific | |
97 | routine must be used. This is because the containing structure is opaque | |
98 | and the B<CRYPTO_EX_DATA> field is not accessible. In both API's, the | |
99 | B<idx> parameter should be an already-created index value. | |
100 | ||
101 | When setting exdata, the pointer specified with a particular index is saved, | |
102 | and returned on a subsequent "get" call. If the application is going to | |
103 | release the data, it must make sure to set a B<NULL> value at the index, | |
d3054fb6 | 104 | to avoid likely double-free crashes. |
e6390aca RS |
105 | |
106 | The function B<CRYPTO_free_ex_data> is used to free all exdata attached | |
107 | to a structure. The appropriate type-specific routine must be used. | |
108 | The B<class_index> identifies the structure type, the B<obj> is | |
84712024 | 109 | a pointer to the actual structure, and B<r> is a pointer to the |
e6390aca RS |
110 | structure's exdata field. |
111 | ||
112 | =head2 Callback Functions | |
113 | ||
114 | This section describes how the callback functions are used. Applications | |
115 | that are defining their own exdata using B<CYPRTO_EX_INDEX_APP> must | |
116 | call them as described here. | |
117 | ||
118 | When a structure is initially allocated (such as RSA_new()) then the | |
119 | new_func() is called for every defined index. There is no requirement | |
120 | that the entire parent, or containing, structure has been set up. | |
121 | The new_func() is typically used only to allocate memory to store the | |
122 | exdata, and perhaps an "initialized" flag within that memory. | |
e17f5b6a RL |
123 | The exdata value may be allocated later on with CRYPTO_alloc_ex_data(), |
124 | or may be set by calling CRYPTO_set_ex_data(). | |
e6390aca RS |
125 | |
126 | When a structure is free'd (such as SSL_CTX_free()) then the | |
127 | free_func() is called for every defined index. Again, the state of the | |
128 | parent structure is not guaranteed. The free_func() may be called with a | |
129 | NULL pointer. | |
130 | ||
131 | Both new_func() and free_func() take the same parameters. | |
132 | The B<parent> is the pointer to the structure that contains the exdata. | |
133 | The B<ptr> is the current exdata item; for new_func() this will typically | |
134 | be NULL. The B<r> parameter is a pointer to the exdata field of the object. | |
135 | The B<idx> is the index and is the value returned when the callbacks were | |
136 | initially registered via CRYPTO_get_ex_new_index() and can be used if | |
137 | the same callback handles different types of exdata. | |
138 | ||
139 | dup_func() is called when a structure is being copied. This is only done | |
1ee21259 TS |
140 | for B<SSL>, B<SSL_SESSION>, B<EC_KEY> objects and B<BIO> chains via |
141 | BIO_dup_chain(). The B<to> and B<from> parameters | |
e6390aca | 142 | are pointers to the destination and source B<CRYPTO_EX_DATA> structures, |
b3c31a65 BE |
143 | respectively. The B<from_d> parameter needs to be cast to a B<void **pptr> |
144 | as the API has currently the wrong signature; that will be changed in a | |
145 | future version. The B<*pptr> is a pointer to the source exdata. | |
146 | When the dup_func() returns, the value in B<*pptr> is copied to the | |
147 | destination ex_data. If the pointer contained in B<*pptr> is not modified | |
d3054fb6 BK |
148 | by the dup_func(), then both B<to> and B<from> will point to the same data. |
149 | The B<idx>, B<argl> and B<argp> parameters are as described for the other | |
b3c31a65 BE |
150 | two callbacks. If the dup_func() returns B<0> the whole CRYPTO_dup_ex_data() |
151 | will fail. | |
e6390aca RS |
152 | |
153 | =head1 RETURN VALUES | |
154 | ||
a95d7574 | 155 | CRYPTO_get_ex_new_index() returns a new index or -1 on failure. |
e6390aca | 156 | |
e17f5b6a RL |
157 | CRYPTO_free_ex_index(), CRYPTO_alloc_ex_data() and CRYPTO_set_ex_data() |
158 | return 1 on success or 0 on failure. | |
e6390aca RS |
159 | |
160 | CRYPTO_get_ex_data() returns the application data or NULL on failure; | |
161 | note that NULL may be a valid value. | |
162 | ||
163 | dup_func() should return 0 for failure and 1 for success. | |
164 | ||
e17f5b6a RL |
165 | =head1 HISTORY |
166 | ||
4674aaf4 | 167 | CRYPTO_alloc_ex_data() was added in OpenSSL 3.0. |
e17f5b6a | 168 | |
e2f92610 RS |
169 | =head1 COPYRIGHT |
170 | ||
a73d990e | 171 | Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 172 | |
4746f25a | 173 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
174 | this file except in compliance with the License. You can obtain a copy |
175 | in the file LICENSE in the source distribution or at | |
176 | L<https://www.openssl.org/source/license.html>. | |
177 | ||
178 | =cut |