diff options
Diffstat (limited to 'secure/lib/libcrypto/man/engine.3')
| -rw-r--r-- | secure/lib/libcrypto/man/engine.3 | 784 |
1 files changed, 0 insertions, 784 deletions
diff --git a/secure/lib/libcrypto/man/engine.3 b/secure/lib/libcrypto/man/engine.3 deleted file mode 100644 index a6d54005c2d2..000000000000 --- a/secure/lib/libcrypto/man/engine.3 +++ /dev/null @@ -1,784 +0,0 @@ -.\" Automatically generated by Pod::Man version 1.15 -.\" Wed Feb 19 16:43:04 2003 -.\" -.\" Standard preamble: -.\" ====================================================================== -.de Sh \" Subsection heading -.br -.if t .Sp -.ne 5 -.PP -\fB\\$1\fR -.PP -.. -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Ip \" List item -.br -.ie \\n(.$>=3 .ne \\$3 -.el .ne 3 -.IP "\\$1" \\$2 -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R - -.fi -.. -.\" Set up some character translations and predefined strings. \*(-- will -.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left -.\" double quote, and \*(R" will give a right double quote. | will give a -.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used -.\" to do unbreakable dashes and therefore won't be available. \*(C` and -.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<> -.tr \(*W-|\(bv\*(Tr -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.ie n \{\ -. ds -- \(*W- -. ds PI pi -. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -. ds L" "" -. ds R" "" -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds -- \|\(em\| -. ds PI \(*p -. ds L" `` -. ds R" '' -'br\} -.\" -.\" If the F register is turned on, we'll generate index entries on stderr -.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and -.\" index entries marked with X<> in POD. Of course, you'll have to process -.\" the output yourself in some meaningful fashion. -.if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. nr % 0 -. rr F -.\} -.\" -.\" For nroff, turn off justification. Always turn off hyphenation; it -.\" makes way too many mistakes in technical documents. -.hy 0 -.if n .na -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). -.\" Fear. Run. Save yourself. No user-serviceable parts. -.bd B 3 -. \" fudge factors for nroff and troff -.if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP -.\} -.if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& -.\} -. \" simple accents for nroff and troff -.if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds / -.\} -.if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -.\} -. \" troff and (daisy-wheel) nroff accents -.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' -.ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] -.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' -.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' -.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] -.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] -.ds ae a\h'-(\w'a'u*4/10)'e -.ds Ae A\h'-(\w'A'u*4/10)'E -. \" corrections for vroff -.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' -.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) -.if \n(.H>23 .if \n(.V>19 \ -\{\ -. ds : e -. ds 8 ss -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -.\} -.rm #[ #] #H #V #F C -.\" ====================================================================== -.\" -.IX Title "engine 3" -.TH engine 3 "0.9.7a" "2003-02-19" "OpenSSL" -.UC -.SH "NAME" -engine \- \s-1ENGINE\s0 cryptographic module support -.SH "SYNOPSIS" -.IX Header "SYNOPSIS" -.Vb 1 -\& #include <openssl/engine.h> -.Ve -.Vb 4 -\& ENGINE *ENGINE_get_first(void); -\& ENGINE *ENGINE_get_last(void); -\& ENGINE *ENGINE_get_next(ENGINE *e); -\& ENGINE *ENGINE_get_prev(ENGINE *e); -.Ve -.Vb 2 -\& int ENGINE_add(ENGINE *e); -\& int ENGINE_remove(ENGINE *e); -.Ve -.Vb 1 -\& ENGINE *ENGINE_by_id(const char *id); -.Ve -.Vb 2 -\& int ENGINE_init(ENGINE *e); -\& int ENGINE_finish(ENGINE *e); -.Ve -.Vb 12 -\& void ENGINE_load_openssl(void); -\& void ENGINE_load_dynamic(void); -\& void ENGINE_load_cswift(void); -\& void ENGINE_load_chil(void); -\& void ENGINE_load_atalla(void); -\& void ENGINE_load_nuron(void); -\& void ENGINE_load_ubsec(void); -\& void ENGINE_load_aep(void); -\& void ENGINE_load_sureware(void); -\& void ENGINE_load_4758cca(void); -\& void ENGINE_load_openbsd_dev_crypto(void); -\& void ENGINE_load_builtin_engines(void); -.Ve -.Vb 1 -\& void ENGINE_cleanup(void); -.Ve -.Vb 6 -\& ENGINE *ENGINE_get_default_RSA(void); -\& ENGINE *ENGINE_get_default_DSA(void); -\& ENGINE *ENGINE_get_default_DH(void); -\& ENGINE *ENGINE_get_default_RAND(void); -\& ENGINE *ENGINE_get_cipher_engine(int nid); -\& ENGINE *ENGINE_get_digest_engine(int nid); -.Ve -.Vb 7 -\& int ENGINE_set_default_RSA(ENGINE *e); -\& int ENGINE_set_default_DSA(ENGINE *e); -\& int ENGINE_set_default_DH(ENGINE *e); -\& int ENGINE_set_default_RAND(ENGINE *e); -\& int ENGINE_set_default_ciphers(ENGINE *e); -\& int ENGINE_set_default_digests(ENGINE *e); -\& int ENGINE_set_default_string(ENGINE *e, const char *list); -.Ve -.Vb 1 -\& int ENGINE_set_default(ENGINE *e, unsigned int flags); -.Ve -.Vb 2 -\& unsigned int ENGINE_get_table_flags(void); -\& void ENGINE_set_table_flags(unsigned int flags); -.Ve -.Vb 20 -\& int ENGINE_register_RSA(ENGINE *e); -\& void ENGINE_unregister_RSA(ENGINE *e); -\& void ENGINE_register_all_RSA(void); -\& int ENGINE_register_DSA(ENGINE *e); -\& void ENGINE_unregister_DSA(ENGINE *e); -\& void ENGINE_register_all_DSA(void); -\& int ENGINE_register_DH(ENGINE *e); -\& void ENGINE_unregister_DH(ENGINE *e); -\& void ENGINE_register_all_DH(void); -\& int ENGINE_register_RAND(ENGINE *e); -\& void ENGINE_unregister_RAND(ENGINE *e); -\& void ENGINE_register_all_RAND(void); -\& int ENGINE_register_ciphers(ENGINE *e); -\& void ENGINE_unregister_ciphers(ENGINE *e); -\& void ENGINE_register_all_ciphers(void); -\& int ENGINE_register_digests(ENGINE *e); -\& void ENGINE_unregister_digests(ENGINE *e); -\& void ENGINE_register_all_digests(void); -\& int ENGINE_register_complete(ENGINE *e); -\& int ENGINE_register_all_complete(void); -.Ve -.Vb 6 -\& int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)()); -\& int ENGINE_cmd_is_executable(ENGINE *e, int cmd); -\& int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, -\& long i, void *p, void (*f)(), int cmd_optional); -\& int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, -\& int cmd_optional); -.Ve -.Vb 2 -\& int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg); -\& void *ENGINE_get_ex_data(const ENGINE *e, int idx); -.Ve -.Vb 2 -\& int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, -\& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); -.Ve -.Vb 2 -\& ENGINE *ENGINE_new(void); -\& int ENGINE_free(ENGINE *e); -.Ve -.Vb 16 -\& int ENGINE_set_id(ENGINE *e, const char *id); -\& int ENGINE_set_name(ENGINE *e, const char *name); -\& int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); -\& int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth); -\& int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth); -\& int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); -\& int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); -\& int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); -\& int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); -\& int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); -\& int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f); -\& int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); -\& int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); -\& int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); -\& int ENGINE_set_flags(ENGINE *e, int flags); -\& int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); -.Ve -.Vb 18 -\& const char *ENGINE_get_id(const ENGINE *e); -\& const char *ENGINE_get_name(const ENGINE *e); -\& const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); -\& const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); -\& const DH_METHOD *ENGINE_get_DH(const ENGINE *e); -\& const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); -\& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); -\& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); -\& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); -\& ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); -\& ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); -\& ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); -\& ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); -\& ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); -\& const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); -\& const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); -\& int ENGINE_get_flags(const ENGINE *e); -\& const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); -.Ve -.Vb 4 -\& EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, -\& UI_METHOD *ui_method, void *callback_data); -\& EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, -\& UI_METHOD *ui_method, void *callback_data); -.Ve -.Vb 1 -\& void ENGINE_add_conf_module(void); -.Ve -.SH "DESCRIPTION" -.IX Header "DESCRIPTION" -These functions create, manipulate, and use cryptographic modules in the -form of \fB\s-1ENGINE\s0\fR objects. These objects act as containers for -implementations of cryptographic algorithms, and support a -reference-counted mechanism to allow them to be dynamically loaded in and -out of the running application. -.PP -The cryptographic functionality that can be provided by an \fB\s-1ENGINE\s0\fR -implementation includes the following abstractions; -.PP -.Vb 5 -\& RSA_METHOD - for providing alternative RSA implementations -\& DSA_METHOD, DH_METHOD, RAND_METHOD - alternative DSA, DH, and RAND -\& EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid') -\& EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid') -\& key-loading - loading public and/or private EVP_PKEY keys -.Ve -.Sh "Reference counting and handles" -.IX Subsection "Reference counting and handles" -Due to the modular nature of the \s-1ENGINE\s0 \s-1API\s0, pointers to ENGINEs need to be -treated as handles \- ie. not only as pointers, but also as references to -the underlying \s-1ENGINE\s0 object. Ie. you should obtain a new reference when -making copies of an \s-1ENGINE\s0 pointer if the copies will be used (and -released) independantly. -.PP -\&\s-1ENGINE\s0 objects have two levels of reference-counting to match the way in -which the objects are used. At the most basic level, each \s-1ENGINE\s0 pointer is -inherently a \fBstructural\fR reference \- you need a structural reference -simply to refer to the pointer value at all, as this kind of reference is -your guarantee that the structure can not be deallocated until you release -your reference. -.PP -However, a structural reference provides no guarantee that the \s-1ENGINE\s0 has -been initiliased to be usable to perform any of its cryptographic -implementations \- and indeed it's quite possible that most ENGINEs will not -initialised at all on standard setups, as ENGINEs are typically used to -support specialised hardware. To use an \s-1ENGINE\s0's functionality, you need a -\&\fBfunctional\fR reference. This kind of reference can be considered a -specialised form of structural reference, because each functional reference -implicitly contains a structural reference as well \- however to avoid -difficult-to-find programming bugs, it is recommended to treat the two -kinds of reference independantly. If you have a functional reference to an -\&\s-1ENGINE\s0, you have a guarantee that the \s-1ENGINE\s0 has been initialised ready to -perform cryptographic operations and will not be uninitialised or cleaned -up until after you have released your reference. -.PP -We will discuss the two kinds of reference separately, including how to -tell which one you are dealing with at any given point in time (after all -they are both simply (\s-1ENGINE\s0 *) pointers, the difference is in the way they -are used). -.PP -\&\fIStructural references\fR -.PP -This basic type of reference is typically used for creating new ENGINEs -dynamically, iterating across OpenSSL's internal linked-list of loaded -ENGINEs, reading information about an \s-1ENGINE\s0, etc. Essentially a structural -reference is sufficient if you only need to query or manipulate the data of -an \s-1ENGINE\s0 implementation rather than use its functionality. -.PP -The \fIENGINE_new()\fR function returns a structural reference to a new (empty) -\&\s-1ENGINE\s0 object. Other than that, structural references come from return -values to various \s-1ENGINE\s0 \s-1API\s0 functions such as; \fIENGINE_by_id()\fR, -\&\fIENGINE_get_first()\fR, \fIENGINE_get_last()\fR, \fIENGINE_get_next()\fR, -\&\fIENGINE_get_prev()\fR. All structural references should be released by a -corresponding to call to the \fIENGINE_free()\fR function \- the \s-1ENGINE\s0 object -itself will only actually be cleaned up and deallocated when the last -structural reference is released. -.PP -It should also be noted that many \s-1ENGINE\s0 \s-1API\s0 function calls that accept a -structural reference will internally obtain another reference \- typically -this happens whenever the supplied \s-1ENGINE\s0 will be needed by OpenSSL after -the function has returned. Eg. the function to add a new \s-1ENGINE\s0 to -OpenSSL's internal list is \fIENGINE_add()\fR \- if this function returns success, -then OpenSSL will have stored a new structural reference internally so the -caller is still responsible for freeing their own reference with -\&\fIENGINE_free()\fR when they are finished with it. In a similar way, some -functions will automatically release the structural reference passed to it -if part of the function's job is to do so. Eg. the \fIENGINE_get_next()\fR and -\&\fIENGINE_get_prev()\fR functions are used for iterating across the internal -\&\s-1ENGINE\s0 list \- they will return a new structural reference to the next (or -previous) \s-1ENGINE\s0 in the list or \s-1NULL\s0 if at the end (or beginning) of the -list, but in either case the structural reference passed to the function is -released on behalf of the caller. -.PP -To clarify a particular function's handling of references, one should -always consult that function's documentation \*(L"man\*(R" page, or failing that -the openssl/engine.h header file includes some hints. -.PP -\&\fIFunctional references\fR -.PP -As mentioned, functional references exist when the cryptographic -functionality of an \s-1ENGINE\s0 is required to be available. A functional -reference can be obtained in one of two ways; from an existing structural -reference to the required \s-1ENGINE\s0, or by asking OpenSSL for the default -operational \s-1ENGINE\s0 for a given cryptographic purpose. -.PP -To obtain a functional reference from an existing structural reference, -call the \fIENGINE_init()\fR function. This returns zero if the \s-1ENGINE\s0 was not -already operational and couldn't be successfully initialised (eg. lack of -system drivers, no special hardware attached, etc), otherwise it will -return non-zero to indicate that the \s-1ENGINE\s0 is now operational and will -have allocated a new \fBfunctional\fR reference to the \s-1ENGINE\s0. In this case, -the supplied \s-1ENGINE\s0 pointer is, from the point of the view of the caller, -both a structural reference and a functional reference \- so if the caller -intends to use it as a functional reference it should free the structural -reference with \fIENGINE_free()\fR first. If the caller wishes to use it only as -a structural reference (eg. if the \fIENGINE_init()\fR call was simply to test if -the \s-1ENGINE\s0 seems available/online), then it should free the functional -reference; all functional references are released by the \fIENGINE_finish()\fR -function. -.PP -The second way to get a functional reference is by asking OpenSSL for a -default implementation for a given task, eg. by \fIENGINE_get_default_RSA()\fR, -\&\fIENGINE_get_default_cipher_engine()\fR, etc. These are discussed in the next -section, though they are not usually required by application programmers as -they are used automatically when creating and using the relevant -algorithm-specific types in OpenSSL, such as \s-1RSA\s0, \s-1DSA\s0, \s-1EVP_CIPHER_CTX\s0, etc. -.Sh "Default implementations" -.IX Subsection "Default implementations" -For each supported abstraction, the \s-1ENGINE\s0 code maintains an internal table -of state to control which implementations are available for a given -abstraction and which should be used by default. These implementations are -registered in the tables separated-out by an 'nid' index, because -abstractions like \s-1EVP_CIPHER\s0 and \s-1EVP_DIGEST\s0 support many distinct -algorithms and modes \- ENGINEs will support different numbers and -combinations of these. In the case of other abstractions like \s-1RSA\s0, \s-1DSA\s0, -etc, there is only one \*(L"algorithm\*(R" so all implementations implicitly -register using the same 'nid' index. ENGINEs can be \fBregistered\fR into -these tables to make themselves available for use automatically by the -various abstractions, eg. \s-1RSA\s0. For illustrative purposes, we continue with -the \s-1RSA\s0 example, though all comments apply similarly to the other -abstractions (they each get their own table and linkage to the -corresponding section of openssl code). -.PP -When a new \s-1RSA\s0 key is being created, ie. in \fIRSA_new_method()\fR, a -\&\*(L"get_default\*(R" call will be made to the \s-1ENGINE\s0 subsystem to process the \s-1RSA\s0 -state table and return a functional reference to an initialised \s-1ENGINE\s0 -whose \s-1RSA_METHOD\s0 should be used. If no \s-1ENGINE\s0 should (or can) be used, it -will return \s-1NULL\s0 and the \s-1RSA\s0 key will operate with a \s-1NULL\s0 \s-1ENGINE\s0 handle by -using the conventional \s-1RSA\s0 implementation in OpenSSL (and will from then on -behave the way it used to before the \s-1ENGINE\s0 \s-1API\s0 existed \- for details see -RSA_new_method(3)). -.PP -Each state table has a flag to note whether it has processed this -\&\*(L"get_default\*(R" query since the table was last modified, because to process -this question it must iterate across all the registered ENGINEs in the -table trying to initialise each of them in turn, in case one of them is -operational. If it returns a functional reference to an \s-1ENGINE\s0, it will -also cache another reference to speed up processing future queries (without -needing to iterate across the table). Likewise, it will cache a \s-1NULL\s0 -response if no \s-1ENGINE\s0 was available so that future queries won't repeat the -same iteration unless the state table changes. This behaviour can also be -changed; if the \s-1ENGINE_TABLE_FLAG_NOINIT\s0 flag is set (using -\&\fIENGINE_set_table_flags()\fR), no attempted initialisations will take place, -instead the only way for the state table to return a non-NULL \s-1ENGINE\s0 to the -\&\*(L"get_default\*(R" query will be if one is expressly set in the table. Eg. -\&\fIENGINE_set_default_RSA()\fR does the same job as \fIENGINE_register_RSA()\fR except -that it also sets the state table's cached response for the \*(L"get_default\*(R" -query. -.PP -In the case of abstractions like \s-1EVP_CIPHER\s0, where implementations are -indexed by 'nid', these flags and cached-responses are distinct for each -\&'nid' value. -.PP -It is worth illustrating the difference between \*(L"registration\*(R" of ENGINEs -into these per-algorithm state tables and using the alternative -\&\*(L"set_default\*(R" functions. The latter handles both \*(L"registration\*(R" and also -setting the cached \*(L"default\*(R" \s-1ENGINE\s0 in each relevant state table \- so -registered ENGINEs will only have a chance to be initialised for use as a -default if a default \s-1ENGINE\s0 wasn't already set for the same state table. -Eg. if \s-1ENGINE\s0 X supports cipher nids {A,B} and \s-1RSA\s0, \s-1ENGINE\s0 Y supports -ciphers {A} and \s-1DSA\s0, and the following code is executed; -.PP -.Vb 7 -\& ENGINE_register_complete(X); -\& ENGINE_set_default(Y, ENGINE_METHOD_ALL); -\& e1 = ENGINE_get_default_RSA(); -\& e2 = ENGINE_get_cipher_engine(A); -\& e3 = ENGINE_get_cipher_engine(B); -\& e4 = ENGINE_get_default_DSA(); -\& e5 = ENGINE_get_cipher_engine(C); -.Ve -The results would be as follows; -.PP -.Vb 5 -\& assert(e1 == X); -\& assert(e2 == Y); -\& assert(e3 == X); -\& assert(e4 == Y); -\& assert(e5 == NULL); -.Ve -.Sh "Application requirements" -.IX Subsection "Application requirements" -This section will explain the basic things an application programmer should -support to make the most useful elements of the \s-1ENGINE\s0 functionality -available to the user. The first thing to consider is whether the -programmer wishes to make alternative \s-1ENGINE\s0 modules available to the -application and user. OpenSSL maintains an internal linked list of -\&\*(L"visible\*(R" ENGINEs from which it has to operate \- at start-up, this list is -empty and in fact if an application does not call any \s-1ENGINE\s0 \s-1API\s0 calls and -it uses static linking against openssl, then the resulting application -binary will not contain any alternative \s-1ENGINE\s0 code at all. So the first -consideration is whether any/all available \s-1ENGINE\s0 implementations should be -made visible to OpenSSL \- this is controlled by calling the various \*(L"load\*(R" -functions, eg. -.PP -.Vb 9 -\& /* Make the "dynamic" ENGINE available */ -\& void ENGINE_load_dynamic(void); -\& /* Make the CryptoSwift hardware acceleration support available */ -\& void ENGINE_load_cswift(void); -\& /* Make support for nCipher's "CHIL" hardware available */ -\& void ENGINE_load_chil(void); -\& ... -\& /* Make ALL ENGINE implementations bundled with OpenSSL available */ -\& void ENGINE_load_builtin_engines(void); -.Ve -Having called any of these functions, \s-1ENGINE\s0 objects would have been -dynamically allocated and populated with these implementations and linked -into OpenSSL's internal linked list. At this point it is important to -mention an important \s-1API\s0 function; -.PP -.Vb 1 -\& void ENGINE_cleanup(void); -.Ve -If no \s-1ENGINE\s0 \s-1API\s0 functions are called at all in an application, then there -are no inherent memory leaks to worry about from the \s-1ENGINE\s0 functionality, -however if any ENGINEs are \*(L"load\*(R"ed, even if they are never registered or -used, it is necessary to use the \fIENGINE_cleanup()\fR function to -correspondingly cleanup before program exit, if the caller wishes to avoid -memory leaks. This mechanism uses an internal callback registration table -so that any \s-1ENGINE\s0 \s-1API\s0 functionality that knows it requires cleanup can -register its cleanup details to be called during \fIENGINE_cleanup()\fR. This -approach allows \fIENGINE_cleanup()\fR to clean up after any \s-1ENGINE\s0 functionality -at all that your program uses, yet doesn't automatically create linker -dependencies to all possible \s-1ENGINE\s0 functionality \- only the cleanup -callbacks required by the functionality you do use will be required by the -linker. -.PP -The fact that ENGINEs are made visible to OpenSSL (and thus are linked into -the program and loaded into memory at run-time) does not mean they are -\&\*(L"registered\*(R" or called into use by OpenSSL automatically \- that behaviour -is something for the application to have control over. Some applications -will want to allow the user to specify exactly which \s-1ENGINE\s0 they want used -if any is to be used at all. Others may prefer to load all support and have -OpenSSL automatically use at run-time any \s-1ENGINE\s0 that is able to -successfully initialise \- ie. to assume that this corresponds to -acceleration hardware attached to the machine or some such thing. There are -probably numerous other ways in which applications may prefer to handle -things, so we will simply illustrate the consequences as they apply to a -couple of simple cases and leave developers to consider these and the -source code to openssl's builtin utilities as guides. -.PP -\&\fIUsing a specific \s-1ENGINE\s0 implementation\fR -.PP -Here we'll assume an application has been configured by its user or admin -to want to use the \*(L"\s-1ACME\s0\*(R" \s-1ENGINE\s0 if it is available in the version of -OpenSSL the application was compiled with. If it is available, it should be -used by default for all \s-1RSA\s0, \s-1DSA\s0, and symmetric cipher operation, otherwise -OpenSSL should use its builtin software as per usual. The following code -illustrates how to approach this; -.PP -.Vb 22 -\& ENGINE *e; -\& const char *engine_id = "ACME"; -\& ENGINE_load_builtin_engines(); -\& e = ENGINE_by_id(engine_id); -\& if(!e) -\& /* the engine isn't available */ -\& return; -\& if(!ENGINE_init(e)) { -\& /* the engine couldn't initialise, release 'e' */ -\& ENGINE_free(e); -\& return; -\& } -\& if(!ENGINE_set_default_RSA(e)) -\& /* This should only happen when 'e' can't initialise, but the previous -\& * statement suggests it did. */ -\& abort(); -\& ENGINE_set_default_DSA(e); -\& ENGINE_set_default_ciphers(e); -\& /* Release the functional reference from ENGINE_init() */ -\& ENGINE_finish(e); -\& /* Release the structural reference from ENGINE_by_id() */ -\& ENGINE_free(e); -.Ve -\&\fIAutomatically using builtin \s-1ENGINE\s0 implementations\fR -.PP -Here we'll assume we want to load and register all \s-1ENGINE\s0 implementations -bundled with OpenSSL, such that for any cryptographic algorithm required by -OpenSSL \- if there is an \s-1ENGINE\s0 that implements it and can be initialise, -it should be used. The following code illustrates how this can work; -.PP -.Vb 4 -\& /* Load all bundled ENGINEs into memory and make them visible */ -\& ENGINE_load_builtin_engines(); -\& /* Register all of them for every algorithm they collectively implement */ -\& ENGINE_register_all_complete(); -.Ve -That's all that's required. Eg. the next time OpenSSL tries to set up an -\&\s-1RSA\s0 key, any bundled ENGINEs that implement \s-1RSA_METHOD\s0 will be passed to -\&\fIENGINE_init()\fR and if any of those succeed, that \s-1ENGINE\s0 will be set as the -default for use with \s-1RSA\s0 from then on. -.Sh "Advanced configuration support" -.IX Subsection "Advanced configuration support" -There is a mechanism supported by the \s-1ENGINE\s0 framework that allows each -\&\s-1ENGINE\s0 implementation to define an arbitrary set of configuration -\&\*(L"commands\*(R" and expose them to OpenSSL and any applications based on -OpenSSL. This mechanism is entirely based on the use of name-value pairs -and and assumes \s-1ASCII\s0 input (no unicode or \s-1UTF\s0 for now!), so it is ideal if -applications want to provide a transparent way for users to provide -arbitrary configuration \*(L"directives\*(R" directly to such ENGINEs. It is also -possible for the application to dynamically interrogate the loaded \s-1ENGINE\s0 -implementations for the names, descriptions, and input flags of their -available \*(L"control commands\*(R", providing a more flexible configuration -scheme. However, if the user is expected to know which \s-1ENGINE\s0 device he/she -is using (in the case of specialised hardware, this goes without saying) -then applications may not need to concern themselves with discovering the -supported control commands and simply prefer to allow settings to passed -into ENGINEs exactly as they are provided by the user. -.PP -Before illustrating how control commands work, it is worth mentioning what -they are typically used for. Broadly speaking there are two uses for -control commands; the first is to provide the necessary details to the -implementation (which may know nothing at all specific to the host system) -so that it can be initialised for use. This could include the path to any -driver or config files it needs to load, required network addresses, -smart-card identifiers, passwords to initialise password-protected devices, -logging information, etc etc. This class of commands typically needs to be -passed to an \s-1ENGINE\s0 \fBbefore\fR attempting to initialise it, ie. before -calling \fIENGINE_init()\fR. The other class of commands consist of settings or -operations that tweak certain behaviour or cause certain operations to take -place, and these commands may work either before or after \fIENGINE_init()\fR, or -in same cases both. \s-1ENGINE\s0 implementations should provide indications of -this in the descriptions attached to builtin control commands and/or in -external product documentation. -.PP -\&\fIIssuing control commands to an \s-1ENGINE\s0\fR -.PP -Let's illustrate by example; a function for which the caller supplies the -name of the \s-1ENGINE\s0 it wishes to use, a table of string-pairs for use before -initialisation, and another table for use after initialisation. Note that -the string-pairs used for control commands consist of a command \*(L"name\*(R" -followed by the command \*(L"parameter\*(R" \- the parameter could be \s-1NULL\s0 in some -cases but the name can not. This function should initialise the \s-1ENGINE\s0 -(issuing the \*(L"pre\*(R" commands beforehand and the \*(L"post\*(R" commands afterwards) -and set it as the default for everything except \s-1RAND\s0 and then return a -boolean success or failure. -.PP -.Vb 36 -\& int generic_load_engine_fn(const char *engine_id, -\& const char **pre_cmds, int pre_num, -\& const char **post_cmds, int post_num) -\& { -\& ENGINE *e = ENGINE_by_id(engine_id); -\& if(!e) return 0; -\& while(pre_num--) { -\& if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) { -\& fprintf(stderr, "Failed command (%s - %s:%s)\en", engine_id, -\& pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)"); -\& ENGINE_free(e); -\& return 0; -\& } -\& pre_cmds += 2; -\& } -\& if(!ENGINE_init(e)) { -\& fprintf(stderr, "Failed initialisation\en"); -\& ENGINE_free(e); -\& return 0; -\& } -\& /* ENGINE_init() returned a functional reference, so free the structural -\& * reference from ENGINE_by_id(). */ -\& ENGINE_free(e); -\& while(post_num--) { -\& if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) { -\& fprintf(stderr, "Failed command (%s - %s:%s)\en", engine_id, -\& post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)"); -\& ENGINE_finish(e); -\& return 0; -\& } -\& post_cmds += 2; -\& } -\& ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); -\& /* Success */ -\& return 1; -\& } -.Ve -Note that \fIENGINE_ctrl_cmd_string()\fR accepts a boolean argument that can -relax the semantics of the function \- if set non-zero it will only return -failure if the \s-1ENGINE\s0 supported the given command name but failed while -executing it, if the \s-1ENGINE\s0 doesn't support the command name it will simply -return success without doing anything. In this case we assume the user is -only supplying commands specific to the given \s-1ENGINE\s0 so we set this to -\&\s-1FALSE\s0. -.PP -\&\fIDiscovering supported control commands\fR -.PP -It is possible to discover at run-time the names, numerical-ids, descriptions -and input parameters of the control commands supported from a structural -reference to any \s-1ENGINE\s0. It is first important to note that some control -commands are defined by OpenSSL itself and it will intercept and handle these -control commands on behalf of the \s-1ENGINE\s0, ie. the \s-1ENGINE\s0's \fIctrl()\fR handler is not -used for the control command. openssl/engine.h defines a symbol, -\&\s-1ENGINE_CMD_BASE\s0, that all control commands implemented by ENGINEs from. Any -command value lower than this symbol is considered a \*(L"generic\*(R" command is -handled directly by the OpenSSL core routines. -.PP -It is using these \*(L"core\*(R" control commands that one can discover the the control -commands implemented by a given \s-1ENGINE\s0, specifically the commands; -.PP -.Vb 9 -\& #define ENGINE_HAS_CTRL_FUNCTION 10 -\& #define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11 -\& #define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12 -\& #define ENGINE_CTRL_GET_CMD_FROM_NAME 13 -\& #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14 -\& #define ENGINE_CTRL_GET_NAME_FROM_CMD 15 -\& #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16 -\& #define ENGINE_CTRL_GET_DESC_FROM_CMD 17 -\& #define ENGINE_CTRL_GET_CMD_FLAGS 18 -.Ve -Whilst these commands are automatically processed by the OpenSSL framework code, -they use various properties exposed by each \s-1ENGINE\s0 by which to process these -queries. An \s-1ENGINE\s0 has 3 properties it exposes that can affect this behaviour; -it can supply a \fIctrl()\fR handler, it can specify \s-1ENGINE_FLAGS_MANUAL_CMD_CTRL\s0 in -the \s-1ENGINE\s0's flags, and it can expose an array of control command descriptions. -If an \s-1ENGINE\s0 specifies the \s-1ENGINE_FLAGS_MANUAL_CMD_CTRL\s0 flag, then it will -simply pass all these \*(L"core\*(R" control commands directly to the \s-1ENGINE\s0's \fIctrl()\fR -handler (and thus, it must have supplied one), so it is up to the \s-1ENGINE\s0 to -reply to these \*(L"discovery\*(R" commands itself. If that flag is not set, then the -OpenSSL framework code will work with the following rules; -.PP -.Vb 9 -\& if no ctrl() handler supplied; -\& ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero), -\& all other commands fail. -\& if a ctrl() handler was supplied but no array of control commands; -\& ENGINE_HAS_CTRL_FUNCTION returns TRUE, -\& all other commands fail. -\& if a ctrl() handler and array of control commands was supplied; -\& ENGINE_HAS_CTRL_FUNCTION returns TRUE, -\& all other commands proceed processing ... -.Ve -If the \s-1ENGINE\s0's array of control commands is empty then all other commands will -fail, otherwise; \s-1ENGINE_CTRL_GET_FIRST_CMD_TYPE\s0 returns the identifier of -the first command supported by the \s-1ENGINE\s0, \s-1ENGINE_GET_NEXT_CMD_TYPE\s0 takes the -identifier of a command supported by the \s-1ENGINE\s0 and returns the next command -identifier or fails if there are no more, \s-1ENGINE_CMD_FROM_NAME\s0 takes a string -name for a command and returns the corresponding identifier or fails if no such -command name exists, and the remaining commands take a command identifier and -return properties of the corresponding commands. All except -\&\s-1ENGINE_CTRL_GET_FLAGS\s0 return the string length of a command name or description, -or populate a supplied character buffer with a copy of the command name or -description. \s-1ENGINE_CTRL_GET_FLAGS\s0 returns a bitwise-OR'd mask of the following -possible values; -.PP -.Vb 4 -\& #define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001 -\& #define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002 -\& #define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 -\& #define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 -.Ve -If the \s-1ENGINE_CMD_FLAG_INTERNAL\s0 flag is set, then any other flags are purely -informational to the caller \- this flag will prevent the command being usable -for any higher-level \s-1ENGINE\s0 functions such as \fIENGINE_ctrl_cmd_string()\fR. -\&\*(L"\s-1INTERNAL\s0\*(R" commands are not intended to be exposed to text-based configuration -by applications, administrations, users, etc. These can support arbitrary -operations via \fIENGINE_ctrl()\fR, including passing to and/or from the control -commands data of any arbitrary type. These commands are supported in the -discovery mechanisms simply to allow applications determinie if an \s-1ENGINE\s0 -supports certain specific commands it might want to use (eg. application \*(L"foo\*(R" -might query various ENGINEs to see if they implement \*(L"\s-1FOO_GET_VENDOR_LOGO_GIF\s0\*(R" \- -and \s-1ENGINE\s0 could therefore decide whether or not to support this \*(L"foo\*(R"\-specific -extension). -.Sh "Future developments" -.IX Subsection "Future developments" -The \s-1ENGINE\s0 \s-1API\s0 and internal architecture is currently being reviewed. Slated for -possible release in 0.9.8 is support for transparent loading of \*(L"dynamic\*(R" -ENGINEs (built as self-contained shared-libraries). This would allow \s-1ENGINE\s0 -implementations to be provided independantly of OpenSSL libraries and/or -OpenSSL-based applications, and would also remove any requirement for -applications to explicitly use the \*(L"dynamic\*(R" \s-1ENGINE\s0 to bind to shared-library -implementations. -.SH "SEE ALSO" -.IX Header "SEE ALSO" -rsa(3), dsa(3), dh(3), rand(3), -RSA_new_method(3) |