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

.\" $OpenBSD: CRYPTO_set_ex_data.3,v 1.10 2018/04/08 01:00:15 schwarze Exp $
.\" full merge up to:
.\" OpenSSL CRYPTO_get_ex_new_index 9e183d22 Mar 11 08:56:44 2017 -0500
.\" selective merge up to: a73d990e Feb 27 19:02:24 2018 +0100
.\"
.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
.\" and by Rich Salz <rsalz@akamai.com>.
.\" Copyright (c) 2000, 2006, 2015, 2016 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: April 8 2018 $
.Dt CRYPTO_SET_EX_DATA 3
.Os
.Sh NAME
.Nm CRYPTO_EX_new ,
.Nm CRYPTO_EX_free ,
.Nm CRYPTO_EX_dup ,
.Nm CRYPTO_get_ex_new_index ,
.Nm CRYPTO_set_ex_data ,
.Nm CRYPTO_get_ex_data ,
.Nm CRYPTO_free_ex_data ,
.Nm CRYPTO_new_ex_data
.Nd functions supporting application-specific data
.Sh SYNOPSIS
.In openssl/crypto.h
.Ft int
.Fo CRYPTO_get_ex_new_index
.Fa "int class_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 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 "const CRYPTO_EX_DATA *from"
.Fa "void *from_d"
.Fa "int idx"
.Fa "long argl"
.Fa "void *argp"
.Fc
.Ft int
.Fo CRYPTO_new_ex_data
.Fa "int class_index"
.Fa "void *obj"
.Fa "CRYPTO_EX_DATA *ad"
.Fc
.Ft int
.Fo CRYPTO_set_ex_data
.Fa "CRYPTO_EX_DATA *r"
.Fa "int idx"
.Fa "void *arg"
.Fc
.Ft void *
.Fo CRYPTO_get_ex_data
.Fa "CRYPTO_EX_DATA *r"
.Fa "int idx"
.Fc
.Ft void
.Fo CRYPTO_free_ex_data
.Fa "int class_index"
.Fa "void *obj"
.Fa "CRYPTO_EX_DATA *r"
.Fc
.Sh DESCRIPTION
Several OpenSSL structures can have application specific data attached
to them, known as "exdata".
The specific structures are:
.Bd -literal
    BIO
    DH
    DSA
    ECDH
    ECDSA
    ENGINE
    RSA
    SSL
    SSL_CTX
    SSL_SESSION
    UI
    X509
    X509_STORE
    X509_STORE_CTX
