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