Lines Matching +full:crypto +full:- +full:engine
5 ----------------
7 The ENGINE API was introduced in OpenSSL version 0.9.6 as a low level
9 primitives, most notably for integrating hardware crypto devices.
11 The ENGINE interface has its limitations and it has been superseeded
12 by the [PROVIDER API](README-PROVIDERS.md), it is deprecated in OpenSSL
14 users who need to maintain or support existing ENGINE implementations.
19 Built-in ENGINE implementations
20 -------------------------------
22 There are currently built-in ENGINE implementations for the following
23 crypto devices:
29 In addition, dynamic binding to external ENGINE implementations is now
30 provided by a special ENGINE called "dynamic". See the "DYNAMIC ENGINE"
40 --------------------------
43 the ENGINE model so that alternative implementations of existing
45 ENGINE implementations.
48 ---------------------
50 Configuration support currently exists in the ENGINE API itself, in the
52 user/admin the set of commands and parameter types a given ENGINE
54 based input to those ENGINEs, in the form of name-value pairs. This is an
56 that are specific to a given ENGINE (eg. for a particular hardware
57 device) but that should be consistent across *all* OpenSSL-based
58 applications when they use that ENGINE. Work is in progress (or at least
61 file format can have ENGINE settings specified in much the same way.
62 Presently however, applications must use the ENGINE API itself to provide
64 with the various compiled-in ENGINEs (see further down for dynamic
65 ENGINEs), use the "engine" openssl utility with full verbosity, i.e.:
67 openssl engine -vvvv
70 -------------
73 self-documenting, but some summaries and usage instructions are needed -
78 STABILITY & BUG-REPORTS
85 guarantees) have experience in using the ENGINE support to drive their
86 devices from common OpenSSL-based applications. Bugs and/or inexplicable
87 behaviour in using a specific ENGINE implementation should be sent to the
92 ENGINE API itself (ie. not necessarily specific to a particular ENGINE
97 * openssl-users: if you are *using* the ENGINE abstraction, either in an
98 pre-compiled application or in your own application code.
100 * openssl-dev: if you are discussing problems with OpenSSL source code.
105 The default "openssl" ENGINE is always chosen when performing crypto
108 switch called "-engine". Also, if you want to use the ENGINE support in
110 select the ENGINE implementation you want.
113 may need to be applied to an ENGINE for it to function as expected/hoped.
115 ENGINE "control commands" so that each ENGINE implementation can provide
118 also) to provide any such input directly to the ENGINE implementation.
121 input through to the ENGINE in question. Ie. this connects *you* (and
122 your helpdesk) to the specific ENGINE implementation (and device), and
126 A new "openssl" utility, "openssl engine", has been added in that allows
127 for testing and examination of ENGINE implementations. Basic usage
128 instructions are available by specifying the "-?" command line switch.
133 The new "dynamic" ENGINE provides a low-overhead way to support ENGINE
134 implementations that aren't pre-compiled and linked into OpenSSL-based
135 applications. This could be because existing compiled-in implementations
138 library) you are using simply doesn't have support for the ENGINE you
139 wish to use, and the ENGINE provider (eg. hardware vendor) is providing
140 you with a self-contained implementation in the form of a shared-library.
141 The other use-case for "dynamic" is with applications that wish to
142 maintain the smallest foot-print possible and so do not link in various
143 ENGINE implementations from OpenSSL, but instead leaves you to provide
144 them, if you want them, in the form of "dynamic"-loadable
145 shared-libraries. It should be possible for hardware vendors to provide
146 their own shared-libraries to support arbitrary hardware to work with
150 backport their ENGINE to the version you need.
153 ------------------------
155 The dynamic ENGINE has a special flag in its implementation such that
156 every time application code asks for the 'dynamic' ENGINE, it in fact
157 gets its own copy of it. As such, multi-threaded code (or code that
161 only ever 1 ENGINE structure of its type (and reference counts are used
162 to keep order). The dynamic ENGINE itself provides absolutely no
163 cryptographic functionality, and any attempt to "initialise" the ENGINE
165 that can be used to control how it will load an external ENGINE
166 implementation from a shared-library. To see these control commands,
167 use the command-line;
169 openssl engine -vvvv dynamic
172 shared-library that contains the ENGINE implementation, and "NO_VCHECK"
175 "ID" is probably only needed if a shared-library implements
176 multiple ENGINEs, but if you know the engine id you expect to be using,
179 loaded ENGINE to be discoverable by application code later on using the
180 ENGINE's "id". For most applications, this isn't necessary - but some
184 the shared-library ENGINE implementation. If this command succeeds, the
185 (copy of the) 'dynamic' ENGINE will magically morph into the ENGINE
186 that has been loaded from the shared-library. As such, any control
187 commands supported by the loaded ENGINE could then be executed as per
188 normal. Eg. if ENGINE "foo" is implemented in the shared-library
193 ENGINE *e = ENGINE_by_id("dynamic");
199 For testing, the "openssl engine" utility can be useful for this sort
203 openssl engine dynamic \
204 -pre SO_PATH:/lib/libfoo.so \
205 -pre ID:foo \
206 -pre LOAD \
207 -pre "CMD_FOO:some input data"
209 Or to simply see the list of commands supported by the "foo" ENGINE;
211 openssl engine -vvvv dynamic \
212 -pre SO_PATH:/lib/libfoo.so \
213 -pre ID:foo \
214 -pre LOAD
216 Applications that support the ENGINE API and more specifically, the
219 as the ENGINE to use, and the parameters/commands you pass would
220 control the *actual* ENGINE used. Each command is actually a name-value
222 Whilst the syntax demonstrated in "openssl engine" uses a colon to
225 key-value pair may be used by some applications). The reason for the
226 "-pre" syntax in the "openssl engine" utility is that some commands
227 might be issued to an ENGINE *after* it has been initialised for use.
228 Eg. if an ENGINE implementation requires a smart-card to be inserted
230 a control command you can issue afterwards to "forget" the smart-card
232 applications such as web-servers, where potentially volatile code may
234 value. In such a case, the command would be passed to the ENGINE after
235 it has been initialised for use, and so the "-post" switch would be
238 ("-pre" is almost always what you're after, in reality).
240 How do I build a "dynamic" ENGINE?
241 ----------------------------------
243 This question is trickier - currently OpenSSL bundles various ENGINE
248 would have to use "dynamic" to load any such ENGINE - but on the other
253 "external" ENGINE suffers no unnecessary memory footprint from unused
254 ENGINEs. Likewise, installations that do require an ENGINE incur the
255 overheads from only *that* ENGINE once it has been loaded.
257 Sounds good? Maybe, but currently building an ENGINE implementation as
258 a shared-library that can be loaded by "dynamic" isn't automated in
260 Such a shared-library can either be built with any OpenSSL code it
265 position-independent code ("PIC"). The default OpenSSL compilation may
269 This example will show building the "atalla" ENGINE in the
270 crypto/engine/ directory as a shared-library for use via the "dynamic"
271 ENGINE.
273 1. "cd" to the crypto/engine/ directory of a pre-compiled OpenSSL
285 * add "-DENGINE_DYNAMIC_SUPPORT" to the command line switches,
289 4. Link "tmp_atalla.o" into a shared-library using the top-level
292 known well to anyone who has worked with shared-library portability
295 gcc -shared -o dyn_atalla.so tmp_atalla.o -L../.. -lcrypto
297 5. Test your shared library using "openssl engine" as explained in the
298 previous section. Eg. from the top-level directory, you might try
300 apps/openssl engine -vvvv dynamic \
301 -pre SO_PATH:./crypto/engine/dyn_atalla.so -pre LOAD
303 If the shared-library loads successfully, you will see both "-pre"
305 displayed (because of "-vvvv") will be the control commands for the
306 *atalla* ENGINE (ie. *not* the 'dynamic' ENGINE). You can also add
307 the "-t" switch to the utility if you want it to try and initialise
308 the atalla ENGINE for use to test any possible hardware/driver issues.
313 It seems like the ENGINE part doesn't work too well with CryptoSwift on Win32.
315 -engine cswift" generated errors. If the DSO gets enabled, an attempt is made