1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
|
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 superseeded
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
|
