path: root/lib/libcrypto/man/RSA_get_ex_new_index.3

.\"	$OpenBSD: RSA_get_ex_new_index.3,v 1.10 2018/03/23 23:18:17 schwarze Exp $
.\"	OpenSSL 35cb565a Nov 19 15:49:30 2015 -0500
.\"
.\" This file was written by Ulf Moeller <ulf@openssl.org> and
.\" Dr. Stephen Henson <steve@openssl.org>.
.\" Copyright (c) 2000, 2006 The OpenSSL Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\"    software must display the following acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\"    endorse or promote products derived from this software without
.\"    prior written permission. For written permission, please contact
.\"    openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\"    nor may "OpenSSL" appear in their names without prior written
.\"    permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\"    acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: March 23 2018 $
.Dt RSA_GET_EX_NEW_INDEX 3
.Os
.Sh NAME
.Nm RSA_get_ex_new_index ,
.Nm RSA_set_ex_data ,
.Nm RSA_get_ex_data ,
.Nm CRYPTO_EX_new ,
.Nm CRYPTO_EX_dup ,
.Nm CRYPTO_EX_free
.Nd add application specific data to RSA structures
.Sh SYNOPSIS
.In openssl/rsa.h
.Ft int
.Fo RSA_get_ex_new_index
.Fa "long argl"
.Fa "void *argp"
.Fa "CRYPTO_EX_new *new_func"
.Fa "CRYPTO_EX_dup *dup_func"
.Fa "CRYPTO_EX_free *free_func"
.Fc
.Ft int
.Fo RSA_set_ex_data
.Fa "RSA *r"
.Fa "int idx"
.Fa "void *arg"
.Fc
.Ft void *
.Fo RSA_get_ex_data
.Fa "RSA *r"
.Fa "int idx"
.Fc
.In openssl/crypto.h
.Ft typedef int
.Fo CRYPTO_EX_new
.Fa "void *parent"
.Fa "void *ptr"
.Fa "CRYPTO_EX_DATA *ad"
.Fa "int idx"
.Fa "long argl"
.Fa "void *argp"
.Fc
.Ft typedef void
.Fo CRYPTO_EX_free
.Fa "void *parent"
.Fa "void *ptr"
.Fa "CRYPTO_EX_DATA *ad"
.Fa "int idx"
.Fa "long argl"
.Fa "void *argp"
.Fc
.Ft typedef int
.Fo CRYPTO_EX_dup
.Fa "CRYPTO_EX_DATA *to"
.Fa "CRYPTO_EX_DATA *from"
.Fa "void *from_d"
.Fa "int idx"
.Fa "long argl"
.Fa "void *argp"
.Fc
.Sh 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).
.Pp
Since the application data can be anything at all it is passed and
retrieved as a
.Vt void *
type.
.Pp
The
.Fn 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
.Dv NULL .
The precise manner in which these function pointers are called is
described in more detail below.
.Fn RSA_get_ex_new_index
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 as the
.Fa idx
parameter in the remaining functions.
Each successful call to
.Fn 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.
.Pp
.Fn RSA_set_ex_data
is used to set application specific data.
The data is supplied in the
.Fa arg
parameter and its precise meaning is up to the application.
.Pp
.Fn RSA_get_ex_data
is used to retrieve application specific data.
The data is returned to the application, which will be the same value as
supplied to a previous
.Fn RSA_set_ex_data
call.
.Pp
.Fa new_func
is called when a structure is initially allocated (for example with
.Xr RSA_new 3 .
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.
.Pp
.Fa free_func
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.
.Pp
.Fa new_func
and
.Fa free_func
take the same parameters.
.Fa parent
is a pointer to the parent
.Vt RSA
structure.
.Fa ptr
is the application specific data (this won't be of much use in
.Fa new_func ) .
.Fa ad
is a pointer to the
.Vt CRYPTO_EX_DATA
structure from the parent
.Vt RSA
structure: the functions
.Fn CRYPTO_get_ex_data
and
.Fn CRYPTO_set_ex_data
can be called to manipulate it.
The
.Fa idx
parameter is the index: this will be the same value returned by
.Fn RSA_get_ex_new_index
when the functions were initially registered.
Finally the
.Fa argl
and
.Fa argp
parameters are the values originally passed to the same corresponding
parameters when
.Fn RSA_get_ex_new_index
was called.
.Pp
.Fa dup_func
is called when a structure is being copied.
Pointers to the destination and source
.Vt CRYPTO_EX_DATA
structures are passed in the
.Fa to
and
.Fa from
parameters, respectively.
The
.Fa 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
.Fa from_d
and have different values in the source and destination.
The
.Fa idx ,
.Fa argl ,
and
.Fa argp
parameters are the same as those in
.Fa new_func
and
.Fa free_func .
.Sh RETURN VALUES
.Fn RSA_get_ex_new_index
returns a new index or -1 on failure.
Note that 0 is a valid index value.
.Pp
.Fn RSA_set_ex_data
returns 1 on success or 0 on failure.
.Pp
.Fn RSA_get_ex_data
returns the application data or
.Dv NULL
on failure.
.Dv NULL
may also be valid application data, but currently it can only fail if
given an invalid
.Fa idx
parameter.
.Pp
.Fa new_func
and
.Fa dup_func
should return 0 for failure and 1 for success.
.Pp
On failure an error code can be obtained from
.Xr ERR_get_error 3 .
.Sh SEE ALSO
.Xr BIO_set_ex_data 3 ,
.Xr CRYPTO_set_ex_data 3 ,
.Xr DH_set_ex_data 3 ,
.Xr DSA_set_ex_data 3 ,
.Xr RSA_new 3 ,
.Xr SSL_CTX_set_ex_data 3 ,
.Xr SSL_SESSION_set_ex_data 3 ,
.Xr SSL_set_ex_data 3 ,
.Xr X509_STORE_CTX_set_ex_data 3 ,
.Xr X509_STORE_set_ex_data 3
.Sh HISTORY
These functions first appeared in SSLeay 0.9.0
and have been available since
.Ox 2.4 .
.Sh BUGS
.Fa dup_func
is currently never called.
.Pp
The return value of
.Fa new_func
is ignored.
.Pp
The
.Fa new_func
function isn't very useful because no meaningful values are present in
the parent RSA structure when it is called.