470 lines
11 KiB
Groff
470 lines
11 KiB
Groff
.\" $OpenBSD: ENGINE_ctrl.3,v 1.5 2022/01/15 23:38:50 jsg 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: January 15 2022 $
|
|
.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 responsibility 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 responsibility 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 .
|