.\" $OpenBSD: ENGINE_ctrl.3,v 1.4 2018/04/19 18:43:58 schwarze Exp $
.\" content checked up to:
.\" OpenSSL ENGINE_add 1f13ad31 Dec 25 17:50:39 2017 +0800
.\"
.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: April 19 2018 $
.Dt ENGINE_CTRL 3
.Os
.Sh NAME
.Nm ENGINE_ctrl ,
.Nm ENGINE_cmd_is_executable ,
.Nm ENGINE_ctrl_cmd ,
.Nm ENGINE_ctrl_cmd_string ,
.Nm ENGINE_set_ctrl_function ,
.Nm ENGINE_get_ctrl_function ,
.Nm ENGINE_set_cmd_defns ,
.Nm ENGINE_get_cmd_defns
.Nd control commands for ENGINE objects
.Sh SYNOPSIS
.In openssl/engine.h
.Ft int
.Fo ENGINE_ctrl
.Fa "ENGINE *e"
.Fa "int cmd"
.Fa "long i"
.Fa "void *p"
.Fa "void (*f)(void)"
.Fc
.Ft int
.Fo ENGINE_cmd_is_executable
.Fa "ENGINE *e"
.Fa "int cmd"
.Fc
.Ft int
.Fo ENGINE_ctrl_cmd
.Fa "ENGINE *e"
.Fa "const char *cmd_name"
.Fa "long i"
.Fa "void *p"
.Fa "void (*f)(void)"
.Fa "int cmd_optional"
.Fc
.Ft int
.Fo ENGINE_ctrl_cmd_string
.Fa "ENGINE *e"
.Fa "const char *cmd_name"
.Fa "const char *arg"
.Fa "int cmd_optional"
.Fc
.Ft typedef int
.Fo (*ENGINE_CTRL_FUNC_PTR)
.Fa "ENGINE *e"
.Fa "int cmd"
.Fa "long i"
.Fa "void *p"
.Fa "void (*f)(void)"
.Fc
.Ft int
.Fo ENGINE_set_ctrl_function
.Fa "ENGINE *e"
.Fa "ENGINE_CTRL_FUNC_PTR ctrl_f"
.Fc
.Ft ENGINE_CTRL_FUNC_PTR
.Fo ENGINE_get_ctrl_function
.Fa "const ENGINE *e"
.Fc
.Ft int
.Fo ENGINE_set_cmd_defns
.Fa "ENGINE *e"
.Fa "const ENGINE_CMD_DEFN *defns"
.Fc
.Ft const ENGINE_CMD_DEFN *
.Fo ENGINE_get_cmd_defns
.Fa "const ENGINE *e"
.Fc
.Sh DESCRIPTION
.Fn ENGINE_ctrl
calls the built-in or user-defined
.Fa cmd
for the engine
.Fa e ,
passing the arguments
.Fa i
and
.Fa p .
.Pp
User-defined commands can be used before
.Xr ENGINE_init 3
to provide data required for initialization
or at any time to modify the behaviour of an engine.
.Pp
Most built-in commands operate on user-defined commands installed with
.Fn ENGINE_set_cmd_defns ,
either using the
.Fa p
argument to indicate the user-defined command with the command name
.Fa cmd_name
or using the
.Fa i
argument to indicate the user-defined command with the command number
.Fa cmd_num .
The
.Fa cmd
arguments to call the built-in commands are as follows:
.Bl -tag -width Ds
.It Dv ENGINE_CTRL_GET_CMD_FLAGS
Return the
.Fa cmd_flags
of the user-defined command with the number
.Fa i ,
or a number less than or equal to 0 if an error occurs or
the command number does not exist.
A return value of 0 indicates failure if
.Fa e
is
.Dv NULL
or has a reference count of 0, or success if
.Fa e
is valid.
.It Dv ENGINE_CTRL_GET_CMD_FROM_NAME
Return the positive command number
of the user-defined command with the name
.Fa p ,
or a number less than or equal to 0 if an error occurs or no
matching name is found.
.It Dv ENGINE_CTRL_GET_DESC_FROM_CMD
Copy the description of the user-defined command with the number
.Fa i
into the buffer
.Fa p
and NUL-terminate it.
It is the reponsability of the caller to make sure that the buffer
.Fa p
is large enough, either by calling
.Dv ENGINE_CTRL_GET_DESC_LEN_FROM_CMD
first or using knowledge about the array passed to
.Fn ENGINE_set_cmd_defns .
The return value is the number of bytes written
.Em including
the terminating NUL byte, or a number less than or equal to 0
if an error occurs.
.It Dv ENGINE_CTRL_GET_DESC_LEN_FROM_CMD
Return the length in bytes
.Em excluding
the terminating NUL byte
of the description of the user-defined command with the number
.Fa i ,
or a number less than or equal to 0 if an error occurs.
A return value of 0 indicates failure if
.Fa e
is
.Dv NULL
or has a reference count of 0, or success if
.Fa e
is valid.
.It Dv ENGINE_CTRL_GET_FIRST_CMD_TYPE
Return the positive command number
of the first user-defined command installed with
.Fn 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.
.It Dv ENGINE_CTRL_GET_NAME_FROM_CMD
Copy the name of the user-defined command with the number
.Fa i
into the buffer
.Fa p
and NUL-terminate it.
It is the reponsability of the caller to make sure that the buffer
.Fa p
is large enough, either by calling
.Dv ENGINE_CTRL_GET_NAME_LEN_FROM_CMD
first or using knowledge about the array passed to
.Fn ENGINE_set_cmd_defns .
The return value is the number of bytes written
.Em including
the terminating NUL byte, or a number less than or equal to 0
if an error occurs.
.It Dv ENGINE_CTRL_GET_NAME_LEN_FROM_CMD
Return the length in bytes
.Em excluding
the terminating NULL byte
of the name of the user-defined command with the number
.Fa i ,
or a number less than or equal to 0 if an error occurs.
A return value of 0 indicates failure if
.Fa e
is
.Dv NULL
or has a reference count of 0, or success if
.Fa e
is valid.
.It Dv ENGINE_CTRL_GET_NEXT_CMD_TYPE
Return the positive command number of the next user-defined command
after the user-defined command with the number
.Fa i ,
or a number less than or equal to 0 if an error occurs or if
.Fa i
is the last user-defined command.
Together with
.Dv ENGINE_CTRL_GET_FIRST_CMD_TYPE ,
this can be used to iterate the user-defined commands installed with
.Fn ENGINE_set_cmd_defns .
.It Dv ENGINE_CTRL_HAS_CTRL_FUNCTION
Return 1 if
.Fa e
has its own
.Fa ctrl_f
installed with
.Fn ENGINE_set_ctrl_function
or 0 otherwise.
.El
.Pp
.Fn ENGINE_ctrl_cmd
translates the
.Fa cmd_name
of a user-defined command to a
.Fa cmd
number and calls
.Fn ENGINE_ctrl
on it.
If
.Fa cmd_optional
is non-zero, lack of a
.Fa ctrl_f
in
.Fa e
and translation failure with
.Dv ENGINE_CTRL_GET_CMD_FROM_NAME
are considered success, and the command has no effect.
Otherwise, these problems cause
.Fn ENGINE_ctrl_cmd
to fail.
.Pp
Neither
.Fn ENGINE_ctrl
nor
.Fn ENGINE_ctrl_cmd
ever call the
.Fa f
callback, but merely pass it on as an argument to the engine-specific
.Fa ctrl_f
control function.
It is up to
.Fa ctrl_f
how to use it, or alternatively to ignore it as well.
.Pp
.Fn ENGINE_ctrl_cmd_string
translates the
.Fa cmd_name
of a user-defined command to a
.Fa cmd
number.
If that command has the
.Dv ENGINE_CMD_FLAG_NO_INPUT
flag set,
.Fa arg
must be
.Dv NULL
and
.Fn ENGINE_ctrl
is called with
.Fa i
set to 0 and
.Fa p
set to
.Dv NULL .
Otherwise,
.Fa arg
must not be
.Dv NULL .
If the command accepts string input,
.Fa i
is set to 0 and
.Fa arg
is passed as the
.Fa p
argument to
.Fn ENGINE_ctrl .
Otherwise,
.Fa arg
is converted with
.Xr strtol 3
and passed as the
.Fa i
argument to
.Fn ENGINE_ctrl ,
setting
.Fa p
to
.Dv NULL .
.Pp
.Fn ENGINE_set_ctrl_function
installs
.Fa ctrl_f
as the engine-specific control function for
.Fa e .
Future calls to
.Fn ENGINE_ctrl
will call that function, passing on their arguments unchanged, if the
.Fa cmd
is not built-in to the library or if the
.Dv ENGINE_FLAGS_MANUAL_CMD_CTRL
flag is set in
.Fa e .
Let the
.Fa ctrl_f
return positive values on success or negative values on failure.
Avoid return values of 0 because they cause dangerous ambiguity.
In particular,
.Fn ENGINE_ctrl_cmd
and
.Fn ENGINE_ctrl_cmd_string
cannot be used with user-defined commands
that may return 0 on success.
.Pp
.Fn ENGINE_set_cmd_defns
install an array of command definitions in
.Fa e .
.Pp
The structure
.Vt ENGINE_CMD_DEFN
has the following fields:
.Bl -tag -width Ds
.It Fa "unsigned int cmd_num"
A positive, unique, monotonically increasing command number.
Avoid using numbers below
.Dv ENGINE_CMD_BASE .
.It Fa "const char *cmd_name"
The unique name of the command.
.It Fa "const char *cmd_desc"
A short description of the command.
.It Fa "unsigned int cmd_flags"
The bitwise OR of zero or more of the following flags:
.Bl -tag -width Ds
.It Dv ENGINE_CMD_FLAG_NUMERIC
The command uses
.Fa i .
.It Dv ENGINE_CMD_FLAG_STRING
The command uses
.Fa p .
.It Dv ENGINE_CMD_FLAG_NO_INPUT
The command neither uses
.Fa i
nor
.Fa p .
.It Dv ENGINE_CMD_FLAG_INTERNAL
This flag has no effect and is only provided for compatibility.
.El
.El
.Pp
The last element of
.Fa defns
does not specify a command, but must have a
.Fa cmd_num
of 0 and a
.Fa cmd_name
of
.Dv NULL
to indicate the end of the array.
.Sh RETURN VALUES
For
.Fn ENGINE_ctrl ,
positive return values indicate success and negative return values
indicate failure.
The meaning of a zero return value depends on the particular
.Fa cmd
and may indicate both success and failure, which is pathetic.
.Pp
Regardless of the
.Fa cmd ,
.Fn ENGINE_ctrl
returns 0 if
.Fa e
is
.Dv NULL
or has a reference count of 0.
This is quite unfortunate for commands like
.Dv ENGINE_CTRL_GET_CMD_FLAGS
where 0 may indicate success, so make sure
.Fa e
is valid before issuing a control command.
.Pp
For built-in commands except
.Dv ENGINE_CTRL_HAS_CTRL_FUNCTION ,
.Fn ENGINE_ctrl
returns \-1 if
.Dv ENGINE_FLAGS_MANUAL_CMD_CTRL
is set but no
.Fa ctrl_f
has been installed with
.Fn ENGINE_set_ctrl_function .
.Pp
For commands that are not built in,
.Fn ENGINE_ctrl
returns 0 if no
.Fa ctrl_f
has been installed with
.Fn ENGINE_set_ctrl_function .
.Pp
.Fn ENGINE_cmd_is_executable
returns 1 if the user-defined
.Fa cmd
is executable and has at least one of the flags
.Dv ENGINE_CMD_FLAG_NUMERIC ,
.Dv ENGINE_CMD_FLAG_STRING ,
and
.Dv ENGINE_CMD_FLAG_NO_INPUT
set, or 0 otherwise.
.Pp
.Fn ENGINE_ctrl_cmd
and
.Fn ENGINE_ctrl_cmd_string
return 1 on success or 0 on error.
.Pp
.Fn ENGINE_set_ctrl_function
and
.Fn ENGINE_set_cmd_defns
always return 1.
.Pp
.Fn ENGINE_get_ctrl_function
returns a pointer to the function
.Fa ctrl_f
installed with
.Fn ENGINE_set_ctrl_function ,
or
.Dv NULL
if none has been installed.
.Pp
.Fn ENGINE_get_cmd_defns
returns the array of command definitions installed in
.Fa e
or
.Dv NULL
if none is installed.
.Sh SEE ALSO
.Xr ENGINE_add 3 ,
.Xr ENGINE_init 3 ,
.Xr ENGINE_new 3 ,
.Xr ENGINE_register_RSA 3 ,
.Xr ENGINE_set_flags 3 ,
.Xr ENGINE_set_RSA 3
.Sh HISTORY
.Fn ENGINE_ctrl ,
.Fn ENGINE_set_ctrl_function ,
and
.Fn ENGINE_get_ctrl_function
first appeared in OpenSSL 0.9.7 and have been available since
.Ox 2.9 .
.Pp
.Fn ENGINE_cmd_is_executable ,
.Fn ENGINE_ctrl_cmd ,
.Fn ENGINE_ctrl_cmd_string ,
.Fn ENGINE_set_cmd_defns ,
and
.Fn ENGINE_get_cmd_defns
first appeared in OpenSSL 0.9.7 and have been available since
.Ox 3.2 .