1.\" $OpenBSD: RSA_get_ex_new_index.3,v 1.7 2017/08/01 14:57:03 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: August 1 2017 $ 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.Ft typedef int 85.Fo CRYPTO_EX_new 86.Fa "void *parent" 87.Fa "void *ptr" 88.Fa "CRYPTO_EX_DATA *ad" 89.Fa "int idx" 90.Fa "long argl" 91.Fa "void *argp" 92.Fc 93.Ft typedef void 94.Fo CRYPTO_EX_free 95.Fa "void *parent" 96.Fa "void *ptr" 97.Fa "CRYPTO_EX_DATA *ad" 98.Fa "int idx" 99.Fa "long argl" 100.Fa "void *argp" 101.Fc 102.Ft typedef int 103.Fo CRYPTO_EX_dup 104.Fa "CRYPTO_EX_DATA *to" 105.Fa "CRYPTO_EX_DATA *from" 106.Fa "void *from_d" 107.Fa "int idx" 108.Fa "long argl" 109.Fa "void *argp" 110.Fc 111.Sh DESCRIPTION 112Several OpenSSL structures can have application specific data attached 113to them. 114This has several potential uses: it can be used to cache data associated 115with a structure (for example the hash of some part of the structure) or 116some additional data (for example a handle to the data in an external 117library). 118.Pp 119Since the application data can be anything at all it is passed and 120retrieved as a 121.Vt void * 122type. 123.Pp 124The 125.Fn RSA_get_ex_new_index 126function is initially called to "register" some new application specific 127data. 128It takes three optional function pointers which are called when the 129parent structure (in this case an RSA structure) is initially created, 130when it is copied and when it is freed up. 131If any or all of these function pointer arguments are not used, they 132should be set to 133.Dv NULL . 134The precise manner in which these function pointers are called is 135described in more detail below. 136.Fn RSA_get_ex_new_index 137also takes additional long and pointer parameters which will be passed 138to the supplied functions but which otherwise have no special meaning. 139It returns an index which should be stored (typically in a static 140variable) and passed as the 141.Fa idx 142parameter in the remaining functions. 143Each successful call to 144.Fn RSA_get_ex_new_index 145will return an index greater than any previously returned. 146This is 147important because the optional functions are called in order of 148increasing index value. 149.Pp 150.Fn RSA_set_ex_data 151is used to set application specific data. 152The data is supplied in the 153.Fa arg 154parameter and its precise meaning is up to the application. 155.Pp 156.Fn RSA_get_ex_data 157is used to retrieve application specific data. 158The data is returned to the application, which will be the same value as 159supplied to a previous 160.Fn RSA_set_ex_data 161call. 162.Pp 163.Fa new_func 164is called when a structure is initially allocated (for example with 165.Xr RSA_new 3 . 166The parent structure members will not have any meaningful values at this 167point. 168This function will typically be used to allocate any application 169specific structure. 170.Pp 171.Fa free_func 172is called when a structure is being freed up. 173The dynamic parent structure members should not be accessed because they 174will be freed up when this function is called. 175.Pp 176.Fa new_func 177and 178.Fa free_func 179take the same parameters. 180.Fa parent 181is a pointer to the parent 182.Vt RSA 183structure. 184.Fa ptr 185is the application specific data (this won't be of much use in 186.Fa new_func ) . 187.Fa ad 188is a pointer to the 189.Vt CRYPTO_EX_DATA 190structure from the parent 191.Vt RSA 192structure: the functions 193.Fn CRYPTO_get_ex_data 194and 195.Fn CRYPTO_set_ex_data 196can be called to manipulate it. 197The 198.Fa idx 199parameter is the index: this will be the same value returned by 200.Fn RSA_get_ex_new_index 201when the functions were initially registered. 202Finally the 203.Fa argl 204and 205.Fa argp 206parameters are the values originally passed to the same corresponding 207parameters when 208.Fn RSA_get_ex_new_index 209was called. 210.Pp 211.Fa dup_func 212is called when a structure is being copied. 213Pointers to the destination and source 214.Vt CRYPTO_EX_DATA 215structures are passed in the 216.Fa to 217and 218.Fa from 219parameters, respectively. 220The 221.Fa from_d 222parameter is passed a pointer to the source application data when the 223function is called. 224When the function returns, the value is copied to the destination: 225the application can thus modify the data pointed to by 226.Fa from_d 227and have different values in the source and destination. 228The 229.Fa idx , 230.Fa argl , 231and 232.Fa argp 233parameters are the same as those in 234.Fa new_func 235and 236.Fa free_func . 237.Sh RETURN VALUES 238.Fn RSA_get_ex_new_index 239returns a new index or -1 on failure. 240Note that 0 is a valid index value. 241.Pp 242.Fn RSA_set_ex_data 243returns 1 on success or 0 on failure. 244.Pp 245.Fn RSA_get_ex_data 246returns the application data or 247.Dv NULL 248on failure. 249.Dv NULL 250may also be valid application data, but currently it can only fail if 251given an invalid 252.Fa idx 253parameter. 254.Pp 255.Fa new_func 256and 257.Fa dup_func 258should return 0 for failure and 1 for success. 259.Pp 260On failure an error code can be obtained from 261.Xr ERR_get_error 3 . 262.Sh SEE ALSO 263.Xr BIO_set_ex_data 3 , 264.Xr CRYPTO_set_ex_data 3 , 265.Xr DH_set_ex_data 3 , 266.Xr DSA_set_ex_data 3 , 267.Xr RSA_new 3 , 268.Xr X509_STORE_CTX_set_ex_data 3 269.Sh HISTORY 270.Fn RSA_get_ex_new_index , 271.Fn RSA_set_ex_data , 272and 273.Fn RSA_get_ex_data 274are available since SSLeay 0.9.0. 275.Sh BUGS 276.Fa dup_func 277is currently never called. 278.Pp 279The return value of 280.Fa new_func 281is ignored. 282.Pp 283The 284.Fa new_func 285function isn't very useful because no meaningful values are present in 286the parent RSA structure when it is called. 287