Document the remaining ENGINE stubs in a single manual

1 files changed, 103 insertions, 146 deletions

diff --git a/lib/libcrypto/man/ENGINE_new.3 b/lib/libcrypto/man/ENGINE_new.3
index eaab08d1f91..0081b8a0aad 100644
--- a/lib/libcrypto/man/ENGINE_new.3
+++ b/lib/libcrypto/man/ENGINE_new.3
@@ -1,7 +1,6 @@
-.\" $OpenBSD: ENGINE_new.3,v 1.5 2021/03/12 05:18:00 jsg Exp $
-.\" content checked up to:
-.\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
+.\" $OpenBSD: ENGINE_new.3,v 1.6 2023/11/19 10:19:54 tb Exp $
 .\"
+.\" Copyright (c) 2023 Theo Buehler <tb@openbsd.org>
 .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
@@ -16,175 +15,133 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: March 12 2021 $
+.Dd $Mdocdate: November 19 2023 $
 .Dt ENGINE_NEW 3
 .Os
 .Sh NAME
 .Nm ENGINE_new ,
-.Nm ENGINE_up_ref ,
 .Nm ENGINE_free ,
-.Nm ENGINE_set_destroy_function ,
-.Nm ENGINE_get_destroy_function
-.Nd create and destroy ENGINE objects
+.Nm ENGINE_init ,
+.Nm ENGINE_finish ,
+.Nm ENGINE_by_id ,
+.Nm ENGINE_get_id ,
+.Nm ENGINE_get_name ,
+.Nm ENGINE_set_default ,
+.Nm ENGINE_get_default_RSA ,
+.Nm ENGINE_set_default_RSA ,
+.Nm ENGINE_load_private_key ,
+.Nm ENGINE_load_public_key ,
+.Nm ENGINE_load_builtin_engines ,
+.Nm ENGINE_load_dynamic ,
+.Nm ENGINE_load_openssl ,
+.Nm ENGINE_register_all_complete
+.Nd ENGINE stub functions
 .Sh SYNOPSIS
 .In openssl/engine.h
 .Ft ENGINE *
 .Fn ENGINE_new void
 .Ft int
-.Fo ENGINE_up_ref
-.Fa "ENGINE *e"
-.Fc
-.Ft int
 .Fo ENGINE_free
-.Fa "ENGINE *e"
-.Fc
-.Ft typedef int
-.Fo (*ENGINE_GEN_INT_FUNC_PTR)
-.Fa "ENGINE *e"
+.Fa "ENGINE *engine"
 .Fc
 .Ft int
-.Fo ENGINE_set_destroy_function
-.Fa "ENGINE *e"
-.Fa "ENGINE_GEN_INT_FUNC_PTR destroy_f"
+.Fn ENGINE_init "ENGINE *engine"
+.Ft int
+.Fn ENGINE_finish "ENGINE *engine"
+.Ft ENGINE *
+.Fn ENGINE_by_id "const char *id"
+.Ft const char *
+.Fn ENGINE_get_id "const ENGINE *engine"
+.Ft const char *
+.Fn ENGINE_get_name "const ENGINE *engine"
+.Ft int
+.Fn ENGINE_set_default "ENGINE *engine" "unsigned int flags"
+.Ft ENGINE *
+.Fn ENGINE_get_default_RSA "ENGINE *engine"
+.Ft int
+.Fn ENGINE_set_default_RSA "ENGINE *engine"
+.Ft EVP_PKEY *
+.Fo ENGINE_load_private_key
+.Fa "ENGINE *engine"
+.Fa "const char *key_id"
+.Fa "UI_METHOD *ui_method"
+.Fa "void *callback_data"
 .Fc
-.Ft ENGINE_GEN_INT_FUNC_PTR
-.Fo ENGINE_get_destroy_function
-.Fa "const ENGINE *e"
+.Ft EVP_PKEY *
+.Fo ENGINE_load_public_key
+.Fa "ENGINE *engine"
+.Fa "const char *key_id"
+.Fa "UI_METHOD *ui_method"
+.Fa "void *callback_data"
 .Fc
+.Ft void
+.Fn ENGINE_load_builtin_engines "void"
+.Ft void
+.Fn ENGINE_load_dynamic "void"
+.Ft void
+.Fn ENGINE_load_openssl "void"
+.Ft int
+.Fn ENGINE_register_all_complete "void"
 .Sh DESCRIPTION
 .Vt ENGINE
