From: Milan Broz Date: Tue, 16 Sep 2025 12:45:23 +0000 (+0200) Subject: Remove README-ENGINES.md X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3b20ec983fd03bbe575c7825c568bc98b4a55ee3;p=thirdparty%2Fopenssl.git Remove README-ENGINES.md Resolves: https://github.com/openssl/project/issues/1616 Signed-off-by: Milan Broz Reviewed-by: Neil Horman Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/28618) --- diff --git a/README-ENGINES.md b/README-ENGINES.md deleted file mode 100644 index 24ec748fe56..00000000000 --- a/README-ENGINES.md +++ /dev/null @@ -1,317 +0,0 @@ -Engines -======= - -Deprecation Note ----------------- - -The ENGINE API was introduced in OpenSSL version 0.9.6 as a low level -interface for adding alternative implementations of cryptographic -primitives, most notably for integrating hardware crypto devices. - -The ENGINE interface has its limitations and it has been superseded -by the [PROVIDER API](README-PROVIDERS.md), it is deprecated in OpenSSL -version 3.0. The following documentation is retained as an aid for -users who need to maintain or support existing ENGINE implementations. -Support for new hardware devices or new algorithms should be added -via providers, and existing engines should be converted to providers -as soon as possible. - -Built-in ENGINE implementations -------------------------------- - -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. - -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: - -- 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; - - 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. For instance, 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. - -2. Recompile at least one source file so you can see all the compiler - flags (and syntax) being used to build normally. Eg; - - touch hw_atalla.c ; make - - 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" - -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; - - 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 - - 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. - -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. diff --git a/README.md b/README.md index ec21a38d3dd..1d84f5ab1b9 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,6 @@ containing additional information on specific topics. * [Information about the OpenSSL QUIC protocol implementation](README-QUIC.md) * [Information about the OpenSSL Provider architecture](README-PROVIDERS.md) * [Information about using the OpenSSL FIPS validated module](README-FIPS.md) - * [Information about the legacy OpenSSL Engine architecture](README-ENGINES.md) The OpenSSL Guide -----------------