From 98c78a164de61419afd84a699e8695cecbf49866 Mon Sep 17 00:00:00 2001 From: tb Date: Sun, 19 Nov 2023 10:19:54 +0000 Subject: [PATCH] Document the remaining ENGINE stubs in a single manual --- lib/libcrypto/man/ENGINE_new.3 | 249 ++++++++++++++------------------- 1 file 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 .\" Copyright (c) 2018 Ingo Schwarze .\" .\" 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 . -- 2.20.1