203 lines
9.4 KiB
HTML
203 lines
9.4 KiB
HTML
|
<?xml version="1.0" ?>
|
||
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
<head>
|
||
|
<title>CRYPTO_get_ex_new_index</title>
|
||
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||
|
<link rev="made" href="mailto:root@localhost" />
|
||
|
</head>
|
||
|
|
||
|
<body style="background-color: white">
|
||
|
|
||
|
|
||
|
<!-- INDEX BEGIN -->
|
||
|
<div name="index">
|
||
|
<p><a name="__index__"></a></p>
|
||
|
|
||
|
<ul>
|
||
|
|
||
|
<li><a href="#name">NAME</a></li>
|
||
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
||
|
<li><a href="#description">DESCRIPTION</a></li>
|
||
|
<ul>
|
||
|
|
||
|
<li><a href="#callback_functions">Callback Functions</a></li>
|
||
|
</ul>
|
||
|
|
||
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
||
|
<li><a href="#history">HISTORY</a></li>
|
||
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
||
|
</ul>
|
||
|
|
||
|
<hr name="index" />
|
||
|
</div>
|
||
|
<!-- INDEX END -->
|
||
|
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="name">NAME</a></h1>
|
||
|
<p>CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup,
|
||
|
CRYPTO_free_ex_index, CRYPTO_get_ex_new_index,
|
||
|
CRYPTO_alloc_ex_data, CRYPTO_set_ex_data, CRYPTO_get_ex_data,
|
||
|
CRYPTO_free_ex_data, CRYPTO_new_ex_data
|
||
|
- functions supporting application-specific data</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
||
|
<pre>
|
||
|
#include <openssl/crypto.h></pre>
|
||
|
<pre>
|
||
|
int CRYPTO_get_ex_new_index(int class_index,
|
||
|
long argl, void *argp,
|
||
|
CRYPTO_EX_new *new_func,
|
||
|
CRYPTO_EX_dup *dup_func,
|
||
|
CRYPTO_EX_free *free_func);</pre>
|
||
|
<pre>
|
||
|
typedef void 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, const CRYPTO_EX_DATA *from,
|
||
|
void *from_d, int idx, long argl, void *argp);</pre>
|
||
|
<pre>
|
||
|
int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad)</pre>
|
||
|
<pre>
|
||
|
int CRYPTO_alloc_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad,
|
||
|
int idx);</pre>
|
||
|
<pre>
|
||
|
int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);</pre>
|
||
|
<pre>
|
||
|
void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);</pre>
|
||
|
<pre>
|
||
|
void CRYPTO_free_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *r);</pre>
|
||
|
<pre>
|
||
|
int CRYPTO_free_ex_index(int class_index, int idx);</pre>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="description">DESCRIPTION</a></h1>
|
||
|
<p>Several OpenSSL structures can have application-specific data attached to them,
|
||
|
known as "exdata."
|
||
|
The specific structures are:</p>
|
||
|
<pre>
|
||
|
BIO
|
||
|
DH
|
||
|
DSA
|
||
|
EC_KEY
|
||
|
ENGINE
|
||
|
RAND_DRBG
|
||
|
RSA
|
||
|
SSL
|
||
|
SSL_CTX
|
||
|
SSL_SESSION
|
||
|
UI
|
||
|
UI_METHOD
|
||
|
X509
|
||
|
X509_STORE
|
||
|
X509_STORE_CTX</pre>
|
||
|
<p>In addition, the <strong>APP</strong> name is reserved for use by application code.</p>
|
||
|
<p>Each is identified by an <strong>CRYPTO_EX_INDEX_xxx</strong> define in the <strong>crypto.h</strong>
|
||
|
header file. In addition, <strong>CRYPTO_EX_INDEX_APP</strong> is reserved for
|
||
|
applications to use this facility for their own structures.</p>
|
||
|
<p>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 <strong>void *</strong> type.</p>
|
||
|
<p>The <strong>CRYPTO_EX_DATA</strong> type is opaque. To initialize the exdata part of
|
||
|
a structure, call <code>CRYPTO_new_ex_data()</code>. This is only necessary for
|
||
|
<strong>CRYPTO_EX_INDEX_APP</strong> objects.</p>
|
||
|
<p>Exdata types are identified by an <strong>index</strong>, an integer guaranteed to be
|
||
|
unique within structures for the lifetime of the program. Applications
|
||
|
using exdata typically call <strong>CRYPTO_get_ex_new_index</strong> at startup, and
|
||
|
store the result in a global variable, or write a wrapper function to
|
||
|
provide lazy evaluation. The <strong>class_index</strong> should be one of the
|
||
|
<strong>CRYPTO_EX_INDEX_xxx</strong> values. The <strong>argl</strong> and <strong>argp</strong> 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.</p>
|
||
|
<p>When copying or releasing objects with exdata, the callback functions
|
||
|
are called in increasing order of their <strong>index</strong> value.</p>
|
||
|
<p>If a dynamic library can be unloaded, it should call <code>CRYPTO_free_ex_index()</code>
|
||
|
when this is done.
|
||
|
This will replace the callbacks with no-ops
|
||
|
so that applications don't crash. Any existing exdata will be leaked.</p>
|
||
|
<p>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 <strong>CRYPTO_EX_DATA</strong> field is not accessible. In both API's, the
|
||
|
<strong>idx</strong> parameter should be an already-created index value.</p>
|
||
|
<p>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 <strong>NULL</strong> value at the index,
|
||
|
to avoid likely double-free crashes.</p>
|
||
|
<p>The function <strong>CRYPTO_free_ex_data</strong> is used to free all exdata attached
|
||
|
to a structure. The appropriate type-specific routine must be used.
|
||
|
The <strong>class_index</strong> identifies the structure type, the <strong>obj</strong> is
|
||
|
a pointer to the actual structure, and <strong>r</strong> is a pointer to the
|
||
|
structure's exdata field.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<h2><a name="callback_functions">Callback Functions</a></h2>
|
||
|
<p>This section describes how the callback functions are used. Applications
|
||
|
that are defining their own exdata using <strong>CYPRTO_EX_INDEX_APP</strong> must
|
||
|
call them as described here.</p>
|
||
|
<p>When a structure is initially allocated (such as RSA_new()) then the
|
||
|
<code>new_func()</code> is called for every defined index. There is no requirement
|
||
|
that the entire parent, or containing, structure has been set up.
|
||
|
The <code>new_func()</code> is typically used only to allocate memory to store the
|
||
|
exdata, and perhaps an "initialized" flag within that memory.
|
||
|
The exdata value may be allocated later on with <code>CRYPTO_alloc_ex_data()</code>,
|
||
|
or may be set by calling <code>CRYPTO_set_ex_data()</code>.</p>
|
||
|
<p>When a structure is free'd (such as SSL_CTX_free()) then the
|
||
|
<code>free_func()</code> is called for every defined index. Again, the state of the
|
||
|
parent structure is not guaranteed. The <code>free_func()</code> may be called with a
|
||
|
NULL pointer.</p>
|
||
|
<p>Both <code>new_func()</code> and <code>free_func()</code> take the same parameters.
|
||
|
The <strong>parent</strong> is the pointer to the structure that contains the exdata.
|
||
|
The <strong>ptr</strong> is the current exdata item; for <code>new_func()</code> this will typically
|
||
|
be NULL. The <strong>r</strong> parameter is a pointer to the exdata field of the object.
|
||
|
The <strong>idx</strong> is the index and is the value returned when the callbacks were
|
||
|
initially registered via <code>CRYPTO_get_ex_new_index()</code> and can be used if
|
||
|
the same callback handles different types of exdata.</p>
|
||
|
<p><code>dup_func()</code> is called when a structure is being copied. This is only done
|
||
|
for <strong>SSL</strong>, <strong>SSL_SESSION</strong>, <strong>EC_KEY</strong> objects and <strong>BIO</strong> chains via
|
||
|
<code>BIO_dup_chain()</code>. The <strong>to</strong> and <strong>from</strong> parameters
|
||
|
are pointers to the destination and source <strong>CRYPTO_EX_DATA</strong> structures,
|
||
|
respectively. The <strong>from_d</strong> parameter needs to be cast to a <strong>void **pptr</strong>
|
||
|
as the API has currently the wrong signature; that will be changed in a
|
||
|
future version. The <strong>*pptr</strong> is a pointer to the source exdata.
|
||
|
When the <code>dup_func()</code> returns, the value in <strong>*pptr</strong> is copied to the
|
||
|
destination ex_data. If the pointer contained in <strong>*pptr</strong> is not modified
|
||
|
by the <code>dup_func()</code>, then both <strong>to</strong> and <strong>from</strong> will point to the same data.
|
||
|
The <strong>idx</strong>, <strong>argl</strong> and <strong>argp</strong> parameters are as described for the other
|
||
|
two callbacks. If the <code>dup_func()</code> returns <strong>0</strong> the whole <code>CRYPTO_dup_ex_data()</code>
|
||
|
will fail.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
||
|
<p><code>CRYPTO_get_ex_new_index()</code> returns a new index or -1 on failure.</p>
|
||
|
<p><code>CRYPTO_free_ex_index()</code>, <code>CRYPTO_alloc_ex_data()</code> and <code>CRYPTO_set_ex_data()</code>
|
||
|
return 1 on success or 0 on failure.</p>
|
||
|
<p><code>CRYPTO_get_ex_data()</code> returns the application data or NULL on failure;
|
||
|
note that NULL may be a valid value.</p>
|
||
|
<p><code>dup_func()</code> should return 0 for failure and 1 for success.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="history">HISTORY</a></h1>
|
||
|
<p><code>CRYPTO_alloc_ex_data()</code> was added in OpenSSL 3.0.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
||
|
<p>Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.</p>
|
||
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
||
|
this file except in compliance with the License. You can obtain a copy
|
||
|
in the file LICENSE in the source distribution or at
|
||
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
||
|
|
||
|
</body>
|
||
|
|
||
|
</html>
|