xref: /openssl/crypto/engine/eng_ctrl.c (revision da1c088f)
1 /*
2  * Copyright 2001-2023 The OpenSSL Project Authors. All Rights Reserved.
3  *
4  * Licensed under the Apache License 2.0 (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
8  */
9 
10 /* We need to use some engine deprecated APIs */
11 #define OPENSSL_SUPPRESS_DEPRECATED
12 
13 #include "eng_local.h"
14 
15 /*
16  * When querying a ENGINE-specific control command's 'description', this
17  * string is used if the ENGINE_CMD_DEFN has cmd_desc set to NULL.
18  */
19 static const char *int_no_description = "";
20 
21 /*
22  * These internal functions handle 'CMD'-related control commands when the
23  * ENGINE in question has asked us to take care of it (ie. the ENGINE did not
24  * set the ENGINE_FLAGS_MANUAL_CMD_CTRL flag.
25  */
26 
int_ctrl_cmd_is_null(const ENGINE_CMD_DEFN * defn)27 static int int_ctrl_cmd_is_null(const ENGINE_CMD_DEFN *defn)
28 {
29     if ((defn->cmd_num == 0) || (defn->cmd_name == NULL))
30         return 1;
31     return 0;
32 }
33 
int_ctrl_cmd_by_name(const ENGINE_CMD_DEFN * defn,const char * s)34 static int int_ctrl_cmd_by_name(const ENGINE_CMD_DEFN *defn, const char *s)
35 {
36     int idx = 0;
37     while (!int_ctrl_cmd_is_null(defn) && (strcmp(defn->cmd_name, s) != 0)) {
38         idx++;
39         defn++;
40     }
41     if (int_ctrl_cmd_is_null(defn))
42         /* The given name wasn't found */
43         return -1;
44     return idx;
45 }
46 
int_ctrl_cmd_by_num(const ENGINE_CMD_DEFN * defn,unsigned int num)47 static int int_ctrl_cmd_by_num(const ENGINE_CMD_DEFN *defn, unsigned int num)
48 {
49     int idx = 0;
50     /*
51      * NB: It is stipulated that 'cmd_defn' lists are ordered by cmd_num. So
52      * our searches don't need to take any longer than necessary.
53      */
54     while (!int_ctrl_cmd_is_null(defn) && (defn->cmd_num < num)) {
55         idx++;
56         defn++;
57     }
58     if (defn->cmd_num == num)
59         return idx;
60     /* The given cmd_num wasn't found */
61     return -1;
62 }
63 
int_ctrl_helper(ENGINE * e,int cmd,long i,void * p,void (* f)(void))64 static int int_ctrl_helper(ENGINE *e, int cmd, long i, void *p,
65                            void (*f) (void))
66 {
67     int idx;
68     char *s = (char *)p;
69     const ENGINE_CMD_DEFN *cdp;
70 
71     /* Take care of the easy one first (eg. it requires no searches) */
72     if (cmd == ENGINE_CTRL_GET_FIRST_CMD_TYPE) {
73         if ((e->cmd_defns == NULL) || int_ctrl_cmd_is_null(e->cmd_defns))
74             return 0;
75         return e->cmd_defns->cmd_num;
76     }
77     /* One or two commands require that "p" be a valid string buffer */
78     if ((cmd == ENGINE_CTRL_GET_CMD_FROM_NAME) ||
79         (cmd == ENGINE_CTRL_GET_NAME_FROM_CMD) ||
80         (cmd == ENGINE_CTRL_GET_DESC_FROM_CMD)) {
81         if (s == NULL) {
82             ERR_raise(ERR_LIB_ENGINE, ERR_R_PASSED_NULL_PARAMETER);
83             return -1;
84         }
85     }
86     /* Now handle cmd_name -> cmd_num conversion */
87     if (cmd == ENGINE_CTRL_GET_CMD_FROM_NAME) {
88         if ((e->cmd_defns == NULL)
89             || ((idx = int_ctrl_cmd_by_name(e->cmd_defns, s)) < 0)) {
90             ERR_raise(ERR_LIB_ENGINE, ENGINE_R_INVALID_CMD_NAME);
91             return -1;
92         }
93         return e->cmd_defns[idx].cmd_num;
94     }
95     /*
96      * For the rest of the commands, the 'long' argument must specify a valid
97      * command number - so we need to conduct a search.
98      */
99     if ((e->cmd_defns == NULL)
100         || ((idx = int_ctrl_cmd_by_num(e->cmd_defns, (unsigned int)i)) < 0)) {
101         ERR_raise(ERR_LIB_ENGINE, ENGINE_R_INVALID_CMD_NUMBER);
102         return -1;
103     }
104     /* Now the logic splits depending on command type */
105     cdp = &e->cmd_defns[idx];
106     switch (cmd) {
107     case ENGINE_CTRL_GET_NEXT_CMD_TYPE:
108         cdp++;
109         return int_ctrl_cmd_is_null(cdp) ? 0 : cdp->cmd_num;
110     case ENGINE_CTRL_GET_NAME_LEN_FROM_CMD:
111         return strlen(cdp->cmd_name);
112     case ENGINE_CTRL_GET_NAME_FROM_CMD:
113         return strlen(strcpy(s, cdp->cmd_name));
114     case ENGINE_CTRL_GET_DESC_LEN_FROM_CMD:
115         return strlen(cdp->cmd_desc == NULL ? int_no_description
116                                             : cdp->cmd_desc);
117     case ENGINE_CTRL_GET_DESC_FROM_CMD:
118         return strlen(strcpy(s, cdp->cmd_desc == NULL ? int_no_description
119                                                       : cdp->cmd_desc));
120     case ENGINE_CTRL_GET_CMD_FLAGS:
121         return cdp->cmd_flags;
122     }
123     /* Shouldn't really be here ... */
124     ERR_raise(ERR_LIB_ENGINE, ENGINE_R_INTERNAL_LIST_ERROR);
125     return -1;
126 }
127 
ENGINE_ctrl(ENGINE * e,int cmd,long i,void * p,void (* f)(void))128 int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f) (void))
129 {
130     int ctrl_exists;
131 
132     if (e == NULL) {
133         ERR_raise(ERR_LIB_ENGINE, ERR_R_PASSED_NULL_PARAMETER);
134         return 0;
135     }
136 
137     ctrl_exists = ((e->ctrl == NULL) ? 0 : 1);
138 
139     /*
140      * Intercept any "root-level" commands before trying to hand them on to
141      * ctrl() handlers.
142      */
143     switch (cmd) {
144     case ENGINE_CTRL_HAS_CTRL_FUNCTION:
145         return ctrl_exists;
146     case ENGINE_CTRL_GET_FIRST_CMD_TYPE:
147     case ENGINE_CTRL_GET_NEXT_CMD_TYPE:
148     case ENGINE_CTRL_GET_CMD_FROM_NAME:
149     case ENGINE_CTRL_GET_NAME_LEN_FROM_CMD:
150     case ENGINE_CTRL_GET_NAME_FROM_CMD:
151     case ENGINE_CTRL_GET_DESC_LEN_FROM_CMD:
152     case ENGINE_CTRL_GET_DESC_FROM_CMD:
153     case ENGINE_CTRL_GET_CMD_FLAGS:
154         if (ctrl_exists && !(e->flags & ENGINE_FLAGS_MANUAL_CMD_CTRL))
155             return int_ctrl_helper(e, cmd, i, p, f);
156         if (!ctrl_exists) {
157             ERR_raise(ERR_LIB_ENGINE, ENGINE_R_NO_CONTROL_FUNCTION);
158             /*
159              * For these cmd-related functions, failure is indicated by a -1
160              * return value (because 0 is used as a valid return in some
161              * places).
162              */
163             return -1;
164         }
165     default:
166         break;
167     }
168     /* Anything else requires a ctrl() handler to exist. */
169     if (!ctrl_exists) {
170         ERR_raise(ERR_LIB_ENGINE, ENGINE_R_NO_CONTROL_FUNCTION);
171         return 0;
172     }
173     return e->ctrl(e, cmd, i, p, f);
174 }
175 
ENGINE_cmd_is_executable(ENGINE * e,int cmd)176 int ENGINE_cmd_is_executable(ENGINE *e, int cmd)
177 {
178     int flags;
179     if ((flags =
180          ENGINE_ctrl(e, ENGINE_CTRL_GET_CMD_FLAGS, cmd, NULL, NULL)) < 0) {
181         ERR_raise(ERR_LIB_ENGINE, ENGINE_R_INVALID_CMD_NUMBER);
182         return 0;
183     }
184     if (!(flags & ENGINE_CMD_FLAG_NO_INPUT) &&
185         !(flags & ENGINE_CMD_FLAG_NUMERIC) &&
186         !(flags & ENGINE_CMD_FLAG_STRING))
187         return 0;
188     return 1;
189 }
190 
ENGINE_ctrl_cmd(ENGINE * e,const char * cmd_name,long i,void * p,void (* f)(void),int cmd_optional)191 int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,
192                     long i, void *p, void (*f) (void), int cmd_optional)
193 {
194     int num;
195 
196     if (e == NULL || cmd_name == NULL) {
197         ERR_raise(ERR_LIB_ENGINE, ERR_R_PASSED_NULL_PARAMETER);
198         return 0;
199     }
200     if (e->ctrl == NULL
201         || (num = ENGINE_ctrl(e, ENGINE_CTRL_GET_CMD_FROM_NAME,
202                               0, (void *)cmd_name, NULL)) <= 0) {
203         /*
204          * If the command didn't *have* to be supported, we fake success.
205          * This allows certain settings to be specified for multiple ENGINEs
206          * and only require a change of ENGINE id (without having to
207          * selectively apply settings). Eg. changing from a hardware device
208          * back to the regular software ENGINE without editing the config
209          * file, etc.
210          */
211         if (cmd_optional) {
212             ERR_clear_error();
213             return 1;
214         }
215         ERR_raise(ERR_LIB_ENGINE, ENGINE_R_INVALID_CMD_NAME);
216         return 0;
217     }
218     /*
219      * Force the result of the control command to 0 or 1, for the reasons
220      * mentioned before.
221      */
222     if (ENGINE_ctrl(e, num, i, p, f) > 0)
223         return 1;
224     return 0;
225 }
226 
ENGINE_ctrl_cmd_string(ENGINE * e,const char * cmd_name,const char * arg,int cmd_optional)227 int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
228                            int cmd_optional)
229 {
230     int num, flags;
231     long l;
232     char *ptr;
233 
234     if (e == NULL || cmd_name == NULL) {
235         ERR_raise(ERR_LIB_ENGINE, ERR_R_PASSED_NULL_PARAMETER);
236         return 0;
237     }
238     if (e->ctrl == NULL
239         || (num = ENGINE_ctrl(e, ENGINE_CTRL_GET_CMD_FROM_NAME,
240                               0, (void *)cmd_name, NULL)) <= 0) {
241         /*
242          * If the command didn't *have* to be supported, we fake success.
243          * This allows certain settings to be specified for multiple ENGINEs
244          * and only require a change of ENGINE id (without having to
245          * selectively apply settings). Eg. changing from a hardware device
246          * back to the regular software ENGINE without editing the config
247          * file, etc.
248          */
249         if (cmd_optional) {
250             ERR_clear_error();
251             return 1;
252         }
253         ERR_raise(ERR_LIB_ENGINE, ENGINE_R_INVALID_CMD_NAME);
254         return 0;
255     }
256     if (!ENGINE_cmd_is_executable(e, num)) {
257         ERR_raise(ERR_LIB_ENGINE, ENGINE_R_CMD_NOT_EXECUTABLE);
258         return 0;
259     }
260 
261     flags = ENGINE_ctrl(e, ENGINE_CTRL_GET_CMD_FLAGS, num, NULL, NULL);
262     if (flags < 0) {
263         /*
264          * Shouldn't happen, given that ENGINE_cmd_is_executable() returned
265          * success.
266          */
267         ERR_raise(ERR_LIB_ENGINE, ENGINE_R_INTERNAL_LIST_ERROR);
268         return 0;
269     }
270     /*
271      * If the command takes no input, there must be no input. And vice versa.
272      */
273     if (flags & ENGINE_CMD_FLAG_NO_INPUT) {
274         if (arg != NULL) {
275             ERR_raise(ERR_LIB_ENGINE, ENGINE_R_COMMAND_TAKES_NO_INPUT);
276             return 0;
277         }
278         /*
279          * We deliberately force the result of ENGINE_ctrl() to 0 or 1 rather
280          * than returning it as "return data". This is to ensure usage of
281          * these commands is consistent across applications and that certain
282          * applications don't understand it one way, and others another.
283          */
284         if (ENGINE_ctrl(e, num, 0, (void *)arg, NULL) > 0)
285             return 1;
286         return 0;
287     }
288     /* So, we require input */
289     if (arg == NULL) {
290         ERR_raise(ERR_LIB_ENGINE, ENGINE_R_COMMAND_TAKES_INPUT);
291         return 0;
292     }
293     /* If it takes string input, that's easy */
294     if (flags & ENGINE_CMD_FLAG_STRING) {
295         /* Same explanation as above */
296         if (ENGINE_ctrl(e, num, 0, (void *)arg, NULL) > 0)
297             return 1;
298         return 0;
299     }
300     /*
301      * If it doesn't take numeric either, then it is unsupported for use in a
302      * config-setting situation, which is what this function is for. This
303      * should never happen though, because ENGINE_cmd_is_executable() was
304      * used.
305      */
306     if (!(flags & ENGINE_CMD_FLAG_NUMERIC)) {
307         ERR_raise(ERR_LIB_ENGINE, ENGINE_R_INTERNAL_LIST_ERROR);
308         return 0;
309     }
310     l = strtol(arg, &ptr, 10);
311     if ((arg == ptr) || (*ptr != '\0')) {
312         ERR_raise(ERR_LIB_ENGINE, ENGINE_R_ARGUMENT_IS_NOT_A_NUMBER);
313         return 0;
314     }
315     /*
316      * Force the result of the control command to 0 or 1, for the reasons
317      * mentioned before.
318      */
319     if (ENGINE_ctrl(e, num, l, NULL, NULL) > 0)
320         return 1;
321     return 0;
322 }
323