Manual Pages for UNIX Operating System command usage for man RSA_get_ex_new_index

OpenSSL                            RSA_get_ex_new_index(3openssl)



NNNNAAAAMMMMEEEE
     RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add
     application specific data to RSA structures

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
      #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);


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     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 vvvvooooiiiidddd **** type.

     The RRRRSSSSAAAA_ggggeeeetttt_eeeexxxx_nnnneeeewwww_iiiinnnnddddeeeexxxx(((()))) 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. RRRRSSSSAAAA_ggggeeeetttt_eeeexxxx_nnnneeeewwww_iiiinnnnddddeeeexxxx(((()))) 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 iiiinnnnddddeeeexxxx which should be stored
     (typically in a static variable) and passed used in the iiiiddddxxxx
     parameter in the remaining functions. Each successful call
     to RRRRSSSSAAAA_ggggeeeetttt_eeeexxxx_nnnneeeewwww_iiiinnnnddddeeeexxxx(((()))) will return an index greater than
     any previously returned, this is important because the
     optional functions are called in order of increasing index



6/Dec/2006             Last change: 0.9.8o                      1






OpenSSL                            RSA_get_ex_new_index(3openssl)



     value.

     RRRRSSSSAAAA_sssseeeetttt_eeeexxxx_ddddaaaattttaaaa(((()))) is used to set application specific data,
     the data is supplied in the aaaarrrrgggg parameter and its precise
     meaning is up to the application.

     RRRRSSSSAAAA_ggggeeeetttt_eeeexxxx_ddddaaaattttaaaa(((()))) 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 RRRRSSSSAAAA_sssseeeetttt_eeeexxxx_ddddaaaattttaaaa(((())))
     call.

     nnnneeeewwww_ffffuuuunnnncccc(((()))) is called when a structure is initially allocated
     (for example with RRRRSSSSAAAA_nnnneeeewwww(((()))). 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.

     ffffrrrreeeeeeee_ffffuuuunnnncccc(((()))) 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.

     nnnneeeewwww_ffffuuuunnnncccc(((()))) and ffffrrrreeeeeeee_ffffuuuunnnncccc(((()))) take the same parameters. ppppaaaarrrreeeennnntttt
     is a pointer to the parent RSA structure. ppppttttrrrr is a the
     application specific data (this wont be of much use in
     nnnneeeewwww_ffffuuuunnnncccc(((()))). aaaadddd is a pointer to the CCCCRRRRYYYYPPPPTTTTOOOO_EEEEXXXX_DDDDAAAATTTTAAAA structure
     from the parent RSA structure: the functions
     CCCCRRRRYYYYPPPPTTTTOOOO_ggggeeeetttt_eeeexxxx_ddddaaaattttaaaa(((()))) and CCCCRRRRYYYYPPPPTTTTOOOO_sssseeeetttt_eeeexxxx_ddddaaaattttaaaa(((()))) can be called
     to manipulate it. The iiiiddddxxxx parameter is the index: this will
     be the same value returned by RRRRSSSSAAAA_ggggeeeetttt_eeeexxxx_nnnneeeewwww_iiiinnnnddddeeeexxxx(((()))) when
     the functions were initially registered. Finally the aaaarrrrggggllll
     and aaaarrrrggggpppp parameters are the values originally passed to the
     same corresponding parameters when RRRRSSSSAAAA_ggggeeeetttt_eeeexxxx_nnnneeeewwww_iiiinnnnddddeeeexxxx(((())))
     was called.

     dddduuuupppp_ffffuuuunnnncccc(((()))) is called when a structure is being copied.
     Pointers to the destination and source CCCCRRRRYYYYPPPPTTTTOOOO_EEEEXXXX_DDDDAAAATTTTAAAA
     structures are passed in the ttttoooo and ffffrrrroooommmm parameters
     respectively. The ffffrrrroooommmm_dddd 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 ffffrrrroooommmm_dddd and have different values in the source
     and destination.  The iiiiddddxxxx, aaaarrrrggggllll and aaaarrrrggggpppp parameters are the
     same as those in nnnneeeewwww_ffffuuuunnnncccc(((()))) and ffffrrrreeeeeeee_ffffuuuunnnncccc(((()))).

RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEESSSS
     RRRRSSSSAAAA_ggggeeeetttt_eeeexxxx_nnnneeeewwww_iiiinnnnddddeeeexxxx(((()))) returns a new index or -1 on failure
     (note 0 is a valid index value).

     RRRRSSSSAAAA_sssseeeetttt_eeeexxxx_ddddaaaattttaaaa(((()))) returns 1 on success or 0 on failure.





6/Dec/2006             Last change: 0.9.8o                      2






OpenSSL                            RSA_get_ex_new_index(3openssl)



     RRRRSSSSAAAA_ggggeeeetttt_eeeexxxx_ddddaaaattttaaaa(((()))) 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 iiiiddddxxxx parameter.

     nnnneeeewwww_ffffuuuunnnncccc(((()))) and dddduuuupppp_ffffuuuunnnncccc(((()))) should return 0 for failure and 1
     for success.

     On failure an error code can be obtained from
     ERR_get_error(3).

BBBBUUUUGGGGSSSS
     dddduuuupppp_ffffuuuunnnncccc(((()))) is currently never called.

     The return value of nnnneeeewwww_ffffuuuunnnncccc(((()))) is ignored.

     The nnnneeeewwww_ffffuuuunnnncccc(((()))) function isn't very useful because no
     meaningful values are present in the parent RSA structure
     when it is called.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     rsa(3), CRYPTO_set_ex_data(3)

HHHHIIIISSSSTTTTOOOORRRRYYYY
     RSA_get_ex_new_index(), RSA_set_ex_data() and
     RSA_get_ex_data() are available since SSLeay 0.9.0.






























6/Dec/2006             Last change: 0.9.8o                      3