RSA_get_ex_new_index(3)RSA_get_ex_new_index(3)NAME
RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - Add applica‐
tion specific data to RSA structures
SYNOPSIS
#include <openssl/rsa.h>
int RSA_get_ex_new_index(
long argl, void *argp, CRYPTO_EX_new *new_func, CRYPTO_EX_dup
*dup_func, CRYPTO_EX_free *free_func ); int RSA_set_ex_data(
RSA *r, int idx, void *arg ); void *RSA_get_ex_data(
RSA *r, int idx ); typedef int new_func(
void *parent, void *ptr, CRYPTO_EX_DATA *ad, int idx, long
argl, void *argp ); typedef void free_func(
void *parent, void *ptr, CRYPTO_EX_DATA *ad, int idx, long
argl, void *argp ); typedef int dup_func(
CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, int
idx, long argl, void *argp );
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).
Since the application data can be anything at all, it is passed and
retrieved as a void * type.
The 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 NULL. The RSA_get_ex_new_index() function
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 vari‐
able) and passed used in the idx parameter in the remaining functions.
Each successful call to 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.
The RSA_set_ex_data() function is used to set application specific
data. The data is supplied in the arg parameter and its precise meaning
is up to the application.
The RSA_get_ex_data() function is used to retrieve application specific
data. The data is returned to the application. This will be the same
value as supplied to a previous RSA_set_ex_data() call.
The new_func() function is called when a structure is initially allo‐
cated, such as with the RSA_new() function. The parent structure mem‐
bers will not have any meaningful values at this point. This function
will typically be used to allocate any application specific structure.
The free_func() function 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.
The new_func() and free_func() functions take the same parameters. The
parent is a pointer to the parent RSA structure. The ptr is the appli‐
cation specific data, which is not very useful in new_func(). The ad
is a pointer to the CRYPTO_EX_DATA structure from the parent RSA struc‐
ture. The functions CRYPTO_get_ex_data() and CRYPTO_set_ex_data() can
be called to manipulate it. The idx parameter is the index. This will
be the same value returned by the RSA_get_ex_new_index() function when
the functions were initially registered. Finally, the argl and argp
parameters are the values originally passed to the same corresponding
parameters when the RSA_get_ex_new_index() function was called.
The dup_func() function is called when a structure is being copied.
Pointers to the destination and source CRYPTO_EX_DATA structures are
passed in the to and from parameters respectively. The 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 destina‐
tion. The application can thus modify the data pointed to by from_d and
have different values in the source and destination. The idx, argl and
argp parameters are the same as those in the new_func() and free_func()
functions.
RESTRICTIONS
The dup_func() function is never called.
The return value of the new_func() function is ignored.
The new_func() function is not very useful because no meaningful values
are present in the parent RSA structure when it is called.
RETURN VALUES
The RSA_get_ex_new_index() function returns a new index or -1 on fail‐
ure (0 is a valid index value).
The RSA_set_ex_data() function returns 1 on success or 0 on failure.
The RSA_get_ex_data() function returns the application data or 0 on
failure. 0 may also be valid application data but currently it can only
fail if given an invalid idx parameter.
The new_func() and dup_func() functions should return 0 for failure and
1 for success.
On failure an error code can be obtained by using the ERR_get_error()
function.
HISTORY
The RSA_get_ex_new_index(), RSA_set_ex_data(), and RSA_get_ex_data()
functions are available since SSLeay 0.9.0.
SEE ALSO
Functions: rsa(3), CRYPTO_set_ex_data(3)RSA_get_ex_new_index(3)