Rewrite RSA_get_ex_new_index(3) and CRYPTO_set_ex_data(3) from scratch.

The defects of the old pages were too numerous to list in full but included
vagueness, gaps, misleading statements, bad ordering, and duplication.
Use my Copyright since none of the text we inherited from OpenSSL remains.

Without doing a thorough review, tb@ thinks he likes the new pages
after quickly reading through both of them.

1 files changed, 438 insertions, 240 deletions

diff --git a/src/lib/libcrypto/man/CRYPTO_set_ex_data.3 b/src/lib/libcrypto/man/CRYPTO_set_ex_data.3
index abdef79d87..c22fb22352 100644
--- a/src/lib/libcrypto/man/CRYPTO_set_ex_data.3
+++ b/src/lib/libcrypto/man/CRYPTO_set_ex_data.3
@@ -1,70 +1,32 @@
-.\" $OpenBSD: CRYPTO_set_ex_data.3,v 1.14 2023/07/28 14:34:54 tb Exp $
-.\" full merge up to:
-.\" OpenSSL CRYPTO_get_ex_new_index 9e183d22 Mar 11 08:56:44 2017 -0500
-.\" selective merge up to: 72a7a702 Feb 26 14:05:09 2019 +0000
+.\" $OpenBSD: CRYPTO_set_ex_data.3,v 1.15 2023/09/18 14:49:43 schwarze Exp $
 .\"
-.\" 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.
+.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org>
 .\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
 .\"
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" 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: July 28 2023 $
+.Dd $Mdocdate: September 18 2023 $
 .Dt CRYPTO_SET_EX_DATA 3
 .Os
 .Sh NAME
+.Nm CRYPTO_get_ex_new_index ,
 .Nm CRYPTO_EX_new ,
 .Nm CRYPTO_EX_free ,
 .Nm CRYPTO_EX_dup ,
-.Nm CRYPTO_get_ex_new_index ,
+.Nm CRYPTO_new_ex_data ,
 .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
+.Nm CRYPTO_free_ex_data
+.Nd low-level functions for application specific data
 .Sh SYNOPSIS
 .In openssl/crypto.h
 .Ft int
@@ -79,7 +41,7 @@
 .Ft typedef int
 .Fo CRYPTO_EX_new
 .Fa "void *parent"
-.Fa "void *ptr"
+.Fa "void *data"
 .Fa "CRYPTO_EX_DATA *ad"
 .Fa "int idx"
 .Fa "long argl"
@@ -88,7 +50,7 @@
 .Ft typedef void
 .Fo CRYPTO_EX_free
 .Fa "void *parent"
-.Fa "void *ptr"
+.Fa "void *data"
 .Fa "CRYPTO_EX_DATA *ad"
 .Fa "int idx"
 .Fa "long argl"
@@ -98,7 +60,7 @@
 .Fo CRYPTO_EX_dup
 .Fa "CRYPTO_EX_DATA *to"
 .Fa "const CRYPTO_EX_DATA *from"
-.Fa "void *from_d"
+.Fa "void *datap"
 .Fa "int idx"
 .Fa "long argl"
 .Fa "void *argp"
@@ -106,238 +68,336 @@
 .Ft int
 .Fo CRYPTO_new_ex_data
 .Fa "int class_index"
-.Fa "void *obj"
+.Fa "void *parent"
 .Fa "CRYPTO_EX_DATA *ad"
 .Fc
 .Ft int
 .Fo CRYPTO_set_ex_data
-.Fa "CRYPTO_EX_DATA *r"
+.Fa "CRYPTO_EX_DATA *ad"
 .Fa "int idx"
-.Fa "void *arg"
+.Fa "void *data"
 .Fc
 .Ft void *
 .Fo CRYPTO_get_ex_data
-.Fa "CRYPTO_EX_DATA *r"
+.Fa "CRYPTO_EX_DATA *ad"
 .Fa "int idx"
 .Fc
 .Ft void
 .Fo CRYPTO_free_ex_data
 .Fa "int class_index"
-.Fa "void *obj"
-.Fa "CRYPTO_EX_DATA *r"
+.Fa "void *parent"
+.Fa "CRYPTO_EX_DATA *ad"
 .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
-    EC_KEY
-    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.
+The library implements the functions documented in the
+.Xr RSA_get_ex_new_index 3
+manual page and similar functions for other parent object types
+using the functions documented in the present manual page.
+Application programs almost never need
+to call the functions documented here directly.
 .Pp
