Rewrite the ENGINE_*(3) documentation from scratch (step 1,

covering 60% of the documented functions).  The old, abominable
engine(3) manual page shall die soon.

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 @@
+.\" $OpenBSD: ENGINE_ctrl.3,v 1.1 2018/04/15 01:43:45 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 15 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
+.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
+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
+.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.