-objects can be used to provide alternative implementations of
-cryptographic algorithms, to support additional algorithms, to
-support cryptographic hardware, and to switch among alternative
-implementations of algorithms at run time.
-LibreSSL generally avoids engines and prefers providing
-cryptographic functionality in the crypto library itself.
-.Pp
-.Fn ENGINE_new
-allocates and initializes an empty
-.Vt ENGINE
-object and sets its structural reference count to 1
-and its functional reference count to 0.
-For more information about the functional reference count, see the
-.Xr ENGINE_init 3
-manual page.
-.Pp
-Many functions increment the structural reference count by 1
-when successful.
-Some of them, including
-.Xr ENGINE_get_first 3 ,
-.Xr ENGINE_get_last 3 ,
-.Xr ENGINE_get_next 3 ,
-.Xr ENGINE_get_prev 3 ,
-and
-.Xr ENGINE_by_id 3 ,
-do so because they return a structural reference to the user.
-Other functions, including
-.Xr ENGINE_add 3 ,
-.Xr ENGINE_init 3 ,
-.Xr ENGINE_get_cipher_engine 3 ,
-.Xr ENGINE_get_digest_engine 3 ,
-and the
-.Xr ENGINE_get_default_RSA 3
-and
-.Xr ENGINE_set_default 3
-families of functions
-do so when they store a structural reference internally.
-.Pp
-.Fn ENGINE_up_ref
-explicitly increment the structural reference count by 1.
-.Pp
-.Fn ENGINE_free
-decrements the structural reference count by 1,
-and if it reaches 0, the optional
-.Fa destroy_f
-previously installed with
-.Fn ENGINE_set_destroy_function
-is called, if one is installed, and both the memory used internally by
-.Fa e
-and
-.Fa e
-itself are freed.
-If
-.Fa e
-is a
-.Dv NULL
-pointer, no action occurs.
+objects used to provide alternative implementations of
+cryptographic algorithms, for example using specialized hardware.
+LibreSSL no longer supports this feature.
 .Pp
-Many functions internally call the equivalent of
-.Fn ENGINE_free .
-Some of them, including
-.Xr ENGINE_get_next 3
+All functions in this manual ignore all their arguments and
+do nothing except return failure if possible.
+They are provided only to avoid patching software that expects
+ENGINE support to be available.
+.Sh RETURN VALUES
+.Fn ENGINE_new ,
+.Fn ENGINE_by_id ,
+.Fn ENGINE_get_default_RSA ,
+.Fn ENGINE_load_private_key ,
 and
-.Xr ENGINE_get_prev 3 ,
-thus invalidate the structural reference passed in by the user.
-Other functions, including
-.Xr ENGINE_finish 3 ,
-.Xr ENGINE_remove 3 ,
-and the
-.Xr ENGINE_set_default 3
-family of functions
-do so when an internally stored structural reference is no longer needed.
+.Fn ENGINE_load_public_key ,
+always return
+.Dv NULL .
 .Pp
-.Fn ENGINE_set_destroy_function
-installs a callback function that will be called by
 .Fn ENGINE_free ,
-but only when
-.Fa e
-actually gets destroyed,
-not when only its reference count gets decremented.
-The value returned from the
-.Fa destroy_f
-will be ignored.
-.Sh RETURN VALUES
-.Fn ENGINE_new
-returns a structural reference to the new
-.Vt ENGINE
-object or
-.Dv NULL
-if an error occurs.
-.Pp
-.Fn ENGINE_up_ref
-returns 0 if
-.Fa e
-is
-.Dv NULL
-and 1 otherwise.
-.Pp
-.Fn ENGINE_free
+.Fn ENGINE_init ,
+.Fn ENGINE_finish ,
+.Fn ENGINE_set_default ,
+.Fn ENGINE_set_default_RSA ,
 and
-.Fn ENGINE_set_destroy_function
-always return 1.
+.Fn ENGINE_register_all_complete
+always return 0.
 .Pp
-.Fn ENGINE_get_destroy_function
-returns a function pointer to the callback, or
-.Dv NULL
-if none is installed.
+.Fn ENGINE_get_id
+and
+.Fn ENGINE_get_name
+always return the constant empty string.
 .Sh SEE ALSO
-.Xr crypto 3 ,
-.Xr ENGINE_add 3 ,
-.Xr ENGINE_ctrl 3 ,
-.Xr ENGINE_get_default_RSA 3 ,
-.Xr ENGINE_init 3 ,
-.Xr ENGINE_register_all_RSA 3 ,
-.Xr ENGINE_register_RSA 3 ,
-.Xr ENGINE_set_default 3 ,
-.Xr ENGINE_set_flags 3 ,
-.Xr ENGINE_set_RSA 3 ,
-.Xr ENGINE_unregister_RSA 3
+.Xr crypto 3
 .Sh HISTORY
-.Fn ENGINE_new
+.Fn ENGINE_new ,
+.Fn ENGINE_free ,
+.Fn ENGINE_init ,
+.Fn ENGINE_finish ,
+.Fn ENGINE_by_id ,
+.Fn ENGINE_get_id ,
+.Fn ENGINE_get_name ,
+.Fn ENGINE_set_default ,
+.Fn ENGINE_get_default_RSA ,
+.Fn ENGINE_set_default_RSA ,
+.Fn ENGINE_load_private_key ,
 and
-.Fn ENGINE_free
-first appeared in OpenSSL 0.9.7 and have been available since
-.Ox 2.9 .
+.Fn ENGINE_load_public_key
+first appeared in OpenSSL 0.9.7
+and have been available since
+.Ox 2.9
 .Pp
-.Fn ENGINE_set_destroy_function
+.Fn ENGINE_load_builtin_engines ,
+.Fn ENGINE_load_openssl ,
 and
-.Fn ENGINE_get_destroy_function
-first appeared in OpenSSL 0.9.7 and have been available since
-.Ox 3.2 .
-.Pp
-.Fn ENGINE_up_ref
-first appeared in OpenSSL 0.9.7 and has been available since
+.Fn ENGINE_register_all_complete
+first appeared in OpenSSL 0.9.7
+and have been available since
 .Ox 3.4 .
+.Pp
+All these functions were turned into stubs in
+.Ox 7.4 .