-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
+behaves in the same way as
+.Xr RSA_get_ex_new_index 3
+except that the parent object type that the new
+.Fa idx
+is reserved for is not part of the function name
+but instead specified by the additional
 .Fa class_index
-should be one of the
+argument receiving one of the
 .Dv CRYPTO_EX_INDEX_*
-values.
-The
+constants defined in
+.In openssl/crypto.h .
+The recommendation given in
+.Xr RSA_get_ex_new_index 3
+to set the
+.Fa argl
+argument to 0 and the last four arguments all to
+.Dv NULL
+applies.
+The library passes 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 a 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.
+arguments through to the callback functions for the respective
+.Fa idx ,
+but ignores them otherwise.
 .Pp
-When a structure is initially allocated (such as by
-.Xr RSA_new 3 ) ,
-then
+If a function pointer is passed for the
 .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
+argument, that function is called for the returned
+.Fa idx
+whenever a new parent object is allocated with
+.Xr RSA_new 3
+or a similar function.
+.Pp
+If a function pointer is passed for the
 .Fa free_func
-may be called with a
-.Dv NULL
-pointer.
+argument, that function is called for the returned
+.Fa idx
+when a parent object is freed with
+.Xr RSA_free 3
+or a similar function.
 .Pp
-Both
+The arguments of
 .Fa new_func
 and
 .Fa free_func
-take the same parameters.
-The
+are as follows:
+.Pp
+.Bl -tag -width Ds -compact
+.It Fa parent
+the parent object that contains the
+.Fa data
+.It Fa data
+the
+.Fa data
+previously set by
+.Fn CRYPTO_set_ex_data
+at
+.Fa idx
+in
 .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
+.It Fa ad
+the
+.Vt CRYPTO_EX_DATA
+subobject of the
+.Fa parent
+object
+.It Fa idx
+return value of
+.Fn CRYPTO_get_ex_new_index
+that set this callback
+.It Fa argl
+the
+.Fa argl
+passed to
+.Fn CRYPTO_get_ex_new_index
+for this
 .Fa idx
-is the index and is the value returned when the callbacks were initially
-registered via
+.It Fa argp
+the
+.Fa argp
+passed to
 .Fn CRYPTO_get_ex_new_index
-and can be used if the same callback handles different types of exdata.
+for this
+.Fa idx
+.El
 .Pp
-.Fa dup_func
-is called when a structure is being copied.
-This is only done for
-.Vt SSL
+If a function pointer is passed for the
+.Fa dup_func ,
+that function is supposed to be called for the returned
+.Fa idx
+whenever a parent object of the respective type is copied.
+Actually, the only functions doing that are
+.Xr BIO_dup_chain 3 ,
+.Xr EC_KEY_copy 3 ,
 and
+.Xr SSL_dup 3 ,
+and the TLS 1.3 network stack does it internally when duplicating a
 .Vt SSL_SESSION
-objects.
-The
-.Fa to
+object after receiving a new session ticket message.
+Most other object types supporting ex_data do not support
+copying in the first place, whereas
+.Xr DSA_dup_DH 3
 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
+.Xr X509_dup 3
+simply ignore
+.Fa dup_func .
+.Pp
+The arguments of
 .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 ,
+are as follows:
+.Pp
+.Bl -tag -width Ds -compact
+.It Fa to
+the
+.Vt CRYPTO_EX_DATA
+subobject of the new parent object
+.It Fa from
+the
+.Vt CRYPTO_EX_DATA
+subobject of the original parent object
+.It Fa datap
+a pointer to a copy of the pointer to the original ex_data
+.It Fa idx
+return value of
+.Fn CRYPTO_get_ex_new_index
+that set this callback
+.It Fa argl
+the
 .Fa argl
-and
+passed to
+.Fn CRYPTO_get_ex_new_index
+for this
+.Fa idx
+.It Fa argp
+the
 .Fa argp
-parameters are as described for the other two callbacks.
+passed to
+.Fn CRYPTO_get_ex_new_index
+for this
+.Fa idx
+.El
 .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.
