-.\" $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
.\" 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 .
projects / openbsd / commitdiff