2
/* Written by Geoff Thorpe (geoff@geoffthorpe.net) for the OpenSSL
5
/* ====================================================================
6
* Copyright (c) 1999-2004 The OpenSSL Project. All rights reserved.
8
* Redistribution and use in source and binary forms, with or without
9
* modification, are permitted provided that the following conditions
12
* 1. Redistributions of source code must retain the above copyright
13
* notice, this list of conditions and the following disclaimer.
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
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/)"
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.
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.
34
* 6. Redistributions of any form whatsoever must retain the following
36
* "This product includes software developed by the OpenSSL Project
37
* for use in the OpenSSL Toolkit (http://www.OpenSSL.org/)"
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
* ====================================================================
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).
58
/* ====================================================================
59
* Copyright 2002 Sun Microsystems, Inc. ALL RIGHTS RESERVED.
60
* ECDH support in OpenSSL originally developed by
61
* SUN MICROSYSTEMS, INC., and contributed to the OpenSSL project.
64
#ifndef HEADER_ENGINE_H
65
#define HEADER_ENGINE_H
67
#include <openssl/opensslconf.h>
69
#ifdef OPENSSL_NO_ENGINE
70
#error ENGINE is disabled.
73
#ifndef OPENSSL_NO_DEPRECATED
74
#include <openssl/bn.h>
75
#ifndef OPENSSL_NO_RSA
76
#include <openssl/rsa.h>
78
#ifndef OPENSSL_NO_DSA
79
#include <openssl/dsa.h>
82
#include <openssl/dh.h>
84
#ifndef OPENSSL_NO_ECDH
85
#include <openssl/ecdh.h>
87
#ifndef OPENSSL_NO_ECDSA
88
#include <openssl/ecdsa.h>
90
#include <openssl/rand.h>
91
#include <openssl/store.h>
92
#include <openssl/ui.h>
93
#include <openssl/err.h>
96
#include <openssl/x509.h>
98
#include <openssl/ossl_typ.h>
99
#include <openssl/symhacks.h>
105
/* These flags are used to control combinations of algorithm (methods)
106
* by bitwise "OR"ing. */
107
#define ENGINE_METHOD_RSA (unsigned int)0x0001
108
#define ENGINE_METHOD_DSA (unsigned int)0x0002
109
#define ENGINE_METHOD_DH (unsigned int)0x0004
110
#define ENGINE_METHOD_RAND (unsigned int)0x0008
111
#define ENGINE_METHOD_ECDH (unsigned int)0x0010
112
#define ENGINE_METHOD_ECDSA (unsigned int)0x0020
113
#define ENGINE_METHOD_CIPHERS (unsigned int)0x0040
114
#define ENGINE_METHOD_DIGESTS (unsigned int)0x0080
115
#define ENGINE_METHOD_STORE (unsigned int)0x0100
116
/* Obvious all-or-nothing cases. */
117
#define ENGINE_METHOD_ALL (unsigned int)0xFFFF
118
#define ENGINE_METHOD_NONE (unsigned int)0x0000
120
/* This(ese) flag(s) controls behaviour of the ENGINE_TABLE mechanism used
121
* internally to control registration of ENGINE implementations, and can be set
122
* by ENGINE_set_table_flags(). The "NOINIT" flag prevents attempts to
123
* initialise registered ENGINEs if they are not already initialised. */
124
#define ENGINE_TABLE_FLAG_NOINIT (unsigned int)0x0001
126
/* ENGINE flags that can be set by ENGINE_set_flags(). */
127
/* #define ENGINE_FLAGS_MALLOCED 0x0001 */ /* Not used */
129
/* This flag is for ENGINEs that wish to handle the various 'CMD'-related
130
* control commands on their own. Without this flag, ENGINE_ctrl() handles these
131
* control commands on behalf of the ENGINE using their "cmd_defns" data. */
132
#define ENGINE_FLAGS_MANUAL_CMD_CTRL (int)0x0002
134
/* This flag is for ENGINEs who return new duplicate structures when found via
135
* "ENGINE_by_id()". When an ENGINE must store state (eg. if ENGINE_ctrl()
136
* commands are called in sequence as part of some stateful process like
137
* key-generation setup and execution), it can set this flag - then each attempt
138
* to obtain the ENGINE will result in it being copied into a new structure.
139
* Normally, ENGINEs don't declare this flag so ENGINE_by_id() just increments
140
* the existing ENGINE's structural reference count. */
141
#define ENGINE_FLAGS_BY_ID_COPY (int)0x0004
143
/* ENGINEs can support their own command types, and these flags are used in
144
* ENGINE_CTRL_GET_CMD_FLAGS to indicate to the caller what kind of input each
145
* command expects. Currently only numeric and string input is supported. If a
146
* control command supports none of the _NUMERIC, _STRING, or _NO_INPUT options,
147
* then it is regarded as an "internal" control command - and not for use in
148
* config setting situations. As such, they're not available to the
149
* ENGINE_ctrl_cmd_string() function, only raw ENGINE_ctrl() access. Changes to
150
* this list of 'command types' should be reflected carefully in
151
* ENGINE_cmd_is_executable() and ENGINE_ctrl_cmd_string(). */
153
/* accepts a 'long' input value (3rd parameter to ENGINE_ctrl) */
154
#define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001
155
/* accepts string input (cast from 'void*' to 'const char *', 4th parameter to
157
#define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002
158
/* Indicates that the control command takes *no* input. Ie. the control command
159
* is unparameterised. */
160
#define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004
161
/* Indicates that the control command is internal. This control command won't
162
* be shown in any output, and is only usable through the ENGINE_ctrl_cmd()
164
#define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008
166
/* NB: These 3 control commands are deprecated and should not be used. ENGINEs
167
* relying on these commands should compile conditional support for
168
* compatibility (eg. if these symbols are defined) but should also migrate the
169
* same functionality to their own ENGINE-specific control functions that can be
170
* "discovered" by calling applications. The fact these control commands
171
* wouldn't be "executable" (ie. usable by text-based config) doesn't change the
172
* fact that application code can find and use them without requiring per-ENGINE
175
/* These flags are used to tell the ctrl function what should be done.
176
* All command numbers are shared between all engines, even if some don't
177
* make sense to some engines. In such a case, they do nothing but return
178
* the error ENGINE_R_CTRL_COMMAND_NOT_IMPLEMENTED. */
179
#define ENGINE_CTRL_SET_LOGSTREAM 1
180
#define ENGINE_CTRL_SET_PASSWORD_CALLBACK 2
181
#define ENGINE_CTRL_HUP 3 /* Close and reinitialise any
182
handles/connections etc. */
183
#define ENGINE_CTRL_SET_USER_INTERFACE 4 /* Alternative to callback */
184
#define ENGINE_CTRL_SET_CALLBACK_DATA 5 /* User-specific data, used
185
when calling the password
186
callback and the user
188
#define ENGINE_CTRL_LOAD_CONFIGURATION 6 /* Load a configuration, given
189
a string that represents a
191
#define ENGINE_CTRL_LOAD_SECTION 7 /* Load data from a given
192
section in the already loaded
195
/* These control commands allow an application to deal with an arbitrary engine
196
* in a dynamic way. Warn: Negative return values indicate errors FOR THESE
197
* COMMANDS because zero is used to indicate 'end-of-list'. Other commands,
198
* including ENGINE-specific command types, return zero for an error.
200
* An ENGINE can choose to implement these ctrl functions, and can internally
201
* manage things however it chooses - it does so by setting the
202
* ENGINE_FLAGS_MANUAL_CMD_CTRL flag (using ENGINE_set_flags()). Otherwise the
203
* ENGINE_ctrl() code handles this on the ENGINE's behalf using the cmd_defns
204
* data (set using ENGINE_set_cmd_defns()). This means an ENGINE's ctrl()
205
* handler need only implement its own commands - the above "meta" commands will
206
* be taken care of. */
208
/* Returns non-zero if the supplied ENGINE has a ctrl() handler. If "not", then
209
* all the remaining control commands will return failure, so it is worth
210
* checking this first if the caller is trying to "discover" the engine's
211
* capabilities and doesn't want errors generated unnecessarily. */
212
#define ENGINE_CTRL_HAS_CTRL_FUNCTION 10
213
/* Returns a positive command number for the first command supported by the
214
* engine. Returns zero if no ctrl commands are supported. */
215
#define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11
216
/* The 'long' argument specifies a command implemented by the engine, and the
217
* return value is the next command supported, or zero if there are no more. */
218
#define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12
219
/* The 'void*' argument is a command name (cast from 'const char *'), and the
220
* return value is the command that corresponds to it. */
221
#define ENGINE_CTRL_GET_CMD_FROM_NAME 13
222
/* The next two allow a command to be converted into its corresponding string
223
* form. In each case, the 'long' argument supplies the command. In the NAME_LEN
224
* case, the return value is the length of the command name (not counting a
225
* trailing EOL). In the NAME case, the 'void*' argument must be a string buffer
226
* large enough, and it will be populated with the name of the command (WITH a
228
#define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14
229
#define ENGINE_CTRL_GET_NAME_FROM_CMD 15
230
/* The next two are similar but give a "short description" of a command. */
231
#define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16
232
#define ENGINE_CTRL_GET_DESC_FROM_CMD 17
233
/* With this command, the return value is the OR'd combination of
234
* ENGINE_CMD_FLAG_*** values that indicate what kind of input a given
235
* engine-specific ctrl command expects. */
236
#define ENGINE_CTRL_GET_CMD_FLAGS 18
238
/* ENGINE implementations should start the numbering of their own control
239
* commands from this value. (ie. ENGINE_CMD_BASE, ENGINE_CMD_BASE + 1, etc). */
240
#define ENGINE_CMD_BASE 200
242
/* NB: These 2 nCipher "chil" control commands are deprecated, and their
243
* functionality is now available through ENGINE-specific control commands
244
* (exposed through the above-mentioned 'CMD'-handling). Code using these 2
245
* commands should be migrated to the more general command handling before these
248
/* Flags specific to the nCipher "chil" engine */
249
#define ENGINE_CTRL_CHIL_SET_FORKCHECK 100
250
/* Depending on the value of the (long)i argument, this sets or
251
* unsets the SimpleForkCheck flag in the CHIL API to enable or
252
* disable checking and workarounds for applications that fork().
254
#define ENGINE_CTRL_CHIL_NO_LOCKING 101
255
/* This prevents the initialisation function from providing mutex
256
* callbacks to the nCipher library. */
258
/* If an ENGINE supports its own specific control commands and wishes the
259
* framework to handle the above 'ENGINE_CMD_***'-manipulation commands on its
260
* behalf, it should supply a null-terminated array of ENGINE_CMD_DEFN entries
261
* to ENGINE_set_cmd_defns(). It should also implement a ctrl() handler that
262
* supports the stated commands (ie. the "cmd_num" entries as described by the
263
* array). NB: The array must be ordered in increasing order of cmd_num.
264
* "null-terminated" means that the last ENGINE_CMD_DEFN element has cmd_num set
265
* to zero and/or cmd_name set to NULL. */
266
typedef struct ENGINE_CMD_DEFN_st
268
unsigned int cmd_num; /* The command number */
269
const char *cmd_name; /* The command name itself */
270
const char *cmd_desc; /* A short description of the command */
271
unsigned int cmd_flags; /* The input the command expects */
274
/* Generic function pointer */
275
typedef int (*ENGINE_GEN_FUNC_PTR)(void);
276
/* Generic function pointer taking no arguments */
277
typedef int (*ENGINE_GEN_INT_FUNC_PTR)(ENGINE *);
278
/* Specific control function pointer */
279
typedef int (*ENGINE_CTRL_FUNC_PTR)(ENGINE *, int, long, void *, void (*f)(void));
280
/* Generic load_key function pointer */
281
typedef EVP_PKEY * (*ENGINE_LOAD_KEY_PTR)(ENGINE *, const char *,
282
UI_METHOD *ui_method, void *callback_data);
283
typedef int (*ENGINE_SSL_CLIENT_CERT_PTR)(ENGINE *, SSL *ssl,
284
STACK_OF(X509_NAME) *ca_dn, X509 **pcert, EVP_PKEY **pkey,
285
STACK_OF(X509) **pother, UI_METHOD *ui_method, void *callback_data);
286
/* These callback types are for an ENGINE's handler for cipher and digest logic.
287
* These handlers have these prototypes;
288
* int foo(ENGINE *e, const EVP_CIPHER **cipher, const int **nids, int nid);
289
* int foo(ENGINE *e, const EVP_MD **digest, const int **nids, int nid);
290
* Looking at how to implement these handlers in the case of cipher support, if
291
* the framework wants the EVP_CIPHER for 'nid', it will call;
292
* foo(e, &p_evp_cipher, NULL, nid); (return zero for failure)
293
* If the framework wants a list of supported 'nid's, it will call;
294
* foo(e, NULL, &p_nids, 0); (returns number of 'nids' or -1 for error)
296
/* Returns to a pointer to the array of supported cipher 'nid's. If the second
297
* parameter is non-NULL it is set to the size of the returned array. */
298
typedef int (*ENGINE_CIPHERS_PTR)(ENGINE *, const EVP_CIPHER **, const int **, int);
299
typedef int (*ENGINE_DIGESTS_PTR)(ENGINE *, const EVP_MD **, const int **, int);
301
/* STRUCTURE functions ... all of these functions deal with pointers to ENGINE
302
* structures where the pointers have a "structural reference". This means that
303
* their reference is to allowed access to the structure but it does not imply
304
* that the structure is functional. To simply increment or decrement the
305
* structural reference count, use ENGINE_by_id and ENGINE_free. NB: This is not
306
* required when iterating using ENGINE_get_next as it will automatically
307
* decrement the structural reference count of the "current" ENGINE and
308
* increment the structural reference count of the ENGINE it returns (unless it
311
/* Get the first/last "ENGINE" type available. */
312
ENGINE *ENGINE_get_first(void);
313
ENGINE *ENGINE_get_last(void);
314
/* Iterate to the next/previous "ENGINE" type (NULL = end of the list). */
315
ENGINE *ENGINE_get_next(ENGINE *e);
316
ENGINE *ENGINE_get_prev(ENGINE *e);
317
/* Add another "ENGINE" type into the array. */
318
int ENGINE_add(ENGINE *e);
319
/* Remove an existing "ENGINE" type from the array. */
320
int ENGINE_remove(ENGINE *e);
321
/* Retrieve an engine from the list by its unique "id" value. */
322
ENGINE *ENGINE_by_id(const char *id);
323
/* Add all the built-in engines. */
324
void ENGINE_load_openssl(void);
325
void ENGINE_load_dynamic(void);
326
#ifndef OPENSSL_NO_STATIC_ENGINE
327
void ENGINE_load_4758cca(void);
328
void ENGINE_load_aep(void);
329
void ENGINE_load_atalla(void);
330
void ENGINE_load_chil(void);
331
void ENGINE_load_cswift(void);
332
#ifndef OPENSSL_NO_GMP
333
void ENGINE_load_gmp(void);
335
void ENGINE_load_nuron(void);
336
void ENGINE_load_sureware(void);
337
void ENGINE_load_ubsec(void);
339
void ENGINE_load_cryptodev(void);
340
void ENGINE_load_padlock(void);
341
void ENGINE_load_builtin_engines(void);
342
#ifdef OPENSSL_SYS_WIN32
343
#ifndef OPENSSL_NO_CAPIENG
344
void ENGINE_load_capi(void);
348
/* Get and set global flags (ENGINE_TABLE_FLAG_***) for the implementation
349
* "registry" handling. */
350
unsigned int ENGINE_get_table_flags(void);
351
void ENGINE_set_table_flags(unsigned int flags);
353
/* Manage registration of ENGINEs per "table". For each type, there are 3
355
* ENGINE_register_***(e) - registers the implementation from 'e' (if it has one)
356
* ENGINE_unregister_***(e) - unregister the implementation from 'e'
357
* ENGINE_register_all_***() - call ENGINE_register_***() for each 'e' in the list
358
* Cleanup is automatically registered from each table when required, so
359
* ENGINE_cleanup() will reverse any "register" operations. */
361
int ENGINE_register_RSA(ENGINE *e);
362
void ENGINE_unregister_RSA(ENGINE *e);
363
void ENGINE_register_all_RSA(void);
365
int ENGINE_register_DSA(ENGINE *e);
366
void ENGINE_unregister_DSA(ENGINE *e);
367
void ENGINE_register_all_DSA(void);
369
int ENGINE_register_ECDH(ENGINE *e);
370
void ENGINE_unregister_ECDH(ENGINE *e);
371
void ENGINE_register_all_ECDH(void);
373
int ENGINE_register_ECDSA(ENGINE *e);
374
void ENGINE_unregister_ECDSA(ENGINE *e);
375
void ENGINE_register_all_ECDSA(void);
377
int ENGINE_register_DH(ENGINE *e);
378
void ENGINE_unregister_DH(ENGINE *e);
379
void ENGINE_register_all_DH(void);
381
int ENGINE_register_RAND(ENGINE *e);
382
void ENGINE_unregister_RAND(ENGINE *e);
383
void ENGINE_register_all_RAND(void);
385
int ENGINE_register_STORE(ENGINE *e);
386
void ENGINE_unregister_STORE(ENGINE *e);
387
void ENGINE_register_all_STORE(void);
389
int ENGINE_register_ciphers(ENGINE *e);
390
void ENGINE_unregister_ciphers(ENGINE *e);
391
void ENGINE_register_all_ciphers(void);
393
int ENGINE_register_digests(ENGINE *e);
394
void ENGINE_unregister_digests(ENGINE *e);
395
void ENGINE_register_all_digests(void);
397
/* These functions register all support from the above categories. Note, use of
398
* these functions can result in static linkage of code your application may not
399
* need. If you only need a subset of functionality, consider using more
400
* selective initialisation. */
401
int ENGINE_register_complete(ENGINE *e);
402
int ENGINE_register_all_complete(void);
404
/* Send parametrised control commands to the engine. The possibilities to send
405
* down an integer, a pointer to data or a function pointer are provided. Any of
406
* the parameters may or may not be NULL, depending on the command number. In
407
* actuality, this function only requires a structural (rather than functional)
408
* reference to an engine, but many control commands may require the engine be
409
* functional. The caller should be aware of trying commands that require an
410
* operational ENGINE, and only use functional references in such situations. */
411
int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void));
413
/* This function tests if an ENGINE-specific command is usable as a "setting".
414
* Eg. in an application's config file that gets processed through
415
* ENGINE_ctrl_cmd_string(). If this returns zero, it is not available to
416
* ENGINE_ctrl_cmd_string(), only ENGINE_ctrl(). */
417
int ENGINE_cmd_is_executable(ENGINE *e, int cmd);
419
/* This function works like ENGINE_ctrl() with the exception of taking a
420
* command name instead of a command number, and can handle optional commands.
421
* See the comment on ENGINE_ctrl_cmd_string() for an explanation on how to
422
* use the cmd_name and cmd_optional. */
423
int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,
424
long i, void *p, void (*f)(void), int cmd_optional);
426
/* This function passes a command-name and argument to an ENGINE. The cmd_name
427
* is converted to a command number and the control command is called using
428
* 'arg' as an argument (unless the ENGINE doesn't support such a command, in
429
* which case no control command is called). The command is checked for input
430
* flags, and if necessary the argument will be converted to a numeric value. If
431
* cmd_optional is non-zero, then if the ENGINE doesn't support the given
432
* cmd_name the return value will be success anyway. This function is intended
433
* for applications to use so that users (or config files) can supply
434
* engine-specific config data to the ENGINE at run-time to control behaviour of
435
* specific engines. As such, it shouldn't be used for calling ENGINE_ctrl()
436
* functions that return data, deal with binary data, or that are otherwise
437
* supposed to be used directly through ENGINE_ctrl() in application code. Any
438
* "return" data from an ENGINE_ctrl() operation in this function will be lost -
439
* the return value is interpreted as failure if the return value is zero,
440
* success otherwise, and this function returns a boolean value as a result. In
441
* other words, vendors of 'ENGINE'-enabled devices should write ENGINE
442
* implementations with parameterisations that work in this scheme, so that
443
* compliant ENGINE-based applications can work consistently with the same
444
* configuration for the same ENGINE-enabled devices, across applications. */
445
int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
448
/* These functions are useful for manufacturing new ENGINE structures. They
449
* don't address reference counting at all - one uses them to populate an ENGINE
450
* structure with personalised implementations of things prior to using it
451
* directly or adding it to the builtin ENGINE list in OpenSSL. These are also
452
* here so that the ENGINE structure doesn't have to be exposed and break binary
454
ENGINE *ENGINE_new(void);
455
int ENGINE_free(ENGINE *e);
456
int ENGINE_up_ref(ENGINE *e);
457
int ENGINE_set_id(ENGINE *e, const char *id);
458
int ENGINE_set_name(ENGINE *e, const char *name);
459
int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);
460
int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);
461
int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *ecdh_meth);
462
int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *ecdsa_meth);
463
int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);
464
int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);
465
int ENGINE_set_STORE(ENGINE *e, const STORE_METHOD *store_meth);
466
int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f);
467
int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);
468
int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);
469
int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);
470
int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f);
471
int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f);
472
int ENGINE_set_load_ssl_client_cert_function(ENGINE *e,
473
ENGINE_SSL_CLIENT_CERT_PTR loadssl_f);
474
int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);
475
int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);
476
int ENGINE_set_flags(ENGINE *e, int flags);
477
int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);
478
/* These functions allow control over any per-structure ENGINE data. */
479
int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
480
CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
481
int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg);
482
void *ENGINE_get_ex_data(const ENGINE *e, int idx);
484
/* This function cleans up anything that needs it. Eg. the ENGINE_add() function
485
* automatically ensures the list cleanup function is registered to be called
486
* from ENGINE_cleanup(). Similarly, all ENGINE_register_*** functions ensure
487
* ENGINE_cleanup() will clean up after them. */
488
void ENGINE_cleanup(void);
490
/* These return values from within the ENGINE structure. These can be useful
491
* with functional references as well as structural references - it depends
492
* which you obtained. Using the result for functional purposes if you only
493
* obtained a structural reference may be problematic! */
494
const char *ENGINE_get_id(const ENGINE *e);
495
const char *ENGINE_get_name(const ENGINE *e);
496
const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e);
497
const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e);
498
const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e);
499
const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e);
500
const DH_METHOD *ENGINE_get_DH(const ENGINE *e);
501
const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e);
502
const STORE_METHOD *ENGINE_get_STORE(const ENGINE *e);
503
ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e);
504
ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e);
505
ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e);
506
ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e);
507
ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e);
508
ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e);
509
ENGINE_SSL_CLIENT_CERT_PTR ENGINE_get_ssl_client_cert_function(const ENGINE *e);
510
ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e);
511
ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e);
512
const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid);
513
const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid);
514
const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e);
515
int ENGINE_get_flags(const ENGINE *e);
517
/* FUNCTIONAL functions. These functions deal with ENGINE structures
518
* that have (or will) be initialised for use. Broadly speaking, the
519
* structural functions are useful for iterating the list of available
520
* engine types, creating new engine types, and other "list" operations.
521
* These functions actually deal with ENGINEs that are to be used. As
522
* such these functions can fail (if applicable) when particular
523
* engines are unavailable - eg. if a hardware accelerator is not
524
* attached or not functioning correctly. Each ENGINE has 2 reference
525
* counts; structural and functional. Every time a functional reference
526
* is obtained or released, a corresponding structural reference is
527
* automatically obtained or released too. */
529
/* Initialise a engine type for use (or up its reference count if it's
530
* already in use). This will fail if the engine is not currently
531
* operational and cannot initialise. */
532
int ENGINE_init(ENGINE *e);
533
/* Free a functional reference to a engine type. This does not require
534
* a corresponding call to ENGINE_free as it also releases a structural
536
int ENGINE_finish(ENGINE *e);
538
/* The following functions handle keys that are stored in some secondary
539
* location, handled by the engine. The storage may be on a card or
541
EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,
542
UI_METHOD *ui_method, void *callback_data);
543
EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
544
UI_METHOD *ui_method, void *callback_data);
545
int ENGINE_load_ssl_client_cert(ENGINE *e, SSL *s,
546
STACK_OF(X509_NAME) *ca_dn, X509 **pcert, EVP_PKEY **ppkey,
547
STACK_OF(X509) **pother,
548
UI_METHOD *ui_method, void *callback_data);
550
/* This returns a pointer for the current ENGINE structure that
551
* is (by default) performing any RSA operations. The value returned
552
* is an incremented reference, so it should be free'd (ENGINE_finish)
553
* before it is discarded. */
554
ENGINE *ENGINE_get_default_RSA(void);
555
/* Same for the other "methods" */
556
ENGINE *ENGINE_get_default_DSA(void);
557
ENGINE *ENGINE_get_default_ECDH(void);
558
ENGINE *ENGINE_get_default_ECDSA(void);
559
ENGINE *ENGINE_get_default_DH(void);
560
ENGINE *ENGINE_get_default_RAND(void);
561
/* These functions can be used to get a functional reference to perform
562
* ciphering or digesting corresponding to "nid". */
563
ENGINE *ENGINE_get_cipher_engine(int nid);
564
ENGINE *ENGINE_get_digest_engine(int nid);
566
/* This sets a new default ENGINE structure for performing RSA
567
* operations. If the result is non-zero (success) then the ENGINE
568
* structure will have had its reference count up'd so the caller
569
* should still free their own reference 'e'. */
570
int ENGINE_set_default_RSA(ENGINE *e);
571
int ENGINE_set_default_string(ENGINE *e, const char *def_list);
572
/* Same for the other "methods" */
573
int ENGINE_set_default_DSA(ENGINE *e);
574
int ENGINE_set_default_ECDH(ENGINE *e);
575
int ENGINE_set_default_ECDSA(ENGINE *e);
576
int ENGINE_set_default_DH(ENGINE *e);
577
int ENGINE_set_default_RAND(ENGINE *e);
578
int ENGINE_set_default_ciphers(ENGINE *e);
579
int ENGINE_set_default_digests(ENGINE *e);
581
/* The combination "set" - the flags are bitwise "OR"d from the
582
* ENGINE_METHOD_*** defines above. As with the "ENGINE_register_complete()"
583
* function, this function can result in unnecessary static linkage. If your
584
* application requires only specific functionality, consider using more
585
* selective functions. */
586
int ENGINE_set_default(ENGINE *e, unsigned int flags);
588
void ENGINE_add_conf_module(void);
590
/* Deprecated functions ... */
591
/* int ENGINE_clear_defaults(void); */
593
/**************************/
594
/* DYNAMIC ENGINE SUPPORT */
595
/**************************/
597
/* Binary/behaviour compatibility levels */
598
#define OSSL_DYNAMIC_VERSION (unsigned long)0x00020000
599
/* Binary versions older than this are too old for us (whether we're a loader or
601
#define OSSL_DYNAMIC_OLDEST (unsigned long)0x00020000
603
/* When compiling an ENGINE entirely as an external shared library, loadable by
604
* the "dynamic" ENGINE, these types are needed. The 'dynamic_fns' structure
605
* type provides the calling application's (or library's) error functionality
606
* and memory management function pointers to the loaded library. These should
607
* be used/set in the loaded library code so that the loading application's
608
* 'state' will be used/changed in all operations. The 'static_state' pointer
609
* allows the loaded library to know if it shares the same static data as the
610
* calling application (or library), and thus whether these callbacks need to be
612
typedef void *(*dyn_MEM_malloc_cb)(size_t);
613
typedef void *(*dyn_MEM_realloc_cb)(void *, size_t);
614
typedef void (*dyn_MEM_free_cb)(void *);
615
typedef struct st_dynamic_MEM_fns {
616
dyn_MEM_malloc_cb malloc_cb;
617
dyn_MEM_realloc_cb realloc_cb;
618
dyn_MEM_free_cb free_cb;
620
/* FIXME: Perhaps the memory and locking code (crypto.h) should declare and use
621
* these types so we (and any other dependant code) can simplify a bit?? */
622
typedef void (*dyn_lock_locking_cb)(int,int,const char *,int);
623
typedef int (*dyn_lock_add_lock_cb)(int*,int,int,const char *,int);
624
typedef struct CRYPTO_dynlock_value *(*dyn_dynlock_create_cb)(
626
typedef void (*dyn_dynlock_lock_cb)(int,struct CRYPTO_dynlock_value *,
628
typedef void (*dyn_dynlock_destroy_cb)(struct CRYPTO_dynlock_value *,
630
typedef struct st_dynamic_LOCK_fns {
631
dyn_lock_locking_cb lock_locking_cb;
632
dyn_lock_add_lock_cb lock_add_lock_cb;
633
dyn_dynlock_create_cb dynlock_create_cb;
634
dyn_dynlock_lock_cb dynlock_lock_cb;
635
dyn_dynlock_destroy_cb dynlock_destroy_cb;
637
/* The top-level structure */
638
typedef struct st_dynamic_fns {
640
const ERR_FNS *err_fns;
641
const CRYPTO_EX_DATA_IMPL *ex_data_fns;
642
dynamic_MEM_fns mem_fns;
643
dynamic_LOCK_fns lock_fns;
646
/* The version checking function should be of this prototype. NB: The
647
* ossl_version value passed in is the OSSL_DYNAMIC_VERSION of the loading code.
648
* If this function returns zero, it indicates a (potential) version
649
* incompatibility and the loaded library doesn't believe it can proceed.
650
* Otherwise, the returned value is the (latest) version supported by the
651
* loading library. The loader may still decide that the loaded code's version
652
* is unsatisfactory and could veto the load. The function is expected to
653
* be implemented with the symbol name "v_check", and a default implementation
654
* can be fully instantiated with IMPLEMENT_DYNAMIC_CHECK_FN(). */
655
typedef unsigned long (*dynamic_v_check_fn)(unsigned long ossl_version);
656
#define IMPLEMENT_DYNAMIC_CHECK_FN() \
657
OPENSSL_EXPORT unsigned long v_check(unsigned long v) { \
658
if(v >= OSSL_DYNAMIC_OLDEST) return OSSL_DYNAMIC_VERSION; \
661
/* This function is passed the ENGINE structure to initialise with its own
662
* function and command settings. It should not adjust the structural or
663
* functional reference counts. If this function returns zero, (a) the load will
664
* be aborted, (b) the previous ENGINE state will be memcpy'd back onto the
665
* structure, and (c) the shared library will be unloaded. So implementations
666
* should do their own internal cleanup in failure circumstances otherwise they
667
* could leak. The 'id' parameter, if non-NULL, represents the ENGINE id that
668
* the loader is looking for. If this is NULL, the shared library can choose to
669
* return failure or to initialise a 'default' ENGINE. If non-NULL, the shared
670
* library must initialise only an ENGINE matching the passed 'id'. The function
671
* is expected to be implemented with the symbol name "bind_engine". A standard
672
* implementation can be instantiated with IMPLEMENT_DYNAMIC_BIND_FN(fn) where
673
* the parameter 'fn' is a callback function that populates the ENGINE structure
674
* and returns an int value (zero for failure). 'fn' should have prototype;
675
* [static] int fn(ENGINE *e, const char *id); */
676
typedef int (*dynamic_bind_engine)(ENGINE *e, const char *id,
677
const dynamic_fns *fns);
678
#define IMPLEMENT_DYNAMIC_BIND_FN(fn) \
680
int bind_engine(ENGINE *e, const char *id, const dynamic_fns *fns) { \
681
if(ENGINE_get_static_state() == fns->static_state) goto skip_cbs; \
682
if(!CRYPTO_set_mem_functions(fns->mem_fns.malloc_cb, \
683
fns->mem_fns.realloc_cb, fns->mem_fns.free_cb)) \
685
CRYPTO_set_locking_callback(fns->lock_fns.lock_locking_cb); \
686
CRYPTO_set_add_lock_callback(fns->lock_fns.lock_add_lock_cb); \
687
CRYPTO_set_dynlock_create_callback(fns->lock_fns.dynlock_create_cb); \
688
CRYPTO_set_dynlock_lock_callback(fns->lock_fns.dynlock_lock_cb); \
689
CRYPTO_set_dynlock_destroy_callback(fns->lock_fns.dynlock_destroy_cb); \
690
if(!CRYPTO_set_ex_data_implementation(fns->ex_data_fns)) \
692
if(!ERR_set_implementation(fns->err_fns)) return 0; \
694
if(!fn(e,id)) return 0; \
697
/* If the loading application (or library) and the loaded ENGINE library share
698
* the same static data (eg. they're both dynamically linked to the same
699
* libcrypto.so) we need a way to avoid trying to set system callbacks - this
700
* would fail, and for the same reason that it's unnecessary to try. If the
701
* loaded ENGINE has (or gets from through the loader) its own copy of the
702
* libcrypto static data, we will need to set the callbacks. The easiest way to
703
* detect this is to have a function that returns a pointer to some static data
704
* and let the loading application and loaded ENGINE compare their respective
706
void *ENGINE_get_static_state(void);
708
#if defined(__OpenBSD__) || defined(__FreeBSD__)
709
void ENGINE_setup_bsd_cryptodev(void);
712
/* BEGIN ERROR CODES */
713
/* The following lines are auto generated by the script mkerr.pl. Any changes
714
* made after this point may be overwritten when the script is next run.
716
void ERR_load_ENGINE_strings(void);
718
/* Error codes for the ENGINE functions. */
720
/* Function codes. */
721
#define ENGINE_F_DYNAMIC_CTRL 180
722
#define ENGINE_F_DYNAMIC_GET_DATA_CTX 181
723
#define ENGINE_F_DYNAMIC_LOAD 182
724
#define ENGINE_F_DYNAMIC_SET_DATA_CTX 183
725
#define ENGINE_F_ENGINE_ADD 105
726
#define ENGINE_F_ENGINE_BY_ID 106
727
#define ENGINE_F_ENGINE_CMD_IS_EXECUTABLE 170
728
#define ENGINE_F_ENGINE_CTRL 142
729
#define ENGINE_F_ENGINE_CTRL_CMD 178
730
#define ENGINE_F_ENGINE_CTRL_CMD_STRING 171
731
#define ENGINE_F_ENGINE_FINISH 107
732
#define ENGINE_F_ENGINE_FREE_UTIL 108
733
#define ENGINE_F_ENGINE_GET_CIPHER 185
734
#define ENGINE_F_ENGINE_GET_DEFAULT_TYPE 177
735
#define ENGINE_F_ENGINE_GET_DIGEST 186
736
#define ENGINE_F_ENGINE_GET_NEXT 115
737
#define ENGINE_F_ENGINE_GET_PREV 116
738
#define ENGINE_F_ENGINE_INIT 119
739
#define ENGINE_F_ENGINE_LIST_ADD 120
740
#define ENGINE_F_ENGINE_LIST_REMOVE 121
741
#define ENGINE_F_ENGINE_LOAD_PRIVATE_KEY 150
742
#define ENGINE_F_ENGINE_LOAD_PUBLIC_KEY 151
743
#define ENGINE_F_ENGINE_LOAD_SSL_CLIENT_CERT 192
744
#define ENGINE_F_ENGINE_NEW 122
745
#define ENGINE_F_ENGINE_REMOVE 123
746
#define ENGINE_F_ENGINE_SET_DEFAULT_STRING 189
747
#define ENGINE_F_ENGINE_SET_DEFAULT_TYPE 126
748
#define ENGINE_F_ENGINE_SET_ID 129
749
#define ENGINE_F_ENGINE_SET_NAME 130
750
#define ENGINE_F_ENGINE_TABLE_REGISTER 184
751
#define ENGINE_F_ENGINE_UNLOAD_KEY 152
752
#define ENGINE_F_ENGINE_UNLOCKED_FINISH 191
753
#define ENGINE_F_ENGINE_UP_REF 190
754
#define ENGINE_F_INT_CTRL_HELPER 172
755
#define ENGINE_F_INT_ENGINE_CONFIGURE 188
756
#define ENGINE_F_INT_ENGINE_MODULE_INIT 187
757
#define ENGINE_F_LOG_MESSAGE 141
760
#define ENGINE_R_ALREADY_LOADED 100
761
#define ENGINE_R_ARGUMENT_IS_NOT_A_NUMBER 133
762
#define ENGINE_R_CMD_NOT_EXECUTABLE 134
763
#define ENGINE_R_COMMAND_TAKES_INPUT 135
764
#define ENGINE_R_COMMAND_TAKES_NO_INPUT 136
765
#define ENGINE_R_CONFLICTING_ENGINE_ID 103
766
#define ENGINE_R_CTRL_COMMAND_NOT_IMPLEMENTED 119
767
#define ENGINE_R_DH_NOT_IMPLEMENTED 139
768
#define ENGINE_R_DSA_NOT_IMPLEMENTED 140
769
#define ENGINE_R_DSO_FAILURE 104
770
#define ENGINE_R_DSO_NOT_FOUND 132
771
#define ENGINE_R_ENGINES_SECTION_ERROR 148
772
#define ENGINE_R_ENGINE_CONFIGURATION_ERROR 101
773
#define ENGINE_R_ENGINE_IS_NOT_IN_LIST 105
774
#define ENGINE_R_ENGINE_SECTION_ERROR 149
775
#define ENGINE_R_FAILED_LOADING_PRIVATE_KEY 128
776
#define ENGINE_R_FAILED_LOADING_PUBLIC_KEY 129
777
#define ENGINE_R_FINISH_FAILED 106
778
#define ENGINE_R_GET_HANDLE_FAILED 107
779
#define ENGINE_R_ID_OR_NAME_MISSING 108
780
#define ENGINE_R_INIT_FAILED 109
781
#define ENGINE_R_INTERNAL_LIST_ERROR 110
782
#define ENGINE_R_INVALID_ARGUMENT 143
783
#define ENGINE_R_INVALID_CMD_NAME 137
784
#define ENGINE_R_INVALID_CMD_NUMBER 138
785
#define ENGINE_R_INVALID_INIT_VALUE 151
786
#define ENGINE_R_INVALID_STRING 150
787
#define ENGINE_R_NOT_INITIALISED 117
788
#define ENGINE_R_NOT_LOADED 112
789
#define ENGINE_R_NO_CONTROL_FUNCTION 120
790
#define ENGINE_R_NO_INDEX 144
791
#define ENGINE_R_NO_LOAD_FUNCTION 125
792
#define ENGINE_R_NO_REFERENCE 130
793
#define ENGINE_R_NO_SUCH_ENGINE 116
794
#define ENGINE_R_NO_UNLOAD_FUNCTION 126
795
#define ENGINE_R_PROVIDE_PARAMETERS 113
796
#define ENGINE_R_RSA_NOT_IMPLEMENTED 141
797
#define ENGINE_R_UNIMPLEMENTED_CIPHER 146
798
#define ENGINE_R_UNIMPLEMENTED_DIGEST 147
799
#define ENGINE_R_VERSION_INCOMPATIBILITY 145
added
removed
crypto/engine/engine.h
