|
|
RSA_get_ex_new_index(3)
Contents
|
RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data -
Add application specific data to RSA structures
#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 );
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 variable) 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
allocated, such as with the RSA_new() function.
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.
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 application 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 structure.
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 destination. 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.
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.
The RSA_get_ex_new_index() function returns a new index or
-1 on failure (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.
The RSA_get_ex_new_index(), RSA_set_ex_data(), and
RSA_get_ex_data() functions are available since SSLeay
0.9.0.
Functions: rsa(3), CRYPTO_set_ex_data(3)
RSA_get_ex_new_index(3)
[ Back ] |
