summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/ENGINE_ctrl.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/ENGINE_ctrl.3')
-rw-r--r--src/lib/libcrypto/man/ENGINE_ctrl.3428
1 files changed, 428 insertions, 0 deletions
diff --git a/src/lib/libcrypto/man/ENGINE_ctrl.3 b/src/lib/libcrypto/man/ENGINE_ctrl.3
new file mode 100644
index 0000000000..1672f2976e
--- /dev/null
+++ b/src/lib/libcrypto/man/ENGINE_ctrl.3
@@ -0,0 +1,428 @@
1.\" $OpenBSD: ENGINE_ctrl.3,v 1.1 2018/04/15 01:43:45 schwarze 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: April 15 2018 $
20.Dt ENGINE_CTRL 3
21.Os
22.Sh NAME
23.Nm ENGINE_ctrl ,
24.Nm ENGINE_cmd_is_executable ,
25.Nm ENGINE_ctrl_cmd ,
26.Nm ENGINE_ctrl_cmd_string ,
27.Nm ENGINE_set_ctrl_function ,
28.Nm ENGINE_get_ctrl_function ,
29.Nm ENGINE_set_cmd_defns ,
30.Nm ENGINE_get_cmd_defns
31.Nd control commands for ENGINE objects
32.Sh SYNOPSIS
33.In openssl/engine.h
34.Fo ENGINE_ctrl
35.Fa "ENGINE *e"
36.Fa "int cmd"
37.Fa "long i"
38.Fa "void *p"
39.Fa "void (*f)(void)"
40.Fc
41.Ft int
42.Fo ENGINE_cmd_is_executable
43.Fa "ENGINE *e"
44.Fa "int cmd"
45.Fc
46.Ft int
47.Fo ENGINE_ctrl_cmd
48.Fa "ENGINE *e"
49.Fa "const char *cmd_name"
50.Fa "long i"
51.Fa "void *p"
52.Fa "void (*f)(void)"
53.Fa "int cmd_optional"
54.Fc
55.Ft int
56.Fo ENGINE_ctrl_cmd_string
57.Fa "ENGINE *e"
58.Fa "const char *cmd_name"
59.Fa "const char *arg"
60.Fa "int cmd_optional"
61.Fc
62.Ft typedef int
63.Fo (*ENGINE_CTRL_FUNC_PTR)
64.Fa "ENGINE *e"
65.Fa "int cmd"
66.Fa "long i"
67.Fa "void *p"
68.Fa "void (*f)(void)"
69.Fc
70.Ft int
71.Fo ENGINE_set_ctrl_function
72.Fa "ENGINE *e"
73.Fa "ENGINE_CTRL_FUNC_PTR ctrl_f"
74.Fc
75.Ft ENGINE_CTRL_FUNC_PTR
76.Fo ENGINE_get_ctrl_function
77.Fa "const ENGINE *e"
78.Fc
79.Ft int
80.Fo ENGINE_set_cmd_defns
81.Fa "ENGINE *e"
82.Fa "const ENGINE_CMD_DEFN *defns"
83.Fc
84.Ft const ENGINE_CMD_DEFN *
85.Fo ENGINE_get_cmd_defns
86.Fa "const ENGINE *e"
87.Fc
88.Sh DESCRIPTION
89.Fn ENGINE_ctrl
90calls the built-in or user-defined
91.Fa cmd
92for the engine
93.Fa e ,
94passing the arguments
95.Fa i
96and
97.Fa p .
98.Pp
99Most built-in commands operate on user-defined commands installed with
100.Fn ENGINE_set_cmd_defns ,
101either using the
102.Fa p
103argument to indicate the user-defined command with the command name
104.Fa cmd_name
105or using the
106.Fa i
107argument to indicate the user-defined command with the command number
108.Fa cmd_num .
109The
110.Fa cmd
111arguments to call the built-in commands are as follows:
112.Bl -tag -width Ds
113.It Dv ENGINE_CTRL_GET_CMD_FLAGS
114Return the
115.Fa cmd_flags
116of the user-defined command with the number
117.Fa i ,
118or a number less than or equal to 0 if an error occurs or
119the command number does not exist.
120A return value of 0 indicates failure if
121.Fa e
122is
123.Dv NULL
124or has a reference count of 0, or success if
125.Fa e
126is valid.
127.It Dv ENGINE_CTRL_GET_CMD_FROM_NAME
128Return the positive command number
129of the user-defined command with the name
130.Fa p ,
131or a number less than or equal to 0 if an error occurs or no
132matching name is found.
133.It Dv ENGINE_CTRL_GET_DESC_FROM_CMD
134Copy the description of the user-defined command with the number
135.Fa i
136into the buffer
137.Fa p
138and NUL-terminate it.
139It is the reponsability of the caller to make sure that the buffer
140.Fa p
141is large enough, either by calling
142.Dv ENGINE_CTRL_GET_DESC_LEN_FROM_CMD
143first or using knowledge about the array passed to
144.Fn ENGINE_set_cmd_defns .
145The return value is the number of bytes written
146.Em including
147the terminating NUL byte, or a number less than or equal to 0
148if an error occurs.
149.It Dv ENGINE_CTRL_GET_DESC_LEN_FROM_CMD
150Return the length in bytes
151.Em excluding
152the terminating NUL byte
153of the description of the user-defined command with the number
154.Fa i ,
155or a number less than or equal to 0 if an error occurs.
156A return value of 0 indicates failure if
157.Fa e
158is
159.Dv NULL
160or has a reference count of 0, or success if
161.Fa e
162is valid.
163.It Dv ENGINE_CTRL_GET_FIRST_CMD_TYPE
164Return the positive command number
165of the first user-defined command installed with
166.Fn ENGINE_set_cmd_defns
167or a number less than or equal to 0 if an error occurs or no
168user-defined command has been installed.
169.It Dv ENGINE_CTRL_GET_NAME_FROM_CMD
170Copy the name of the user-defined command with the number
171.Fa i
172into the buffer
173.Fa p
174and NUL-terminate it.
175It is the reponsability of the caller to make sure that the buffer
176.Fa p
177is large enough, either by calling
178.Dv ENGINE_CTRL_GET_NAME_LEN_FROM_CMD
179first or using knowledge about the array passed to
180.Fn ENGINE_set_cmd_defns .
181The return value is the number of bytes written
182.Em including
183the terminating NUL byte, or a number less than or equal to 0
184if an error occurs.
185.It Dv ENGINE_CTRL_GET_NAME_LEN_FROM_CMD
186Return the length in bytes
187.Em excluding
188the terminating NULL byte
189of the name of the user-defined command with the number
190.Fa i ,
191or a number less than or equal to 0 if an error occurs.
192A return value of 0 indicates failure if
193.Fa e
194is
195.Dv NULL
196or has a reference count of 0, or success if
197.Fa e
198is valid.
199.It Dv ENGINE_CTRL_GET_NEXT_CMD_TYPE
200Return the positive command number of the next user-defined command
201after the user-defined command with the number
202.Fa i ,
203or a number less than or equal to 0 if an error occurs or if
204.Fa i
205is the last user-defined command.
206Together with
207.Dv ENGINE_CTRL_GET_FIRST_CMD_TYPE ,
208this can be used to iterate the user-defined commands installed with
209.Fn ENGINE_set_cmd_defns .
210.It Dv ENGINE_CTRL_HAS_CTRL_FUNCTION
211Return 1 if
212.Fa e
213has its own
214.Fa ctrl_f
215installed with
216.Fn ENGINE_set_ctrl_function
217or 0 otherwise.
218.El
219.Pp
220.Fn ENGINE_ctrl_cmd
221translates the
222.Fa cmd_name
223of a user-defined command to a
224.Fa cmd
225number and calls
226.Fn ENGINE_ctrl
227on it.
228If
229.Fa cmd_optional
230is non-zero, lack of a
231.Fa ctrl_f
232in
233.Fa e
234and translation failure with
235.Dv ENGINE_CTRL_GET_CMD_FROM_NAME
236are considered success, and the command has no effect.
237Otherwise, these problems cause
238.Fn ENGINE_ctrl_cmd
239to fail.
240.Pp
241.Fn ENGINE_ctrl_cmd_string
242translates the
243.Fa cmd_name
244of a user-defined command to a
245.Fa cmd
246number.
247If that command has the
248.Dv ENGINE_CMD_FLAG_NO_INPUT
249flag set,
250.Fa arg
251must be
252.Dv NULL
253and
254.Fn ENGINE_ctrl
255is called with
256.Fa i
257set to 0 and
258.Fa p
259set to
260.Dv NULL .
261Otherwise,
262.Fa arg
263must not be
264.Dv NULL .
265If the command accepts string input,
266.Fa i
267is set to 0 and
268.Fa arg
269is passed as the
270.Fa p
271argument to
272.Fn ENGINE_ctrl .
273Otherwise,
274.Fa arg
275is converted with
276.Xr strtol 3
277and passed as the
278.Fa i
279argument to
280.Fn ENGINE_ctrl ,
281setting
282.Fa p
283to
284.Dv NULL .
285.Pp
286.Fn ENGINE_set_ctrl_function
287installs
288.Fa ctrl_f
289as the engine-specific control function for
290.Fa e .
291Future calls to
292.Fn ENGINE_ctrl
293will call that function, passing on their arguments unchanged, if the
294.Fa cmd
295is not built-in to the library or if the
296.Dv ENGINE_FLAGS_MANUAL_CMD_CTRL
297flag is set in
298.Fa e .
299Let the
300.Fa ctrl_f
301return positive values on success or negative values on failure.
302Avoid return values of 0 because they cause dangerous ambiguity.
303In particular,
304.Fn ENGINE_ctrl_cmd
305and
306.Fn ENGINE_ctrl_cmd_string
307cannot be used with user-defined commands
308that may return 0 on success.
309.Pp
310.Fn ENGINE_set_cmd_defns
311install an array of command definitions in
312.Fa e .
313.Pp
314The structure
315.Vt ENGINE_CMD_DEFN
316has the following fields:
317.Bl -tag -width Ds
318.It Fa "unsigned int cmd_num"
319A positive, unique, monotonically increasing command number.
320Avoid using numbers below
321.Dv ENGINE_CMD_BASE .
322.It Fa "const char *cmd_name"
323The unique name of the command.
324.It Fa "const char *cmd_desc"
325A short description of the command.
326.It Fa "unsigned int cmd_flags"
327The bitwise OR of zero or more of the following flags:
328.Bl -tag -width Ds
329.It Dv ENGINE_CMD_FLAG_NUMERIC
330The command uses
331.Fa i .
332.It Dv ENGINE_CMD_FLAG_STRING
333The command uses
334.Fa p .
335.It Dv ENGINE_CMD_FLAG_NO_INPUT
336The command neither uses
337.Fa i
338nor
339.Fa p .
340.It Dv ENGINE_CMD_FLAG_INTERNAL
341This flag has no effect and is only provided for compatibility.
342.El
343.El
344.Pp
345The last element of
346.Fa defns
347does not specify a command, but must have a
348.Fa cmd_num
349of 0 and a
350.Fa cmd_name
351of
352.Dv NULL
353to indicate the end of the array.
354.Sh RETURN VALUES
355For
356.Fn ENGINE_ctrl ,
357positive return values indicate success and negative return values
358indicate failure.
359The meaning of a zero return value depends on the particular
360.Fa cmd
361and may indicate both success and failure, which is pathetic.
362.Pp
363Regardless of the
364.Fa cmd ,
365.Fn ENGINE_ctrl
366returns 0 if
367.Fa e
368is
369.Dv NULL
370or has a reference count of 0.
371This is quite unfortunate for commands like
372.Dv ENGINE_CTRL_GET_CMD_FLAGS
373where 0 may indicate success, so make sure
374.Fa e
375is valid before issuing a control command.
376.Pp
377For built-in commands except
378.Dv ENGINE_CTRL_HAS_CTRL_FUNCTION ,
379.Fn ENGINE_ctrl
380returns \-1 if
381.Dv ENGINE_FLAGS_MANUAL_CMD_CTRL
382is set but no
383.Fa ctrl_f
384has been installed with
385.Fn ENGINE_set_ctrl_function .
386.Pp
387For commands that are not built in,
388.Fn ENGINE_ctrl
389returns 0 if no
390.Fa ctrl_f
391has been installed with
392.Fn ENGINE_set_ctrl_function .
393.Pp
394.Fn ENGINE_cmd_is_executable
395returns 1 if the user-defined
396.Fa cmd
397is executable and has at least one of the flags
398.Dv ENGINE_CMD_FLAG_NUMERIC ,
399.Dv ENGINE_CMD_FLAG_STRING ,
400and
401.Dv ENGINE_CMD_FLAG_NO_INPUT
402set, or 0 otherwise.
403.Pp
404.Fn ENGINE_ctrl_cmd
405and
406.Fn ENGINE_ctrl_cmd_string
407return 1 on success or 0 on error.
408.Pp
409.Fn ENGINE_set_ctrl_function
410and
411.Fn ENGINE_set_cmd_defns
412always return 1.
413.Pp
414.Fn ENGINE_get_ctrl_function
415returns a pointer to the function
416.Fa ctrl_f
417installed with
418.Fn ENGINE_set_ctrl_function ,
419or
420.Dv NULL
421if none has been installed.
422.Pp
423.Fn ENGINE_get_cmd_defns
424returns the array of command definitions installed in
425.Fa e
426or
427.Dv NULL
428if none is installed.
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-10-29 17:57:59 +0000