Formatting is still very mixed in the NOTES and README files. This commit tries to make formatting more consistent with the one introduced in pull request #10545. Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from https://github.com/openssl/openssl/pull/14042)master
Dr. Matthias St. Pierre
2 years ago
parent
9f1fe6a950
commit
dc589daec8
@ -1,125 +1,133 @@
|
||||
TOC
|
||||
===
|
||||
Notes on Perl
|
||||
=============
|
||||
|
||||
- Notes on Perl
|
||||
- Notes on Perl on Windows
|
||||
- Notes on Perl modules we use
|
||||
- Notes on installing a perl module
|
||||
- [General Notes](#general-notes)
|
||||
- [Perl on Windows](#perl-on-windows)
|
||||
- [Perl on VMS](#perl-on-vms)
|
||||
- [Required Perl modules](#required-perl-modules)
|
||||
- [Notes on installing a Perl module](#notes-on-installing-a-perl-module])
|
||||
|
||||
Notes on Perl
|
||||
-------------
|
||||
|
||||
For our scripts, we rely quite a bit on Perl, and increasingly on
|
||||
some core Perl modules. These Perl modules are part of the Perl
|
||||
source, so if you build Perl on your own, you should be set.
|
||||
General Notes
|
||||
-------------
|
||||
|
||||
However, if you install Perl as binary packages, the outcome might
|
||||
differ, and you may have to check that you do get the core modules
|
||||
installed properly. We do not claim to know them all, but experience
|
||||
has told us the following:
|
||||
For our scripts, we rely quite a bit on Perl, and increasingly on
|
||||
some core Perl modules. These Perl modules are part of the Perl
|
||||
source, so if you build Perl on your own, you should be set.
|
||||
|
||||
However, if you install Perl as binary packages, the outcome might
|
||||
differ, and you may have to check that you do get the core modules
|
||||
installed properly. We do not claim to know them all, but experience
|
||||
has told us the following:
|
||||
|
||||
- on Linux distributions based on Debian, the package `perl` will
|
||||
install the core Perl modules as well, so you will be fine.
|
||||
- on Linux distributions based on RPMs, you will need to install
|
||||
`perl-core` rather than just `perl`.
|
||||
|
||||
You MUST have at least Perl version 5.10.0 installed. This minimum
|
||||
requirement is due to our use of regexp backslash sequence \R among
|
||||
other features that didn't exist in core Perl before that version.
|
||||
You MUST have at least Perl version 5.10.0 installed. This minimum
|
||||
requirement is due to our use of regexp backslash sequence \R among
|
||||
other features that didn't exist in core Perl before that version.
|
||||
|
||||
Perl on Windows
|
||||
---------------
|
||||
|
||||
There are a number of build targets that can be viewed as "Windows".
|
||||
Indeed, there are `VC-*` configs targeting VisualStudio C, as well as
|
||||
MinGW and Cygwin. The key recommendation is to use a Perl installation
|
||||
that matches the build environment. For example, if you will build
|
||||
on Cygwin be sure to use the Cygwin package manager to install Perl.
|
||||
For MSYS builds use the MSYS provided Perl.
|
||||
For VC-* builds we recommend Strawberry Perl, from <http://strawberryperl.com>.
|
||||
An alternative is ActiveState Perl, from <http://www.activestate.com/ActivePerl>
|
||||
for which you may need to explicitly select the Perl module Win32/Console.pm
|
||||
available via <https://platform.activestate.com/ActiveState>.
|
||||
|
||||
Perl on VMS
|
||||
-----------
|
||||
|
||||
You will need to install Perl separately. One way to do so is to
|
||||
download the source from <http://perl.org/>, unpacking it, reading
|
||||
`README-VMS.md` and follow the instructions. Another way is to download a
|
||||
`.PCSI` file from <http://www.vmsperl.com/> and install it using the
|
||||
POLYCENTER install tool.
|
||||
|
||||
Required Perl modules
|
||||
---------------------
|
||||
|
||||
Notes on Perl on Windows
|
||||
------------------------
|
||||
We do our best to limit ourselves to core Perl modules to keep the
|
||||
requirements down. There are just a few exceptions.
|
||||
|
||||
There are a number of build targets that can be viewed as "Windows".
|
||||
Indeed, there are `VC-*` configs targeting VisualStudio C, as well as
|
||||
MinGW and Cygwin. The key recommendation is to use "matching" Perl,
|
||||
one that matches build environment. For example, if you will build
|
||||
on Cygwin be sure to use the Cygwin package manager to install Perl.
|
||||
For MSYS builds use the MSYS provided Perl.
|
||||
For VC-* builds we recommend Strawberry Perl, from <http://strawberryperl.com>.
|
||||
An alternative is ActiveState Perl, from <http://www.activestate.com/ActivePerl>
|
||||
for which you may need to explicitly select the Perl module Win32/Console.pm
|
||||
available via <https://platform.activestate.com/ActiveState>.
|
||||
|
||||
Notes on Perl on VMS
|
||||
--------------------
|
||||
## For Building
|
||||
|
||||
You will need to install Perl separately. One way to do so is to
|
||||
download the source from <http://perl.org/>, unpacking it, reading
|
||||
`README-VMS.md` and follow the instructions. Another way is to download a
|
||||
`.PCSI` file from <http://www.vmsperl.com/> and install it using the
|
||||
POLYCENTER install tool.
|
||||
* `Text::Template`
|
||||
|
||||
Notes on Perl modules we use
|
||||
----------------------------
|
||||
This module is not part of the core Perl modules.
|
||||
As a matter of fact, the core Perl modules do not
|
||||
include any templating module to date.
|
||||
This module is absolutely needed,
|
||||
configuration depends on it.
|
||||
|
||||
We make increasing use of Perl modules, and do our best to limit
|
||||
ourselves to core Perl modules to keep the requirements down. There
|
||||
are just a few exceptions:
|
||||
## For Testing
|
||||
|
||||
* `Test::More`
|
||||
* `Test::More`
|
||||
|
||||
We require the minimum version to be 0.96, which
|
||||
appeared in Perl 5.13.4, because that version was
|
||||
the first to have all the features we're using.
|
||||
This module is required for testing only!
|
||||
If you don't plan on running the tests,
|
||||
you don't need to bother with this one.
|
||||
We require the minimum version to be 0.96, which
|
||||
appeared in Perl 5.13.4, because that version was
|
||||
the first to have all the features we're using.
|
||||
This module is required for testing only!
|
||||
If you don't plan on running the tests,
|
||||
you don't need to bother with this one.
|
||||
|
||||
* `Text::Template`
|
||||
|
||||
This module is not part of the core Perl modules.
|
||||
As a matter of fact, the core Perl modules do not
|
||||
include any templating module to date.
|
||||
This module is absolutely needed,
|
||||
configuration depends on it.
|
||||
|
||||
To avoid unnecessary initial hurdles, we have bundled a copy of the
|
||||
following modules in our source. They will work as fallbacks if
|
||||
these modules aren't already installed on the system.
|
||||
To avoid unnecessary initial hurdles, we have bundled a copy of the
|
||||
following modules in our source. They will work as fallbacks if
|
||||
these modules aren't already installed on the system.
|
||||
|
||||
Text::Template
|
||||
Text::Template
|
||||
|
||||
Notes on installing a perl module
|
||||
---------------------------------
|
||||
Notes on installing a Perl module
|
||||
---------------------------------
|
||||
|
||||
There are a number of ways to install a perl module. In all
|
||||
descriptions below, `Text::Template` will serve as an example.
|
||||
There are a number of ways to install a perl module. In all
|
||||
descriptions below, `Text::Template` will serve as an example.
|
||||
|
||||
1. for Linux users, the easiest is to install with the use of your
|
||||
favorite package manager. Usually, all you need to do is search
|
||||
for the module name and to install the package that comes up.
|
||||
1. for Linux users, the easiest is to install with the use of your
|
||||
favorite package manager. Usually, all you need to do is search
|
||||
for the module name and to install the package that comes up.
|
||||
|
||||
On Debian based Linux distributions, it would go like this:
|
||||
On Debian based Linux distributions, it would go like this:
|
||||
|
||||
$ apt-cache search Text::Template
|
||||
...
|
||||
libtext-template-perl - perl module to process text templates
|
||||
$ sudo apt-get install libtext-template-perl
|
||||
$ apt-cache search Text::Template
|
||||
...
|
||||
libtext-template-perl - perl module to process text templates
|
||||
$ sudo apt-get install libtext-template-perl
|
||||
|
||||
Perl modules in Debian based distributions use package names like
|
||||
the name of the module in question, with "lib" prepended and
|
||||
"-perl" appended.
|
||||
Perl modules in Debian based distributions use package names like
|
||||
the name of the module in question, with "lib" prepended and
|
||||
"-perl" appended.
|
||||
|
||||
2. Install using CPAN. This is very easy, but usually requires root
|
||||
access:
|
||||
2. Install using CPAN. This is very easy, but usually requires root
|
||||
access:
|
||||
|
||||
$ cpan -i Text::Template
|
||||
$ cpan -i Text::Template
|
||||
|
||||
Note that this runs all the tests that the module to be installed
|
||||
comes with. This is usually a smooth operation, but there are
|
||||
platforms where a failure is indicated even though the actual tests
|
||||
were successful. Should that happen, you can force an
|
||||
installation regardless (that should be safe since you've already
|
||||
seen the tests succeed!):
|
||||
Note that this runs all the tests that the module to be installed
|
||||
comes with. This is usually a smooth operation, but there are
|
||||
platforms where a failure is indicated even though the actual tests
|
||||
were successful. Should that happen, you can force an
|
||||
installation regardless (that should be safe since you've already
|
||||
seen the tests succeed!):
|
||||
|
||||
$ cpan -f -i Text::Template
|
||||
$ cpan -f -i Text::Template
|
||||
|
||||
Note: on VMS, you must quote any argument that contains upper case
|
||||
characters, so the lines above would be:
|
||||
Note: on VMS, you must quote any argument that contains upper case
|
||||
characters, so the lines above would be:
|
||||
|
||||
$ cpan -i "Text::Template"
|
||||
$ cpan -i "Text::Template"
|
||||
|
||||
and:
|
||||
and:
|
||||
|
||||
$ cpan -f -i "Text::Template"
|
||||
$ cpan -f -i "Text::Template"
|
||||
|
||||
@ -1,308 +1,308 @@
|
||||
ENGINES
|
||||
=======
|
||||
|
||||
With OpenSSL 0.9.6, a new component was added to support alternative
|
||||
cryptography implementations, most commonly for interfacing with external
|
||||
crypto devices (eg. accelerator cards). This component is called ENGINE,
|
||||
and its presence in OpenSSL 0.9.6 (and subsequent bug-fix releases)
|
||||
caused a little confusion as 0.9.6** releases were rolled in two
|
||||
versions, a "standard" and an "engine" version. In development for 0.9.7,
|
||||
the ENGINE code has been merged into the main branch and will be present
|
||||
in the standard releases from 0.9.7 forwards.
|
||||
|
||||
There are currently built-in ENGINE implementations for the following
|
||||
crypto devices:
|
||||
With OpenSSL 0.9.6, a new component was added to support alternative
|
||||
cryptography implementations, most commonly for interfacing with external
|
||||
crypto devices (eg. accelerator cards). This component is called ENGINE,
|
||||
and its presence in OpenSSL 0.9.6 (and subsequent bug-fix releases)
|
||||
caused a little confusion as 0.9.6** releases were rolled in two
|
||||
versions, a "standard" and an "engine" version. In development for 0.9.7,
|
||||
the ENGINE code has been merged into the main branch and will be present
|
||||
in the standard releases from 0.9.7 forwards.
|
||||
|
||||
There are currently built-in ENGINE implementations for the following
|
||||
crypto devices:
|
||||
|
||||
* Microsoft CryptoAPI
|
||||
* VIA Padlock
|
||||
* nCipher CHIL
|
||||
|
||||
In addition, dynamic binding to external ENGINE implementations is now
|
||||
provided by a special ENGINE called "dynamic". See the "DYNAMIC ENGINE"
|
||||
section below for details.
|
||||
In addition, dynamic binding to external ENGINE implementations is now
|
||||
provided by a special ENGINE called "dynamic". See the "DYNAMIC ENGINE"
|
||||
section below for details.
|
||||
|
||||
At this stage, a number of things are still needed and are being worked on:
|
||||
At this stage, a number of things are still needed and are being worked on:
|
||||
|
||||
1. Integration of EVP support.
|
||||
2. Configuration support.
|
||||
3. Documentation!
|
||||
|
||||
Integration of EVP support
|
||||
--------------------------
|
||||
|
||||
With respect to EVP, this relates to support for ciphers and digests in
|
||||
the ENGINE model so that alternative implementations of existing
|
||||
algorithms/modes (or previously unimplemented ones) can be provided by
|
||||
ENGINE implementations.
|
||||
|
||||
Configuration support
|
||||
---------------------
|
||||
|
||||
Configuration support currently exists in the ENGINE API itself, in the
|
||||
form of "control commands". These allow an application to expose to the
|
||||
user/admin the set of commands and parameter types a given ENGINE
|
||||
implementation supports, and for an application to directly feed string
|
||||
based input to those ENGINEs, in the form of name-value pairs. This is an
|
||||
extensible way for ENGINEs to define their own "configuration" mechanisms
|
||||
that are specific to a given ENGINE (eg. for a particular hardware
|
||||
device) but that should be consistent across *all* OpenSSL-based
|
||||
applications when they use that ENGINE. Work is in progress (or at least
|
||||
in planning) for supporting these control commands from the CONF (or
|
||||
NCONF) code so that applications using OpenSSL's existing configuration
|
||||
file format can have ENGINE settings specified in much the same way.
|
||||
Presently however, applications must use the ENGINE API itself to provide
|
||||
such functionality. To see first hand the types of commands available
|
||||
with the various compiled-in ENGINEs (see further down for dynamic
|
||||
ENGINEs), use the "engine" openssl utility with full verbosity, i.e.:
|
||||
|
||||
openssl engine -vvvv
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
Documentation? Volunteers welcome! The source code is reasonably well
|
||||
self-documenting, but some summaries and usage instructions are needed -
|
||||
moreover, they are needed in the same POD format the existing OpenSSL
|
||||
documentation is provided in. Any complete or incomplete contributions
|
||||
would help make this happen.
|
||||
|
||||
STABILITY & BUG-REPORTS
|
||||
=======================
|
||||
|
||||
What already exists is fairly stable as far as it has been tested, but
|
||||
the test base has been a bit small most of the time. For the most part,
|
||||
the vendors of the devices these ENGINEs support have contributed to the
|
||||
development and/or testing of the implementations, and *usually* (with no
|
||||
guarantees) have experience in using the ENGINE support to drive their
|
||||
devices from common OpenSSL-based applications. Bugs and/or inexplicable
|
||||
behaviour in using a specific ENGINE implementation should be sent to the
|
||||
author of that implementation (if it is mentioned in the corresponding C
|
||||
file), and in the case of implementations for commercial hardware
|
||||
devices, also through whatever vendor support channels are available. If
|
||||
none of this is possible, or the problem seems to be something about the
|
||||
ENGINE API itself (ie. not necessarily specific to a particular ENGINE
|
||||
implementation) then you should mail complete details to the relevant
|
||||
OpenSSL mailing list. For a definition of "complete details", refer to
|
||||
the OpenSSL "README" file. As for which list to send it to:
|
||||
Integration of EVP support
|
||||
--------------------------
|
||||
|
||||
With respect to EVP, this relates to support for ciphers and digests in
|
||||
the ENGINE model so that alternative implementations of existing
|
||||
algorithms/modes (or previously unimplemented ones) can be provided by
|
||||
ENGINE implementations.
|
||||
|
||||
Configuration support
|
||||
---------------------
|
||||
|
||||
Configuration support currently exists in the ENGINE API itself, in the
|
||||
form of "control commands". These allow an application to expose to the
|
||||
user/admin the set of commands and parameter types a given ENGINE
|
||||
implementation supports, and for an application to directly feed string
|
||||
based input to those ENGINEs, in the form of name-value pairs. This is an
|
||||
extensible way for ENGINEs to define their own "configuration" mechanisms
|
||||
that are specific to a given ENGINE (eg. for a particular hardware
|
||||
device) but that should be consistent across *all* OpenSSL-based
|
||||
applications when they use that ENGINE. Work is in progress (or at least
|
||||
in planning) for supporting these control commands from the CONF (or
|
||||
NCONF) code so that applications using OpenSSL's existing configuration
|
||||
file format can have ENGINE settings specified in much the same way.
|
||||
Presently however, applications must use the ENGINE API itself to provide
|
||||
such functionality. To see first hand the types of commands available
|
||||
with the various compiled-in ENGINEs (see further down for dynamic
|
||||
ENGINEs), use the "engine" openssl utility with full verbosity, i.e.:
|
||||
|
||||
openssl engine -vvvv
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
Documentation? Volunteers welcome! The source code is reasonably well
|
||||
self-documenting, but some summaries and usage instructions are needed -
|
||||
moreover, they are needed in the same POD format the existing OpenSSL
|
||||
documentation is provided in. Any complete or incomplete contributions
|
||||
would help make this happen.
|
||||
|
||||
STABILITY & BUG-REPORTS
|
||||
=======================
|
||||
|
||||
What already exists is fairly stable as far as it has been tested, but
|
||||
the test base has been a bit small most of the time. For the most part,
|
||||
the vendors of the devices these ENGINEs support have contributed to the
|
||||
development and/or testing of the implementations, and *usually* (with no
|
||||
guarantees) have experience in using the ENGINE support to drive their
|
||||
devices from common OpenSSL-based applications. Bugs and/or inexplicable
|
||||
behaviour in using a specific ENGINE implementation should be sent to the
|
||||
author of that implementation (if it is mentioned in the corresponding C
|
||||
file), and in the case of implementations for commercial hardware
|
||||
devices, also through whatever vendor support channels are available. If
|
||||
none of this is possible, or the problem seems to be something about the
|
||||
ENGINE API itself (ie. not necessarily specific to a particular ENGINE
|
||||
implementation) then you should mail complete details to the relevant
|
||||
OpenSSL mailing list. For a definition of "complete details", refer to
|
||||
the OpenSSL "README" file. As for which list to send it to:
|
||||
|
||||
* openssl-users: if you are *using* the ENGINE abstraction, either in an
|
||||
pre-compiled application or in your own application code.
|
||||
|
||||
* openssl-dev: if you are discussing problems with OpenSSL source code.
|
||||
|
||||
USAGE
|
||||
=====
|
||||
|
||||
The default "openssl" ENGINE is always chosen when performing crypto
|
||||
operations unless you specify otherwise. You must actively tell the
|
||||
openssl utility commands to use anything else through a new command line
|
||||
switch called "-engine". Also, if you want to use the ENGINE support in
|
||||
your own code to do something similar, you must likewise explicitly
|
||||
select the ENGINE implementation you want.
|
||||
|
||||
Depending on the type of hardware, system, and configuration, "settings"
|
||||
may need to be applied to an ENGINE for it to function as expected/hoped.
|
||||
The recommended way of doing this is for the application to support
|
||||
ENGINE "control commands" so that each ENGINE implementation can provide
|
||||
whatever configuration primitives it might require and the application
|
||||
can allow the user/admin (and thus the hardware vendor's support desk
|
||||
also) to provide any such input directly to the ENGINE implementation.
|
||||
This way, applications do not need to know anything specific to any
|
||||
device, they only need to provide the means to carry such user/admin
|
||||
input through to the ENGINE in question. Ie. this connects *you* (and
|
||||
your helpdesk) to the specific ENGINE implementation (and device), and
|
||||
allows application authors to not get buried in hassle supporting
|
||||
arbitrary devices they know (and care) nothing about.
|
||||
|
||||
A new "openssl" utility, "openssl engine", has been added in that allows
|
||||
for testing and examination of ENGINE implementations. Basic usage
|
||||
instructions are available by specifying the "-?" command line switch.
|
||||
|
||||
DYNAMIC ENGINES
|
||||
===============
|
||||
|
||||
The new "dynamic" ENGINE provides a low-overhead way to support ENGINE
|
||||
implementations that aren't pre-compiled and linked into OpenSSL-based
|
||||
applications. This could be because existing compiled-in implementations
|
||||
have known problems and you wish to use a newer version with an existing
|
||||
application. It could equally be because the application (or OpenSSL
|
||||
library) you are using simply doesn't have support for the ENGINE you
|
||||
wish to use, and the ENGINE provider (eg. hardware vendor) is providing
|
||||
you with a self-contained implementation in the form of a shared-library.
|
||||
The other use-case for "dynamic" is with applications that wish to
|
||||
maintain the smallest foot-print possible and so do not link in various
|
||||
ENGINE implementations from OpenSSL, but instead leaves you to provide
|
||||
them, if you want them, in the form of "dynamic"-loadable
|
||||
shared-libraries. It should be possible for hardware vendors to provide
|
||||
their own shared-libraries to support arbitrary hardware to work with
|
||||
applications based on OpenSSL 0.9.7 or later. If you're using an
|
||||
application based on 0.9.7 (or later) and the support you desire is only
|
||||
announced for versions later than the one you need, ask the vendor to
|
||||
backport their ENGINE to the version you need.
|
||||
|
||||
How does "dynamic" work?
|
||||
------------------------
|
||||
|
||||
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;
|
||||
USAGE
|
||||
=====
|
||||
|
||||
The default "openssl" ENGINE is always chosen when performing crypto
|
||||
operations unless you specify otherwise. You must actively tell the
|
||||
openssl utility commands to use anything else through a new command line
|
||||
switch called "-engine". Also, if you want to use the ENGINE support in
|
||||
your own code to do something similar, you must likewise explicitly
|
||||
select the ENGINE implementation you want.
|
||||
|
||||
Depending on the type of hardware, system, and configuration, "settings"
|
||||
may need to be applied to an ENGINE for it to function as expected/hoped.
|
||||
The recommended way of doing this is for the application to support
|
||||
ENGINE "control commands" so that each ENGINE implementation can provide
|
||||
whatever configuration primitives it might require and the application
|
||||
can allow the user/admin (and thus the hardware vendor's support desk
|
||||
also) to provide any such input directly to the ENGINE implementation.
|
||||
This way, applications do not need to know anything specific to any
|
||||
device, they only need to provide the means to carry such user/admin
|
||||
input through to the ENGINE in question. Ie. this connects *you* (and
|
||||
your helpdesk) to the specific ENGINE implementation (and device), and
|
||||
allows application authors to not get buried in hassle supporting
|
||||
arbitrary devices they know (and care) nothing about.
|
||||
|
||||
A new "openssl" utility, "openssl engine", has been added in that allows
|
||||
for testing and examination of ENGINE implementations. Basic usage
|
||||
instructions are available by specifying the "-?" command line switch.
|
||||
|
||||
DYNAMIC ENGINES
|
||||
===============
|
||||
|
||||
The new "dynamic" ENGINE provides a low-overhead way to support ENGINE
|
||||
implementations that aren't pre-compiled and linked into OpenSSL-based
|
||||
applications. This could be because existing compiled-in implementations
|
||||
have known problems and you wish to use a newer version with an existing
|
||||
application. It could equally be because the application (or OpenSSL
|
||||
library) you are using simply doesn't have support for the ENGINE you
|
||||
wish to use, and the ENGINE provider (eg. hardware vendor) is providing
|
||||
you with a self-contained implementation in the form of a shared-library.
|
||||
The other use-case for "dynamic" is with applications that wish to
|
||||
maintain the smallest foot-print possible and so do not link in various
|
||||
ENGINE implementations from OpenSSL, but instead leaves you to provide
|
||||
them, if you want them, in the form of "dynamic"-loadable
|
||||
shared-libraries. It should be possible for hardware vendors to provide
|
||||
their own shared-libraries to support arbitrary hardware to work with
|
||||
applications based on OpenSSL 0.9.7 or later. If you're using an
|
||||
application based on 0.9.7 (or later) and the support you desire is only
|
||||
announced for versions later than the one you need, ask the vendor to
|
||||
backport their ENGINE to the version you need.
|
||||
|
||||
How does "dynamic" work?
|
||||
------------------------
|
||||
|
||||
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).
|
||||
|
||||
How do I build a "dynamic" ENGINE?
|
||||
----------------------------------
|
||||
|
||||
This question is trickier - currently OpenSSL bundles various ENGINE
|
||||
implementations that are statically built in, and any application that
|
||||
calls the "ENGINE_load_builtin_engines()" function will automatically
|
||||
have all such ENGINEs available (and occupying memory). Applications
|
||||
that don't call that function have no ENGINEs available like that and
|
||||
would have to use "dynamic" to load any such ENGINE - but on the other
|
||||
hand such applications would only have the memory footprint of any
|
||||
ENGINEs explicitly loaded using user/admin provided control commands.
|
||||
The main advantage of not statically linking ENGINEs and only using
|
||||
"dynamic" for hardware support is that any installation using no
|
||||
"external" ENGINE suffers no unnecessary memory footprint from unused
|
||||
ENGINEs. Likewise, installations that do require an ENGINE incur the
|
||||
overheads from only *that* ENGINE once it has been loaded.
|
||||
|
||||
Sounds good? Maybe, but currently building an ENGINE implementation as
|
||||
a shared-library that can be loaded by "dynamic" isn't automated in
|
||||
OpenSSL's build process. It can be done manually quite easily however.
|
||||
Such a shared-library can either be built with any OpenSSL code it
|
||||
needs statically linked in, or it can link dynamically against OpenSSL
|
||||
if OpenSSL itself is built as a shared library. The instructions are
|
||||
the same in each case, but in the former (statically linked any
|
||||
dependencies on OpenSSL) you must ensure OpenSSL is built with
|
||||
position-independent code ("PIC"). The default OpenSSL compilation may
|
||||
already specify the relevant flags to do this, but you should consult
|
||||
with your compiler documentation if you are in any doubt.
|
||||
|
||||
This example will show building the "atalla" ENGINE in the
|
||||
crypto/engine/ directory as a shared-library for use via the "dynamic"
|
||||
ENGINE.
|
||||
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).
|
||||
|
||||
How do I build a "dynamic" ENGINE?
|
||||
----------------------------------
|
||||
|
||||
This question is trickier - currently OpenSSL bundles various ENGINE
|
||||
implementations that are statically built in, and any application that
|
||||
calls the "ENGINE_load_builtin_engines()" function will automatically
|
||||
have all such ENGINEs available (and occupying memory). Applications
|
||||
that don't call that function have no ENGINEs available like that and
|
||||
would have to use "dynamic" to load any such ENGINE - but on the other
|
||||
hand such applications would only have the memory footprint of any
|
||||
ENGINEs explicitly loaded using user/admin provided control commands.
|
||||
The main advantage of not statically linking ENGINEs and only using
|
||||
"dynamic" for hardware support is that any installation using no
|
||||
"external" ENGINE suffers no unnecessary memory footprint from unused
|
||||
ENGINEs. Likewise, installations that do require an ENGINE incur the
|
||||
overheads from only *that* ENGINE once it has been loaded.
|
||||
|
||||
Sounds good? Maybe, but currently building an ENGINE implementation as
|
||||
a shared-library that can be loaded by "dynamic" isn't automated in
|
||||
OpenSSL's build process. It can be done manually quite easily however.
|
||||
Such a shared-library can either be built with any OpenSSL code it
|
||||
needs statically linked in, or it can link dynamically against OpenSSL
|
||||
if OpenSSL itself is built as a shared library. The instructions are
|
||||
the same in each case, but in the former (statically linked any
|
||||
dependencies on OpenSSL) you must ensure OpenSSL is built with
|
||||
position-independent code ("PIC"). The default OpenSSL compilation may
|
||||
already specify the relevant flags to do this, but you should consult
|
||||
with your compiler documentation if you are in any doubt.
|
||||
|
||||
This example will show building the "atalla" ENGINE in the
|
||||
crypto/engine/ directory as a shared-library for use via the "dynamic"
|
||||
ENGINE.
|
||||
|
||||
1. "cd" to the crypto/engine/ directory of a pre-compiled OpenSSL
|
||||
source tree.
|
||||
source tree.
|
||||
|
||||
2. Recompile at least one source file so you can see all the compiler
|
||||
flags (and syntax) being used to build normally. Eg;
|
||||
flags (and syntax) being used to build normally. Eg;
|
||||
|
||||
touch hw_atalla.c ; make
|
||||
touch hw_atalla.c ; make
|
||||
|
||||
will rebuild "hw_atalla.o" using all such flags.
|
||||
will rebuild "hw_atalla.o" using all such flags.
|
||||
|
||||
3. Manually enter the same compilation line to compile the
|
||||
"hw_atalla.c" file but with the following two changes;
|
||||
* add "-DENGINE_DYNAMIC_SUPPORT" to the command line switches,
|
||||
* change the output file from "hw_atalla.o" to something new,
|
||||
eg. "tmp_atalla.o"
|
||||
"hw_atalla.c" file but with the following two changes;
|
||||
* add "-DENGINE_DYNAMIC_SUPPORT" to the command line switches,
|
||||
* change the output file from "hw_atalla.o" to something new,
|
||||
eg. "tmp_atalla.o"
|
||||
|
||||
4. Link "tmp_atalla.o" into a shared-library using the top-level
|
||||
OpenSSL libraries to resolve any dependencies. The syntax for doing
|
||||
this depends heavily on your system/compiler and is a nightmare
|
||||
known well to anyone who has worked with shared-library portability
|
||||
before. 'gcc' on Linux, for example, would use the following syntax;
|
||||
OpenSSL libraries to resolve any dependencies. The syntax for doing
|
||||
this depends heavily on your system/compiler and is a nightmare
|
||||
known well to anyone who has worked with shared-library portability
|
||||
before. 'gcc' on Linux, for example, would use the following syntax;
|
||||
|
||||
gcc -shared -o dyn_atalla.so tmp_atalla.o -L../.. -lcrypto
|
||||
gcc -shared -o dyn_atalla.so tmp_atalla.o -L../.. -lcrypto
|
||||
|
||||
5. Test your shared library using "openssl engine" as explained in the
|
||||
previous section. Eg. from the top-level directory, you might try
|
||||
previous section. Eg. from the top-level directory, you might try
|
||||
|
||||
apps/openssl engine -vvvv dynamic \
|
||||
-pre SO_PATH:./crypto/engine/dyn_atalla.so -pre LOAD
|
||||
apps/openssl engine -vvvv dynamic \
|
||||
-pre SO_PATH:./crypto/engine/dyn_atalla.so -pre LOAD
|
||||
|
||||
If the shared-library loads successfully, you will see both "-pre"
|
||||
commands marked as "SUCCESS" and the list of control commands
|
||||
displayed (because of "-vvvv") will be the control commands for the
|
||||
*atalla* ENGINE (ie. *not* the 'dynamic' ENGINE). You can also add
|
||||
the "-t" switch to the utility if you want it to try and initialise
|
||||
the atalla ENGINE for use to test any possible hardware/driver issues.
|
||||
If the shared-library loads successfully, you will see both "-pre"
|
||||
commands marked as "SUCCESS" and the list of control commands
|
||||
displayed (because of "-vvvv") will be the control commands for the
|
||||
*atalla* ENGINE (ie. *not* the 'dynamic' ENGINE). You can also add
|
||||
the "-t" switch to the utility if you want it to try and initialise
|
||||
the atalla ENGINE for use to test any possible hardware/driver issues.
|
||||
|
||||
PROBLEMS
|
||||
========
|
||||
PROBLEMS
|
||||
========
|
||||
|
||||
It seems like the ENGINE part doesn't work too well with CryptoSwift on Win32.
|
||||
A quick test done right before the release showed that trying "openssl speed
|
||||
-engine cswift" generated errors. If the DSO gets enabled, an attempt is made
|
||||
to write at memory address 0x00000002.
|
||||
It seems like the ENGINE part doesn't work too well with CryptoSwift on Win32.
|
||||
A quick test done right before the release showed that trying "openssl speed
|
||||
-engine cswift" generated errors. If the DSO gets enabled, an attempt is made
|
||||
to write at memory address 0x00000002.
|
||||
|
||||
|
||||
Loading…
Reference in new issue