.\" $OpenBSD: RSA_get_ex_new_index.3,v 1.6 2017/01/06 20:35:23 schwarze Exp $ .\" OpenSSL 35cb565a Nov 19 15:49:30 2015 -0500 .\" .\" This file was written by Ulf Moeller and .\" Dr. Stephen Henson . .\" Copyright (c) 2000, 2006 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" 3. All advertising materials mentioning features or use of this .\" software must display the following acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" .\" .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to .\" endorse or promote products derived from this software without .\" prior written permission. For written permission, please contact .\" openssl-core@openssl.org. .\" .\" 5. Products derived from this software may not be called "OpenSSL" .\" nor may "OpenSSL" appear in their names without prior written .\" permission of the OpenSSL Project. .\" .\" 6. Redistributions of any form whatsoever must retain the following .\" acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" .\" .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: January 6 2017 $ .Dt RSA_GET_EX_NEW_INDEX 3 .Os .Sh NAME .Nm RSA_get_ex_new_index , .Nm RSA_set_ex_data , .Nm RSA_get_ex_data .Nd add application specific data to RSA structures .Sh SYNOPSIS .In openssl/rsa.h .Ft int .Fo RSA_get_ex_new_index .Fa "long argl" .Fa "void *argp" .Fa "CRYPTO_EX_new *new_func" .Fa "CRYPTO_EX_dup *dup_func" .Fa "CRYPTO_EX_free *free_func" .Fc .Ft int .Fo RSA_set_ex_data .Fa "RSA *r" .Fa "int idx" .Fa "void *arg" .Fc .Ft void * .Fo RSA_get_ex_data .Fa "RSA *r" .Fa "int idx" .Fc .Ft typedef int .Fo CRYPTO_EX_new .Fa "void *parent" .Fa "void *ptr" .Fa "CRYPTO_EX_DATA *ad" .Fa "int idx" .Fa "long argl" .Fa "void *argp" .Fc .Ft typedef void .Fo CRYPTO_EX_free .Fa "void *parent" .Fa "void *ptr" .Fa "CRYPTO_EX_DATA *ad" .Fa "int idx" .Fa "long argl" .Fa "void *argp" .Fc .Ft typedef int .Fo CRYPTO_EX_dup .Fa "CRYPTO_EX_DATA *to" .Fa "CRYPTO_EX_DATA *from" .Fa "void *from_d" .Fa "int idx" .Fa "long argl" .Fa "void *argp" .Fc .Sh DESCRIPTION Several OpenSSL structures can have application specific data attached to them. This has several potential uses: it can be used to cache data associated with a structure (for example the hash of some part of the structure) or some additional data (for example a handle to the data in an external library). .Pp Since the application data can be anything at all it is passed and retrieved as a .Vt void * type. .Pp The .Fn RSA_get_ex_new_index function is initially called to "register" some new application specific data. It takes three optional function pointers which are called when the parent structure (in this case an RSA structure) is initially created, when it is copied and when it is freed up. If any or all of these function pointer arguments are not used, they should be set to .Dv NULL . The precise manner in which these function pointers are called is described in more detail below. .Fn RSA_get_ex_new_index also takes additional long and pointer parameters which will be passed to the supplied functions but which otherwise have no special meaning. It returns an index which should be stored (typically in a static variable) and passed as the .Fa idx parameter in the remaining functions. Each successful call to .Fn RSA_get_ex_new_index will return an index greater than any previously returned. This is important because the optional functions are called in order of increasing index value. .Pp .Fn RSA_set_ex_data is used to set application specific data. The data is supplied in the .Fa arg parameter and its precise meaning is up to the application. .Pp .Fn RSA_get_ex_data is used to retrieve application specific data. The data is returned to the application, which will be the same value as supplied to a previous .Fn RSA_set_ex_data call. .Pp .Fa new_func is called when a structure is initially allocated (for example with .Xr RSA_new 3 . The parent structure members will not have any meaningful values at this point. This function will typically be used to allocate any application specific structure. .Pp .Fa free_func is called when a structure is being freed up. The dynamic parent structure members should not be accessed because they will be freed up when this function is called. .Pp .Fa new_func and .Fa free_func take the same parameters. .Fa parent is a pointer to the parent .Vt RSA structure. .Fa ptr is the application specific data (this won't be of much use in .Fa new_func ) . .Fa ad is a pointer to the .Vt CRYPTO_EX_DATA structure from the parent .Vt RSA structure: the functions .Fn CRYPTO_get_ex_data and .Fn CRYPTO_set_ex_data can be called to manipulate it. The .Fa idx parameter is the index: this will be the same value returned by .Fn RSA_get_ex_new_index when the functions were initially registered. Finally the .Fa argl and .Fa argp parameters are the values originally passed to the same corresponding parameters when .Fn RSA_get_ex_new_index was called. .Pp .Fa dup_func is called when a structure is being copied. Pointers to the destination and source .Vt CRYPTO_EX_DATA structures are passed in the .Fa to and .Fa from parameters, respectively. The .Fa from_d parameter is passed a pointer to the source application data when the function is called. When the function returns, the value is copied to the destination: the application can thus modify the data pointed to by .Fa from_d and have different values in the source and destination. The .Fa idx , .Fa argl , and .Fa argp parameters are the same as those in .Fa new_func and .Fa free_func . .Sh RETURN VALUES .Fn RSA_get_ex_new_index returns a new index or -1 on failure. Note that 0 is a valid index value. .Pp .Fn RSA_set_ex_data returns 1 on success or 0 on failure. .Pp .Fn RSA_get_ex_data returns the application data or .Dv NULL on failure. .Dv NULL may also be valid application data, but currently it can only fail if given an invalid .Fa idx parameter. .Pp .Fa new_func and .Fa dup_func should return 0 for failure and 1 for success. .Pp On failure an error code can be obtained from .Xr ERR_get_error 3 . .Sh SEE ALSO .Xr BIO_set_ex_data 3 , .Xr CRYPTO_set_ex_data 3 , .Xr DH_set_ex_data 3 , .Xr DSA_set_ex_data 3 , .Xr RSA_new 3 , .Xr X509_STORE_CTX_set_ex_data 3 .Sh HISTORY .Fn RSA_get_ex_new_index , .Fn RSA_set_ex_data , and .Fn RSA_get_ex_data are available since SSLeay 0.9.0. .Sh BUGS .Fa dup_func is currently never called. .Pp The return value of .Fa new_func is ignored. .Pp The .Fa new_func function isn't very useful because no meaningful values are present in the parent RSA structure when it is called.