being enabled or disabled (respectively) for operation. Additionally, each
ENGINE has a constructor function where it can do more 'structural' level
intialisations such as loading error strings, creating "ex_data" indices,
etc. This change introduces a handler function that gives an ENGINE a
corresponding opportunity to cleanup when the ENGINE is being destroyed. It
also adds the "get/set" API functions that control this "destroy" handler
function in an ENGINE.

defined.

(Preprocessor symbols such as _POSIX_C_SOURCE or _XOPEN_SOURCE are
supposed to disable anything not allowed by the respective
specification; I'm not sure why 'strdup' would be considered
an outlaw though.)

locking callbacks to pass to the loaded library (in addition to the
existing mem, ex_data, and err callbacks). Also change the default
implementation of the "bind_engine" function to apply those callbacks, ie.
the IMPLEMENT_DYNAMIC_BIND_FN macro.

declare their own error strings so that they can be more easily compiled as
external shared-libraries if desired. Also, each implementation has been
given canonical "dynamic" support at the base of each file and is only
built if the ENGINE_DYNAMIC_SUPPORT symbol is defined.

Also, use "void" prototypes rather than empty prototypes in engine_int.h.

This does not yet;
  (i) remove error strings when unloading,
 (ii) remove the redundant ENGINE_R_*** codes (though ENGINE_F_*** codes
      have gone), or
(iii) provide any instructions on how to build shared-library ENGINEs or
      use them.

All are on their way.

implementations to be loaded from self-contained shared-libraries. It also
provides (in engine.h) definitions and macros to help implement a
self-contained ENGINE. Version control is handled in a way whereby the
loader or loadee can veto the load depending on any objections it has with
each other's declared interface level. The way this is currently
implemented assumes a veto will only take place when one side notices the
other's interface level is too *old*. If the other side is newer, it should
be assumed the newer version knows better whether to veto the load or not.
Version checking (like other "dynamic" settings) can be controlled using
the "dynamic" ENGINE's control commands. Also, the semantics for the
loading allow a shared-library ENGINE implementation to handle differing
interface levels on the fly (eg. loading secondary shared-libraries
depending on the versions required).

Code will be added soon to the existing ENGINEs to illustrate how they can
be built as external libraries rather than building statically into
libcrypto.

NB: Applications wanting to support "dynamic"-loadable ENGINEs will need to
add support for ENGINE "control commands". See apps/engine.c for an example
of this, and use "apps/openssl engine -vvvv" to test or experiment.

See the commit log message for that for more information.

NB: X509_STORE_CTX's use of "ex_data" support was actually misimplemented
(initialisation by "memset" won't/can't/doesn't work). This fixes that but
requires that X509_STORE_CTX_init() be able to handle errors - so its
prototype has been changed to return 'int' rather than 'void'. All uses of
that function throughout the source code have been tracked down and
adjusted.

setting stack (actually, array) values in ex_data. So only increment the
global counters if the underlying CRYPTO_get_ex_new_index() call succeeds.
This change doesn't make "ex_data" right (see the comment at the head of
ex_data.c to know why), but at least makes the source code marginally less
frustrating.

NOTE: Boolean input hasn't been very well tested yet, so this part may
fail miserably.

_XOPEN_SOURCE_EXTENDED wasn't very smart...

success return, any negative number is a failure.  Make sure we check
the return value with that in mind.

Fix memory leak when RAND is used: need to cleanup
RANDs ENGINE reference in ENGINE_cleanup().

  with arbitrary arguments instead of just a string.
- Change the key loaders to take a UI_METHOD instead of a callback
  function pointer.  NOTE: this breaks binary compatibility with
  earlier versions of OpenSSL [engine].
- Addapt the nCipher code for these new conditions and add a card
  insertion callback.

PR:

_XOPEN_SOURCE.

passwords that were given to the key loading functions were completely
ignored, at least in the ncipher code, and then we made the assumption
that the callback wanted a prompt as user argument.

All that is now changed, and the application author is forced to give
a callback function of type pem_callback_cb and possibly an argument
for it, just as for all other functions that want to generate password
prompting.

NOTE: this change creates binary and source incompatibilities with
previous versions of OpenSSL [engine].  It's worth it this time, to
get it right (or at least better and with a chance that it'll work).

turned on, and (b) left a somewhat curious debugging string in the output.

few statements equivalent to "ENGINE_add(ENGINE_openssl())" etc. The inner
call to ENGINE_openssl() (as with other functions like it) orphans a
structural reference count. Second, the ENGINE_cleanup() function also
needs to clean up the functional reference counts held internally as the
list of "defaults" (ie. as used when RSA_new() requires an appropriate
ENGINE reference). So ENGINE_clear_defaults() was created and is called
from within ENGINE_cleanup(). Third, some of the existing code was
logically broken in its treatment of reference counts and locking (my
fault), so the necessary bits have been restructured and tidied up.

To test this stuff, compiling with ENGINE_REF_COUNT_DEBUG will cause every
reference count change (both structural and functional) to log a message to
'stderr'. Using with "openssl engine" for example shows this in action
quite well as the 'engine' sub-command cleans up after itself properly.

Also replaced some spaces with tabs.

 * "ex_data" - a CRYPTO_EX_DATA structure in the ENGINE structure itself
   that allows an ENGINE to store its own information there rather than in
   global variables. It follows the declarations and implementations used
   in RSA code, for better or worse. However there's a problem when storing
   state with ENGINEs because, unlike related structure types in OpenSSL,
   there is no ENGINE-vs-ENGINE_METHOD separation. Because of what ENGINE
   is, it has method pointers as its structure elements ...  which leads
   to;

 * ENGINE_FLAGS_BY_ID_COPY - if an ENGINE should not be used just as a
   reference to an "implementation" (eg. to get to a hardware device), but
   should also be able to maintain state, then this flag can be set by the
   ENGINE implementation. The result is that any call to ENGINE_by_id()
   will not result in the existing ENGINE being returned (with its
   structural reference count incremented) but instead a new copy of the
   ENGINE will be returned that can maintain its own state independantly of
   any other copies returned in the past or future. Eg. key-generation
   might involve a series of ENGINE-specific control commands to set
   algorithms, sizes, module-keys, ids, ACLs, etc. A final command could
   generate the key. An ENGINE doing this would *have* to declare
   ENGINE_FLAGS_BY_ID_COPY so that the state of that process can be
   maintained "per-handle" and unaffected by other code having a reference
   to the same ENGINE structure.

takes care of what would otherwise be seen as a memory leak.

unless there's a default clause.

appropriate code if any of them is defined.

here.

This change adds some basic control commands to the existing ENGINEs
(except the software 'openssl' engine). All these engines currently load
shared-libraries for hardware APIs, so they've all been given "SO_PATH"
commands that will configure the chosen ENGINE to load its shared library
from the given path. Eg. by calling;
    ENGINE_ctrl_cmd_string(e, "SO_PATH", <path>, 0).

The nCipher 'chil' ENGINE has also had "FORK_CHECK" and "THREAD_LOCKING"
commands added so these settings could be handled via application-level
configuration rather than in application source code.

Changes to "openssl engine" to test and examine these control commands will
be made shortly. It will also provide the necessary tips to application
programs wanting to support these dynamic control commands.