1 files changed, 0 insertions, 382 deletions

diff --git a/src/lib/libcrypto/man/RSA_get_ex_new_index.3 b/src/lib/libcrypto/man/RSA_get_ex_new_index.3
deleted file mode 100644
index 5f1fb4335f..0000000000
--- a/src/lib/libcrypto/man/RSA_get_ex_new_index.3
+++ /dev/null
@@ -1,382 +0,0 @@
-.\" $OpenBSD: RSA_get_ex_new_index.3,v 1.13 2023/11/19 21:08:04 tb Exp $
-.\"
-.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org>
-.\"
-.\" 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.
-.\"
-.\" 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.
-.\"
-.Dd $Mdocdate: November 19 2023 $
-.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
-.Nd add application specific data to RSA objects
-.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 *rsa"
-.Fa "int idx"
-.Fa "void *data"
-.Fc
-.Ft void *
-.Fo RSA_get_ex_data
-.Fa "RSA *rsa"
-.Fa "int idx"
-.Fc
-.Sh DESCRIPTION
-The following parent objects can have application specific data called
-.Dq ex_data
-attached to them:
-.Vt BIO , DH , DSA , EC_KEY , RSA ,
-.Vt SSL , SSL_CTX , SSL_SESSION , UI , X509 , X509_STORE ,
-and
-.Vt X509_STORE_CTX .
-.\" CRYPTO_EX_INDEX_APP and CRYPTO_EX_INDEX_UI_METHOD are unused.
-The present manual page documents the related API functions taking the
-.Vt RSA
-object type as an example.
-The functions for the other object types work in exactly the same way:
-just replace the string
-.Qq RSA
-with the name of the respective object type
-throughout the rest of this manual page.
-.Pp
-By default, each individual
-.Vt RSA
-object can store one
-.Vt void *
-pointing to application specific data.
-That specific pointer is identified by an
-.Fa idx
-argument of 0.
-.Pp
-.Fn RSA_get_ex_new_index
-reserves the next consecutive
-.Fa idx
-argument, enabling storage of one additional
-.Vt void *
-per
-.Vt RSA
-object.
-It is typically called at program startup.
-It can be called more than once if some
-.Vt RSA
-objects need to store more than two application specific pointers.
-Reserving an additional index for one parent object type, for example for
-.Vt RSA ,
-does not change the numbers of indices that can be used
-with any other parent object type.
-.Pp
-It is strongly recommended to always pass three
-.Dv NULL
-pointers for the arguments
-.Fa new_func ,
-.Fa dup_func ,
-and
-.Fa free_func .
-When following this recommendation, the arguments
-.Fa argl
-and
-.Fa argp
-are ignored; conventionally, passing 0 and
-.Dv NULL
-is recommended.
-Because using them is discouraged, the three function callback types
-are only documented in the low-level
-.Xr CRYPTO_EX_new 3
-manual page.
-.Pp
-.Fn RSA_set_ex_data
-stores the
-.Fa data
-pointer as application specific data at the given
-.Fa idx
-in the given
-.Fa rsa
-object.
-The meaning of the data pointed to is up to the application.
-The caller retains ownership of the
-.Fa data
-and is responsible for freeing it when neither the caller nor the
-.Fa rsa
-object need it any longer.
-Any other pointer that was previously stored at the same
-.Fa idx
-in the same
-.Fa rsa
-object is silently overwritten.
-Passing a
-.Dv NULL
-pointer for the
-.Fa data
-argument is valid and indicates that no application specific data
-currently needs to be stored at the given
-.Fa idx .
-.Pp
-.Fn RSA_get_ex_data
-retrieves the last pointer that was stored using
-.Fn RSA_set_ex_data
-at the given
-.Fa idx
-in the given
-.Fa rsa
-object.
-.Sh RETURN VALUES
-.Fn RSA_get_ex_new_index
-returns a new index equal to or greater than 1
-or \-1 if memory allocation fails.
-.Pp
-.Fn RSA_set_ex_data
-returns 1 on success or 0 if memory allocation fails.
-.Pp
-.Fn RSA_get_ex_data
-returns the application specific data or
-.Dv NULL
-if
-.Fa rsa
-does not contain application specific data at the given
-.Fa idx .
-.Sh ERRORS
-After failure of
-.Fn RSA_get_ex_new_index
-or
-.Fn RSA_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
-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
-.Fn RSA_get_ex_data
-does not distinguish success from failure.
-Consequently, after
-.Fn RSA_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_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 CAVEATS
-A relatively small minority of application programs
-attempt to change the API contract such that
-.Fn RSA_set_ex_data
-transfers ownership of the
-.Fa data
-to the
-.Fa rsa
-object.
-They do this by providing a
-.Fa free_func
-that calls
-.Xr free 3
-or higher-level
-.Fn *_free
-functions on the
-.Fa data
-and sometimes also attempt additional cleanup work as a side effect.
-.Pp
-This practice is discouraged for several reasons:
-.Bl -enum
-.It
-Due to a massive design mistake in the low-level API function
-.Xr CRYPTO_free_ex_data 3 ,
-this practice creates a possibility that
-.Xr RSA_free 3
-may fail due to memory allocation failure, consequently leaking the
-memory containing the application specific data and silently skipping
-any additional cleanup work the
-.Fa free_func
-was supposed to do, leaving the application in an undetectably
-inconsistent state.
-Arguably, leaking additional memory while trying to free some
-is most unfortunate especially when the program
-is already starved for memory.
-.It
-This practice introduces a risk of use-after-free and double-free
-bugs in case the
-.Fa rsa
-object gets destructed while a caller of
-.Fn RSA_set_ex_data
-or
-.Fn RSA_get_ex_data
-still holds a
-.Fa data
-pointer.
-No such risk exists when no
-.Fa free_func
-is installed.
-.It
-Attempting additional cleanup work in
-.Fa free_func
-is an even worse idea because
-.Fa free_func
-is unable to report any issues it might detect while doing that work.
-Instead, if any additional cleanup work is needed, it is recommended
-that the calling code takes care of that before calling
-.Xr RSA_free 3 .
-.El
-.Pp
-Even fewer application programs install a
-.Fa new_func
-that allocates memory and stores a pointer to it in the
-.Fa rsa
-object by calling
-.Xr CRYPTO_set_ex_data 3 .
-That is useless because
-.Fa new_func
-does not have access to any useful information it could store in such memory
-and because the default return value of
-.Dv NULL
-from
-.Fn RSA_get_ex_data
-is sufficient to indicate
-that no application specific data has been stored yet.
-In addition, allocating memory in
-.Fa new_func
-is also inadvisable because it introduces an additional responsibility
-for callers of
-.Fn RSA_set_ex_data
-to always call
-.Fn RSA_get_ex_data
-first, even when it is the first time the application wants to set
-application specific data in a particular
-.Fa rsa
-object, and to either modify whatever
-.Fn RSA_get_ex_data
-returns or to free it before calling
-.Fn RSA_set_ex_data .
-If that is forgotten, a memory leak results.
-.Pp
-Consequently, allocating any required memory
-is better left to the application code that calls
-.Fn RSA_set_ex_data .
-.Pp
-Installing a
-.Fa dup_func
-is often seen in combination with installing a
-.Fa free_func ,
-for obvious reasons.
-It is rarely useful because for most parent object types
-that support ex_data, including for
-.Vt RSA ,
-the library does not provide a copying API function in the first place, and
-even where copying functions exist, they tend to be fragile and error-prone.
-When a new object is needed, it is usually advisable to construct it from
-scratch whenever possible, rather than attempting a copy operation.
-.Pp
-On top of that, if
-.Fa dup_func
-fails, for example because of a memory allocation failure, the
-failure is neither reported nor detectable in any way, leaving the
-new parent object with incomplete data and potentially in an
-inconsistent state.
-.Sh BUGS
-If
-.Fn RSA_set_ex_data
-fails, recovery is very difficult.
-In particular, calling
-.Xr RSA_free 3
-on the parent
-.Fa rsa
-object right afterwards is likely to also hit a memory allocation
-failure, leaking all memory internally allocated by all earlier calls of
-.Fn RSA_set_ex_data
-on
-.Fa rsa
-rather than freeing that memory.
-In order to recover, the application program
-would have to free a sufficient amount of
-.Em other
-memory before calling
-.Xr RSA_free 3 ,
-which will rarely be feasible.
-Consequently, after a failure of
-.Fn RSA_set_ex_data ,
-terminating the program is likely the only reasonable option.
-.Pp
-If
-.Fn RSA_set_ex_data
-is called with an
-.Fa idx
-argument greater than the last one previously returned from
-.Fn RSA_get_ex_new_index ,
-it may still succeed, and though that is not guaranteed by the API,
-retrieving the
-.Fa data
-from such a bogus
-.Fa idx
-may even be possible with
-.Fn RSA_get_ex_data ,
-hiding the bug in the application program that caused passing the bogus
-.Fa idx
-to
-.Fn RSA_set_ex_data
-in the first place.
-.Pp
-If the bogus
-.Fa idx
-argument is large,
-.Fn RSA_set_ex_data
-may uselessly allocate a large amount of memory.
-Calling
-.Xr RSA_free 3
-on the parent
-.Fa rsa
-object is the only way to recover that memory.
-.Pp
-If the bogus
-.Fa idx
-argument is very large,
-.Fn RSA_set_ex_data
-is likely to cause a significant delay before eventually failing
-due to memory exhaustion.
-It is likely to return without releasing the memory already
-allocated, causing any subsequent attempt to allocate memory
-for other purposes to fail, too.
-In this situation, what was said above about failure of
-.Fn RSA_set_ex_data
-applies, so terminating the program is likely the only reasonable option.