.Ed
.Pp
Each is identified by a
.Dv CRYPTO_EX_INDEX_*
constant defined in the
.In openssl/crypto.h
header file.
.Pp
The API described here is used by OpenSSL to manipulate exdata for
specific structures.
Since the application data can be anything at all it is passed and
retrieved as a
.Vt void *
type.
.Pp
The
.Vt CRYPTO_EX_DATA
type is opaque.
To initialize the exdata part of a structure, call
.Fn CRYPTO_new_ex_data .
.Pp
Exdata types are identified by an index, an integer guaranteed to
be unique within structures for the lifetime of the program.
Applications using exdata typically call
.Fn CRYPTO_get_ex_new_index
at startup and store the result in a global variable, or write a
wrapper function to provide lazy evaluation.
The
.Fa class_index
should be one of the
.Dv CRYPTO_EX_INDEX_*
values.
The
.Fa argl
and
.Fa argp
parameters are saved to be passed to the callbacks but are otherwise not
used.
In order to transparently manipulate exdata, three callbacks must be
provided.
The semantics of those callbacks are described below.
.Pp
When copying or releasing objects with exdata, the callback functions
are called in increasing order of their index value.
.Pp
To set or get the exdata on an object, the appropriate type-specific
routine must be used.
This is because the containing structure is opaque and the
.Vt CRYPTO_EX_DATA
field is not accessible.
In both APIs, the
.Fa idx
parameter should be an already-created index value.
.Pp
When setting exdata, the pointer specified with a particular index is
saved, and returned on a subsequent "get" call.
If the application is going to release the data, it must make sure to
set a
.Dv NULL
value at the index, to avoid likely double-free crashes.
.Pp
The function
.Fn CRYPTO_free_ex_data
is used to free all exdata attached to a structure.
The appropriate type-specific routine must be used.
The
.Fa class_index
identifies the structure type, the
.Fa obj
is be the pointer to the actual structure, and
.Fa r
is a pointer to the structure's exdata field.
.Pp
The callback functions are used as follows.
.Pp
When a structure is initially allocated (such as by
.Xr RSA_new 3 ) ,
then
.Fa new_func
is called for every defined index.
There is no requirement that the entire parent, or containing, structure
has been set up.
The
.Fa new_func
is typically used only to allocate memory to store the
exdata, and perhaps an "initialized" flag within that memory.
The exdata value should be set by calling
.Fn CRYPTO_set_ex_data .
.Pp
When a structure is free'd (such as by
.Xr SSL_CTX_free 3 ) ,
then the
.Fa free_func
is called for every defined index.
Again, the state of the parent structure is not guaranteed.
The
.Fa free_func
may be called with a
.Dv NULL
pointer.
.Pp
Both
.Fa new_func
and
.Fa free_func
take the same parameters.
The
.Fa parent
is the pointer to the structure that contains the exdata.
The
.Fa ptr
is the current exdata item; for
.Fa new_func
this will typically be
.Dv NULL .
The
.Fa r
parameter is a pointer to the exdata field of the object.
The
.Fa idx
is the index and is the value returned when the callbacks were initially
registered via
.Fn CRYPTO_get_ex_new_index
and can be used if the same callback handles different types of exdata.
.Pp
.Fa dup_func
is called when a structure is being copied.
This is only done for
.Vt SSL
and
.Vt SSL_SESSION
objects.
The
.Fa to
and
.Fa from
parameters are pointers to the destination and source
.Vt CRYPTO_EX_DATA
structures, respectively.
The
.Fa from_d
parameter is a pointer to the source exdata.
When
.Fa dup_func
returns, the value in
.Fa from_d
is copied to the destination ex_data.
If the pointer contained in
.Fa from_d
is not modified by the
.Fa dup_func ,
then both
.Fa to
and
.Fa from
will point to the same data.
The
.Fa idx ,
.Fa argl
and
.Fa argp
parameters are as described for the other two callbacks.
.Pp
.Fn CRYPTO_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 CRYPTO_get_ex_data
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
.Fn CRYPTO_set_ex_data
call.
.Sh RETURN VALUES
.Fn CRYPTO_get_ex_new_index
returns a new index or -1 on failure; the value 0 is reserved for
the legacy "app_data" APIs.
.Pp
.Fn CRYPTO_set_ex_data
returns 1 on success or 0 on failure.
.Pp
.Fn CRYPTO_get_ex_data
returns the application data or
.Dv NULL
on failure; note that
.Dv NULL
may be a valid value.
.Pp
.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_get_ex_new_index 3 ,
.Xr DH_get_ex_new_index 3 ,
.Xr DSA_get_ex_new_index 3 ,
.Xr RSA_get_ex_new_index 3 ,
.Xr X509_STORE_CTX_get_ex_new_index 3
.Sh HISTORY
.Fn CRYPTO_get_ex_new_index ,
.Fn CRYPTO_set_ex_data ,
.Fn CRYPTO_get_ex_data ,
.Fn CRYPTO_free_ex_data ,
and
.Fn CRYPTO_new_ex_data
first appeared in SSLeay 0.9.0 and have been available since
.Ox 2.4 .
.Pp
.Fn CRYPTO_EX_new ,
.Fn CRYPTO_EX_free ,
and
.Fn CRYPTO_EX_dup
first appeared in OpenSSL 0.9.5 and have been available since
.Ox 2.7 .