1.\" $OpenBSD: ENGINE_new.3,v 1.5 2021/03/12 05:18:00 jsg Exp $ 2.\" content checked up to: 3.\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800 4.\" 5.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org> 6.\" 7.\" Permission to use, copy, modify, and distribute this software for any 8.\" purpose with or without fee is hereby granted, provided that the above 9.\" copyright notice and this permission notice appear in all copies. 10.\" 11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18.\" 19.Dd $Mdocdate: March 12 2021 $ 20.Dt ENGINE_NEW 3 21.Os 22.Sh NAME 23.Nm ENGINE_new , 24.Nm ENGINE_up_ref , 25.Nm ENGINE_free , 26.Nm ENGINE_set_destroy_function , 27.Nm ENGINE_get_destroy_function 28.Nd create and destroy ENGINE objects 29.Sh SYNOPSIS 30.In openssl/engine.h 31.Ft ENGINE * 32.Fn ENGINE_new void 33.Ft int 34.Fo ENGINE_up_ref 35.Fa "ENGINE *e" 36.Fc 37.Ft int 38.Fo ENGINE_free 39.Fa "ENGINE *e" 40.Fc 41.Ft typedef int 42.Fo (*ENGINE_GEN_INT_FUNC_PTR) 43.Fa "ENGINE *e" 44.Fc 45.Ft int 46.Fo ENGINE_set_destroy_function 47.Fa "ENGINE *e" 48.Fa "ENGINE_GEN_INT_FUNC_PTR destroy_f" 49.Fc 50.Ft ENGINE_GEN_INT_FUNC_PTR 51.Fo ENGINE_get_destroy_function 52.Fa "const ENGINE *e" 53.Fc 54.Sh DESCRIPTION 55.Vt ENGINE 56objects can be used to provide alternative implementations of 57cryptographic algorithms, to support additional algorithms, to 58support cryptographic hardware, and to switch among alternative 59implementations of algorithms at run time. 60LibreSSL generally avoids engines and prefers providing 61cryptographic functionality in the crypto library itself. 62.Pp 63.Fn ENGINE_new 64allocates and initializes an empty 65.Vt ENGINE 66object and sets its structural reference count to 1 67and its functional reference count to 0. 68For more information about the functional reference count, see the 69.Xr ENGINE_init 3 70manual page. 71.Pp 72Many functions increment the structural reference count by 1 73when successful. 74Some of them, including 75.Xr ENGINE_get_first 3 , 76.Xr ENGINE_get_last 3 , 77.Xr ENGINE_get_next 3 , 78.Xr ENGINE_get_prev 3 , 79and 80.Xr ENGINE_by_id 3 , 81do so because they return a structural reference to the user. 82Other functions, including 83.Xr ENGINE_add 3 , 84.Xr ENGINE_init 3 , 85.Xr ENGINE_get_cipher_engine 3 , 86.Xr ENGINE_get_digest_engine 3 , 87and the 88.Xr ENGINE_get_default_RSA 3 89and 90.Xr ENGINE_set_default 3 91families of functions 92do so when they store a structural reference internally. 93.Pp 94.Fn ENGINE_up_ref 95explicitly increment the structural reference count by 1. 96.Pp 97.Fn ENGINE_free 98decrements the structural reference count by 1, 99and if it reaches 0, the optional 100.Fa destroy_f 101previously installed with 102.Fn ENGINE_set_destroy_function 103is called, if one is installed, and both the memory used internally by 104.Fa e 105and 106.Fa e 107itself are freed. 108If 109.Fa e 110is a 111.Dv NULL 112pointer, no action occurs. 113.Pp 114Many functions internally call the equivalent of 115.Fn ENGINE_free . 116Some of them, including 117.Xr ENGINE_get_next 3 118and 119.Xr ENGINE_get_prev 3 , 120thus invalidate the structural reference passed in by the user. 121Other functions, including 122.Xr ENGINE_finish 3 , 123.Xr ENGINE_remove 3 , 124and the 125.Xr ENGINE_set_default 3 126family of functions 127do so when an internally stored structural reference is no longer needed. 128.Pp 129.Fn ENGINE_set_destroy_function 130installs a callback function that will be called by 131.Fn ENGINE_free , 132but only when 133.Fa e 134actually gets destroyed, 135not when only its reference count gets decremented. 136The value returned from the 137.Fa destroy_f 138will be ignored. 139.Sh RETURN VALUES 140.Fn ENGINE_new 141returns a structural reference to the new 142.Vt ENGINE 143object or 144.Dv NULL 145if an error occurs. 146.Pp 147.Fn ENGINE_up_ref 148returns 0 if 149.Fa e 150is 151.Dv NULL 152and 1 otherwise. 153.Pp 154.Fn ENGINE_free 155and 156.Fn ENGINE_set_destroy_function 157always return 1. 158.Pp 159.Fn ENGINE_get_destroy_function 160returns a function pointer to the callback, or 161.Dv NULL 162if none is installed. 163.Sh SEE ALSO 164.Xr crypto 3 , 165.Xr ENGINE_add 3 , 166.Xr ENGINE_ctrl 3 , 167.Xr ENGINE_get_default_RSA 3 , 168.Xr ENGINE_init 3 , 169.Xr ENGINE_register_all_RSA 3 , 170.Xr ENGINE_register_RSA 3 , 171.Xr ENGINE_set_default 3 , 172.Xr ENGINE_set_flags 3 , 173.Xr ENGINE_set_RSA 3 , 174.Xr ENGINE_unregister_RSA 3 175.Sh HISTORY 176.Fn ENGINE_new 177and 178.Fn ENGINE_free 179first appeared in OpenSSL 0.9.7 and have been available since 180.Ox 2.9 . 181.Pp 182.Fn ENGINE_set_destroy_function 183and 184.Fn ENGINE_get_destroy_function 185first appeared in OpenSSL 0.9.7 and have been available since 186.Ox 3.2 . 187.Pp 188.Fn ENGINE_up_ref 189first appeared in OpenSSL 0.9.7 and has been available since 190.Ox 3.4 . 191