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.

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).

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

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.

ENGINE handler functions should take the ENGINE structure as a parameter -
this is because ENGINE structures can be copied, and like other
structure/method setups in OpenSSL, it should be possible for init(),
finish(), ctrl(), etc to adjust state inside the ENGINE structures rather
than globally. This commit includes the dependant changes in the ENGINE
implementations.

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.

BCM5805 and BCM5820 units. So far I've merely taken a skim over the code
and changed a few things from their original contributed source
(de-shadowing variables, removing variables from the header, and
re-constifying some functions to remove warnings). If this gives
compilation problems on any system, please let me know. We will hopefully
know for sure whether this actually functions on a system with the relevant
hardware in a day or two.  :-)

situation where they've initialised the ENGINE, loaded keys (which are then
linked to that ENGINE), and performed other checks (such as verifying
certificate chains etc). At that point, if the application goes
multi-threaded or multi-process it creates problems for any ENGINE
implementations that are either not thread/process safe or that perform
optimally when they do not have to perform locking and other contention
management tasks at "run-time".

This defines a new ENGINE_ctrl() command that can be supported by engines
at their discretion. If ENGINE_ctrl(..., ENGINE_CTRL_HUP,...) returns an
error then the caller should check if the *_R_COMMAND_NOT_IMPLEMENTED error
reason was set - it may just be that the engine doesn't support or need the
HUP command, or it could be that the attempted reinitialisation failed. A
crude alternative is to ignore the return value from ENGINE_ctrl() (and
clear any errors with ERR_clear_error()) and perform a test operation
immediately after the "HUP". Very crude indeed.

ENGINEs can support this command to close and reopen connections, files,
handles, or whatever as an alternative to run-time locking when such things
would otherwise be needed. In such a case, it's advisable for the engine
implementations to support locking by default but disable it after the
arrival of a HUP command, or any other indication by the application that
locking is not required. NB: This command exists to allow an ENGINE to
reinitialise without the ENGINE's functional reference count having to sink
down to zero and back up - which is what is normally required for the
finish() and init() handlers to get invoked. It would also be a bad idea
for engine_lib to catch this command itself and interpret it by calling the
engine's init() and finish() handlers directly, because reinitialisation
may need special handling on a case-by-case basis that is distinct from a
finish/init pair - eg. calling a finish() handler may invalidate the state
stored inside individual keys that have already loaded for this engine.

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.