crypto/engine/eng_ctrl.c

   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
  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
  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
  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
  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
 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
 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
 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
 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 }