Index for Section 3

Alphabetical listing for R

Bottom of page

RSA_get_ex_new_index(3)
NAME
  RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - Add application
  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 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.

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 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.

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)

Index for Section 3

Alphabetical listing for R

Top of page