summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/ENGINE_new.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/ENGINE_new.3')
-rw-r--r--src/lib/libcrypto/man/ENGINE_new.3190
1 files changed, 0 insertions, 190 deletions
diff --git a/src/lib/libcrypto/man/ENGINE_new.3 b/src/lib/libcrypto/man/ENGINE_new.3
deleted file mode 100644
index eaab08d1f9..0000000000
--- a/src/lib/libcrypto/man/ENGINE_new.3
+++ /dev/null
@@ -1,190 +0,0 @@
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 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-02-13 22:41:30 +0000