+Inside
+.Fa dup_func ,
+the
+.Fa data
+pointer contained in the original parent object being copied
+can be accessed by casting and dereferencing
+.Fa datap ,
+for example:
+.Pp
+.Dl char *orig_data = *(char **)datap;
+.Pp
+If the original data is copied, for example in a manner similar to
+.Bd -literal -offset indent
+char *new_data;
+if ((new_data = strdup(orig_data)) == NULL)
+        return 0;
+.Ed
+.Pp
+then the pointer to the newly allocated memory needs to be passed
+back to the caller in the
+.Fa datap
+argument, for example:
+.Bd -literal -offset indent
+*(char **)datap = new_data;
+return 1;
+.Ed
+.Pp
+Calling
+.Fn CRYPTO_set_ex_data to idx new_data
+from inside
+.Fa dup_func
+has no effect because the code calling
+.Fa dup_func
+unconditionally calls
+.Fn CRYPTO_set_ex_data to idx *datap
+after
+.Fa dup_func
+returns successfully.
+Consequently, if
+.Fa dup_func
+does not change
+.Pf * Fa datap ,
+the new parent object ends up containing a pointer to the same memory
+as the original parent object and any memory allocated in
+.Fa dup_func
+is leaked.
+.Pp
+When multiple callback functions are called,
+they are called in increasing order of their
+.Fa idx
+value.
+.Pp
+.Fn CRYPTO_new_ex_data
+is an internal function that initializes the
+.Fa ad
+subobject of the
+.Fa parent
+object, with the type of the parent object specified by the
+.Fa class_index
+argument.
+Initialization includes calling the respective
+.Fa new_func
+callbacks for all reserved
+.Fa idx
+values that have such callbacks configured.
+Despite its name,
+.Fn CRYPTO_new_ex_data
+does not create a new object but requires that
+.Fa ad
+points to an already allocated but still uninitialized object.
 .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.
+and
+.Fn CRYPTO_get_ex_data
+behave in the same way as
+.Xr RSA_set_ex_data 3
+and
+.Xr RSA_get_ex_data 3 ,
+respectively, except that they do not accept a pointer
+to the parent object but instead require a pointer to the
+.Vt CRYPTO_EX_DATA
+subobject of that parent object.
+.Pp
+.Fn CRYPTO_free_ex_data
+is an internal function that frees any memory used inside the
+.Fa ad
+subobject of the
+.Fa parent
+object, with the type of the parent object specified by the
+.Fa class_index
+argument.
+This includes calling the respective
+.Fa free_func
+callbacks for all reserved
+.Fa idx
+values that have such callbacks configured.
+Despite its name,
+.Fn CRYPTO_free_ex_data
+does not free
+.Fa ad
+itself.
 .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.
+returns a new index equal to or greater than 1
+or \-1 if memory allocation fails.
+.Pp
+.Fn CRYPTO_EX_new
+and
+.Fn CRYPTO_EX_dup
+functions are supposed to return 1 on success or 0 on failure.
 .Pp
+.Fn CRYPTO_new_ex_data
+and
 .Fn CRYPTO_set_ex_data
-returns 1 on success or 0 on failure.
+return 1 on success or 0 if memory allocation fails.
 .Pp
 .Fn CRYPTO_get_ex_data
-returns the application data or
-.Dv NULL
-on failure; note that
+returns the application specific data or
 .Dv NULL
-may be a valid value.
+if the parent object that contains
+.Fa ad
+does not contain application specific data at the given
+.Fa idx .
+.Sh ERRORS
+After failure of
+.Fn CRYPTO_get_ex_new_index ,
+.Fn CRYPTO_new_ex_data ,
+or
+.Fn CRYPTO_set_ex_data ,
+the following diagnostic can be retrieved with
+.Xr ERR_get_error 3 ,
+.Xr ERR_GET_REASON 3 ,
+and
+.Xr ERR_reason_error_string 3 :
+.Bl -tag -width Ds
+.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure"
+Memory allocation failed.
+.El
 .Pp
-.Fa dup_func
-should return 0 for failure and 1 for success.
+In a few unusual failure cases,
+.Xr ERR_get_error 3
+may report different errors caused by
+.Xr OPENSSL_init_crypto 3
+or even none at all.
 .Pp
-On failure an error code can be obtained from
+Even though it cannot indicate failure,
+.Fn CRYPTO_free_ex_data
+may occasionally also set an error code that can be retrieved with
 .Xr ERR_get_error 3 .
+.Pp
+.Fn CRYPTO_get_ex_data
+does not distinguish success from failure.
+Consequently, after
+.Fn CRYPTO_get_ex_data
+returns
+.Dv NULL ,
+.Xr ERR_get_error 3
+returns 0 unless there is still an earlier error in the queue.
 .Sh SEE ALSO
 .Xr BIO_get_ex_new_index 3 ,
 .Xr DH_get_ex_new_index 3 ,
@@ -350,11 +410,11 @@ On failure an error code can be obtained from
 .Xr X509_STORE_get_ex_new_index 3
 .Sh HISTORY
 .Fn CRYPTO_get_ex_new_index ,
