1.\" $OpenBSD: RSA_get_ex_new_index.3,v 1.10 2018/03/23 23:18:17 schwarze Exp $ 2.\" OpenSSL 35cb565a Nov 19 15:49:30 2015 -0500 3.\" 4.\" This file was written by Ulf Moeller <ulf@openssl.org> and 5.\" Dr. Stephen Henson <steve@openssl.org>. 6.\" Copyright (c) 2000, 2006 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: March 23 2018 $ 53.Dt RSA_GET_EX_NEW_INDEX 3 54.Os 55.Sh NAME 56.Nm RSA_get_ex_new_index , 57.Nm RSA_set_ex_data , 58.Nm RSA_get_ex_data , 59.Nm CRYPTO_EX_new , 60.Nm CRYPTO_EX_dup , 61.Nm CRYPTO_EX_free 62.Nd add application specific data to RSA structures 63.Sh SYNOPSIS 64.In openssl/rsa.h 65.Ft int 66.Fo RSA_get_ex_new_index 67.Fa "long argl" 68.Fa "void *argp" 69.Fa "CRYPTO_EX_new *new_func" 70.Fa "CRYPTO_EX_dup *dup_func" 71.Fa "CRYPTO_EX_free *free_func" 72.Fc 73.Ft int 74.Fo RSA_set_ex_data 75.Fa "RSA *r" 76.Fa "int idx" 77.Fa "void *arg" 78.Fc 79.Ft void * 80.Fo RSA_get_ex_data 81.Fa "RSA *r" 82.Fa "int idx" 83.Fc 84.In openssl/crypto.h 85.Ft typedef int 86.Fo CRYPTO_EX_new 87.Fa "void *parent" 88.Fa "void *ptr" 89.Fa "CRYPTO_EX_DATA *ad" 90.Fa "int idx" 91.Fa "long argl" 92.Fa "void *argp" 93.Fc 94.Ft typedef void 95.Fo CRYPTO_EX_free 96.Fa "void *parent" 97.Fa "void *ptr" 98.Fa "CRYPTO_EX_DATA *ad" 99.Fa "int idx" 100.Fa "long argl" 101.Fa "void *argp" 102.Fc 103.Ft typedef int 104.Fo CRYPTO_EX_dup 105.Fa "CRYPTO_EX_DATA *to" 106.Fa "CRYPTO_EX_DATA *from" 107.Fa "void *from_d" 108.Fa "int idx" 109.Fa "long argl" 110.Fa "void *argp" 111.Fc 112.Sh DESCRIPTION 113Several OpenSSL structures can have application specific data attached 114to them. 115This has several potential uses: it can be used to cache data associated 116with a structure (for example the hash of some part of the structure) or 117some additional data (for example a handle to the data in an external 118library). 119.Pp 120Since the application data can be anything at all it is passed and 121retrieved as a 122.Vt void * 123type. 124.Pp 125The 126.Fn RSA_get_ex_new_index 127function is initially called to "register" some new application specific 128data. 129It takes three optional function pointers which are called when the 130parent structure (in this case an RSA structure) is initially created, 131when it is copied and when it is freed up. 132If any or all of these function pointer arguments are not used, they 133should be set to 134.Dv NULL . 135The precise manner in which these function pointers are called is 136described in more detail below. 137.Fn RSA_get_ex_new_index 138also takes additional long and pointer parameters which will be passed 139to the supplied functions but which otherwise have no special meaning. 140It returns an index which should be stored (typically in a static 141variable) and passed as the 142.Fa idx 143parameter in the remaining functions. 144Each successful call to 145.Fn RSA_get_ex_new_index 146will return an index greater than any previously returned. 147This is 148important because the optional functions are called in order of 149increasing index value. 150.Pp 151.Fn RSA_set_ex_data 152is used to set application specific data. 153The data is supplied in the 154.Fa arg 155parameter and its precise meaning is up to the application. 156.Pp 157.Fn RSA_get_ex_data 158is used to retrieve application specific data. 159The data is returned to the application, which will be the same value as 160supplied to a previous 161.Fn RSA_set_ex_data 162call. 163.Pp 164.Fa new_func 165is called when a structure is initially allocated (for example with 166.Xr RSA_new 3 . 167The parent structure members will not have any meaningful values at this 168point. 169This function will typically be used to allocate any application 170specific structure. 171.Pp 172.Fa free_func 173is called when a structure is being freed up. 174The dynamic parent structure members should not be accessed because they 175will be freed up when this function is called. 176.Pp 177.Fa new_func 178and 179.Fa free_func 180take the same parameters. 181.Fa parent 182is a pointer to the parent 183.Vt RSA 184structure. 185.Fa ptr 186is the application specific data (this won't be of much use in 187.Fa new_func ) . 188.Fa ad 189is a pointer to the 190.Vt CRYPTO_EX_DATA 191structure from the parent 192.Vt RSA 193structure: the functions 194.Fn CRYPTO_get_ex_data 195and 196.Fn CRYPTO_set_ex_data 197can be called to manipulate it. 198The 199.Fa idx 200parameter is the index: this will be the same value returned by 201.Fn RSA_get_ex_new_index 202when the functions were initially registered. 203Finally the 204.Fa argl 205and 206.Fa argp 207parameters are the values originally passed to the same corresponding 208parameters when 209.Fn RSA_get_ex_new_index 210was called. 211.Pp 212.Fa dup_func 213is called when a structure is being copied. 214Pointers to the destination and source 215.Vt CRYPTO_EX_DATA 216structures are passed in the 217.Fa to 218and 219.Fa from 220parameters, respectively. 221The 222.Fa from_d 223parameter is passed a pointer to the source application data when the 224function is called. 225When the function returns, the value is copied to the destination: 226the application can thus modify the data pointed to by 227.Fa from_d 228and have different values in the source and destination. 229The 230.Fa idx , 231.Fa argl , 232and 233.Fa argp 234parameters are the same as those in 235.Fa new_func 236and 237.Fa free_func . 238.Sh RETURN VALUES 239.Fn RSA_get_ex_new_index 240returns a new index or -1 on failure. 241Note that 0 is a valid index value. 242.Pp 243.Fn RSA_set_ex_data 244returns 1 on success or 0 on failure. 245.Pp 246.Fn RSA_get_ex_data 247returns the application data or 248.Dv NULL 249on failure. 250.Dv NULL 251may also be valid application data, but currently it can only fail if 252given an invalid 253.Fa idx 254parameter. 255.Pp 256.Fa new_func 257and 258.Fa dup_func 259should return 0 for failure and 1 for success. 260.Pp 261On failure an error code can be obtained from 262.Xr ERR_get_error 3 . 263.Sh SEE ALSO 264.Xr BIO_set_ex_data 3 , 265.Xr CRYPTO_set_ex_data 3 , 266.Xr DH_set_ex_data 3 , 267.Xr DSA_set_ex_data 3 , 268.Xr RSA_new 3 , 269.Xr SSL_CTX_set_ex_data 3 , 270.Xr SSL_SESSION_set_ex_data 3 , 271.Xr SSL_set_ex_data 3 , 272.Xr X509_STORE_CTX_set_ex_data 3 , 273.Xr X509_STORE_set_ex_data 3 274.Sh HISTORY 275These functions first appeared in SSLeay 0.9.0 276and have been available since 277.Ox 2.4 . 278.Sh BUGS 279.Fa dup_func 280is currently never called. 281.Pp 282The return value of 283.Fa new_func 284is ignored. 285.Pp 286The 287.Fa new_func 288function isn't very useful because no meaningful values are present in 289the parent RSA structure when it is called. 290