NAME

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

SYNOPSIS

#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);

DESCRIPTION

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

Return the cmd_flags of the user-defined command with the number 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 e is NULL or has a reference count of 0, or success if e is valid.

ENGINE_CTRL_GET_CMD_FROM_NAME

Return the positive command number of the user-defined command with the name p, or a number less than or equal to 0 if an error occurs or no matching name is found.

ENGINE_CTRL_GET_DESC_FROM_CMD

Copy the description of the user-defined command with the number i into the buffer p and NUL-terminate it. It is the reponsability of the caller to make sure that the buffer p is large enough, either by calling 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

Return the length in bytes excluding the terminating NUL byte of the description of the user-defined command with the number i, or a number less than or equal to 0 if an error occurs. A return value of 0 indicates failure if e is NULL or has a reference count of 0, or success if e is valid.

ENGINE_CTRL_GET_FIRST_CMD_TYPE

Return the positive command number of the first user-defined command installed with 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

Copy the name of the user-defined command with the number i into the buffer p and NUL-terminate it. It is the reponsability of the caller to make sure that the buffer p is large enough, either by calling 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

Return the length in bytes excluding the terminating NULL byte of the name of the user-defined command with the number i, or a number less than or equal to 0 if an error occurs. A return value of 0 indicates failure if e is NULL or has a reference count of 0, or success if e is valid.

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 i, or a number less than or equal to 0 if an error occurs or if i is the last user-defined command. Together with 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

Return 1 if e has its own ctrl_f installed with 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:

unsigned int cmd_num

A positive, unique, monotonically increasing command number. Avoid using numbers below ENGINE_CMD_BASE.

const char *cmd_name

The unique name of the command.

const char *cmd_desc

A short description of the command.

unsigned int cmd_flags

The bitwise OR of zero or more of the following flags:

ENGINE_CMD_FLAG_NUMERIC

The command uses i.

ENGINE_CMD_FLAG_STRING

The command uses p.

ENGINE_CMD_FLAG_NO_INPUT

The command neither uses i nor p.

ENGINE_CMD_FLAG_INTERNAL

This flag has no effect and is only provided for compatibility.

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.

RETURN VALUES

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.

SEE ALSO

ENGINE_add(3), ENGINE_init(3), ENGINE_new(3), ENGINE_register_RSA(3), ENGINE_set_flags(3), ENGINE_set_RSA(3)

HISTORY

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.