+.Fn CRYPTO_new_ex_data ,
 .Fn CRYPTO_set_ex_data ,
 .Fn CRYPTO_get_ex_data ,
-.Fn CRYPTO_free_ex_data ,
 and
-.Fn CRYPTO_new_ex_data
+.Fn CRYPTO_free_ex_data
 first appeared in SSLeay 0.9.0 and have been available since
 .Ox 2.4 .
 .Pp
@@ -364,3 +424,141 @@ and
 .Fn CRYPTO_EX_dup
 first appeared in OpenSSL 0.9.5 and have been available since
 .Ox 2.7 .
+.Sh CAVEATS
+If an program installs callback functions, the last call to
+.Fn CRYPTO_get_ex_new_index
+installing a function of a certain type for a certain
+.Fa class_index
+needs to be complete before the first object of that
+.Fa class_index
+can be created, freed, or copied, respectively.
+Otherwise, incomplete initialization or cleanup will result.
+.Pp
+At the time
+.Fa new_func
+is called, the
+.Fa parent
+object is only partially initialized,
+so trying to access any data in it is strongly discouraged.
+The
+.Fa data
+argument is typically
+.Dv NULL
+in
+.Fa new_func .
+.Pp
+At the time
+.Fa free_func
+is called, the
+.Fa parent
+object is already mostly deconstructed
+and part of its content may have been cleared and freed.
+Consequently, trying to access any data in
+.Fa parent
+is strongly discouraged.
+According to the OpenSSL API documentation, the library code calling
+.Fa free_func
+would even be permitted to pass a
+.Dv NULL
+pointer for the
+.Fa parent
+argument.
+.Pp
+.Fn CRYPTO_set_ex_data
+and
+.Fn CRYPTO_get_ex_data
+cannot reasonably be used outside the callback functions
+because no API function provides access to any pointers of the type
+.Vt CRYPTO_EX_DATA * .
+.Pp
+Inside
+.Fa new_func ,
+calling
+.Fn CRYPTO_get_ex_data
+makes no sense because it always returns
+.Dv NULL ,
+and calling
+.Fn CRYPTO_set_ex_data
+makes no sense because
+.Fa new_func
+does not have access to any meaningful
+.Fa data
+it could store, and the absence of application specific data at any given
+.Fa idx
+is already sufficiently indicated by the default return value
+.Dv NULL
+of
+.Fn CRYPTO_get_ex_data ,
+.Xr RSA_get_ex_data 3 ,
+and similar functions.
+.Pp
+Inside
+.Fa free_func ,
+calling
+.Fn CRYPTO_get_ex_data
+makes no sense because the return value is already available in
+.Fa data ,
+and calling
+.Fn CRYPTO_set_ex_data
+makes no sense because the parent object, including any ex_data
+contained in it, is already being deconstructed and will no longer
+exist by the time application code regains control.
+.Pp
+Inside
+.Fa dup_func ,
+calling
+.Fn CRYPTO_get_ex_data
+makes no sense because the return value for
+.Fa from
+is already available as
+.Pf * Fa datap ,
+and the return value for
+.Fa to
+is
+.Dv NULL .
+Calling
+.Fn CRYPTO_set_ex_data
+makes no sense because changing
+.Fa from
+would cause an undesirable side effect in this context
+and trying to change
+.Fa to
+is ineffective as explained above.
+.Pp
+Consequently, application code can never use
+.Fn CRYPTO_set_ex_data
+or
+.Fn CRYPTO_get_ex_data
+in a meaningful way.
+.Pp
+The fact that the functions documented in the present manual page
+are part of the public API might create the impression
+that application programs could add ex_data support
+to additional object types not offering it by default.
+However, for built-in object types not offering ex_support, this
+is not possible because such objects do not contain the required
+.Vt CRYPTO_EX_DATA
+subobject.
+.Pp
+It is theoretically possible to add ex_data support to an
+application-defined object type by adding a
+.Vt CRYPTO_EX_DATA
+field to the struct declaration, a call to
+.Fn CRYPTO_new_ex_data
+to the object constructor, and a call to
+.Fn CRYPTO_free_ex_data
+to the object destructor.
+The OpenSSL documentation mentions that the constant
+.Dv CRYPTO_EX_INDEX_APP
+is reserved for this very purpose.
+However, doing this would hardly be useful.
+It is much more straightforward to just add
+all the required data fields to the struct declaration itself.
+.Sh BUGS
+If
+.Fa new_func
+or
+.Fa dup_func
+fails, the failure is silently ignored by the library, potentially
+resulting in an incompletely initialized object.
+The application program cannot detect this kind of failure.