like des_read_password and friends (backward compatibility functions
using this new API are provided). The purpose is to remove prompting
functions from the DES code section as well as provide for prompting
through dialog boxes in a window system and the like.
For those, unless the environment variables RANDFILE or HOME are
defined (the default case!), RAND_file_name() will return NULL.
This change adds a default HOME for those platforms.
To add a default HOME for any platform, just define DEFAULT_HOME in
the proper place, wrapped in appropriate #ifdef..#endif, in e_os.h.
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.
ENGINE.
* Extra verbosity can be added with more "v"'s, eg. '-vvv' gives
information about input flags and descriptions for each control command
in each ENGINE. Check the output of "openssl engine -vvv" for example.
* '-pre <cmd>' and '-post <cmd>' can be used to invoke control commands on
the specified ENGINE (or on all of them if no engine id is specified,
although that usually gets pretty ugly). '-post' commands are only
attempted if '-t' is specified and the engine successfully initialises.
'-pre' commands are always attempted whether or not '-t' causes an
initialisation to be tried afterwards. Multiple '-pre' and/or '-post'
commands can be specified and they will be called in the order they
occur on the command line.
Parameterised commands (the normal case, there are currently no
unparameterised ones) are split into command and argument via a separating
colon. Eg. "openssl engine -pre SO_PATH:/lib/libdriver.so <id>" results in
the call;
ENGINE_ctrl_cmd_string(e, "SO_PATH", "/lib/libdriver.so", 0);
Application code should similarly allow arbitrary name-value string pairs
to be passed into ENGINEs in a manner matching that in apps/engine.c,
either using the same colon-separated format, or entered as two distinct
strings. Eg. as stored in a registry. The last parameter of
ENGINE_ctrl_cmd_string can be changed from 0 to 1 if the command should
only be attempted if it's supported by the specified ENGINE (eg. for
commands like "FORK_CHECK:1" that may or may not apply to the run-time
ENGINE).
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.
