2 * Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
4 * Licensed under the OpenSSL license (the "License"). You may not use
5 * this file except in compliance with the License. You can obtain a copy
6 * in the file LICENSE in the source distribution or at
7 * https://www.openssl.org/source/license.html
13 * When querying a ENGINE-specific control command's 'description', this
14 * string is used if the ENGINE_CMD_DEFN has cmd_desc set to NULL.
16 static const char *int_no_description = "";
19 * These internal functions handle 'CMD'-related control commands when the
20 * ENGINE in question has asked us to take care of it (ie. the ENGINE did not
21 * set the ENGINE_FLAGS_MANUAL_CMD_CTRL flag.
24 static int int_ctrl_cmd_is_null(const ENGINE_CMD_DEFN *defn)
26 if ((defn->cmd_num == 0) || (defn->cmd_name == NULL))
31 static int int_ctrl_cmd_by_name(const ENGINE_CMD_DEFN *defn, const char *s)
34 while (!int_ctrl_cmd_is_null(defn) && (strcmp(defn->cmd_name, s) != 0)) {
38 if (int_ctrl_cmd_is_null(defn))
39 /* The given name wasn't found */
44 static int int_ctrl_cmd_by_num(const ENGINE_CMD_DEFN *defn, unsigned int num)
48 * NB: It is stipulated that 'cmd_defn' lists are ordered by cmd_num. So
49 * our searches don't need to take any longer than necessary.
51 while (!int_ctrl_cmd_is_null(defn) && (defn->cmd_num < num)) {
55 if (defn->cmd_num == num)
57 /* The given cmd_num wasn't found */
61 static int int_ctrl_helper(ENGINE *e, int cmd, long i, void *p,
66 /* Take care of the easy one first (eg. it requires no searches) */
67 if (cmd == ENGINE_CTRL_GET_FIRST_CMD_TYPE) {
68 if ((e->cmd_defns == NULL) || int_ctrl_cmd_is_null(e->cmd_defns))
70 return e->cmd_defns->cmd_num;
72 /* One or two commands require that "p" be a valid string buffer */
73 if ((cmd == ENGINE_CTRL_GET_CMD_FROM_NAME) ||
74 (cmd == ENGINE_CTRL_GET_NAME_FROM_CMD) ||
75 (cmd == ENGINE_CTRL_GET_DESC_FROM_CMD)) {
77 ENGINEerr(ENGINE_F_INT_CTRL_HELPER, ERR_R_PASSED_NULL_PARAMETER);
81 /* Now handle cmd_name -> cmd_num conversion */
82 if (cmd == ENGINE_CTRL_GET_CMD_FROM_NAME) {
83 if ((e->cmd_defns == NULL)
84 || ((idx = int_ctrl_cmd_by_name(e->cmd_defns, s)) < 0)) {
85 ENGINEerr(ENGINE_F_INT_CTRL_HELPER, ENGINE_R_INVALID_CMD_NAME);
88 return e->cmd_defns[idx].cmd_num;
91 * For the rest of the commands, the 'long' argument must specify a valid
92 * command number - so we need to conduct a search.
94 if ((e->cmd_defns == NULL) || ((idx = int_ctrl_cmd_by_num(e->cmd_defns,
97 ENGINEerr(ENGINE_F_INT_CTRL_HELPER, ENGINE_R_INVALID_CMD_NUMBER);
100 /* Now the logic splits depending on command type */
102 case ENGINE_CTRL_GET_NEXT_CMD_TYPE:
104 if (int_ctrl_cmd_is_null(e->cmd_defns + idx))
108 return e->cmd_defns[idx].cmd_num;
109 case ENGINE_CTRL_GET_NAME_LEN_FROM_CMD:
110 return strlen(e->cmd_defns[idx].cmd_name);
111 case ENGINE_CTRL_GET_NAME_FROM_CMD:
112 return BIO_snprintf(s, strlen(e->cmd_defns[idx].cmd_name) + 1,
113 "%s", e->cmd_defns[idx].cmd_name);
114 case ENGINE_CTRL_GET_DESC_LEN_FROM_CMD:
115 if (e->cmd_defns[idx].cmd_desc)
116 return strlen(e->cmd_defns[idx].cmd_desc);
117 return strlen(int_no_description);
118 case ENGINE_CTRL_GET_DESC_FROM_CMD:
119 if (e->cmd_defns[idx].cmd_desc)
120 return BIO_snprintf(s,
121 strlen(e->cmd_defns[idx].cmd_desc) + 1,
122 "%s", e->cmd_defns[idx].cmd_desc);
123 return BIO_snprintf(s, strlen(int_no_description) + 1, "%s",
125 case ENGINE_CTRL_GET_CMD_FLAGS:
126 return e->cmd_defns[idx].cmd_flags;
128 /* Shouldn't really be here ... */
129 ENGINEerr(ENGINE_F_INT_CTRL_HELPER, ENGINE_R_INTERNAL_LIST_ERROR);
133 int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f) (void))
135 int ctrl_exists, ref_exists;
137 ENGINEerr(ENGINE_F_ENGINE_CTRL, ERR_R_PASSED_NULL_PARAMETER);
140 CRYPTO_THREAD_write_lock(global_engine_lock);
141 ref_exists = ((e->struct_ref > 0) ? 1 : 0);
142 CRYPTO_THREAD_unlock(global_engine_lock);
143 ctrl_exists = ((e->ctrl == NULL) ? 0 : 1);
145 ENGINEerr(ENGINE_F_ENGINE_CTRL, ENGINE_R_NO_REFERENCE);
149 * Intercept any "root-level" commands before trying to hand them on to
153 case ENGINE_CTRL_HAS_CTRL_FUNCTION:
155 case ENGINE_CTRL_GET_FIRST_CMD_TYPE:
156 case ENGINE_CTRL_GET_NEXT_CMD_TYPE:
157 case ENGINE_CTRL_GET_CMD_FROM_NAME:
158 case ENGINE_CTRL_GET_NAME_LEN_FROM_CMD:
159 case ENGINE_CTRL_GET_NAME_FROM_CMD:
160 case ENGINE_CTRL_GET_DESC_LEN_FROM_CMD:
161 case ENGINE_CTRL_GET_DESC_FROM_CMD:
162 case ENGINE_CTRL_GET_CMD_FLAGS:
163 if (ctrl_exists && !(e->flags & ENGINE_FLAGS_MANUAL_CMD_CTRL))
164 return int_ctrl_helper(e, cmd, i, p, f);
166 ENGINEerr(ENGINE_F_ENGINE_CTRL, ENGINE_R_NO_CONTROL_FUNCTION);
168 * For these cmd-related functions, failure is indicated by a -1
169 * return value (because 0 is used as a valid return in some
177 /* Anything else requires a ctrl() handler to exist. */
179 ENGINEerr(ENGINE_F_ENGINE_CTRL, ENGINE_R_NO_CONTROL_FUNCTION);
182 return e->ctrl(e, cmd, i, p, f);
185 int ENGINE_cmd_is_executable(ENGINE *e, int cmd)
189 ENGINE_ctrl(e, ENGINE_CTRL_GET_CMD_FLAGS, cmd, NULL, NULL)) < 0) {
190 ENGINEerr(ENGINE_F_ENGINE_CMD_IS_EXECUTABLE,
191 ENGINE_R_INVALID_CMD_NUMBER);
194 if (!(flags & ENGINE_CMD_FLAG_NO_INPUT) &&
195 !(flags & ENGINE_CMD_FLAG_NUMERIC) &&
196 !(flags & ENGINE_CMD_FLAG_STRING))
201 int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,
202 long i, void *p, void (*f) (void), int cmd_optional)
206 if (e == NULL || cmd_name == NULL) {
207 ENGINEerr(ENGINE_F_ENGINE_CTRL_CMD, ERR_R_PASSED_NULL_PARAMETER);
211 || (num = ENGINE_ctrl(e, ENGINE_CTRL_GET_CMD_FROM_NAME,
212 0, (void *)cmd_name, NULL)) <= 0) {
214 * If the command didn't *have* to be supported, we fake success.
215 * This allows certain settings to be specified for multiple ENGINEs
216 * and only require a change of ENGINE id (without having to
217 * selectively apply settings). Eg. changing from a hardware device
218 * back to the regular software ENGINE without editing the config
225 ENGINEerr(ENGINE_F_ENGINE_CTRL_CMD, ENGINE_R_INVALID_CMD_NAME);
229 * Force the result of the control command to 0 or 1, for the reasons
232 if (ENGINE_ctrl(e, num, i, p, f) > 0)
237 int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
244 if (e == NULL || cmd_name == NULL) {
245 ENGINEerr(ENGINE_F_ENGINE_CTRL_CMD_STRING, ERR_R_PASSED_NULL_PARAMETER);
249 || (num = ENGINE_ctrl(e, ENGINE_CTRL_GET_CMD_FROM_NAME,
250 0, (void *)cmd_name, NULL)) <= 0) {
252 * If the command didn't *have* to be supported, we fake success.
253 * This allows certain settings to be specified for multiple ENGINEs
254 * and only require a change of ENGINE id (without having to
255 * selectively apply settings). Eg. changing from a hardware device
256 * back to the regular software ENGINE without editing the config
263 ENGINEerr(ENGINE_F_ENGINE_CTRL_CMD_STRING, ENGINE_R_INVALID_CMD_NAME);
266 if (!ENGINE_cmd_is_executable(e, num)) {
267 ENGINEerr(ENGINE_F_ENGINE_CTRL_CMD_STRING,
268 ENGINE_R_CMD_NOT_EXECUTABLE);
272 flags = ENGINE_ctrl(e, ENGINE_CTRL_GET_CMD_FLAGS, num, NULL, NULL);
275 * Shouldn't happen, given that ENGINE_cmd_is_executable() returned
278 ENGINEerr(ENGINE_F_ENGINE_CTRL_CMD_STRING,
279 ENGINE_R_INTERNAL_LIST_ERROR);
283 * If the command takes no input, there must be no input. And vice versa.
285 if (flags & ENGINE_CMD_FLAG_NO_INPUT) {
287 ENGINEerr(ENGINE_F_ENGINE_CTRL_CMD_STRING,
288 ENGINE_R_COMMAND_TAKES_NO_INPUT);
292 * We deliberately force the result of ENGINE_ctrl() to 0 or 1 rather
293 * than returning it as "return data". This is to ensure usage of
294 * these commands is consistent across applications and that certain
295 * applications don't understand it one way, and others another.
297 if (ENGINE_ctrl(e, num, 0, (void *)arg, NULL) > 0)
301 /* So, we require input */
303 ENGINEerr(ENGINE_F_ENGINE_CTRL_CMD_STRING,
304 ENGINE_R_COMMAND_TAKES_INPUT);
307 /* If it takes string input, that's easy */
308 if (flags & ENGINE_CMD_FLAG_STRING) {
309 /* Same explanation as above */
310 if (ENGINE_ctrl(e, num, 0, (void *)arg, NULL) > 0)
315 * If it doesn't take numeric either, then it is unsupported for use in a
316 * config-setting situation, which is what this function is for. This
317 * should never happen though, because ENGINE_cmd_is_executable() was
320 if (!(flags & ENGINE_CMD_FLAG_NUMERIC)) {
321 ENGINEerr(ENGINE_F_ENGINE_CTRL_CMD_STRING,
322 ENGINE_R_INTERNAL_LIST_ERROR);
325 l = strtol(arg, &ptr, 10);
326 if ((arg == ptr) || (*ptr != '\0')) {
327 ENGINEerr(ENGINE_F_ENGINE_CTRL_CMD_STRING,
328 ENGINE_R_ARGUMENT_IS_NOT_A_NUMBER);
332 * Force the result of the control command to 0 or 1, for the reasons
335 if (ENGINE_ctrl(e, num, l, NULL, NULL) > 0)