RSA_get_ex_new_index(3) OpenSSL RSA_get_ex_new_index(3) NNAAMMEE RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add applica- tion specific data to RSA structures SSYYNNOOPPSSIISS #include 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 CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad, int idx, long argl, void *argp); typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, int idx, long argl, void *argp); typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, int idx, long argl, void *argp); DDEESSCCRRIIPPTTIIOONN 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 vvooiidd ** type. The _RR_SS_AA____gg_ee_tt____ee_xx____nn_ee_ww____ii_nn_dd_ee_xx_((_)) 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 precise manner in which these function pointers are called is described in more detail below. _RR_SS_AA____gg_ee_tt____ee_xx____nn_ee_ww____ii_nn_dd_ee_xx_((_)) also takes additional long and pointer parame- ters which will be passed to the supplied functions but which otherwise have no special meaning. It returns an iinnddeexx which should be stored (typically in a static variable) and passed used in the iiddxx parameter in the remaining functions. Each successful call to _RR_SS_AA____gg_ee_tt____ee_xx____nn_ee_ww____ii_nn_dd_ee_xx_((_)) will return an index greater than any previously returned, this is important because the optional functions are called in order of increasing index value. _RR_SS_AA____ss_ee_tt____ee_xx____dd_aa_tt_aa_((_)) is used to set application specific data, the data is supplied in the aarrgg parameter and its precise meaning is up to the application. _RR_SS_AA____gg_ee_tt____ee_xx____dd_aa_tt_aa_((_)) 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 _RR_SS_AA____ss_ee_tt____ee_xx____dd_aa_tt_aa_((_)) call. _nn_ee_ww____ff_uu_nn_cc_((_)) is called when a structure is initially allocated (for exam- ple with _RR_SS_AA____nn_ee_ww_((_)). 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. _ff_rr_ee_ee____ff_uu_nn_cc_((_)) 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. _nn_ee_ww____ff_uu_nn_cc_((_)) and _ff_rr_ee_ee____ff_uu_nn_cc_((_)) take the same parameters. ppaarreenntt is a pointer to the parent RSA structure. ppttrr is a the application specific data (this wont be of much use in _nn_ee_ww____ff_uu_nn_cc_((_)). aadd is a pointer to the CCRRYYPPTTOO__EEXX__DDAATTAA structure from the parent RSA structure: the functions _CC_RR_YY_PP_TT_OO____gg_ee_tt____ee_xx____dd_aa_tt_aa_((_)) and _CC_RR_YY_PP_TT_OO____ss_ee_tt____ee_xx____dd_aa_tt_aa_((_)) can be called to manipu- late it. The iiddxx parameter is the index: this will be the same value returned by _RR_SS_AA____gg_ee_tt____ee_xx____nn_ee_ww____ii_nn_dd_ee_xx_((_)) when the functions were initially registered. Finally the aarrggll and aarrggpp parameters are the values origi- nally passed to the same corresponding parameters when _RR_SS_AA____gg_ee_tt____ee_xx____nn_ee_ww____ii_nn_dd_ee_xx_((_)) was called. _dd_uu_pp____ff_uu_nn_cc_((_)) is called when a structure is being copied. Pointers to the destination and source CCRRYYPPTTOO__EEXX__DDAATTAA structures are passed in the ttoo and ffrroomm parameters respectively. The ffrroomm__dd 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 ffrroomm__dd and have dif- ferent values in the source and destination. The iiddxx, aarrggll and aarrggpp parameters are the same as those in _nn_ee_ww____ff_uu_nn_cc_((_)) and _ff_rr_ee_ee____ff_uu_nn_cc_((_)). RREETTUURRNN VVAALLUUEESS _RR_SS_AA____gg_ee_tt____ee_xx____nn_ee_ww____ii_nn_dd_ee_xx_((_)) returns a new index or -1 on failure (note 0 is a valid index value). _RR_SS_AA____ss_ee_tt____ee_xx____dd_aa_tt_aa_((_)) returns 1 on success or 0 on failure. _RR_SS_AA____gg_ee_tt____ee_xx____dd_aa_tt_aa_((_)) 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 iiddxx parameter. _nn_ee_ww____ff_uu_nn_cc_((_)) and _dd_uu_pp____ff_uu_nn_cc_((_)) should return 0 for failure and 1 for suc- cess. On failure an error code can be obtained from _E_R_R___g_e_t___e_r_r_o_r(3). BBUUGGSS _dd_uu_pp____ff_uu_nn_cc_((_)) is currently never called. The return value of _nn_ee_ww____ff_uu_nn_cc_((_)) is ignored. The _nn_ee_ww____ff_uu_nn_cc_((_)) function isn't very useful because no meaningful values are present in the parent RSA structure when it is called. SSEEEE AALLSSOO _r_s_a(3), _C_R_Y_P_T_O___s_e_t___e_x___d_a_t_a(3) HHIISSTTOORRYY _R_S_A___g_e_t___e_x___n_e_w___i_n_d_e_x_(_), _R_S_A___s_e_t___e_x___d_a_t_a_(_) and _R_S_A___g_e_t___e_x___d_a_t_a_(_) are available since SSLeay 0.9.0. 1.0.1u 2016-09-22 RSA_get_ex_new_index(3)