A local copy of OpenSSL from GitHub
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

757 lines
34 KiB

Some BIG tweaks to ENGINE code. This change adds some new functionality to the ENGINE code and API to make it possible for ENGINEs to describe and implement their own control commands that can be interrogated and used by calling applications at run-time. The source code includes numerous comments explaining how it all works and some of the finer details. But basically, an ENGINE will normally declare an array of ENGINE_CMD_DEFN entries in its ENGINE - and the various new ENGINE_CTRL_*** command types take care of iterating through this list of definitions, converting command numbers to names, command names to numbers, getting descriptions, getting input flags, etc. These administrative commands are handled directly in the base ENGINE code rather than in each ENGINE's ctrl() handler, unless they specify the ENGINE_FLAGS_MANUAL_CMD_CTRL flag (ie. if they're doing something clever or dynamic with the command definitions). There is also a new function, ENGINE_cmd_is_executable(), that will determine if an ENGINE control command is of an "executable" type that can be used in another new function, ENGINE_ctrl_cmd_string(). If not, the control command is not supposed to be exposed out to user/config level access - eg. it could involve the exchange of binary data, returning results to calling code, etc etc. If the command is executable then ENGINE_ctrl_cmd_string() can be called using a name/arg string pair. The control command's input flags will be used to determine necessary conversions before the control command is called, and commands of this form will always return zero or one (failure or success, respectively). This is set up so that arbitrary applications can support control commands in a consistent way so that tweaking particular ENGINE behaviour is specific to the ENGINE and the host environment, and independant of the application or OpenSSL. Some code demonstrating this stuff in action will applied shortly to the various ENGINE implementations, as well as "openssl engine" support for executing arbitrary control commands before and/or after initialising various ENGINEs.
22 years ago
Some BIG tweaks to ENGINE code. This change adds some new functionality to the ENGINE code and API to make it possible for ENGINEs to describe and implement their own control commands that can be interrogated and used by calling applications at run-time. The source code includes numerous comments explaining how it all works and some of the finer details. But basically, an ENGINE will normally declare an array of ENGINE_CMD_DEFN entries in its ENGINE - and the various new ENGINE_CTRL_*** command types take care of iterating through this list of definitions, converting command numbers to names, command names to numbers, getting descriptions, getting input flags, etc. These administrative commands are handled directly in the base ENGINE code rather than in each ENGINE's ctrl() handler, unless they specify the ENGINE_FLAGS_MANUAL_CMD_CTRL flag (ie. if they're doing something clever or dynamic with the command definitions). There is also a new function, ENGINE_cmd_is_executable(), that will determine if an ENGINE control command is of an "executable" type that can be used in another new function, ENGINE_ctrl_cmd_string(). If not, the control command is not supposed to be exposed out to user/config level access - eg. it could involve the exchange of binary data, returning results to calling code, etc etc. If the command is executable then ENGINE_ctrl_cmd_string() can be called using a name/arg string pair. The control command's input flags will be used to determine necessary conversions before the control command is called, and commands of this form will always return zero or one (failure or success, respectively). This is set up so that arbitrary applications can support control commands in a consistent way so that tweaking particular ENGINE behaviour is specific to the ENGINE and the host environment, and independant of the application or OpenSSL. Some code demonstrating this stuff in action will applied shortly to the various ENGINE implementations, as well as "openssl engine" support for executing arbitrary control commands before and/or after initialising various ENGINEs.
22 years ago
Some BIG tweaks to ENGINE code. This change adds some new functionality to the ENGINE code and API to make it possible for ENGINEs to describe and implement their own control commands that can be interrogated and used by calling applications at run-time. The source code includes numerous comments explaining how it all works and some of the finer details. But basically, an ENGINE will normally declare an array of ENGINE_CMD_DEFN entries in its ENGINE - and the various new ENGINE_CTRL_*** command types take care of iterating through this list of definitions, converting command numbers to names, command names to numbers, getting descriptions, getting input flags, etc. These administrative commands are handled directly in the base ENGINE code rather than in each ENGINE's ctrl() handler, unless they specify the ENGINE_FLAGS_MANUAL_CMD_CTRL flag (ie. if they're doing something clever or dynamic with the command definitions). There is also a new function, ENGINE_cmd_is_executable(), that will determine if an ENGINE control command is of an "executable" type that can be used in another new function, ENGINE_ctrl_cmd_string(). If not, the control command is not supposed to be exposed out to user/config level access - eg. it could involve the exchange of binary data, returning results to calling code, etc etc. If the command is executable then ENGINE_ctrl_cmd_string() can be called using a name/arg string pair. The control command's input flags will be used to determine necessary conversions before the control command is called, and commands of this form will always return zero or one (failure or success, respectively). This is set up so that arbitrary applications can support control commands in a consistent way so that tweaking particular ENGINE behaviour is specific to the ENGINE and the host environment, and independant of the application or OpenSSL. Some code demonstrating this stuff in action will applied shortly to the various ENGINE implementations, as well as "openssl engine" support for executing arbitrary control commands before and/or after initialising various ENGINEs.
22 years ago
Some BIG tweaks to ENGINE code. This change adds some new functionality to the ENGINE code and API to make it possible for ENGINEs to describe and implement their own control commands that can be interrogated and used by calling applications at run-time. The source code includes numerous comments explaining how it all works and some of the finer details. But basically, an ENGINE will normally declare an array of ENGINE_CMD_DEFN entries in its ENGINE - and the various new ENGINE_CTRL_*** command types take care of iterating through this list of definitions, converting command numbers to names, command names to numbers, getting descriptions, getting input flags, etc. These administrative commands are handled directly in the base ENGINE code rather than in each ENGINE's ctrl() handler, unless they specify the ENGINE_FLAGS_MANUAL_CMD_CTRL flag (ie. if they're doing something clever or dynamic with the command definitions). There is also a new function, ENGINE_cmd_is_executable(), that will determine if an ENGINE control command is of an "executable" type that can be used in another new function, ENGINE_ctrl_cmd_string(). If not, the control command is not supposed to be exposed out to user/config level access - eg. it could involve the exchange of binary data, returning results to calling code, etc etc. If the command is executable then ENGINE_ctrl_cmd_string() can be called using a name/arg string pair. The control command's input flags will be used to determine necessary conversions before the control command is called, and commands of this form will always return zero or one (failure or success, respectively). This is set up so that arbitrary applications can support control commands in a consistent way so that tweaking particular ENGINE behaviour is specific to the ENGINE and the host environment, and independant of the application or OpenSSL. Some code demonstrating this stuff in action will applied shortly to the various ENGINE implementations, as well as "openssl engine" support for executing arbitrary control commands before and/or after initialising various ENGINEs.
22 years ago
Some BIG tweaks to ENGINE code. This change adds some new functionality to the ENGINE code and API to make it possible for ENGINEs to describe and implement their own control commands that can be interrogated and used by calling applications at run-time. The source code includes numerous comments explaining how it all works and some of the finer details. But basically, an ENGINE will normally declare an array of ENGINE_CMD_DEFN entries in its ENGINE - and the various new ENGINE_CTRL_*** command types take care of iterating through this list of definitions, converting command numbers to names, command names to numbers, getting descriptions, getting input flags, etc. These administrative commands are handled directly in the base ENGINE code rather than in each ENGINE's ctrl() handler, unless they specify the ENGINE_FLAGS_MANUAL_CMD_CTRL flag (ie. if they're doing something clever or dynamic with the command definitions). There is also a new function, ENGINE_cmd_is_executable(), that will determine if an ENGINE control command is of an "executable" type that can be used in another new function, ENGINE_ctrl_cmd_string(). If not, the control command is not supposed to be exposed out to user/config level access - eg. it could involve the exchange of binary data, returning results to calling code, etc etc. If the command is executable then ENGINE_ctrl_cmd_string() can be called using a name/arg string pair. The control command's input flags will be used to determine necessary conversions before the control command is called, and commands of this form will always return zero or one (failure or success, respectively). This is set up so that arbitrary applications can support control commands in a consistent way so that tweaking particular ENGINE behaviour is specific to the ENGINE and the host environment, and independant of the application or OpenSSL. Some code demonstrating this stuff in action will applied shortly to the various ENGINE implementations, as well as "openssl engine" support for executing arbitrary control commands before and/or after initialising various ENGINEs.
22 years ago
Some BIG tweaks to ENGINE code. This change adds some new functionality to the ENGINE code and API to make it possible for ENGINEs to describe and implement their own control commands that can be interrogated and used by calling applications at run-time. The source code includes numerous comments explaining how it all works and some of the finer details. But basically, an ENGINE will normally declare an array of ENGINE_CMD_DEFN entries in its ENGINE - and the various new ENGINE_CTRL_*** command types take care of iterating through this list of definitions, converting command numbers to names, command names to numbers, getting descriptions, getting input flags, etc. These administrative commands are handled directly in the base ENGINE code rather than in each ENGINE's ctrl() handler, unless they specify the ENGINE_FLAGS_MANUAL_CMD_CTRL flag (ie. if they're doing something clever or dynamic with the command definitions). There is also a new function, ENGINE_cmd_is_executable(), that will determine if an ENGINE control command is of an "executable" type that can be used in another new function, ENGINE_ctrl_cmd_string(). If not, the control command is not supposed to be exposed out to user/config level access - eg. it could involve the exchange of binary data, returning results to calling code, etc etc. If the command is executable then ENGINE_ctrl_cmd_string() can be called using a name/arg string pair. The control command's input flags will be used to determine necessary conversions before the control command is called, and commands of this form will always return zero or one (failure or success, respectively). This is set up so that arbitrary applications can support control commands in a consistent way so that tweaking particular ENGINE behaviour is specific to the ENGINE and the host environment, and independant of the application or OpenSSL. Some code demonstrating this stuff in action will applied shortly to the various ENGINE implementations, as well as "openssl engine" support for executing arbitrary control commands before and/or after initialising various ENGINEs.
22 years ago
Some BIG tweaks to ENGINE code. This change adds some new functionality to the ENGINE code and API to make it possible for ENGINEs to describe and implement their own control commands that can be interrogated and used by calling applications at run-time. The source code includes numerous comments explaining how it all works and some of the finer details. But basically, an ENGINE will normally declare an array of ENGINE_CMD_DEFN entries in its ENGINE - and the various new ENGINE_CTRL_*** command types take care of iterating through this list of definitions, converting command numbers to names, command names to numbers, getting descriptions, getting input flags, etc. These administrative commands are handled directly in the base ENGINE code rather than in each ENGINE's ctrl() handler, unless they specify the ENGINE_FLAGS_MANUAL_CMD_CTRL flag (ie. if they're doing something clever or dynamic with the command definitions). There is also a new function, ENGINE_cmd_is_executable(), that will determine if an ENGINE control command is of an "executable" type that can be used in another new function, ENGINE_ctrl_cmd_string(). If not, the control command is not supposed to be exposed out to user/config level access - eg. it could involve the exchange of binary data, returning results to calling code, etc etc. If the command is executable then ENGINE_ctrl_cmd_string() can be called using a name/arg string pair. The control command's input flags will be used to determine necessary conversions before the control command is called, and commands of this form will always return zero or one (failure or success, respectively). This is set up so that arbitrary applications can support control commands in a consistent way so that tweaking particular ENGINE behaviour is specific to the ENGINE and the host environment, and independant of the application or OpenSSL. Some code demonstrating this stuff in action will applied shortly to the various ENGINE implementations, as well as "openssl engine" support for executing arbitrary control commands before and/or after initialising various ENGINEs.
22 years ago
Some BIG tweaks to ENGINE code. This change adds some new functionality to the ENGINE code and API to make it possible for ENGINEs to describe and implement their own control commands that can be interrogated and used by calling applications at run-time. The source code includes numerous comments explaining how it all works and some of the finer details. But basically, an ENGINE will normally declare an array of ENGINE_CMD_DEFN entries in its ENGINE - and the various new ENGINE_CTRL_*** command types take care of iterating through this list of definitions, converting command numbers to names, command names to numbers, getting descriptions, getting input flags, etc. These administrative commands are handled directly in the base ENGINE code rather than in each ENGINE's ctrl() handler, unless they specify the ENGINE_FLAGS_MANUAL_CMD_CTRL flag (ie. if they're doing something clever or dynamic with the command definitions). There is also a new function, ENGINE_cmd_is_executable(), that will determine if an ENGINE control command is of an "executable" type that can be used in another new function, ENGINE_ctrl_cmd_string(). If not, the control command is not supposed to be exposed out to user/config level access - eg. it could involve the exchange of binary data, returning results to calling code, etc etc. If the command is executable then ENGINE_ctrl_cmd_string() can be called using a name/arg string pair. The control command's input flags will be used to determine necessary conversions before the control command is called, and commands of this form will always return zero or one (failure or success, respectively). This is set up so that arbitrary applications can support control commands in a consistent way so that tweaking particular ENGINE behaviour is specific to the ENGINE and the host environment, and independant of the application or OpenSSL. Some code demonstrating this stuff in action will applied shortly to the various ENGINE implementations, as well as "openssl engine" support for executing arbitrary control commands before and/or after initialising various ENGINEs.
22 years ago
Some BIG tweaks to ENGINE code. This change adds some new functionality to the ENGINE code and API to make it possible for ENGINEs to describe and implement their own control commands that can be interrogated and used by calling applications at run-time. The source code includes numerous comments explaining how it all works and some of the finer details. But basically, an ENGINE will normally declare an array of ENGINE_CMD_DEFN entries in its ENGINE - and the various new ENGINE_CTRL_*** command types take care of iterating through this list of definitions, converting command numbers to names, command names to numbers, getting descriptions, getting input flags, etc. These administrative commands are handled directly in the base ENGINE code rather than in each ENGINE's ctrl() handler, unless they specify the ENGINE_FLAGS_MANUAL_CMD_CTRL flag (ie. if they're doing something clever or dynamic with the command definitions). There is also a new function, ENGINE_cmd_is_executable(), that will determine if an ENGINE control command is of an "executable" type that can be used in another new function, ENGINE_ctrl_cmd_string(). If not, the control command is not supposed to be exposed out to user/config level access - eg. it could involve the exchange of binary data, returning results to calling code, etc etc. If the command is executable then ENGINE_ctrl_cmd_string() can be called using a name/arg string pair. The control command's input flags will be used to determine necessary conversions before the control command is called, and commands of this form will always return zero or one (failure or success, respectively). This is set up so that arbitrary applications can support control commands in a consistent way so that tweaking particular ENGINE behaviour is specific to the ENGINE and the host environment, and independant of the application or OpenSSL. Some code demonstrating this stuff in action will applied shortly to the various ENGINE implementations, as well as "openssl engine" support for executing arbitrary control commands before and/or after initialising various ENGINEs.
22 years ago
Some BIG tweaks to ENGINE code. This change adds some new functionality to the ENGINE code and API to make it possible for ENGINEs to describe and implement their own control commands that can be interrogated and used by calling applications at run-time. The source code includes numerous comments explaining how it all works and some of the finer details. But basically, an ENGINE will normally declare an array of ENGINE_CMD_DEFN entries in its ENGINE - and the various new ENGINE_CTRL_*** command types take care of iterating through this list of definitions, converting command numbers to names, command names to numbers, getting descriptions, getting input flags, etc. These administrative commands are handled directly in the base ENGINE code rather than in each ENGINE's ctrl() handler, unless they specify the ENGINE_FLAGS_MANUAL_CMD_CTRL flag (ie. if they're doing something clever or dynamic with the command definitions). There is also a new function, ENGINE_cmd_is_executable(), that will determine if an ENGINE control command is of an "executable" type that can be used in another new function, ENGINE_ctrl_cmd_string(). If not, the control command is not supposed to be exposed out to user/config level access - eg. it could involve the exchange of binary data, returning results to calling code, etc etc. If the command is executable then ENGINE_ctrl_cmd_string() can be called using a name/arg string pair. The control command's input flags will be used to determine necessary conversions before the control command is called, and commands of this form will always return zero or one (failure or success, respectively). This is set up so that arbitrary applications can support control commands in a consistent way so that tweaking particular ENGINE behaviour is specific to the ENGINE and the host environment, and independant of the application or OpenSSL. Some code demonstrating this stuff in action will applied shortly to the various ENGINE implementations, as well as "openssl engine" support for executing arbitrary control commands before and/or after initialising various ENGINEs.
22 years ago
Some BIG tweaks to ENGINE code. This change adds some new functionality to the ENGINE code and API to make it possible for ENGINEs to describe and implement their own control commands that can be interrogated and used by calling applications at run-time. The source code includes numerous comments explaining how it all works and some of the finer details. But basically, an ENGINE will normally declare an array of ENGINE_CMD_DEFN entries in its ENGINE - and the various new ENGINE_CTRL_*** command types take care of iterating through this list of definitions, converting command numbers to names, command names to numbers, getting descriptions, getting input flags, etc. These administrative commands are handled directly in the base ENGINE code rather than in each ENGINE's ctrl() handler, unless they specify the ENGINE_FLAGS_MANUAL_CMD_CTRL flag (ie. if they're doing something clever or dynamic with the command definitions). There is also a new function, ENGINE_cmd_is_executable(), that will determine if an ENGINE control command is of an "executable" type that can be used in another new function, ENGINE_ctrl_cmd_string(). If not, the control command is not supposed to be exposed out to user/config level access - eg. it could involve the exchange of binary data, returning results to calling code, etc etc. If the command is executable then ENGINE_ctrl_cmd_string() can be called using a name/arg string pair. The control command's input flags will be used to determine necessary conversions before the control command is called, and commands of this form will always return zero or one (failure or success, respectively). This is set up so that arbitrary applications can support control commands in a consistent way so that tweaking particular ENGINE behaviour is specific to the ENGINE and the host environment, and independant of the application or OpenSSL. Some code demonstrating this stuff in action will applied shortly to the various ENGINE implementations, as well as "openssl engine" support for executing arbitrary control commands before and/or after initialising various ENGINEs.
22 years ago
Some BIG tweaks to ENGINE code. This change adds some new functionality to the ENGINE code and API to make it possible for ENGINEs to describe and implement their own control commands that can be interrogated and used by calling applications at run-time. The source code includes numerous comments explaining how it all works and some of the finer details. But basically, an ENGINE will normally declare an array of ENGINE_CMD_DEFN entries in its ENGINE - and the various new ENGINE_CTRL_*** command types take care of iterating through this list of definitions, converting command numbers to names, command names to numbers, getting descriptions, getting input flags, etc. These administrative commands are handled directly in the base ENGINE code rather than in each ENGINE's ctrl() handler, unless they specify the ENGINE_FLAGS_MANUAL_CMD_CTRL flag (ie. if they're doing something clever or dynamic with the command definitions). There is also a new function, ENGINE_cmd_is_executable(), that will determine if an ENGINE control command is of an "executable" type that can be used in another new function, ENGINE_ctrl_cmd_string(). If not, the control command is not supposed to be exposed out to user/config level access - eg. it could involve the exchange of binary data, returning results to calling code, etc etc. If the command is executable then ENGINE_ctrl_cmd_string() can be called using a name/arg string pair. The control command's input flags will be used to determine necessary conversions before the control command is called, and commands of this form will always return zero or one (failure or success, respectively). This is set up so that arbitrary applications can support control commands in a consistent way so that tweaking particular ENGINE behaviour is specific to the ENGINE and the host environment, and independant of the application or OpenSSL. Some code demonstrating this stuff in action will applied shortly to the various ENGINE implementations, as well as "openssl engine" support for executing arbitrary control commands before and/or after initialising various ENGINEs.
22 years ago
Some BIG tweaks to ENGINE code. This change adds some new functionality to the ENGINE code and API to make it possible for ENGINEs to describe and implement their own control commands that can be interrogated and used by calling applications at run-time. The source code includes numerous comments explaining how it all works and some of the finer details. But basically, an ENGINE will normally declare an array of ENGINE_CMD_DEFN entries in its ENGINE - and the various new ENGINE_CTRL_*** command types take care of iterating through this list of definitions, converting command numbers to names, command names to numbers, getting descriptions, getting input flags, etc. These administrative commands are handled directly in the base ENGINE code rather than in each ENGINE's ctrl() handler, unless they specify the ENGINE_FLAGS_MANUAL_CMD_CTRL flag (ie. if they're doing something clever or dynamic with the command definitions). There is also a new function, ENGINE_cmd_is_executable(), that will determine if an ENGINE control command is of an "executable" type that can be used in another new function, ENGINE_ctrl_cmd_string(). If not, the control command is not supposed to be exposed out to user/config level access - eg. it could involve the exchange of binary data, returning results to calling code, etc etc. If the command is executable then ENGINE_ctrl_cmd_string() can be called using a name/arg string pair. The control command's input flags will be used to determine necessary conversions before the control command is called, and commands of this form will always return zero or one (failure or success, respectively). This is set up so that arbitrary applications can support control commands in a consistent way so that tweaking particular ENGINE behaviour is specific to the ENGINE and the host environment, and independant of the application or OpenSSL. Some code demonstrating this stuff in action will applied shortly to the various ENGINE implementations, as well as "openssl engine" support for executing arbitrary control commands before and/or after initialising various ENGINEs.
22 years ago
  1. /*
  2. * Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
  3. *
  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
  8. */
  9. /* ====================================================================
  10. * Copyright 2002 Sun Microsystems, Inc. ALL RIGHTS RESERVED.
  11. * ECDH support in OpenSSL originally developed by
  12. * SUN MICROSYSTEMS, INC., and contributed to the OpenSSL project.
  13. */
  14. #ifndef HEADER_ENGINE_H
  15. # define HEADER_ENGINE_H
  16. # include <openssl/opensslconf.h>
  17. # ifndef OPENSSL_NO_ENGINE
  18. # if OPENSSL_API_COMPAT < 0x10100000L
  19. # include <openssl/bn.h>
  20. # include <openssl/rsa.h>
  21. # include <openssl/dsa.h>
  22. # include <openssl/dh.h>
  23. # include <openssl/ec.h>
  24. # include <openssl/rand.h>
  25. # include <openssl/ui.h>
  26. # include <openssl/err.h>
  27. # endif
  28. # include <openssl/ossl_typ.h>
  29. # include <openssl/symhacks.h>
  30. # include <openssl/x509.h>
  31. # include <openssl/engineerr.h>
  32. # ifdef __cplusplus
  33. extern "C" {
  34. # endif
  35. /*
  36. * These flags are used to control combinations of algorithm (methods) by
  37. * bitwise "OR"ing.
  38. */
  39. # define ENGINE_METHOD_RSA (unsigned int)0x0001
  40. # define ENGINE_METHOD_DSA (unsigned int)0x0002
  41. # define ENGINE_METHOD_DH (unsigned int)0x0004
  42. # define ENGINE_METHOD_RAND (unsigned int)0x0008
  43. # define ENGINE_METHOD_CIPHERS (unsigned int)0x0040
  44. # define ENGINE_METHOD_DIGESTS (unsigned int)0x0080
  45. # define ENGINE_METHOD_PKEY_METHS (unsigned int)0x0200
  46. # define ENGINE_METHOD_PKEY_ASN1_METHS (unsigned int)0x0400
  47. # define ENGINE_METHOD_EC (unsigned int)0x0800
  48. /* Obvious all-or-nothing cases. */
  49. # define ENGINE_METHOD_ALL (unsigned int)0xFFFF
  50. # define ENGINE_METHOD_NONE (unsigned int)0x0000
  51. /*
  52. * This(ese) flag(s) controls behaviour of the ENGINE_TABLE mechanism used
  53. * internally to control registration of ENGINE implementations, and can be
  54. * set by ENGINE_set_table_flags(). The "NOINIT" flag prevents attempts to
  55. * initialise registered ENGINEs if they are not already initialised.
  56. */
  57. # define ENGINE_TABLE_FLAG_NOINIT (unsigned int)0x0001
  58. /* ENGINE flags that can be set by ENGINE_set_flags(). */
  59. /* Not used */
  60. /* #define ENGINE_FLAGS_MALLOCED 0x0001 */
  61. /*
  62. * This flag is for ENGINEs that wish to handle the various 'CMD'-related
  63. * control commands on their own. Without this flag, ENGINE_ctrl() handles
  64. * these control commands on behalf of the ENGINE using their "cmd_defns"
  65. * data.
  66. */
  67. # define ENGINE_FLAGS_MANUAL_CMD_CTRL (int)0x0002
  68. /*
  69. * This flag is for ENGINEs who return new duplicate structures when found
  70. * via "ENGINE_by_id()". When an ENGINE must store state (eg. if
  71. * ENGINE_ctrl() commands are called in sequence as part of some stateful
  72. * process like key-generation setup and execution), it can set this flag -
  73. * then each attempt to obtain the ENGINE will result in it being copied into
  74. * a new structure. Normally, ENGINEs don't declare this flag so
  75. * ENGINE_by_id() just increments the existing ENGINE's structural reference
  76. * count.
  77. */
  78. # define ENGINE_FLAGS_BY_ID_COPY (int)0x0004
  79. /*
  80. * This flag if for an ENGINE that does not want its methods registered as
  81. * part of ENGINE_register_all_complete() for example if the methods are not
  82. * usable as default methods.
  83. */
  84. # define ENGINE_FLAGS_NO_REGISTER_ALL (int)0x0008
  85. /*
  86. * ENGINEs can support their own command types, and these flags are used in
  87. * ENGINE_CTRL_GET_CMD_FLAGS to indicate to the caller what kind of input
  88. * each command expects. Currently only numeric and string input is
  89. * supported. If a control command supports none of the _NUMERIC, _STRING, or
  90. * _NO_INPUT options, then it is regarded as an "internal" control command -
  91. * and not for use in config setting situations. As such, they're not
  92. * available to the ENGINE_ctrl_cmd_string() function, only raw ENGINE_ctrl()
  93. * access. Changes to this list of 'command types' should be reflected
  94. * carefully in ENGINE_cmd_is_executable() and ENGINE_ctrl_cmd_string().
  95. */
  96. /* accepts a 'long' input value (3rd parameter to ENGINE_ctrl) */
  97. # define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001
  98. /*
  99. * accepts string input (cast from 'void*' to 'const char *', 4th parameter
  100. * to ENGINE_ctrl)
  101. */
  102. # define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002
  103. /*
  104. * Indicates that the control command takes *no* input. Ie. the control
  105. * command is unparameterised.
  106. */
  107. # define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004
  108. /*
  109. * Indicates that the control command is internal. This control command won't
  110. * be shown in any output, and is only usable through the ENGINE_ctrl_cmd()
  111. * function.
  112. */
  113. # define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008
  114. /*
  115. * NB: These 3 control commands are deprecated and should not be used.
  116. * ENGINEs relying on these commands should compile conditional support for
  117. * compatibility (eg. if these symbols are defined) but should also migrate
  118. * the same functionality to their own ENGINE-specific control functions that
  119. * can be "discovered" by calling applications. The fact these control
  120. * commands wouldn't be "executable" (ie. usable by text-based config)
  121. * doesn't change the fact that application code can find and use them
  122. * without requiring per-ENGINE hacking.
  123. */
  124. /*
  125. * These flags are used to tell the ctrl function what should be done. All
  126. * command numbers are shared between all engines, even if some don't make
  127. * sense to some engines. In such a case, they do nothing but return the
  128. * error ENGINE_R_CTRL_COMMAND_NOT_IMPLEMENTED.
  129. */
  130. # define ENGINE_CTRL_SET_LOGSTREAM 1
  131. # define ENGINE_CTRL_SET_PASSWORD_CALLBACK 2
  132. # define ENGINE_CTRL_HUP 3/* Close and reinitialise
  133. * any handles/connections
  134. * etc. */
  135. # define ENGINE_CTRL_SET_USER_INTERFACE 4/* Alternative to callback */
  136. # define ENGINE_CTRL_SET_CALLBACK_DATA 5/* User-specific data, used
  137. * when calling the password
  138. * callback and the user
  139. * interface */
  140. # define ENGINE_CTRL_LOAD_CONFIGURATION 6/* Load a configuration,
  141. * given a string that
  142. * represents a file name
  143. * or so */
  144. # define ENGINE_CTRL_LOAD_SECTION 7/* Load data from a given
  145. * section in the already
  146. * loaded configuration */
  147. /*
  148. * These control commands allow an application to deal with an arbitrary
  149. * engine in a dynamic way. Warn: Negative return values indicate errors FOR
  150. * THESE COMMANDS because zero is used to indicate 'end-of-list'. Other
  151. * commands, including ENGINE-specific command types, return zero for an
  152. * error. An ENGINE can choose to implement these ctrl functions, and can
  153. * internally manage things however it chooses - it does so by setting the
  154. * ENGINE_FLAGS_MANUAL_CMD_CTRL flag (using ENGINE_set_flags()). Otherwise
  155. * the ENGINE_ctrl() code handles this on the ENGINE's behalf using the
  156. * cmd_defns data (set using ENGINE_set_cmd_defns()). This means an ENGINE's
  157. * ctrl() handler need only implement its own commands - the above "meta"
  158. * commands will be taken care of.
  159. */
  160. /*
  161. * Returns non-zero if the supplied ENGINE has a ctrl() handler. If "not",
  162. * then all the remaining control commands will return failure, so it is
  163. * worth checking this first if the caller is trying to "discover" the
  164. * engine's capabilities and doesn't want errors generated unnecessarily.
  165. */
  166. # define ENGINE_CTRL_HAS_CTRL_FUNCTION 10
  167. /*
  168. * Returns a positive command number for the first command supported by the
  169. * engine. Returns zero if no ctrl commands are supported.
  170. */
  171. # define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11
  172. /*
  173. * The 'long' argument specifies a command implemented by the engine, and the
  174. * return value is the next command supported, or zero if there are no more.
  175. */
  176. # define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12
  177. /*
  178. * The 'void*' argument is a command name (cast from 'const char *'), and the
  179. * return value is the command that corresponds to it.
  180. */
  181. # define ENGINE_CTRL_GET_CMD_FROM_NAME 13
  182. /*
  183. * The next two allow a command to be converted into its corresponding string
  184. * form. In each case, the 'long' argument supplies the command. In the
  185. * NAME_LEN case, the return value is the length of the command name (not
  186. * counting a trailing EOL). In the NAME case, the 'void*' argument must be a
  187. * string buffer large enough, and it will be populated with the name of the
  188. * command (WITH a trailing EOL).
  189. */
  190. # define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14
  191. # define ENGINE_CTRL_GET_NAME_FROM_CMD 15
  192. /* The next two are similar but give a "short description" of a command. */
  193. # define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16
  194. # define ENGINE_CTRL_GET_DESC_FROM_CMD 17
  195. /*
  196. * With this command, the return value is the OR'd combination of
  197. * ENGINE_CMD_FLAG_*** values that indicate what kind of input a given
  198. * engine-specific ctrl command expects.
  199. */
  200. # define ENGINE_CTRL_GET_CMD_FLAGS 18
  201. /*
  202. * ENGINE implementations should start the numbering of their own control
  203. * commands from this value. (ie. ENGINE_CMD_BASE, ENGINE_CMD_BASE + 1, etc).
  204. */
  205. # define ENGINE_CMD_BASE 200
  206. /*
  207. * NB: These 2 nCipher "chil" control commands are deprecated, and their
  208. * functionality is now available through ENGINE-specific control commands
  209. * (exposed through the above-mentioned 'CMD'-handling). Code using these 2
  210. * commands should be migrated to the more general command handling before
  211. * these are removed.
  212. */
  213. /* Flags specific to the nCipher "chil" engine */
  214. # define ENGINE_CTRL_CHIL_SET_FORKCHECK 100
  215. /*
  216. * Depending on the value of the (long)i argument, this sets or
  217. * unsets the SimpleForkCheck flag in the CHIL API to enable or
  218. * disable checking and workarounds for applications that fork().
  219. */
  220. # define ENGINE_CTRL_CHIL_NO_LOCKING 101
  221. /*
  222. * This prevents the initialisation function from providing mutex
  223. * callbacks to the nCipher library.
  224. */
  225. /*
  226. * If an ENGINE supports its own specific control commands and wishes the
  227. * framework to handle the above 'ENGINE_CMD_***'-manipulation commands on
  228. * its behalf, it should supply a null-terminated array of ENGINE_CMD_DEFN
  229. * entries to ENGINE_set_cmd_defns(). It should also implement a ctrl()
  230. * handler that supports the stated commands (ie. the "cmd_num" entries as
  231. * described by the array). NB: The array must be ordered in increasing order
  232. * of cmd_num. "null-terminated" means that the last ENGINE_CMD_DEFN element
  233. * has cmd_num set to zero and/or cmd_name set to NULL.
  234. */
  235. typedef struct ENGINE_CMD_DEFN_st {
  236. unsigned int cmd_num; /* The command number */
  237. const char *cmd_name; /* The command name itself */
  238. const char *cmd_desc; /* A short description of the command */
  239. unsigned int cmd_flags; /* The input the command expects */
  240. } ENGINE_CMD_DEFN;
  241. /* Generic function pointer */
  242. typedef int (*ENGINE_GEN_FUNC_PTR) (void);
  243. /* Generic function pointer taking no arguments */
  244. typedef int (*ENGINE_GEN_INT_FUNC_PTR) (ENGINE *);
  245. /* Specific control function pointer */
  246. typedef int (*ENGINE_CTRL_FUNC_PTR) (ENGINE *, int, long, void *,
  247. void (*f) (void));
  248. /* Generic load_key function pointer */
  249. typedef EVP_PKEY *(*ENGINE_LOAD_KEY_PTR)(ENGINE *, const char *,
  250. UI_METHOD *ui_method,
  251. void *callback_data);
  252. typedef int (*ENGINE_SSL_CLIENT_CERT_PTR) (ENGINE *, SSL *ssl,
  253. STACK_OF(X509_NAME) *ca_dn,
  254. X509 **pcert, EVP_PKEY **pkey,
  255. STACK_OF(X509) **pother,
  256. UI_METHOD *ui_method,
  257. void *callback_data);
  258. /*-
  259. * These callback types are for an ENGINE's handler for cipher and digest logic.
  260. * These handlers have these prototypes;
  261. * int foo(ENGINE *e, const EVP_CIPHER **cipher, const int **nids, int nid);
  262. * int foo(ENGINE *e, const EVP_MD **digest, const int **nids, int nid);
  263. * Looking at how to implement these handlers in the case of cipher support, if
  264. * the framework wants the EVP_CIPHER for 'nid', it will call;
  265. * foo(e, &p_evp_cipher, NULL, nid); (return zero for failure)
  266. * If the framework wants a list of supported 'nid's, it will call;
  267. * foo(e, NULL, &p_nids, 0); (returns number of 'nids' or -1 for error)
  268. */
  269. /*
  270. * Returns to a pointer to the array of supported cipher 'nid's. If the
  271. * second parameter is non-NULL it is set to the size of the returned array.
  272. */
  273. typedef int (*ENGINE_CIPHERS_PTR) (ENGINE *, const EVP_CIPHER **,
  274. const int **, int);
  275. typedef int (*ENGINE_DIGESTS_PTR) (ENGINE *, const EVP_MD **, const int **,
  276. int);
  277. typedef int (*ENGINE_PKEY_METHS_PTR) (ENGINE *, EVP_PKEY_METHOD **,
  278. const int **, int);
  279. typedef int (*ENGINE_PKEY_ASN1_METHS_PTR) (ENGINE *, EVP_PKEY_ASN1_METHOD **,
  280. const int **, int);
  281. /*
  282. * STRUCTURE functions ... all of these functions deal with pointers to
  283. * ENGINE structures where the pointers have a "structural reference". This
  284. * means that their reference is to allowed access to the structure but it
  285. * does not imply that the structure is functional. To simply increment or
  286. * decrement the structural reference count, use ENGINE_by_id and
  287. * ENGINE_free. NB: This is not required when iterating using ENGINE_get_next
  288. * as it will automatically decrement the structural reference count of the
  289. * "current" ENGINE and increment the structural reference count of the
  290. * ENGINE it returns (unless it is NULL).
  291. */
  292. /* Get the first/last "ENGINE" type available. */
  293. ENGINE *ENGINE_get_first(void);
  294. ENGINE *ENGINE_get_last(void);
  295. /* Iterate to the next/previous "ENGINE" type (NULL = end of the list). */
  296. ENGINE *ENGINE_get_next(ENGINE *e);
  297. ENGINE *ENGINE_get_prev(ENGINE *e);
  298. /* Add another "ENGINE" type into the array. */
  299. int ENGINE_add(ENGINE *e);
  300. /* Remove an existing "ENGINE" type from the array. */
  301. int ENGINE_remove(ENGINE *e);
  302. /* Retrieve an engine from the list by its unique "id" value. */
  303. ENGINE *ENGINE_by_id(const char *id);
  304. #if OPENSSL_API_COMPAT < 0x10100000L
  305. # define ENGINE_load_openssl() \
  306. OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_OPENSSL, NULL)
  307. # define ENGINE_load_dynamic() \
  308. OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_DYNAMIC, NULL)
  309. # ifndef OPENSSL_NO_STATIC_ENGINE
  310. # define ENGINE_load_padlock() \
  311. OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_PADLOCK, NULL)
  312. # define ENGINE_load_capi() \
  313. OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_CAPI, NULL)
  314. # define ENGINE_load_afalg() \
  315. OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_AFALG, NULL)
  316. # endif
  317. # define ENGINE_load_cryptodev() \
  318. OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_CRYPTODEV, NULL)
  319. # define ENGINE_load_rdrand() \
  320. OPENSSL_init_crypto(OPENSSL_INIT_ENGINE_RDRAND, NULL)
  321. #endif
  322. void ENGINE_load_builtin_engines(void);
  323. /*
  324. * Get and set global flags (ENGINE_TABLE_FLAG_***) for the implementation
  325. * "registry" handling.
  326. */
  327. unsigned int ENGINE_get_table_flags(void);
  328. void ENGINE_set_table_flags(unsigned int flags);
  329. /*- Manage registration of ENGINEs per "table". For each type, there are 3
  330. * functions;
  331. * ENGINE_register_***(e) - registers the implementation from 'e' (if it has one)
  332. * ENGINE_unregister_***(e) - unregister the implementation from 'e'
  333. * ENGINE_register_all_***() - call ENGINE_register_***() for each 'e' in the list
  334. * Cleanup is automatically registered from each table when required.
  335. */
  336. int ENGINE_register_RSA(ENGINE *e);
  337. void ENGINE_unregister_RSA(ENGINE *e);
  338. void ENGINE_register_all_RSA(void);
  339. int ENGINE_register_DSA(ENGINE *e);
  340. void ENGINE_unregister_DSA(ENGINE *e);
  341. void ENGINE_register_all_DSA(void);
  342. int ENGINE_register_EC(ENGINE *e);
  343. void ENGINE_unregister_EC(ENGINE *e);
  344. void ENGINE_register_all_EC(void);
  345. int ENGINE_register_DH(ENGINE *e);
  346. void ENGINE_unregister_DH(ENGINE *e);
  347. void ENGINE_register_all_DH(void);
  348. int ENGINE_register_RAND(ENGINE *e);
  349. void ENGINE_unregister_RAND(ENGINE *e);
  350. void ENGINE_register_all_RAND(void);
  351. int ENGINE_register_ciphers(ENGINE *e);
  352. void ENGINE_unregister_ciphers(ENGINE *e);
  353. void ENGINE_register_all_ciphers(void);
  354. int ENGINE_register_digests(ENGINE *e);
  355. void ENGINE_unregister_digests(ENGINE *e);
  356. void ENGINE_register_all_digests(void);
  357. int ENGINE_register_pkey_meths(ENGINE *e);
  358. void ENGINE_unregister_pkey_meths(ENGINE *e);
  359. void ENGINE_register_all_pkey_meths(void);
  360. int ENGINE_register_pkey_asn1_meths(ENGINE *e);
  361. void ENGINE_unregister_pkey_asn1_meths(ENGINE *e);
  362. void ENGINE_register_all_pkey_asn1_meths(void);
  363. /*
  364. * These functions register all support from the above categories. Note, use
  365. * of these functions can result in static linkage of code your application
  366. * may not need. If you only need a subset of functionality, consider using
  367. * more selective initialisation.
  368. */
  369. int ENGINE_register_complete(ENGINE *e);
  370. int ENGINE_register_all_complete(void);
  371. /*
  372. * Send parametrised control commands to the engine. The possibilities to
  373. * send down an integer, a pointer to data or a function pointer are
  374. * provided. Any of the parameters may or may not be NULL, depending on the
  375. * command number. In actuality, this function only requires a structural
  376. * (rather than functional) reference to an engine, but many control commands
  377. * may require the engine be functional. The caller should be aware of trying
  378. * commands that require an operational ENGINE, and only use functional
  379. * references in such situations.
  380. */
  381. int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f) (void));
  382. /*
  383. * This function tests if an ENGINE-specific command is usable as a
  384. * "setting". Eg. in an application's config file that gets processed through
  385. * ENGINE_ctrl_cmd_string(). If this returns zero, it is not available to
  386. * ENGINE_ctrl_cmd_string(), only ENGINE_ctrl().
  387. */
  388. int ENGINE_cmd_is_executable(ENGINE *e, int cmd);
  389. /*
  390. * This function works like ENGINE_ctrl() with the exception of taking a
  391. * command name instead of a command number, and can handle optional
  392. * commands. See the comment on ENGINE_ctrl_cmd_string() for an explanation
  393. * on how to use the cmd_name and cmd_optional.
  394. */
  395. int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,
  396. long i, void *p, void (*f) (void), int cmd_optional);
  397. /*
  398. * This function passes a command-name and argument to an ENGINE. The
  399. * cmd_name is converted to a command number and the control command is
  400. * called using 'arg' as an argument (unless the ENGINE doesn't support such
  401. * a command, in which case no control command is called). The command is
  402. * checked for input flags, and if necessary the argument will be converted
  403. * to a numeric value. If cmd_optional is non-zero, then if the ENGINE
  404. * doesn't support the given cmd_name the return value will be success
  405. * anyway. This function is intended for applications to use so that users
  406. * (or config files) can supply engine-specific config data to the ENGINE at
  407. * run-time to control behaviour of specific engines. As such, it shouldn't
  408. * be used for calling ENGINE_ctrl() functions that return data, deal with
  409. * binary data, or that are otherwise supposed to be used directly through
  410. * ENGINE_ctrl() in application code. Any "return" data from an ENGINE_ctrl()
  411. * operation in this function will be lost - the return value is interpreted
  412. * as failure if the return value is zero, success otherwise, and this
  413. * function returns a boolean value as a result. In other words, vendors of
  414. * 'ENGINE'-enabled devices should write ENGINE implementations with
  415. * parameterisations that work in this scheme, so that compliant ENGINE-based
  416. * applications can work consistently with the same configuration for the
  417. * same ENGINE-enabled devices, across applications.
  418. */
  419. int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
  420. int cmd_optional);
  421. /*
  422. * These functions are useful for manufacturing new ENGINE structures. They
  423. * don't address reference counting at all - one uses them to populate an
  424. * ENGINE structure with personalised implementations of things prior to
  425. * using it directly or adding it to the builtin ENGINE list in OpenSSL.
  426. * These are also here so that the ENGINE structure doesn't have to be
  427. * exposed and break binary compatibility!
  428. */
  429. ENGINE *ENGINE_new(void);
  430. int ENGINE_free(ENGINE *e);
  431. int ENGINE_up_ref(ENGINE *e);
  432. int ENGINE_set_id(ENGINE *e, const char *id);
  433. int ENGINE_set_name(ENGINE *e, const char *name);
  434. int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);
  435. int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);
  436. int ENGINE_set_EC(ENGINE *e, const EC_KEY_METHOD *ecdsa_meth);
  437. int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);
  438. int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);
  439. int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f);
  440. int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);
  441. int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);
  442. int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);
  443. int ENGINE_set_load_privkey_function(ENGINE *e,
  444. ENGINE_LOAD_KEY_PTR loadpriv_f);
  445. int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f);
  446. int ENGINE_set_load_ssl_client_cert_function(ENGINE *e,
  447. ENGINE_SSL_CLIENT_CERT_PTR
  448. loadssl_f);
  449. int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);
  450. int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);
  451. int ENGINE_set_pkey_meths(ENGINE *e, ENGINE_PKEY_METHS_PTR f);
  452. int ENGINE_set_pkey_asn1_meths(ENGINE *e, ENGINE_PKEY_ASN1_METHS_PTR f);
  453. int ENGINE_set_flags(ENGINE *e, int flags);
  454. int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);
  455. /* These functions allow control over any per-structure ENGINE data. */
  456. #define ENGINE_get_ex_new_index(l, p, newf, dupf, freef) \
  457. CRYPTO_get_ex_new_index(CRYPTO_EX_INDEX_ENGINE, l, p, newf, dupf, freef)
  458. int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg);
  459. void *ENGINE_get_ex_data(const ENGINE *e, int idx);
  460. #if OPENSSL_API_COMPAT < 0x10100000L
  461. /*
  462. * This function previously cleaned up anything that needs it. Auto-deinit will
  463. * now take care of it so it is no longer required to call this function.
  464. */
  465. # define ENGINE_cleanup() while(0) continue
  466. #endif
  467. /*
  468. * These return values from within the ENGINE structure. These can be useful
  469. * with functional references as well as structural references - it depends
  470. * which you obtained. Using the result for functional purposes if you only
  471. * obtained a structural reference may be problematic!
  472. */
  473. const char *ENGINE_get_id(const ENGINE *e);
  474. const char *ENGINE_get_name(const ENGINE *e);
  475. const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e);
  476. const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e);
  477. const EC_KEY_METHOD *ENGINE_get_EC(const ENGINE *e);
  478. const DH_METHOD *ENGINE_get_DH(const ENGINE *e);
  479. const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e);
  480. ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e);
  481. ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e);
  482. ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e);
  483. ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e);
  484. ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e);
  485. ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e);
  486. ENGINE_SSL_CLIENT_CERT_PTR ENGINE_get_ssl_client_cert_function(const ENGINE
  487. *e);
  488. ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e);
  489. ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e);
  490. ENGINE_PKEY_METHS_PTR ENGINE_get_pkey_meths(const ENGINE *e);
  491. ENGINE_PKEY_ASN1_METHS_PTR ENGINE_get_pkey_asn1_meths(const ENGINE *e);
  492. const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid);
  493. const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid);
  494. const EVP_PKEY_METHOD *ENGINE_get_pkey_meth(ENGINE *e, int nid);
  495. const EVP_PKEY_ASN1_METHOD *ENGINE_get_pkey_asn1_meth(ENGINE *e, int nid);
  496. const EVP_PKEY_ASN1_METHOD *ENGINE_get_pkey_asn1_meth_str(ENGINE *e,
  497. const char *str,
  498. int len);
  499. const EVP_PKEY_ASN1_METHOD *ENGINE_pkey_asn1_find_str(ENGINE **pe,
  500. const char *str,
  501. int len);
  502. const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e);
  503. int ENGINE_get_flags(const ENGINE *e);
  504. /*
  505. * FUNCTIONAL functions. These functions deal with ENGINE structures that
  506. * have (or will) be initialised for use. Broadly speaking, the structural
  507. * functions are useful for iterating the list of available engine types,
  508. * creating new engine types, and other "list" operations. These functions
  509. * actually deal with ENGINEs that are to be used. As such these functions
  510. * can fail (if applicable) when particular engines are unavailable - eg. if
  511. * a hardware accelerator is not attached or not functioning correctly. Each
  512. * ENGINE has 2 reference counts; structural and functional. Every time a
  513. * functional reference is obtained or released, a corresponding structural
  514. * reference is automatically obtained or released too.
  515. */
  516. /*
  517. * Initialise a engine type for use (or up its reference count if it's
  518. * already in use). This will fail if the engine is not currently operational
  519. * and cannot initialise.
  520. */
  521. int ENGINE_init(ENGINE *e);
  522. /*
  523. * Free a functional reference to a engine type. This does not require a
  524. * corresponding call to ENGINE_free as it also releases a structural
  525. * reference.
  526. */
  527. int ENGINE_finish(ENGINE *e);
  528. /*
  529. * The following functions handle keys that are stored in some secondary
  530. * location, handled by the engine. The storage may be on a card or
  531. * whatever.
  532. */
  533. EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,
  534. UI_METHOD *ui_method, void *callback_data);
  535. EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
  536. UI_METHOD *ui_method, void *callback_data);
  537. int ENGINE_load_ssl_client_cert(ENGINE *e, SSL *s,
  538. STACK_OF(X509_NAME) *ca_dn, X509 **pcert,
  539. EVP_PKEY **ppkey, STACK_OF(X509) **pother,
  540. UI_METHOD *ui_method, void *callback_data);
  541. /*
  542. * This returns a pointer for the current ENGINE structure that is (by
  543. * default) performing any RSA operations. The value returned is an
  544. * incremented reference, so it should be free'd (ENGINE_finish) before it is
  545. * discarded.
  546. */
  547. ENGINE *ENGINE_get_default_RSA(void);
  548. /* Same for the other "methods" */
  549. ENGINE *ENGINE_get_default_DSA(void);
  550. ENGINE *ENGINE_get_default_EC(void);
  551. ENGINE *ENGINE_get_default_DH(void);
  552. ENGINE *ENGINE_get_default_RAND(void);
  553. /*
  554. * These functions can be used to get a functional reference to perform
  555. * ciphering or digesting corresponding to "nid".
  556. */
  557. ENGINE *ENGINE_get_cipher_engine(int nid);
  558. ENGINE *ENGINE_get_digest_engine(int nid);
  559. ENGINE *ENGINE_get_pkey_meth_engine(int nid);
  560. ENGINE *ENGINE_get_pkey_asn1_meth_engine(int nid);
  561. /*
  562. * This sets a new default ENGINE structure for performing RSA operations. If
  563. * the result is non-zero (success) then the ENGINE structure will have had
  564. * its reference count up'd so the caller should still free their own
  565. * reference 'e'.
  566. */
  567. int ENGINE_set_default_RSA(ENGINE *e);
  568. int ENGINE_set_default_string(ENGINE *e, const char *def_list);
  569. /* Same for the other "methods" */
  570. int ENGINE_set_default_DSA(ENGINE *e);
  571. int ENGINE_set_default_EC(ENGINE *e);
  572. int ENGINE_set_default_DH(ENGINE *e);
  573. int ENGINE_set_default_RAND(ENGINE *e);
  574. int ENGINE_set_default_ciphers(ENGINE *e);
  575. int ENGINE_set_default_digests(ENGINE *e);
  576. int ENGINE_set_default_pkey_meths(ENGINE *e);
  577. int ENGINE_set_default_pkey_asn1_meths(ENGINE *e);
  578. /*
  579. * The combination "set" - the flags are bitwise "OR"d from the
  580. * ENGINE_METHOD_*** defines above. As with the "ENGINE_register_complete()"
  581. * function, this function can result in unnecessary static linkage. If your
  582. * application requires only specific functionality, consider using more
  583. * selective functions.
  584. */
  585. int ENGINE_set_default(ENGINE *e, unsigned int flags);
  586. void ENGINE_add_conf_module(void);
  587. /* Deprecated functions ... */
  588. /* int ENGINE_clear_defaults(void); */
  589. /**************************/
  590. /* DYNAMIC ENGINE SUPPORT */
  591. /**************************/
  592. /* Binary/behaviour compatibility levels */
  593. # define OSSL_DYNAMIC_VERSION (unsigned long)0x00030000
  594. /*
  595. * Binary versions older than this are too old for us (whether we're a loader
  596. * or a loadee)
  597. */
  598. # define OSSL_DYNAMIC_OLDEST (unsigned long)0x00030000
  599. /*
  600. * When compiling an ENGINE entirely as an external shared library, loadable
  601. * by the "dynamic" ENGINE, these types are needed. The 'dynamic_fns'
  602. * structure type provides the calling application's (or library's) error
  603. * functionality and memory management function pointers to the loaded
  604. * library. These should be used/set in the loaded library code so that the
  605. * loading application's 'state' will be used/changed in all operations. The
  606. * 'static_state' pointer allows the loaded library to know if it shares the
  607. * same static data as the calling application (or library), and thus whether
  608. * these callbacks need to be set or not.
  609. */
  610. typedef void *(*dyn_MEM_malloc_fn) (size_t, const char *, int);
  611. typedef void *(*dyn_MEM_realloc_fn) (void *, size_t, const char *, int);
  612. typedef void (*dyn_MEM_free_fn) (void *, const char *, int);
  613. typedef struct st_dynamic_MEM_fns {
  614. dyn_MEM_malloc_fn malloc_fn;
  615. dyn_MEM_realloc_fn realloc_fn;
  616. dyn_MEM_free_fn free_fn;
  617. } dynamic_MEM_fns;
  618. /*
  619. * FIXME: Perhaps the memory and locking code (crypto.h) should declare and
  620. * use these types so we (and any other dependent code) can simplify a bit??
  621. */
  622. /* The top-level structure */
  623. typedef struct st_dynamic_fns {
  624. void *static_state;
  625. dynamic_MEM_fns mem_fns;
  626. } dynamic_fns;
  627. /*
  628. * The version checking function should be of this prototype. NB: The
  629. * ossl_version value passed in is the OSSL_DYNAMIC_VERSION of the loading
  630. * code. If this function returns zero, it indicates a (potential) version
  631. * incompatibility and the loaded library doesn't believe it can proceed.
  632. * Otherwise, the returned value is the (latest) version supported by the
  633. * loading library. The loader may still decide that the loaded code's
  634. * version is unsatisfactory and could veto the load. The function is
  635. * expected to be implemented with the symbol name "v_check", and a default
  636. * implementation can be fully instantiated with
  637. * IMPLEMENT_DYNAMIC_CHECK_FN().
  638. */
  639. typedef unsigned long (*dynamic_v_check_fn) (unsigned long ossl_version);
  640. # define IMPLEMENT_DYNAMIC_CHECK_FN() \
  641. OPENSSL_EXPORT unsigned long v_check(unsigned long v); \
  642. OPENSSL_EXPORT unsigned long v_check(unsigned long v) { \
  643. if (v >= OSSL_DYNAMIC_OLDEST) return OSSL_DYNAMIC_VERSION; \
  644. return 0; }
  645. /*
  646. * This function is passed the ENGINE structure to initialise with its own
  647. * function and command settings. It should not adjust the structural or
  648. * functional reference counts. If this function returns zero, (a) the load
  649. * will be aborted, (b) the previous ENGINE state will be memcpy'd back onto
  650. * the structure, and (c) the shared library will be unloaded. So
  651. * implementations should do their own internal cleanup in failure
  652. * circumstances otherwise they could leak. The 'id' parameter, if non-NULL,
  653. * represents the ENGINE id that the loader is looking for. If this is NULL,
  654. * the shared library can choose to return failure or to initialise a
  655. * 'default' ENGINE. If non-NULL, the shared library must initialise only an
  656. * ENGINE matching the passed 'id'. The function is expected to be
  657. * implemented with the symbol name "bind_engine". A standard implementation
  658. * can be instantiated with IMPLEMENT_DYNAMIC_BIND_FN(fn) where the parameter
  659. * 'fn' is a callback function that populates the ENGINE structure and
  660. * returns an int value (zero for failure). 'fn' should have prototype;
  661. * [static] int fn(ENGINE *e, const char *id);
  662. */
  663. typedef int (*dynamic_bind_engine) (ENGINE *e, const char *id,
  664. const dynamic_fns *fns);
  665. # define IMPLEMENT_DYNAMIC_BIND_FN(fn) \
  666. OPENSSL_EXPORT \
  667. int bind_engine(ENGINE *e, const char *id, const dynamic_fns *fns); \
  668. OPENSSL_EXPORT \
  669. int bind_engine(ENGINE *e, const char *id, const dynamic_fns *fns) { \
  670. if (ENGINE_get_static_state() == fns->static_state) goto skip_cbs; \
  671. CRYPTO_set_mem_functions(fns->mem_fns.malloc_fn, \
  672. fns->mem_fns.realloc_fn, \
  673. fns->mem_fns.free_fn); \
  674. skip_cbs: \
  675. if (!fn(e, id)) return 0; \
  676. return 1; }
  677. /*
  678. * If the loading application (or library) and the loaded ENGINE library
  679. * share the same static data (eg. they're both dynamically linked to the
  680. * same libcrypto.so) we need a way to avoid trying to set system callbacks -
  681. * this would fail, and for the same reason that it's unnecessary to try. If
  682. * the loaded ENGINE has (or gets from through the loader) its own copy of
  683. * the libcrypto static data, we will need to set the callbacks. The easiest
  684. * way to detect this is to have a function that returns a pointer to some
  685. * static data and let the loading application and loaded ENGINE compare
  686. * their respective values.
  687. */
  688. void *ENGINE_get_static_state(void);
  689. # if defined(__OpenBSD__) || defined(__FreeBSD__) || defined(__DragonFly__)
  690. DEPRECATEDIN_1_1_0(void ENGINE_setup_bsd_cryptodev(void))
  691. # endif
  692. int ERR_load_ENGINE_strings(void);
  693. # ifdef __cplusplus
  694. }
  695. # endif
  696. # endif
  697. #endif