From 83e8d72fcb33da2c34c5964418ed6fa3b12d08c7 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sun, 15 Apr 2018 01:43:45 +0000 Subject: 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. --- src/lib/libcrypto/man/ENGINE_ctrl.3 | 428 ++++++++++++++++++++++++++++++++++++ 1 file changed, 428 insertions(+) create mode 100644 src/lib/libcrypto/man/ENGINE_ctrl.3 (limited to 'src/lib/libcrypto/man/ENGINE_ctrl.3') 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 +.\" +.\" 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. -- cgit v1.2.3-55-g6feb