summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/engine
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/engine')
-rw-r--r--src/lib/libcrypto/engine/README278
-rw-r--r--src/lib/libcrypto/engine/engine.h398
2 files changed, 0 insertions, 676 deletions
diff --git a/src/lib/libcrypto/engine/README b/src/lib/libcrypto/engine/README
deleted file mode 100644
index 96595e6f35..0000000000
--- a/src/lib/libcrypto/engine/README
+++ /dev/null
@@ -1,278 +0,0 @@
1NOTES, THOUGHTS, and EVERYTHING
2-------------------------------
3
4(1) Concurrency and locking ... I made a change to the ENGINE_free code
5 because I spotted a potential hold-up in proceedings (doing too
6 much inside a lock including calling a callback), there may be
7 other bits like this. What do the speed/optimisation freaks think
8 of this aspect of the code and design? There's lots of locking for
9 manipulation functions and I need that to keep things nice and
10 solid, but this manipulation is mostly (de)initialisation, I would
11 think that most run-time locking is purely in the ENGINE_init and
12 ENGINE_finish calls that might be made when getting handles for
13 RSA (and friends') structures. These would be mostly reference
14 count operations as the functional references should always be 1
15 or greater at run-time to prevent init/deinit thrashing.
16
17(2) nCipher support, via the HWCryptoHook API, is now in the code.
18 Apparently this hasn't been tested too much yet, but it looks
19 good. :-) Atalla support has been added too, but shares a lot in
20 common with Ben's original hooks in bn_exp.c (although it has been
21 ENGINE-ified, and error handling wrapped around it) and it's also
22 had some low-volume testing, so it should be usable.
23
24(3) Of more concern, we need to work out (a) how to put together usable
25 RAND_METHODs for units that just have one "get n or less random
26 bytes" function, (b) we also need to determine how to hook the code
27 in crypto/rand/ to use the ENGINE defaults in a way similar to what
28 has been done in crypto/rsa/, crypto/dsa/, etc.
29
30(4) ENGINE should really grow to encompass more than 3 public key
31 algorithms and randomness gathering. The structure/data level of
32 the engine code is hidden from code outside the crypto/engine/
33 directory so change shouldn't be too viral. More important though
34 is how things should evolve ... this needs thought and discussion.
35
36
37-----------------------------------==*==-----------------------------------
38
39More notes 2000-08-01
40---------------------
41
42Geoff Thorpe, who designed the engine part, wrote a pretty good description
43of the thoughts he had when he built it, good enough to include verbatim here
44(with his permission) -- Richard Levitte
45
46
47Date: Tue, 1 Aug 2000 16:54:08 +0100 (BST)
48From: Geoff Thorpe
49Subject: Re: The thoughts to merge BRANCH_engine into the main trunk are
50 emerging
51
52Hi there,
53
54I'm going to try and do some justice to this, but I'm a little short on
55time and the there is an endless amount that could be discussed on this
56subject. sigh ... please bear with me :-)
57
58> The changes in BRANCH_engine dig deep into the core of OpenSSL, for example
59> into the RSA and RAND routines, adding a level of indirection which is needed
60> to keep the abstraction, as far as I understand. It would be a good thing if
61> those who do play with those things took a look at the changes that have been
62> done in the branch and say out loud how much (or hopefully little) we've made
63> fools of ourselves.
64
65The point here is that the code that has emerged in the BRANCH_engine
66branch was based on some initial requirements of mine that I went in and
67addressed, and Richard has picked up the ball and run with it too. It
68would be really useful to get some review of the approach we've taken, but
69first I think I need to describe as best I can the reasons behind what has
70been done so far, in particular what issues we have tried to address when
71doing this, and what issues we have intentionally (or necessarily) tried
72to avoid.
73
74methods, engines, and evps
75--------------------------
76
77There has been some dicussion, particularly with Steve, about where this
78ENGINE stuff might fit into the conceptual picture as/when we start to
79abstract algorithms a little bit to make the library more extensible. In
80particular, it would desirable to have algorithms (symmetric, hash, pkc,
81etc) abstracted in some way that allows them to be just objects sitting in
82a list (or database) ... it'll just happen that the "DSA" object doesn't
83support encryption whereas the "RSA" object does. This requires a lot of
84consideration to begin to know how to tackle it; in particular how
85encapsulated should these things be? If the objects also understand their
86own ASN1 encodings and what-not, then it would for example be possible to
87add support for elliptic-curve DSA in as a new algorithm and automatically
88have ECC-DSA certificates supported in SSL applications. Possible, but not
89easy. :-)
90
91Whatever, it seems that the way to go (if I've grok'd Steve's comments on
92this in the past) is to amalgamate these things in EVP as is already done
93(I think) for ciphers or hashes (Steve, please correct/elaborate). I
94certainly think something should be done in this direction because right
95now we have different source directories, types, functions, and methods
96for each algorithm - even when conceptually they are very much different
97feathers of the same bird. (This is certainly all true for the public-key
98stuff, and may be partially true for the other parts.)
99
100ENGINE was *not* conceived as a way of solving this, far from it. Nor was
101it conceived as a way of replacing the various "***_METHOD"s. It was
102conceived as an abstraction of a sort of "virtual crypto device". If we
103lived in a world where "EVP_ALGO"s (or something like them) encapsulated
104particular algorithms like RSA,DSA,MD5,RC4,etc, and "***_METHOD"s
105encapsulated interfaces to algorithms (eg. some algo's might support a
106PKC_METHOD, a HASH_METHOD, or a CIPHER_METHOD, who knows?), then I would
107think that ENGINE would encapsulate an implementation of arbitrarily many
108of those algorithms - perhaps as alternatives to existing algorithms
109and/or perhaps as new previously unimplemented algorithms. An ENGINE could
110be used to contain an alternative software implementation, a wrapper for a
111hardware acceleration and/or key-management unit, a comms-wrapper for
112distributing cryptographic operations to remote machines, or any other
113"devices" your imagination can dream up.
114
115However, what has been done in the ENGINE branch so far is nothing more
116than starting to get our toes wet. I had a couple of self-imposed
117requirements when putting the initial abstraction together, and I may have
118already posed these in one form or another on the list, but briefly;
119
120 (i) only bother with public key algorithms for now, and maybe RAND too
121 (motivated by the need to get hardware support going and the fact
122 this was a comparitively easy subset to address to begin with).
123
124 (ii) don't change (if at all possible) the existing crypto code, ie. the
125 implementations, the way the ***_METHODs work, etc.
126
127 (iii) ensure that if no function from the ENGINE code is ever called then
128 things work the way they always did, and there is no memory
129 allocation (otherwise the failure to cleanup would be a problem -
130 this is part of the reason no STACKs were used, the other part of
131 the reason being I found them inappropriate).
132
133 (iv) ensure that all the built-in crypto was encapsulated by one of
134 these "ENGINE"s and that this engine was automatically selected as
135 the default.
136
137 (v) provide the minimum hooking possible in the existing crypto code
138 so that global functions (eg. RSA_public_encrypt) do not need any
139 extra parameter, yet will use whatever the current default ENGINE
140 for that RSA key is, and that the default can be set "per-key"
141 and globally (new keys will assume the global default, and keys
142 without their own default will be operated on using the global
143 default). NB: Try and make (v) conflict as little as possible with
144 (ii). :-)
145
146 (vi) wrap the ENGINE code up in duct tape so you can't even see the
147 corners. Ie. expose no structures at all, just black-box pointers.
148
149 (v) maintain internally a list of ENGINEs on which a calling
150 application can iterate, interrogate, etc. Allow a calling
151 application to hook in new ENGINEs, remove ENGINEs from the list,
152 and enforce uniqueness within the global list of each ENGINE's
153 "unique id".
154
155 (vi) keep reference counts for everything - eg. this includes storing a
156 reference inside each RSA structure to the ENGINE that it uses.
157 This is freed when the RSA structure is destroyed, or has its
158 ENGINE explicitly changed. The net effect needs to be that at any
159 time, it is deterministic to know whether an ENGINE is in use or
160 can be safely removed (or unloaded in the case of the other type
161 of reference) without invalidating function pointers that may or
162 may not be used indavertently in the future. This was actually
163 one of the biggest problems to overcome in the existing OpenSSL
164 code - implementations had always been assumed to be ever-present,
165 so there was no trivial way to get round this.
166
167 (vii) distinguish between structural references and functional
168 references.
169
170A *little* detail
171-----------------
172
173While my mind is on it; I'll illustrate the bit in item (vii). This idea
174turned out to be very handy - the ENGINEs themselves need to be operated
175on and manipulated simply as objects without necessarily trying to
176"enable" them for use. Eg. most host machines will not have the necessary
177hardware or software to support all the engines one might compile into
178OpenSSL, yet it needs to be possible to iterate across the ENGINEs,
179querying their names, properties, etc - all happening in a thread-safe
180manner that uses reference counts (if you imagine two threads iterating
181through a list and one thread removing the ENGINE the other is currently
182looking at - you can see the gotcha waiting to happen). For all of this,
183*structural references* are used and operate much like the other reference
184counts in OpenSSL.
185
186The other kind of reference count is for *functional* references - these
187indicate a reference on which the caller can actually assume the
188particular ENGINE to be initialised and usable to perform the operations
189it implements. Any increment or decrement of the functional reference
190count automatically invokes a corresponding change in the structural
191reference count, as it is fairly obvious that a functional reference is a
192restricted case of a structural reference. So struct_ref >= funct_ref at
193all times. NB: functional references are usually obtained by a call to
194ENGINE_init(), but can also be created implicitly by calls that require a
195new functional reference to be created, eg. ENGINE_set_default(). Either
196way the only time the underlying ENGINE's "init" function is really called
197is when the (functional) reference count increases to 1, similarly the
198underlying "finish" handler is only called as the count goes down to 0.
199The effect of this, for example, is that if you set the default ENGINE for
200RSA operations to be "cswift", then its functional reference count will
201already be at least 1 so the CryptoSwift shared-library and the card will
202stay loaded and initialised until such time as all RSA keys using the
203cswift ENGINE are changed or destroyed and the default ENGINE for RSA
204operations has been changed. This prevents repeated thrashing of init and
205finish handling if the count keeps getting down as far as zero.
206
207Otherwise, the way the ENGINE code has been put together I think pretty
208much reflects the above points. The reason for the ENGINE structure having
209individual RSA_METHOD, DSA_METHOD, etc pointers is simply that it was the
210easiest way to go about things for now, to hook it all into the raw
211RSA,DSA,etc code, and I was trying to the keep the structure invisible
212anyway so that the way this is internally managed could be easily changed
213later on when we start to work out what's to be done about these other
214abstractions.
215
216Down the line, if some EVP-based technique emerges for adequately
217encapsulating algorithms and all their various bits and pieces, then I can
218imagine that "ENGINE" would turn into a reference-counting database of
219these EVP things, of which the default "openssl" ENGINE would be the
220library's own object database of pre-built software implemented algorithms
221(and such). It would also be cool to see the idea of "METHOD"s detached
222from the algorithms themselves ... so RSA, DSA, ElGamal, etc can all
223expose essentially the same METHOD (aka interface), which would include
224any querying/flagging stuff to identify what the algorithm can/can't do,
225its name, and other stuff like max/min block sizes, key sizes, etc. This
226would result in ENGINE similarly detaching its internal database of
227algorithm implementations from the function definitions that return
228interfaces to them. I think ...
229
230As for DSOs etc. Well the DSO code is pretty handy (but could be made much
231more so) for loading vendor's driver-libraries and talking to them in some
232generic way, but right now there's still big problems associated with
233actually putting OpenSSL code (ie. new ENGINEs, or anything else for that
234matter) in dynamically loadable libraries. These problems won't go away in
235a hurry so I don't think we should expect to have any kind of
236shared-library extensions any time soon - but solving the problems is a
237good thing to aim for, and would as a side-effect probably help make
238OpenSSL more usable as a shared-library itself (looking at the things
239needed to do this will show you why).
240
241One of the problems is that if you look at any of the ENGINE
242implementations, eg. hw_cswift.c or hw_ncipher.c, you'll see how it needs
243a variety of functionality and definitions from various areas of OpenSSL,
244including crypto/bn/, crypto/err/, crypto/ itself (locking for example),
245crypto/dso/, crypto/engine/, crypto/rsa, etc etc etc. So if similar code
246were to be suctioned off into shared libraries, the shared libraries would
247either have to duplicate all the definitions and code and avoid loader
248conflicts, or OpenSSL would have to somehow expose all that functionality
249to the shared-library. If this isn't a big enough problem, the issue of
250binary compatibility will be - anyone writing Apache modules can tell you
251that (Ralf? Ben? :-). However, I don't think OpenSSL would need to be
252quite so forgiving as Apache should be, so OpenSSL could simply tell its
253version to the DSO and leave the DSO with the problem of deciding whether
254to proceed or bail out for fear of binary incompatibilities.
255
256Certainly one thing that would go a long way to addressing this is to
257embark on a bit of an opaqueness mission. I've set the ENGINE code up with
258this in mind - it's so draconian that even to declare your own ENGINE, you
259have to get the engine code to create the underlying ENGINE structure, and
260then feed in the new ENGINE's function/method pointers through various
261"set" functions. The more of the code that takes on such a black-box
262approach, the more of the code that will be (a) easy to expose to shared
263libraries that need it, and (b) easy to expose to applications wanting to
264use OpenSSL itself as a shared-library. From my own explorations in
265OpenSSL, the biggest leviathan I've seen that is a problem in this respect
266is the BIGNUM code. Trying to "expose" the bignum code through any kind of
267organised "METHODs", let alone do all the necessary bignum operations
268solely through functions rather than direct access to the structures and
269macros, will be a massive pain in the "r"s.
270
271Anyway, I'm done for now - hope it was readable. Thoughts?
272
273Cheers,
274Geoff
275
276
277-----------------------------------==*==-----------------------------------
278
diff --git a/src/lib/libcrypto/engine/engine.h b/src/lib/libcrypto/engine/engine.h
deleted file mode 100644
index 2983f47034..0000000000
--- a/src/lib/libcrypto/engine/engine.h
+++ /dev/null
@@ -1,398 +0,0 @@
1/* openssl/engine.h */
2/* Written by Geoff Thorpe (geoff@geoffthorpe.net) for the OpenSSL
3 * project 2000.
4 */
5/* ====================================================================
6 * Copyright (c) 1999 The OpenSSL Project. All rights reserved.
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 *
12 * 1. Redistributions of source code must retain the above copyright
13 * notice, this list of conditions and the following disclaimer.
14 *
15 * 2. Redistributions in binary form must reproduce the above copyright
16 * notice, this list of conditions and the following disclaimer in
17 * the documentation and/or other materials provided with the
18 * distribution.
19 *
20 * 3. All advertising materials mentioning features or use of this
21 * software must display the following acknowledgment:
22 * "This product includes software developed by the OpenSSL Project
23 * for use in the OpenSSL Toolkit. (http://www.OpenSSL.org/)"
24 *
25 * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 * endorse or promote products derived from this software without
27 * prior written permission. For written permission, please contact
28 * licensing@OpenSSL.org.
29 *
30 * 5. Products derived from this software may not be called "OpenSSL"
31 * nor may "OpenSSL" appear in their names without prior written
32 * permission of the OpenSSL Project.
33 *
34 * 6. Redistributions of any form whatsoever must retain the following
35 * acknowledgment:
36 * "This product includes software developed by the OpenSSL Project
37 * for use in the OpenSSL Toolkit (http://www.OpenSSL.org/)"
38 *
39 * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 * OF THE POSSIBILITY OF SUCH DAMAGE.
51 * ====================================================================
52 *
53 * This product includes cryptographic software written by Eric Young
54 * (eay@cryptsoft.com). This product includes software written by Tim
55 * Hudson (tjh@cryptsoft.com).
56 *
57 */
58
59#ifndef HEADER_ENGINE_H
60#define HEADER_ENGINE_H
61
62#include <openssl/bn.h>
63#include <openssl/rsa.h>
64#include <openssl/dsa.h>
65#include <openssl/dh.h>
66#include <openssl/rand.h>
67#include <openssl/evp.h>
68#include <openssl/symhacks.h>
69
70#ifdef __cplusplus
71extern "C" {
72#endif
73
74/* These flags are used to control combinations of algorithm (methods)
75 * by bitwise "OR"ing. */
76#define ENGINE_METHOD_RSA (unsigned int)0x0001
77#define ENGINE_METHOD_DSA (unsigned int)0x0002
78#define ENGINE_METHOD_DH (unsigned int)0x0004
79#define ENGINE_METHOD_RAND (unsigned int)0x0008
80#define ENGINE_METHOD_BN_MOD_EXP (unsigned int)0x0010
81#define ENGINE_METHOD_BN_MOD_EXP_CRT (unsigned int)0x0020
82/* Obvious all-or-nothing cases. */
83#define ENGINE_METHOD_ALL (unsigned int)0xFFFF
84#define ENGINE_METHOD_NONE (unsigned int)0x0000
85
86/* These flags are used to tell the ctrl function what should be done.
87 * All command numbers are shared between all engines, even if some don't
88 * make sense to some engines. In such a case, they do nothing but return
89 * the error ENGINE_R_CTRL_COMMAND_NOT_IMPLEMENTED. */
90#define ENGINE_CTRL_SET_LOGSTREAM 1
91#define ENGINE_CTRL_SET_PASSWORD_CALLBACK 2
92/* Flags specific to the nCipher "chil" engine */
93#define ENGINE_CTRL_CHIL_SET_FORKCHECK 100
94 /* Depending on the value of the (long)i argument, this sets or
95 * unsets the SimpleForkCheck flag in the CHIL API to enable or
96 * disable checking and workarounds for applications that fork().
97 */
98#define ENGINE_CTRL_CHIL_NO_LOCKING 101
99 /* This prevents the initialisation function from providing mutex
100 * callbacks to the nCipher library. */
101
102/* As we're missing a BIGNUM_METHOD, we need a couple of locally
103 * defined function types that engines can implement. */
104
105#ifndef HEADER_ENGINE_INT_H
106/* mod_exp operation, calculates; r = a ^ p mod m
107 * NB: ctx can be NULL, but if supplied, the implementation may use
108 * it if it wishes. */
109typedef int (*BN_MOD_EXP)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
110 const BIGNUM *m, BN_CTX *ctx);
111
112/* private key operation for RSA, provided seperately in case other
113 * RSA implementations wish to use it. */
114typedef int (*BN_MOD_EXP_CRT)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
115 const BIGNUM *q, const BIGNUM *dmp1, const BIGNUM *dmq1,
116 const BIGNUM *iqmp, BN_CTX *ctx);
117
118/* Generic function pointer */
119typedef void (*ENGINE_GEN_FUNC_PTR)();
120/* Generic function pointer taking no arguments */
121typedef void (*ENGINE_GEN_INT_FUNC_PTR)(void);
122/* Specific control function pointer */
123typedef int (*ENGINE_CTRL_FUNC_PTR)(int cmd, long i, void *p, void (*f)());
124
125/* The list of "engine" types is a static array of (const ENGINE*)
126 * pointers (not dynamic because static is fine for now and we otherwise
127 * have to hook an appropriate load/unload function in to initialise and
128 * cleanup). */
129typedef struct engine_st ENGINE;
130#endif
131
132/* STRUCTURE functions ... all of these functions deal with pointers to
133 * ENGINE structures where the pointers have a "structural reference".
134 * This means that their reference is to allow access to the structure
135 * but it does not imply that the structure is functional. To simply
136 * increment or decrement the structural reference count, use ENGINE_new
137 * and ENGINE_free. NB: This is not required when iterating using
138 * ENGINE_get_next as it will automatically decrement the structural
139 * reference count of the "current" ENGINE and increment the structural
140 * reference count of the ENGINE it returns (unless it is NULL). */
141
142/* Get the first/last "ENGINE" type available. */
143ENGINE *ENGINE_get_first(void);
144ENGINE *ENGINE_get_last(void);
145/* Iterate to the next/previous "ENGINE" type (NULL = end of the list). */
146ENGINE *ENGINE_get_next(ENGINE *e);
147ENGINE *ENGINE_get_prev(ENGINE *e);
148/* Add another "ENGINE" type into the array. */
149int ENGINE_add(ENGINE *e);
150/* Remove an existing "ENGINE" type from the array. */
151int ENGINE_remove(ENGINE *e);
152/* Retrieve an engine from the list by its unique "id" value. */
153ENGINE *ENGINE_by_id(const char *id);
154
155/* These functions are useful for manufacturing new ENGINE
156 * structures. They don't address reference counting at all -
157 * one uses them to populate an ENGINE structure with personalised
158 * implementations of things prior to using it directly or adding
159 * it to the builtin ENGINE list in OpenSSL. These are also here
160 * so that the ENGINE structure doesn't have to be exposed and
161 * break binary compatibility!
162 *
163 * NB: I'm changing ENGINE_new to force the ENGINE structure to
164 * be allocated from within OpenSSL. See the comment for
165 * ENGINE_get_struct_size().
166 */
167#if 0
168ENGINE *ENGINE_new(ENGINE *e);
169#else
170ENGINE *ENGINE_new(void);
171#endif
172int ENGINE_free(ENGINE *e);
173int ENGINE_set_id(ENGINE *e, const char *id);
174int ENGINE_set_name(ENGINE *e, const char *name);
175int ENGINE_set_RSA(ENGINE *e, RSA_METHOD *rsa_meth);
176int ENGINE_set_DSA(ENGINE *e, DSA_METHOD *dsa_meth);
177int ENGINE_set_DH(ENGINE *e, DH_METHOD *dh_meth);
178int ENGINE_set_RAND(ENGINE *e, RAND_METHOD *rand_meth);
179int ENGINE_set_BN_mod_exp(ENGINE *e, BN_MOD_EXP bn_mod_exp);
180int ENGINE_set_BN_mod_exp_crt(ENGINE *e, BN_MOD_EXP_CRT bn_mod_exp_crt);
181int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);
182int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);
183int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);
184
185/* These return values from within the ENGINE structure. These can
186 * be useful with functional references as well as structural
187 * references - it depends which you obtained. Using the result
188 * for functional purposes if you only obtained a structural
189 * reference may be problematic! */
190const char *ENGINE_get_id(ENGINE *e);
191const char *ENGINE_get_name(ENGINE *e);
192RSA_METHOD *ENGINE_get_RSA(ENGINE *e);
193DSA_METHOD *ENGINE_get_DSA(ENGINE *e);
194DH_METHOD *ENGINE_get_DH(ENGINE *e);
195RAND_METHOD *ENGINE_get_RAND(ENGINE *e);
196BN_MOD_EXP ENGINE_get_BN_mod_exp(ENGINE *e);
197BN_MOD_EXP_CRT ENGINE_get_BN_mod_exp_crt(ENGINE *e);
198ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(ENGINE *e);
199ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(ENGINE *e);
200ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(ENGINE *e);
201
202/* ENGINE_new is normally passed a NULL in the first parameter because
203 * the calling code doesn't have access to the definition of the ENGINE
204 * structure (for good reason). However, if the caller wishes to use
205 * its own memory allocation or use a static array, the following call
206 * should be used to check the amount of memory the ENGINE structure
207 * will occupy. This will make the code more future-proof.
208 *
209 * NB: I'm "#if 0"-ing this out because it's better to force the use of
210 * internally allocated memory. See similar change in ENGINE_new().
211 */
212#if 0
213int ENGINE_get_struct_size(void);
214#endif
215
216/* FUNCTIONAL functions. These functions deal with ENGINE structures
217 * that have (or will) be initialised for use. Broadly speaking, the
218 * structural functions are useful for iterating the list of available
219 * engine types, creating new engine types, and other "list" operations.
220 * These functions actually deal with ENGINEs that are to be used. As
221 * such these functions can fail (if applicable) when particular
222 * engines are unavailable - eg. if a hardware accelerator is not
223 * attached or not functioning correctly. Each ENGINE has 2 reference
224 * counts; structural and functional. Every time a functional reference
225 * is obtained or released, a corresponding structural reference is
226 * automatically obtained or released too. */
227
228/* Initialise a engine type for use (or up its reference count if it's
229 * already in use). This will fail if the engine is not currently
230 * operational and cannot initialise. */
231int ENGINE_init(ENGINE *e);
232/* Free a functional reference to a engine type. This does not require
233 * a corresponding call to ENGINE_free as it also releases a structural
234 * reference. */
235int ENGINE_finish(ENGINE *e);
236/* Send control parametrised commands to the engine. The possibilities
237 * to send down an integer, a pointer to data or a function pointer are
238 * provided. Any of the parameters may or may not be NULL, depending
239 * on the command number */
240/* WARNING: This is currently experimental and may change radically! */
241int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)());
242
243/* The following functions handle keys that are stored in some secondary
244 * location, handled by the engine. The storage may be on a card or
245 * whatever. */
246EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,
247 const char *passphrase);
248EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
249 const char *passphrase);
250
251/* This returns a pointer for the current ENGINE structure that
252 * is (by default) performing any RSA operations. The value returned
253 * is an incremented reference, so it should be free'd (ENGINE_finish)
254 * before it is discarded. */
255ENGINE *ENGINE_get_default_RSA(void);
256/* Same for the other "methods" */
257ENGINE *ENGINE_get_default_DSA(void);
258ENGINE *ENGINE_get_default_DH(void);
259ENGINE *ENGINE_get_default_RAND(void);
260ENGINE *ENGINE_get_default_BN_mod_exp(void);
261ENGINE *ENGINE_get_default_BN_mod_exp_crt(void);
262
263/* This sets a new default ENGINE structure for performing RSA
264 * operations. If the result is non-zero (success) then the ENGINE
265 * structure will have had its reference count up'd so the caller
266 * should still free their own reference 'e'. */
267int ENGINE_set_default_RSA(ENGINE *e);
268/* Same for the other "methods" */
269int ENGINE_set_default_DSA(ENGINE *e);
270int ENGINE_set_default_DH(ENGINE *e);
271int ENGINE_set_default_RAND(ENGINE *e);
272int ENGINE_set_default_BN_mod_exp(ENGINE *e);
273int ENGINE_set_default_BN_mod_exp_crt(ENGINE *e);
274
275/* The combination "set" - the flags are bitwise "OR"d from the
276 * ENGINE_METHOD_*** defines above. */
277int ENGINE_set_default(ENGINE *e, unsigned int flags);
278
279/* Obligatory error function. */
280void ERR_load_ENGINE_strings(void);
281
282/*
283 * Error codes for all engine functions. NB: We use "generic"
284 * function names instead of per-implementation ones because this
285 * levels the playing field for externally implemented bootstrapped
286 * support code. As the filename and line number is included, it's
287 * more important to indicate the type of function, so that
288 * bootstrapped code (that can't easily add its own errors in) can
289 * use the same error codes too.
290 */
291
292/* BEGIN ERROR CODES */
293/* The following lines are auto generated by the script mkerr.pl. Any changes
294 * made after this point may be overwritten when the script is next run.
295 */
296
297/* Error codes for the ENGINE functions. */
298
299/* Function codes. */
300#define ENGINE_F_ATALLA_FINISH 135
301#define ENGINE_F_ATALLA_INIT 136
302#define ENGINE_F_ATALLA_MOD_EXP 137
303#define ENGINE_F_ATALLA_RSA_MOD_EXP 138
304#define ENGINE_F_CSWIFT_DSA_SIGN 133
305#define ENGINE_F_CSWIFT_DSA_VERIFY 134
306#define ENGINE_F_CSWIFT_FINISH 100
307#define ENGINE_F_CSWIFT_INIT 101
308#define ENGINE_F_CSWIFT_MOD_EXP 102
309#define ENGINE_F_CSWIFT_MOD_EXP_CRT 103
310#define ENGINE_F_CSWIFT_RSA_MOD_EXP 104
311#define ENGINE_F_ENGINE_ADD 105
312#define ENGINE_F_ENGINE_BY_ID 106
313#define ENGINE_F_ENGINE_CTRL 142
314#define ENGINE_F_ENGINE_FINISH 107
315#define ENGINE_F_ENGINE_FREE 108
316#define ENGINE_F_ENGINE_GET_BN_MOD_EXP 109
317#define ENGINE_F_ENGINE_GET_BN_MOD_EXP_CRT 110
318#define ENGINE_F_ENGINE_GET_CTRL_FUNCTION 144
319#define ENGINE_F_ENGINE_GET_DH 111
320#define ENGINE_F_ENGINE_GET_DSA 112
321#define ENGINE_F_ENGINE_GET_FINISH_FUNCTION 145
322#define ENGINE_F_ENGINE_GET_ID 113
323#define ENGINE_F_ENGINE_GET_INIT_FUNCTION 146
324#define ENGINE_F_ENGINE_GET_NAME 114
325#define ENGINE_F_ENGINE_GET_NEXT 115
326#define ENGINE_F_ENGINE_GET_PREV 116
327#define ENGINE_F_ENGINE_GET_RAND 117
328#define ENGINE_F_ENGINE_GET_RSA 118
329#define ENGINE_F_ENGINE_INIT 119
330#define ENGINE_F_ENGINE_LIST_ADD 120
331#define ENGINE_F_ENGINE_LIST_REMOVE 121
332#define ENGINE_F_ENGINE_LOAD_PRIVATE_KEY 150
333#define ENGINE_F_ENGINE_LOAD_PUBLIC_KEY 151
334#define ENGINE_F_ENGINE_NEW 122
335#define ENGINE_F_ENGINE_REMOVE 123
336#define ENGINE_F_ENGINE_SET_BN_MOD_EXP 124
337#define ENGINE_F_ENGINE_SET_BN_MOD_EXP_CRT 125
338#define ENGINE_F_ENGINE_SET_CTRL_FUNCTION 147
339#define ENGINE_F_ENGINE_SET_DEFAULT_TYPE 126
340#define ENGINE_F_ENGINE_SET_DH 127
341#define ENGINE_F_ENGINE_SET_DSA 128
342#define ENGINE_F_ENGINE_SET_FINISH_FUNCTION 148
343#define ENGINE_F_ENGINE_SET_ID 129
344#define ENGINE_F_ENGINE_SET_INIT_FUNCTION 149
345#define ENGINE_F_ENGINE_SET_NAME 130
346#define ENGINE_F_ENGINE_SET_RAND 131
347#define ENGINE_F_ENGINE_SET_RSA 132
348#define ENGINE_F_ENGINE_UNLOAD_KEY 152
349#define ENGINE_F_HWCRHK_CTRL 143
350#define ENGINE_F_HWCRHK_FINISH 135
351#define ENGINE_F_HWCRHK_GET_PASS 155
352#define ENGINE_F_HWCRHK_INIT 136
353#define ENGINE_F_HWCRHK_LOAD_PRIVKEY 153
354#define ENGINE_F_HWCRHK_LOAD_PUBKEY 154
355#define ENGINE_F_HWCRHK_MOD_EXP 137
356#define ENGINE_F_HWCRHK_MOD_EXP_CRT 138
357#define ENGINE_F_HWCRHK_RAND_BYTES 139
358#define ENGINE_F_HWCRHK_RSA_MOD_EXP 140
359#define ENGINE_F_LOG_MESSAGE 141
360
361/* Reason codes. */
362#define ENGINE_R_ALREADY_LOADED 100
363#define ENGINE_R_BIO_WAS_FREED 121
364#define ENGINE_R_BN_CTX_FULL 101
365#define ENGINE_R_BN_EXPAND_FAIL 102
366#define ENGINE_R_CHIL_ERROR 123
367#define ENGINE_R_CONFLICTING_ENGINE_ID 103
368#define ENGINE_R_CTRL_COMMAND_NOT_IMPLEMENTED 119
369#define ENGINE_R_DSO_FAILURE 104
370#define ENGINE_R_ENGINE_IS_NOT_IN_LIST 105
371#define ENGINE_R_FAILED_LOADING_PRIVATE_KEY 128
372#define ENGINE_R_FAILED_LOADING_PUBLIC_KEY 129
373#define ENGINE_R_FINISH_FAILED 106
374#define ENGINE_R_GET_HANDLE_FAILED 107
375#define ENGINE_R_ID_OR_NAME_MISSING 108
376#define ENGINE_R_INIT_FAILED 109
377#define ENGINE_R_INTERNAL_LIST_ERROR 110
378#define ENGINE_R_MISSING_KEY_COMPONENTS 111
379#define ENGINE_R_NOT_INITIALISED 117
380#define ENGINE_R_NOT_LOADED 112
381#define ENGINE_R_NO_CALLBACK 127
382#define ENGINE_R_NO_CONTROL_FUNCTION 120
383#define ENGINE_R_NO_KEY 124
384#define ENGINE_R_NO_LOAD_FUNCTION 125
385#define ENGINE_R_NO_REFERENCE 130
386#define ENGINE_R_NO_SUCH_ENGINE 116
387#define ENGINE_R_NO_UNLOAD_FUNCTION 126
388#define ENGINE_R_PROVIDE_PARAMETERS 113
389#define ENGINE_R_REQUEST_FAILED 114
390#define ENGINE_R_REQUEST_FALLBACK 118
391#define ENGINE_R_SIZE_TOO_LARGE_OR_TOO_SMALL 122
392#define ENGINE_R_UNIT_FAILURE 115
393
394#ifdef __cplusplus
395}
396#endif
397#endif
398
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-19 21:48:44 +0000