ENGINE_CTRL(3) | Library Functions Manual | ENGINE_CTRL(3) |
ENGINE_ctrl
,
ENGINE_cmd_is_executable
,
ENGINE_ctrl_cmd
,
ENGINE_ctrl_cmd_string
,
ENGINE_set_ctrl_function
,
ENGINE_get_ctrl_function
,
ENGINE_set_cmd_defns
,
ENGINE_get_cmd_defns
—
control commands for ENGINE objects
#include
<openssl/engine.h>
int
ENGINE_ctrl
(ENGINE *e,
int cmd, long i,
void *p, void (*f)(void));
int
ENGINE_cmd_is_executable
(ENGINE
*e, int cmd);
int
ENGINE_ctrl_cmd
(ENGINE *e,
const char *cmd_name, long i,
void *p, void (*f)(void),
int cmd_optional);
int
ENGINE_ctrl_cmd_string
(ENGINE
*e, const char *cmd_name, const
char *arg, int cmd_optional);
typedef int
(*ENGINE_CTRL_FUNC_PTR)
(ENGINE
*e, int cmd, long i,
void *p, void (*f)(void));
int
ENGINE_set_ctrl_function
(ENGINE
*e, ENGINE_CTRL_FUNC_PTR ctrl_f);
ENGINE_CTRL_FUNC_PTR
ENGINE_get_ctrl_function
(const ENGINE
*e);
int
ENGINE_set_cmd_defns
(ENGINE *e,
const ENGINE_CMD_DEFN *defns);
const ENGINE_CMD_DEFN *
ENGINE_get_cmd_defns
(const ENGINE
*e);
ENGINE_ctrl
()
calls the built-in or user-defined cmd for the engine
e, passing the arguments i and
p.
User-defined commands can be used before ENGINE_init(3) to provide data required for initialization or at any time to modify the behaviour of an engine.
Most built-in commands operate on
user-defined commands installed with
ENGINE_set_cmd_defns
(),
either using the p argument to indicate the
user-defined command with the command name cmd_name or
using the i argument to indicate the user-defined
command with the command number cmd_num. The
cmd arguments to call the built-in commands are as
follows:
ENGINE_CTRL_GET_CMD_FLAGS
NULL
or has a reference count of 0, or success if
e is valid.ENGINE_CTRL_GET_CMD_FROM_NAME
ENGINE_CTRL_GET_DESC_FROM_CMD
ENGINE_CTRL_GET_DESC_LEN_FROM_CMD
first or using
knowledge about the array passed to
ENGINE_set_cmd_defns
(). The return value is the
number of bytes written including the terminating NUL
byte, or a number less than or equal to 0 if an error occurs.ENGINE_CTRL_GET_DESC_LEN_FROM_CMD
NULL
or has a reference count of 0, or success
if e is valid.ENGINE_CTRL_GET_FIRST_CMD_TYPE
ENGINE_set_cmd_defns
() or a number
less than or equal to 0 if an error occurs or no user-defined command has
been installed.ENGINE_CTRL_GET_NAME_FROM_CMD
ENGINE_CTRL_GET_NAME_LEN_FROM_CMD
first or using
knowledge about the array passed to
ENGINE_set_cmd_defns
(). The return value is the
number of bytes written including the terminating NUL
byte, or a number less than or equal to 0 if an error occurs.ENGINE_CTRL_GET_NAME_LEN_FROM_CMD
NULL
or has a reference count of 0, or success
if e is valid.ENGINE_CTRL_GET_NEXT_CMD_TYPE
ENGINE_CTRL_GET_FIRST_CMD_TYPE
, this can be used
to iterate the user-defined commands installed with
ENGINE_set_cmd_defns
().ENGINE_CTRL_HAS_CTRL_FUNCTION
ENGINE_set_ctrl_function
() or 0 otherwise.ENGINE_ctrl_cmd
()
translates the cmd_name of a user-defined command to a
cmd number and calls
ENGINE_ctrl
() on it. If
cmd_optional is non-zero, lack of a
ctrl_f in e and translation
failure with ENGINE_CTRL_GET_CMD_FROM_NAME
are
considered success, and the command has no effect. Otherwise, these problems
cause ENGINE_ctrl_cmd
() to fail.
Neither
ENGINE_ctrl
()
nor ENGINE_ctrl_cmd
() ever call the
f callback, but merely pass it on as an argument to
the engine-specific ctrl_f control function. It is up
to ctrl_f how to use it, or alternatively to ignore it
as well.
ENGINE_ctrl_cmd_string
()
translates the cmd_name of a user-defined command to a
cmd number. If that command has the
ENGINE_CMD_FLAG_NO_INPUT
flag set,
arg must be NULL
and
ENGINE_ctrl
() is called with i
set to 0 and p set to NULL
.
Otherwise, arg must not be
NULL
. If the command accepts string input,
i is set to 0 and arg is passed
as the p argument to
ENGINE_ctrl
(). Otherwise, arg
is converted with strtol(3) and passed as
the i argument to
ENGINE_ctrl
(), setting p to
NULL
.
ENGINE_set_ctrl_function
()
installs ctrl_f as the engine-specific control
function for e. Future calls to
ENGINE_ctrl
() will call that function, passing on
their arguments unchanged, if the cmd is not built-in
to the library or if the
ENGINE_FLAGS_MANUAL_CMD_CTRL
flag is set in
e. Let the ctrl_f return
positive values on success or negative values on failure. Avoid return
values of 0 because they cause dangerous ambiguity. In particular,
ENGINE_ctrl_cmd
() and
ENGINE_ctrl_cmd_string
() cannot be used with
user-defined commands that may return 0 on success.
ENGINE_set_cmd_defns
()
install an array of command definitions in e.
The structure ENGINE_CMD_DEFN has the following fields:
ENGINE_CMD_BASE
.ENGINE_CMD_FLAG_NUMERIC
ENGINE_CMD_FLAG_STRING
ENGINE_CMD_FLAG_NO_INPUT
ENGINE_CMD_FLAG_INTERNAL
The last element of defns does not specify a
command, but must have a cmd_num of 0 and a
cmd_name of NULL
to indicate
the end of the array.
For ENGINE_ctrl
(), positive return values
indicate success and negative return values indicate failure. The meaning of
a zero return value depends on the particular cmd and
may indicate both success and failure, which is pathetic.
Regardless of the cmd,
ENGINE_ctrl
() returns 0 if e
is NULL
or has a reference count of 0. This is quite
unfortunate for commands like
ENGINE_CTRL_GET_CMD_FLAGS
where 0 may indicate
success, so make sure e is valid before issuing a
control command.
For built-in commands except
ENGINE_CTRL_HAS_CTRL_FUNCTION
,
ENGINE_ctrl
() returns -1 if
ENGINE_FLAGS_MANUAL_CMD_CTRL
is set but no
ctrl_f has been installed with
ENGINE_set_ctrl_function
().
For commands that are not built in,
ENGINE_ctrl
() returns 0 if no
ctrl_f has been installed with
ENGINE_set_ctrl_function
().
ENGINE_cmd_is_executable
() returns 1 if
the user-defined cmd is executable and has at least
one of the flags ENGINE_CMD_FLAG_NUMERIC
,
ENGINE_CMD_FLAG_STRING
, and
ENGINE_CMD_FLAG_NO_INPUT
set, or 0 otherwise.
ENGINE_ctrl_cmd
() and
ENGINE_ctrl_cmd_string
() return 1 on success or 0 on
error.
ENGINE_set_ctrl_function
() and
ENGINE_set_cmd_defns
() always return 1.
ENGINE_get_ctrl_function
() returns a
pointer to the function ctrl_f installed with
ENGINE_set_ctrl_function
(), or
NULL
if none has been installed.
ENGINE_get_cmd_defns
() returns the array
of command definitions installed in e or
NULL
if none is installed.
ENGINE_add(3), ENGINE_init(3), ENGINE_new(3), ENGINE_register_RSA(3), ENGINE_set_flags(3), ENGINE_set_RSA(3)
ENGINE_ctrl
(),
ENGINE_set_ctrl_function
(), and
ENGINE_get_ctrl_function
() first appeared in OpenSSL
0.9.7 and have been available since OpenBSD 2.9.
ENGINE_cmd_is_executable
(),
ENGINE_ctrl_cmd
(),
ENGINE_ctrl_cmd_string
(),
ENGINE_set_cmd_defns
(), and
ENGINE_get_cmd_defns
() first appeared in OpenSSL
0.9.7 and have been available since OpenBSD 3.2.
January 15, 2022 | OpenBSD-current |