- The dynamic ENGINE has a special flag in its implementation such that
- every time application code asks for the 'dynamic' ENGINE, it in fact
- gets its own copy of it. As such, multi-threaded code (or code that
- multiplexes multiple uses of 'dynamic' in a single application in any
- way at all) does not get confused by 'dynamic' being used to do many
- independent things. Other ENGINEs typically don't do this so there is
- only ever 1 ENGINE structure of its type (and reference counts are used
- to keep order). The dynamic ENGINE itself provides absolutely no
- cryptographic functionality, and any attempt to "initialise" the ENGINE
- automatically fails. All it does provide are a few "control commands"
- that can be used to control how it will load an external ENGINE
- implementation from a shared-library. To see these control commands,
- use the command-line;
-
- openssl engine -vvvv dynamic
-
- The "SO_PATH" control command should be used to identify the
- shared-library that contains the ENGINE implementation, and "NO_VCHECK"
- might possibly be useful if there is a minor version conflict and you
- (or a vendor helpdesk) is convinced you can safely ignore it.
- "ID" is probably only needed if a shared-library implements
- multiple ENGINEs, but if you know the engine id you expect to be using,
- it doesn't hurt to specify it (and this provides a sanity check if
- nothing else). "LIST_ADD" is only required if you actually wish the
- loaded ENGINE to be discoverable by application code later on using the
- ENGINE's "id". For most applications, this isn't necessary - but some
- application authors may have nifty reasons for using it. The "LOAD"
- command is the only one that takes no parameters and is the command
- that uses the settings from any previous commands to actually *load*
- the shared-library ENGINE implementation. If this command succeeds, the
- (copy of the) 'dynamic' ENGINE will magically morph into the ENGINE
- that has been loaded from the shared-library. As such, any control
- commands supported by the loaded ENGINE could then be executed as per
- normal. Eg. if ENGINE "foo" is implemented in the shared-library
- "libfoo.so" and it supports some special control command "CMD_FOO", the
- following code would load and use it (NB: obviously this code has no
- error checking);
-
- ENGINE *e = ENGINE_by_id("dynamic");
- ENGINE_ctrl_cmd_string(e, "SO_PATH", "/lib/libfoo.so", 0);
- ENGINE_ctrl_cmd_string(e, "ID", "foo", 0);
- ENGINE_ctrl_cmd_string(e, "LOAD", NULL, 0);
- ENGINE_ctrl_cmd_string(e, "CMD_FOO", "some input data", 0);
-
- For testing, the "openssl engine" utility can be useful for this sort
- of thing. For example the above code excerpt would achieve much the
- same result as;
-
- openssl engine dynamic \
- -pre SO_PATH:/lib/libfoo.so \
- -pre ID:foo \
- -pre LOAD \
- -pre "CMD_FOO:some input data"
-
- Or to simply see the list of commands supported by the "foo" ENGINE;
-
- openssl engine -vvvv dynamic \
- -pre SO_PATH:/lib/libfoo.so \
- -pre ID:foo \
- -pre LOAD
-
- Applications that support the ENGINE API and more specifically, the
- "control commands" mechanism, will provide some way for you to pass
- such commands through to ENGINEs. As such, you would select "dynamic"
- as the ENGINE to use, and the parameters/commands you pass would
- control the *actual* ENGINE used. Each command is actually a name-value
- pair and the value can sometimes be omitted (eg. the "LOAD" command).
- Whilst the syntax demonstrated in "openssl engine" uses a colon to
- separate the command name from the value, applications may provide
- their own syntax for making that separation (eg. a win32 registry
- key-value pair may be used by some applications). The reason for the
- "-pre" syntax in the "openssl engine" utility is that some commands
- might be issued to an ENGINE *after* it has been initialised for use.
- Eg. if an ENGINE implementation requires a smart-card to be inserted
- during initialisation (or a PIN to be typed, or whatever), there may be
- a control command you can issue afterwards to "forget" the smart-card
- so that additional initialisation is no longer possible. In
- applications such as web-servers, where potentially volatile code may
- run on the same host system, this may provide some arguable security
- value. In such a case, the command would be passed to the ENGINE after
- it has been initialised for use, and so the "-post" switch would be
- used instead. Applications may provide a different syntax for
- supporting this distinction, and some may simply not provide it at all
- ("-pre" is almost always what you're after, in reality).
+
+ The dynamic ENGINE has a special flag in its implementation such that
+ every time application code asks for the 'dynamic' ENGINE, it in fact
+ gets its own copy of it. As such, multi-threaded code (or code that
+ multiplexes multiple uses of 'dynamic' in a single application in any
+ way at all) does not get confused by 'dynamic' being used to do many
+ independent things. Other ENGINEs typically don't do this so there is
+ only ever 1 ENGINE structure of its type (and reference counts are used
+ to keep order). The dynamic ENGINE itself provides absolutely no
+ cryptographic functionality, and any attempt to "initialise" the ENGINE
+ automatically fails. All it does provide are a few "control commands"
+ that can be used to control how it will load an external ENGINE
+ implementation from a shared-library. To see these control commands,
+ use the command-line;
+
+ openssl engine -vvvv dynamic
+
+ The "SO_PATH" control command should be used to identify the
+ shared-library that contains the ENGINE implementation, and "NO_VCHECK"
+ might possibly be useful if there is a minor version conflict and you
+ (or a vendor helpdesk) is convinced you can safely ignore it.
+ "ID" is probably only needed if a shared-library implements
+ multiple ENGINEs, but if you know the engine id you expect to be using,
+ it doesn't hurt to specify it (and this provides a sanity check if
+ nothing else). "LIST_ADD" is only required if you actually wish the
+ loaded ENGINE to be discoverable by application code later on using the
+ ENGINE's "id". For most applications, this isn't necessary - but some
+ application authors may have nifty reasons for using it. The "LOAD"
+ command is the only one that takes no parameters and is the command
+ that uses the settings from any previous commands to actually *load*
+ the shared-library ENGINE implementation. If this command succeeds, the
+ (copy of the) 'dynamic' ENGINE will magically morph into the ENGINE
+ that has been loaded from the shared-library. As such, any control
+ commands supported by the loaded ENGINE could then be executed as per
+ normal. Eg. if ENGINE "foo" is implemented in the shared-library
+ "libfoo.so" and it supports some special control command "CMD_FOO", the
+ following code would load and use it (NB: obviously this code has no
+ error checking);
+
+ ENGINE *e = ENGINE_by_id("dynamic");
+ ENGINE_ctrl_cmd_string(e, "SO_PATH", "/lib/libfoo.so", 0);
+ ENGINE_ctrl_cmd_string(e, "ID", "foo", 0);
+ ENGINE_ctrl_cmd_string(e, "LOAD", NULL, 0);
+ ENGINE_ctrl_cmd_string(e, "CMD_FOO", "some input data", 0);
+
+ For testing, the "openssl engine" utility can be useful for this sort
+ of thing. For example the above code excerpt would achieve much the
+ same result as;
+
+ openssl engine dynamic \
+ -pre SO_PATH:/lib/libfoo.so \
+ -pre ID:foo \
+ -pre LOAD \
+ -pre "CMD_FOO:some input data"
+
+ Or to simply see the list of commands supported by the "foo" ENGINE;
+
+ openssl engine -vvvv dynamic \
+ -pre SO_PATH:/lib/libfoo.so \
+ -pre ID:foo \
+ -pre LOAD
+
+ Applications that support the ENGINE API and more specifically, the
+ "control commands" mechanism, will provide some way for you to pass
+ such commands through to ENGINEs. As such, you would select "dynamic"
+ as the ENGINE to use, and the parameters/commands you pass would
+ control the *actual* ENGINE used. Each command is actually a name-value
+ pair and the value can sometimes be omitted (eg. the "LOAD" command).
+ Whilst the syntax demonstrated in "openssl engine" uses a colon to
+ separate the command name from the value, applications may provide
+ their own syntax for making that separation (eg. a win32 registry
+ key-value pair may be used by some applications). The reason for the
+ "-pre" syntax in the "openssl engine" utility is that some commands
+ might be issued to an ENGINE *after* it has been initialised for use.
+ Eg. if an ENGINE implementation requires a smart-card to be inserted
+ during initialisation (or a PIN to be typed, or whatever), there may be
+ a control command you can issue afterwards to "forget" the smart-card
+ so that additional initialisation is no longer possible. In
+ applications such as web-servers, where potentially volatile code may
+ run on the same host system, this may provide some arguable security
+ value. In such a case, the command would be passed to the ENGINE after
+ it has been initialised for use, and so the "-post" switch would be
+ used instead. Applications may provide a different syntax for
+ supporting this distinction, and some may simply not provide it at all
+ ("-pre" is almost always what you're after, in reality).