normal 'structural' case (ENGINE_init() satisfies this in the less normal
'functional' case). This change provides such a function.

- Correct some "read" locks that should actually be "write" locks.

- make update.

automatic load of dynamic engines.  Change the iterator to try to load
the requested engine dynamically.  The environment variable
OPENSSL_ENGINES can be used to override the internal default directory
where one can expect to find dynamically loadable engines.

Note: The changes in step 11 have all been made by Geoff Thorpe.
Credit where credit is due.

Additional changes:
 - use EC_GROUP_get_degree() in apps/req.c
 - add ECDSA and ECDH to apps/speed.c
 - adds support for EC curves over binary fields to ECDSA
 - new function EC_KEY_up_ref() in crypto/ec/ec_key.c
 - reorganize crypto/ecdsa/ecdsatest.c
 - add engine support for ECDH
 - fix a few bugs in ECDSA engine support

Submitted by: Douglas Stebila <douglas.stebila@sun.com>

Submitted by: Nils Larsch <nla@trustcenter.de>

Initial ENGINE config module, docs to follow.

Fix buffer overrun errors in OPENSSL_conf().

ENGING_TABLE mechanism. The necessary hooks from crypto/evp/ to use this
will be committed shortly.

ENGINE_TABLE-based stuff - as described in crypto/engine/README.

Associated miscellaneous changes;
 - the previous cipher/digest hooks that hardwired directly to EVP's
   OBJ_NAME-based storage have been backed out. New cipher/digest support
   has been constructed and will be committed shortly.
 - each implementation defines its own ENGINE_load_<name> function now.
 - the "openssl" ENGINE isn't needed or loaded any more.
 - core (not algorithm or class specific) ENGINE code has been split into
   multiple files to increase readability and decrease linker bloat.
 - ENGINE_cpy() has been removed as it wasn't really a good idea in the
   first place and now, because of registration issues, can't be
   meaningfully defined any more.
 - BN_MOD_EXP[_CRT] support is removed as per the README.
 - a bug in enginetest.c has been fixed.

NB: This commit almost certainly breaks compilation until subsequent
changes are committed.

recently. So comments including file names have been fixed, and copyright
notices brought up to "2001" at the same time.

and DH all conditional upon OPENSSL_NO_RSA.

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.

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.

PR:

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.

appropriate code if any of them is defined.

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.

Previous changes permanently removed the commented-out old code for where
it was possible to create and use an ENGINE statically, and this code gets
rid of the ENGINE_FLAGS_MALLOCED flag that supported the distinction with
dynamically allocated ENGINEs. It also moves the area for ENGINE_FLAGS_***
values from engine_int.h to engine.h - because it should be possible to
declare ENGINEs just from declarations in exported headers.

* Constify the get/set functions, and add some that functions were missing.

* Add a new 'ENGINE_cpy()' function that will produce a new ENGINE based
  copied from an original (except for the references, ie. the new copy will
  be like an ENGINE returned from 'ENGINE_new()' - a structural reference).

* Removed the "null parameter" checking in the get/set functions - it is
  legitimate to set NULL values as a way of *changing* an ENGINE (ie.
  removing a handler that previously existed). Also, passing a NULL pointer
  for an ENGINE is obviously wrong for these functions, so don't bother
  checking for it. The result is a number of error codes and strings could
  be removed.

to ENGINE_free(). Also, remove "#if 0" code that has no useful future.

few small constifying changes, and why not throw in a couple of extras
while I'm at it?

load the "external" built-in engines (those that require DSO).  This
makes linking with libdl or other dso libraries non-mandatory.

Change 'openssl engine' accordingly.

Change the engine header files so some declarations (that differed at
that!) aren't duplicated, and make sure engine_int.h includes
engine.h.  That way, there should be no way of missing the needed
info.

At the same time, add VMS support for Rijndael.