| 1 | .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05) |
| 2 | .\" |
| 3 | .\" Standard preamble: |
| 4 | .\" ======================================================================== |
| 5 | .de Sh \" Subsection heading |
| 6 | .br |
| 7 | .if t .Sp |
| 8 | .ne 5 |
| 9 | .PP |
| 10 | \fB\\$1\fR |
| 11 | .PP |
| 12 | .. |
| 13 | .de Sp \" Vertical space (when we can't use .PP) |
| 14 | .if t .sp .5v |
| 15 | .if n .sp |
| 16 | .. |
| 17 | .de Vb \" Begin verbatim text |
| 18 | .ft CW |
| 19 | .nf |
| 20 | .ne \\$1 |
| 21 | .. |
| 22 | .de Ve \" End verbatim text |
| 23 | .ft R |
| 24 | .fi |
| 25 | .. |
| 26 | .\" Set up some character translations and predefined strings. \*(-- will |
| 27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
| 28 | .\" double quote, and \*(R" will give a right double quote. \*(C+ will |
| 29 | .\" give a nicer C++. Capital omega is used to do unbreakable dashes and |
| 30 | .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, |
| 31 | .\" nothing in troff, for use with C<>. |
| 32 | .tr \(*W- |
| 33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
| 34 | .ie n \{\ |
| 35 | . ds -- \(*W- |
| 36 | . ds PI pi |
| 37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
| 38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
| 39 | . ds L" "" |
| 40 | . ds R" "" |
| 41 | . ds C` "" |
| 42 | . ds C' "" |
| 43 | 'br\} |
| 44 | .el\{\ |
| 45 | . ds -- \|\(em\| |
| 46 | . ds PI \(*p |
| 47 | . ds L" `` |
| 48 | . ds R" '' |
| 49 | 'br\} |
| 50 | .\" |
| 51 | .\" Escape single quotes in literal strings from groff's Unicode transform. |
| 52 | .ie \n(.g .ds Aq \(aq |
| 53 | .el .ds Aq ' |
| 54 | .\" |
| 55 | .\" If the F register is turned on, we'll generate index entries on stderr for |
| 56 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
| 57 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
| 58 | .\" output yourself in some meaningful fashion. |
| 59 | .ie \nF \{\ |
| 60 | . de IX |
| 61 | . tm Index:\\$1\t\\n%\t"\\$2" |
| 62 | .. |
| 63 | . nr % 0 |
| 64 | . rr F |
| 65 | .\} |
| 66 | .el \{\ |
| 67 | . de IX |
| 68 | .. |
| 69 | .\} |
| 70 | .\" |
| 71 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
| 72 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
| 73 | . \" fudge factors for nroff and troff |
| 74 | .if n \{\ |
| 75 | . ds #H 0 |
| 76 | . ds #V .8m |
| 77 | . ds #F .3m |
| 78 | . ds #[ \f1 |
| 79 | . ds #] \fP |
| 80 | .\} |
| 81 | .if t \{\ |
| 82 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
| 83 | . ds #V .6m |
| 84 | . ds #F 0 |
| 85 | . ds #[ \& |
| 86 | . ds #] \& |
| 87 | .\} |
| 88 | . \" simple accents for nroff and troff |
| 89 | .if n \{\ |
| 90 | . ds ' \& |
| 91 | . ds ` \& |
| 92 | . ds ^ \& |
| 93 | . ds , \& |
| 94 | . ds ~ ~ |
| 95 | . ds / |
| 96 | .\} |
| 97 | .if t \{\ |
| 98 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
| 99 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
| 100 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
| 101 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
| 102 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
| 103 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
| 104 | .\} |
| 105 | . \" troff and (daisy-wheel) nroff accents |
| 106 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
| 107 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
| 108 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
| 109 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
| 110 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
| 111 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
| 112 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
| 113 | .ds ae a\h'-(\w'a'u*4/10)'e |
| 114 | .ds Ae A\h'-(\w'A'u*4/10)'E |
| 115 | . \" corrections for vroff |
| 116 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
| 117 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
| 118 | . \" for low resolution devices (crt and lpr) |
| 119 | .if \n(.H>23 .if \n(.V>19 \ |
| 120 | \{\ |
| 121 | . ds : e |
| 122 | . ds 8 ss |
| 123 | . ds o a |
| 124 | . ds d- d\h'-1'\(ga |
| 125 | . ds D- D\h'-1'\(hy |
| 126 | . ds th \o'bp' |
| 127 | . ds Th \o'LP' |
| 128 | . ds ae ae |
| 129 | . ds Ae AE |
| 130 | .\} |
| 131 | .rm #[ #] #H #V #F C |
| 132 | .\" ======================================================================== |
| 133 | .\" |
| 134 | .IX Title "engine 3" |
| 135 | .TH engine 3 "2010-02-27" "0.9.8m" "OpenSSL" |
| 136 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 137 | .\" way too many mistakes in technical documents. |
| 138 | .if n .ad l |
| 139 | .nh |
| 140 | .SH "NAME" |
| 141 | engine \- ENGINE cryptographic module support |
| 142 | .SH "SYNOPSIS" |
| 143 | .IX Header "SYNOPSIS" |
| 144 | .Vb 1 |
| 145 | \& #include <openssl/engine.h> |
| 146 | \& |
| 147 | \& ENGINE *ENGINE_get_first(void); |
| 148 | \& ENGINE *ENGINE_get_last(void); |
| 149 | \& ENGINE *ENGINE_get_next(ENGINE *e); |
| 150 | \& ENGINE *ENGINE_get_prev(ENGINE *e); |
| 151 | \& |
| 152 | \& int ENGINE_add(ENGINE *e); |
| 153 | \& int ENGINE_remove(ENGINE *e); |
| 154 | \& |
| 155 | \& ENGINE *ENGINE_by_id(const char *id); |
| 156 | \& |
| 157 | \& int ENGINE_init(ENGINE *e); |
| 158 | \& int ENGINE_finish(ENGINE *e); |
| 159 | \& |
| 160 | \& void ENGINE_load_openssl(void); |
| 161 | \& void ENGINE_load_dynamic(void); |
| 162 | \& #ifndef OPENSSL_NO_STATIC_ENGINE |
| 163 | \& void ENGINE_load_4758cca(void); |
| 164 | \& void ENGINE_load_aep(void); |
| 165 | \& void ENGINE_load_atalla(void); |
| 166 | \& void ENGINE_load_chil(void); |
| 167 | \& void ENGINE_load_cswift(void); |
| 168 | \& void ENGINE_load_gmp(void); |
| 169 | \& void ENGINE_load_nuron(void); |
| 170 | \& void ENGINE_load_sureware(void); |
| 171 | \& void ENGINE_load_ubsec(void); |
| 172 | \& #endif |
| 173 | \& void ENGINE_load_cryptodev(void); |
| 174 | \& void ENGINE_load_builtin_engines(void); |
| 175 | \& |
| 176 | \& void ENGINE_cleanup(void); |
| 177 | \& |
| 178 | \& ENGINE *ENGINE_get_default_RSA(void); |
| 179 | \& ENGINE *ENGINE_get_default_DSA(void); |
| 180 | \& ENGINE *ENGINE_get_default_ECDH(void); |
| 181 | \& ENGINE *ENGINE_get_default_ECDSA(void); |
| 182 | \& ENGINE *ENGINE_get_default_DH(void); |
| 183 | \& ENGINE *ENGINE_get_default_RAND(void); |
| 184 | \& ENGINE *ENGINE_get_cipher_engine(int nid); |
| 185 | \& ENGINE *ENGINE_get_digest_engine(int nid); |
| 186 | \& |
| 187 | \& int ENGINE_set_default_RSA(ENGINE *e); |
| 188 | \& int ENGINE_set_default_DSA(ENGINE *e); |
| 189 | \& int ENGINE_set_default_ECDH(ENGINE *e); |
| 190 | \& int ENGINE_set_default_ECDSA(ENGINE *e); |
| 191 | \& int ENGINE_set_default_DH(ENGINE *e); |
| 192 | \& int ENGINE_set_default_RAND(ENGINE *e); |
| 193 | \& int ENGINE_set_default_ciphers(ENGINE *e); |
| 194 | \& int ENGINE_set_default_digests(ENGINE *e); |
| 195 | \& int ENGINE_set_default_string(ENGINE *e, const char *list); |
| 196 | \& |
| 197 | \& int ENGINE_set_default(ENGINE *e, unsigned int flags); |
| 198 | \& |
| 199 | \& unsigned int ENGINE_get_table_flags(void); |
| 200 | \& void ENGINE_set_table_flags(unsigned int flags); |
| 201 | \& |
| 202 | \& int ENGINE_register_RSA(ENGINE *e); |
| 203 | \& void ENGINE_unregister_RSA(ENGINE *e); |
| 204 | \& void ENGINE_register_all_RSA(void); |
| 205 | \& int ENGINE_register_DSA(ENGINE *e); |
| 206 | \& void ENGINE_unregister_DSA(ENGINE *e); |
| 207 | \& void ENGINE_register_all_DSA(void); |
| 208 | \& int ENGINE_register_ECDH(ENGINE *e); |
| 209 | \& void ENGINE_unregister_ECDH(ENGINE *e); |
| 210 | \& void ENGINE_register_all_ECDH(void); |
| 211 | \& int ENGINE_register_ECDSA(ENGINE *e); |
| 212 | \& void ENGINE_unregister_ECDSA(ENGINE *e); |
| 213 | \& void ENGINE_register_all_ECDSA(void); |
| 214 | \& int ENGINE_register_DH(ENGINE *e); |
| 215 | \& void ENGINE_unregister_DH(ENGINE *e); |
| 216 | \& void ENGINE_register_all_DH(void); |
| 217 | \& int ENGINE_register_RAND(ENGINE *e); |
| 218 | \& void ENGINE_unregister_RAND(ENGINE *e); |
| 219 | \& void ENGINE_register_all_RAND(void); |
| 220 | \& int ENGINE_register_STORE(ENGINE *e); |
| 221 | \& void ENGINE_unregister_STORE(ENGINE *e); |
| 222 | \& void ENGINE_register_all_STORE(void); |
| 223 | \& int ENGINE_register_ciphers(ENGINE *e); |
| 224 | \& void ENGINE_unregister_ciphers(ENGINE *e); |
| 225 | \& void ENGINE_register_all_ciphers(void); |
| 226 | \& int ENGINE_register_digests(ENGINE *e); |
| 227 | \& void ENGINE_unregister_digests(ENGINE *e); |
| 228 | \& void ENGINE_register_all_digests(void); |
| 229 | \& int ENGINE_register_complete(ENGINE *e); |
| 230 | \& int ENGINE_register_all_complete(void); |
| 231 | \& |
| 232 | \& int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void)); |
| 233 | \& int ENGINE_cmd_is_executable(ENGINE *e, int cmd); |
| 234 | \& int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, |
| 235 | \& long i, void *p, void (*f)(void), int cmd_optional); |
| 236 | \& int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, |
| 237 | \& int cmd_optional); |
| 238 | \& |
| 239 | \& int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg); |
| 240 | \& void *ENGINE_get_ex_data(const ENGINE *e, int idx); |
| 241 | \& |
| 242 | \& int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, |
| 243 | \& CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); |
| 244 | \& |
| 245 | \& ENGINE *ENGINE_new(void); |
| 246 | \& int ENGINE_free(ENGINE *e); |
| 247 | \& int ENGINE_up_ref(ENGINE *e); |
| 248 | \& |
| 249 | \& int ENGINE_set_id(ENGINE *e, const char *id); |
| 250 | \& int ENGINE_set_name(ENGINE *e, const char *name); |
| 251 | \& int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); |
| 252 | \& int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth); |
| 253 | \& int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *dh_meth); |
| 254 | \& int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *dh_meth); |
| 255 | \& int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth); |
| 256 | \& int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); |
| 257 | \& int ENGINE_set_STORE(ENGINE *e, const STORE_METHOD *rand_meth); |
| 258 | \& int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); |
| 259 | \& int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); |
| 260 | \& int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); |
| 261 | \& int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); |
| 262 | \& int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f); |
| 263 | \& int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); |
| 264 | \& int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); |
| 265 | \& int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); |
| 266 | \& int ENGINE_set_flags(ENGINE *e, int flags); |
| 267 | \& int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); |
| 268 | \& |
| 269 | \& const char *ENGINE_get_id(const ENGINE *e); |
| 270 | \& const char *ENGINE_get_name(const ENGINE *e); |
| 271 | \& const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); |
| 272 | \& const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); |
| 273 | \& const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e); |
| 274 | \& const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e); |
| 275 | \& const DH_METHOD *ENGINE_get_DH(const ENGINE *e); |
| 276 | \& const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); |
| 277 | \& const STORE_METHOD *ENGINE_get_STORE(const ENGINE *e); |
| 278 | \& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); |
| 279 | \& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); |
| 280 | \& ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); |
| 281 | \& ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); |
| 282 | \& ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); |
| 283 | \& ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); |
| 284 | \& ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); |
| 285 | \& ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); |
| 286 | \& const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); |
| 287 | \& const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); |
| 288 | \& int ENGINE_get_flags(const ENGINE *e); |
| 289 | \& const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); |
| 290 | \& |
| 291 | \& EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, |
| 292 | \& UI_METHOD *ui_method, void *callback_data); |
| 293 | \& EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, |
| 294 | \& UI_METHOD *ui_method, void *callback_data); |
| 295 | \& |
| 296 | \& void ENGINE_add_conf_module(void); |
| 297 | .Ve |
| 298 | .SH "DESCRIPTION" |
| 299 | .IX Header "DESCRIPTION" |
| 300 | These functions create, manipulate, and use cryptographic modules in the |
| 301 | form of \fB\s-1ENGINE\s0\fR objects. These objects act as containers for |
| 302 | implementations of cryptographic algorithms, and support a |
| 303 | reference-counted mechanism to allow them to be dynamically loaded in and |
| 304 | out of the running application. |
| 305 | .PP |
| 306 | The cryptographic functionality that can be provided by an \fB\s-1ENGINE\s0\fR |
| 307 | implementation includes the following abstractions; |
| 308 | .PP |
| 309 | .Vb 6 |
| 310 | \& RSA_METHOD \- for providing alternative RSA implementations |
| 311 | \& DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD, |
| 312 | \& STORE_METHOD \- similarly for other OpenSSL APIs |
| 313 | \& EVP_CIPHER \- potentially multiple cipher algorithms (indexed by \*(Aqnid\*(Aq) |
| 314 | \& EVP_DIGEST \- potentially multiple hash algorithms (indexed by \*(Aqnid\*(Aq) |
| 315 | \& key\-loading \- loading public and/or private EVP_PKEY keys |
| 316 | .Ve |
| 317 | .Sh "Reference counting and handles" |
| 318 | .IX Subsection "Reference counting and handles" |
| 319 | Due to the modular nature of the \s-1ENGINE\s0 \s-1API\s0, pointers to ENGINEs need to be |
| 320 | treated as handles \- ie. not only as pointers, but also as references to |
| 321 | the underlying \s-1ENGINE\s0 object. Ie. one should obtain a new reference when |
| 322 | making copies of an \s-1ENGINE\s0 pointer if the copies will be used (and |
| 323 | released) independently. |
| 324 | .PP |
| 325 | \&\s-1ENGINE\s0 objects have two levels of reference-counting to match the way in |
| 326 | which the objects are used. At the most basic level, each \s-1ENGINE\s0 pointer is |
| 327 | inherently a \fBstructural\fR reference \- a structural reference is required |
| 328 | to use the pointer value at all, as this kind of reference is a guarantee |
| 329 | that the structure can not be deallocated until the reference is released. |
| 330 | .PP |
| 331 | However, a structural reference provides no guarantee that the \s-1ENGINE\s0 is |
| 332 | initiliased and able to use any of its cryptographic |
| 333 | implementations. Indeed it's quite possible that most ENGINEs will not |
| 334 | initialise at all in typical environments, as ENGINEs are typically used to |
| 335 | support specialised hardware. To use an \s-1ENGINE\s0's functionality, you need a |
| 336 | \&\fBfunctional\fR reference. This kind of reference can be considered a |
| 337 | specialised form of structural reference, because each functional reference |
| 338 | implicitly contains a structural reference as well \- however to avoid |
| 339 | difficult-to-find programming bugs, it is recommended to treat the two |
| 340 | kinds of reference independently. If you have a functional reference to an |
| 341 | \&\s-1ENGINE\s0, you have a guarantee that the \s-1ENGINE\s0 has been initialised ready to |
| 342 | perform cryptographic operations and will remain uninitialised |
| 343 | until after you have released your reference. |
| 344 | .PP |
| 345 | \&\fIStructural references\fR |
| 346 | .PP |
| 347 | This basic type of reference is used for instantiating new ENGINEs, |
| 348 | iterating across OpenSSL's internal linked-list of loaded |
| 349 | ENGINEs, reading information about an \s-1ENGINE\s0, etc. Essentially a structural |
| 350 | reference is sufficient if you only need to query or manipulate the data of |
| 351 | an \s-1ENGINE\s0 implementation rather than use its functionality. |
| 352 | .PP |
| 353 | The \fIENGINE_new()\fR function returns a structural reference to a new (empty) |
| 354 | \&\s-1ENGINE\s0 object. There are other \s-1ENGINE\s0 \s-1API\s0 functions that return structural |
| 355 | references such as; \fIENGINE_by_id()\fR, \fIENGINE_get_first()\fR, \fIENGINE_get_last()\fR, |
| 356 | \&\fIENGINE_get_next()\fR, \fIENGINE_get_prev()\fR. All structural references should be |
| 357 | released by a corresponding to call to the \fIENGINE_free()\fR function \- the |
| 358 | \&\s-1ENGINE\s0 object itself will only actually be cleaned up and deallocated when |
| 359 | the last structural reference is released. |
| 360 | .PP |
| 361 | It should also be noted that many \s-1ENGINE\s0 \s-1API\s0 function calls that accept a |
| 362 | structural reference will internally obtain another reference \- typically |
| 363 | this happens whenever the supplied \s-1ENGINE\s0 will be needed by OpenSSL after |
| 364 | the function has returned. Eg. the function to add a new \s-1ENGINE\s0 to |
| 365 | OpenSSL's internal list is \fIENGINE_add()\fR \- if this function returns success, |
| 366 | then OpenSSL will have stored a new structural reference internally so the |
| 367 | caller is still responsible for freeing their own reference with |
| 368 | \&\fIENGINE_free()\fR when they are finished with it. In a similar way, some |
| 369 | functions will automatically release the structural reference passed to it |
| 370 | if part of the function's job is to do so. Eg. the \fIENGINE_get_next()\fR and |
| 371 | \&\fIENGINE_get_prev()\fR functions are used for iterating across the internal |
| 372 | \&\s-1ENGINE\s0 list \- they will return a new structural reference to the next (or |
| 373 | previous) \s-1ENGINE\s0 in the list or \s-1NULL\s0 if at the end (or beginning) of the |
| 374 | list, but in either case the structural reference passed to the function is |
| 375 | released on behalf of the caller. |
| 376 | .PP |
| 377 | To clarify a particular function's handling of references, one should |
| 378 | always consult that function's documentation \*(L"man\*(R" page, or failing that |
| 379 | the openssl/engine.h header file includes some hints. |
| 380 | .PP |
| 381 | \&\fIFunctional references\fR |
| 382 | .PP |
| 383 | As mentioned, functional references exist when the cryptographic |
| 384 | functionality of an \s-1ENGINE\s0 is required to be available. A functional |
| 385 | reference can be obtained in one of two ways; from an existing structural |
| 386 | reference to the required \s-1ENGINE\s0, or by asking OpenSSL for the default |
| 387 | operational \s-1ENGINE\s0 for a given cryptographic purpose. |
| 388 | .PP |
| 389 | To obtain a functional reference from an existing structural reference, |
| 390 | call the \fIENGINE_init()\fR function. This returns zero if the \s-1ENGINE\s0 was not |
| 391 | already operational and couldn't be successfully initialised (eg. lack of |
| 392 | system drivers, no special hardware attached, etc), otherwise it will |
| 393 | return non-zero to indicate that the \s-1ENGINE\s0 is now operational and will |
| 394 | have allocated a new \fBfunctional\fR reference to the \s-1ENGINE\s0. All functional |
| 395 | references are released by calling \fIENGINE_finish()\fR (which removes the |
| 396 | implicit structural reference as well). |
| 397 | .PP |
| 398 | The second way to get a functional reference is by asking OpenSSL for a |
| 399 | default implementation for a given task, eg. by \fIENGINE_get_default_RSA()\fR, |
| 400 | \&\fIENGINE_get_default_cipher_engine()\fR, etc. These are discussed in the next |
| 401 | section, though they are not usually required by application programmers as |
| 402 | they are used automatically when creating and using the relevant |
| 403 | algorithm-specific types in OpenSSL, such as \s-1RSA\s0, \s-1DSA\s0, \s-1EVP_CIPHER_CTX\s0, etc. |
| 404 | .Sh "Default implementations" |
| 405 | .IX Subsection "Default implementations" |
| 406 | For each supported abstraction, the \s-1ENGINE\s0 code maintains an internal table |
| 407 | of state to control which implementations are available for a given |
| 408 | abstraction and which should be used by default. These implementations are |
| 409 | registered in the tables and indexed by an 'nid' value, because |
| 410 | abstractions like \s-1EVP_CIPHER\s0 and \s-1EVP_DIGEST\s0 support many distinct |
| 411 | algorithms and modes, and ENGINEs can support arbitrarily many of them. |
| 412 | In the case of other abstractions like \s-1RSA\s0, \s-1DSA\s0, etc, there is only one |
| 413 | \&\*(L"algorithm\*(R" so all implementations implicitly register using the same 'nid' |
| 414 | index. |
| 415 | .PP |
| 416 | When a default \s-1ENGINE\s0 is requested for a given abstraction/algorithm/mode, (eg. |
| 417 | when calling RSA_new_method(\s-1NULL\s0)), a \*(L"get_default\*(R" call will be made to the |
| 418 | \&\s-1ENGINE\s0 subsystem to process the corresponding state table and return a |
| 419 | functional reference to an initialised \s-1ENGINE\s0 whose implementation should be |
| 420 | used. If no \s-1ENGINE\s0 should (or can) be used, it will return \s-1NULL\s0 and the caller |
| 421 | will operate with a \s-1NULL\s0 \s-1ENGINE\s0 handle \- this usually equates to using the |
| 422 | conventional software implementation. In the latter case, OpenSSL will from |
| 423 | then on behave the way it used to before the \s-1ENGINE\s0 \s-1API\s0 existed. |
| 424 | .PP |
| 425 | Each state table has a flag to note whether it has processed this |
| 426 | \&\*(L"get_default\*(R" query since the table was last modified, because to process |
| 427 | this question it must iterate across all the registered ENGINEs in the |
| 428 | table trying to initialise each of them in turn, in case one of them is |
| 429 | operational. If it returns a functional reference to an \s-1ENGINE\s0, it will |
| 430 | also cache another reference to speed up processing future queries (without |
| 431 | needing to iterate across the table). Likewise, it will cache a \s-1NULL\s0 |
| 432 | response if no \s-1ENGINE\s0 was available so that future queries won't repeat the |
| 433 | same iteration unless the state table changes. This behaviour can also be |
| 434 | changed; if the \s-1ENGINE_TABLE_FLAG_NOINIT\s0 flag is set (using |
| 435 | \&\fIENGINE_set_table_flags()\fR), no attempted initialisations will take place, |
| 436 | instead the only way for the state table to return a non-NULL \s-1ENGINE\s0 to the |
| 437 | \&\*(L"get_default\*(R" query will be if one is expressly set in the table. Eg. |
| 438 | \&\fIENGINE_set_default_RSA()\fR does the same job as \fIENGINE_register_RSA()\fR except |
| 439 | that it also sets the state table's cached response for the \*(L"get_default\*(R" |
| 440 | query. In the case of abstractions like \s-1EVP_CIPHER\s0, where implementations are |
| 441 | indexed by 'nid', these flags and cached-responses are distinct for each 'nid' |
| 442 | value. |
| 443 | .Sh "Application requirements" |
| 444 | .IX Subsection "Application requirements" |
| 445 | This section will explain the basic things an application programmer should |
| 446 | support to make the most useful elements of the \s-1ENGINE\s0 functionality |
| 447 | available to the user. The first thing to consider is whether the |
| 448 | programmer wishes to make alternative \s-1ENGINE\s0 modules available to the |
| 449 | application and user. OpenSSL maintains an internal linked list of |
| 450 | \&\*(L"visible\*(R" ENGINEs from which it has to operate \- at start-up, this list is |
| 451 | empty and in fact if an application does not call any \s-1ENGINE\s0 \s-1API\s0 calls and |
| 452 | it uses static linking against openssl, then the resulting application |
| 453 | binary will not contain any alternative \s-1ENGINE\s0 code at all. So the first |
| 454 | consideration is whether any/all available \s-1ENGINE\s0 implementations should be |
| 455 | made visible to OpenSSL \- this is controlled by calling the various \*(L"load\*(R" |
| 456 | functions, eg. |
| 457 | .PP |
| 458 | .Vb 9 |
| 459 | \& /* Make the "dynamic" ENGINE available */ |
| 460 | \& void ENGINE_load_dynamic(void); |
| 461 | \& /* Make the CryptoSwift hardware acceleration support available */ |
| 462 | \& void ENGINE_load_cswift(void); |
| 463 | \& /* Make support for nCipher\*(Aqs "CHIL" hardware available */ |
| 464 | \& void ENGINE_load_chil(void); |
| 465 | \& ... |
| 466 | \& /* Make ALL ENGINE implementations bundled with OpenSSL available */ |
| 467 | \& void ENGINE_load_builtin_engines(void); |
| 468 | .Ve |
| 469 | .PP |
| 470 | Having called any of these functions, \s-1ENGINE\s0 objects would have been |
| 471 | dynamically allocated and populated with these implementations and linked |
| 472 | into OpenSSL's internal linked list. At this point it is important to |
| 473 | mention an important \s-1API\s0 function; |
| 474 | .PP |
| 475 | .Vb 1 |
| 476 | \& void ENGINE_cleanup(void); |
| 477 | .Ve |
| 478 | .PP |
| 479 | If no \s-1ENGINE\s0 \s-1API\s0 functions are called at all in an application, then there |
| 480 | are no inherent memory leaks to worry about from the \s-1ENGINE\s0 functionality, |
| 481 | however if any ENGINEs are loaded, even if they are never registered or |
| 482 | used, it is necessary to use the \fIENGINE_cleanup()\fR function to |
| 483 | correspondingly cleanup before program exit, if the caller wishes to avoid |
| 484 | memory leaks. This mechanism uses an internal callback registration table |
| 485 | so that any \s-1ENGINE\s0 \s-1API\s0 functionality that knows it requires cleanup can |
| 486 | register its cleanup details to be called during \fIENGINE_cleanup()\fR. This |
| 487 | approach allows \fIENGINE_cleanup()\fR to clean up after any \s-1ENGINE\s0 functionality |
| 488 | at all that your program uses, yet doesn't automatically create linker |
| 489 | dependencies to all possible \s-1ENGINE\s0 functionality \- only the cleanup |
| 490 | callbacks required by the functionality you do use will be required by the |
| 491 | linker. |
| 492 | .PP |
| 493 | The fact that ENGINEs are made visible to OpenSSL (and thus are linked into |
| 494 | the program and loaded into memory at run-time) does not mean they are |
| 495 | \&\*(L"registered\*(R" or called into use by OpenSSL automatically \- that behaviour |
| 496 | is something for the application to control. Some applications |
| 497 | will want to allow the user to specify exactly which \s-1ENGINE\s0 they want used |
| 498 | if any is to be used at all. Others may prefer to load all support and have |
| 499 | OpenSSL automatically use at run-time any \s-1ENGINE\s0 that is able to |
| 500 | successfully initialise \- ie. to assume that this corresponds to |
| 501 | acceleration hardware attached to the machine or some such thing. There are |
| 502 | probably numerous other ways in which applications may prefer to handle |
| 503 | things, so we will simply illustrate the consequences as they apply to a |
| 504 | couple of simple cases and leave developers to consider these and the |
| 505 | source code to openssl's builtin utilities as guides. |
| 506 | .PP |
| 507 | \&\fIUsing a specific \s-1ENGINE\s0 implementation\fR |
| 508 | .PP |
| 509 | Here we'll assume an application has been configured by its user or admin |
| 510 | to want to use the \*(L"\s-1ACME\s0\*(R" \s-1ENGINE\s0 if it is available in the version of |
| 511 | OpenSSL the application was compiled with. If it is available, it should be |
| 512 | used by default for all \s-1RSA\s0, \s-1DSA\s0, and symmetric cipher operation, otherwise |
| 513 | OpenSSL should use its builtin software as per usual. The following code |
| 514 | illustrates how to approach this; |
| 515 | .PP |
| 516 | .Vb 10 |
| 517 | \& ENGINE *e; |
| 518 | \& const char *engine_id = "ACME"; |
| 519 | \& ENGINE_load_builtin_engines(); |
| 520 | \& e = ENGINE_by_id(engine_id); |
| 521 | \& if(!e) |
| 522 | \& /* the engine isn\*(Aqt available */ |
| 523 | \& return; |
| 524 | \& if(!ENGINE_init(e)) { |
| 525 | \& /* the engine couldn\*(Aqt initialise, release \*(Aqe\*(Aq */ |
| 526 | \& ENGINE_free(e); |
| 527 | \& return; |
| 528 | \& } |
| 529 | \& if(!ENGINE_set_default_RSA(e)) |
| 530 | \& /* This should only happen when \*(Aqe\*(Aq can\*(Aqt initialise, but the previous |
| 531 | \& * statement suggests it did. */ |
| 532 | \& abort(); |
| 533 | \& ENGINE_set_default_DSA(e); |
| 534 | \& ENGINE_set_default_ciphers(e); |
| 535 | \& /* Release the functional reference from ENGINE_init() */ |
| 536 | \& ENGINE_finish(e); |
| 537 | \& /* Release the structural reference from ENGINE_by_id() */ |
| 538 | \& ENGINE_free(e); |
| 539 | .Ve |
| 540 | .PP |
| 541 | \&\fIAutomatically using builtin \s-1ENGINE\s0 implementations\fR |
| 542 | .PP |
| 543 | Here we'll assume we want to load and register all \s-1ENGINE\s0 implementations |
| 544 | bundled with OpenSSL, such that for any cryptographic algorithm required by |
| 545 | OpenSSL \- if there is an \s-1ENGINE\s0 that implements it and can be initialise, |
| 546 | it should be used. The following code illustrates how this can work; |
| 547 | .PP |
| 548 | .Vb 4 |
| 549 | \& /* Load all bundled ENGINEs into memory and make them visible */ |
| 550 | \& ENGINE_load_builtin_engines(); |
| 551 | \& /* Register all of them for every algorithm they collectively implement */ |
| 552 | \& ENGINE_register_all_complete(); |
| 553 | .Ve |
| 554 | .PP |
| 555 | That's all that's required. Eg. the next time OpenSSL tries to set up an |
| 556 | \&\s-1RSA\s0 key, any bundled ENGINEs that implement \s-1RSA_METHOD\s0 will be passed to |
| 557 | \&\fIENGINE_init()\fR and if any of those succeed, that \s-1ENGINE\s0 will be set as the |
| 558 | default for \s-1RSA\s0 use from then on. |
| 559 | .Sh "Advanced configuration support" |
| 560 | .IX Subsection "Advanced configuration support" |
| 561 | There is a mechanism supported by the \s-1ENGINE\s0 framework that allows each |
| 562 | \&\s-1ENGINE\s0 implementation to define an arbitrary set of configuration |
| 563 | \&\*(L"commands\*(R" and expose them to OpenSSL and any applications based on |
| 564 | OpenSSL. This mechanism is entirely based on the use of name-value pairs |
| 565 | and assumes \s-1ASCII\s0 input (no unicode or \s-1UTF\s0 for now!), so it is ideal if |
| 566 | applications want to provide a transparent way for users to provide |
| 567 | arbitrary configuration \*(L"directives\*(R" directly to such ENGINEs. It is also |
| 568 | possible for the application to dynamically interrogate the loaded \s-1ENGINE\s0 |
| 569 | implementations for the names, descriptions, and input flags of their |
| 570 | available \*(L"control commands\*(R", providing a more flexible configuration |
| 571 | scheme. However, if the user is expected to know which \s-1ENGINE\s0 device he/she |
| 572 | is using (in the case of specialised hardware, this goes without saying) |
| 573 | then applications may not need to concern themselves with discovering the |
| 574 | supported control commands and simply prefer to pass settings into ENGINEs |
| 575 | exactly as they are provided by the user. |
| 576 | .PP |
| 577 | Before illustrating how control commands work, it is worth mentioning what |
| 578 | they are typically used for. Broadly speaking there are two uses for |
| 579 | control commands; the first is to provide the necessary details to the |
| 580 | implementation (which may know nothing at all specific to the host system) |
| 581 | so that it can be initialised for use. This could include the path to any |
| 582 | driver or config files it needs to load, required network addresses, |
| 583 | smart-card identifiers, passwords to initialise protected devices, |
| 584 | logging information, etc etc. This class of commands typically needs to be |
| 585 | passed to an \s-1ENGINE\s0 \fBbefore\fR attempting to initialise it, ie. before |
| 586 | calling \fIENGINE_init()\fR. The other class of commands consist of settings or |
| 587 | operations that tweak certain behaviour or cause certain operations to take |
| 588 | place, and these commands may work either before or after \fIENGINE_init()\fR, or |
| 589 | in some cases both. \s-1ENGINE\s0 implementations should provide indications of |
| 590 | this in the descriptions attached to builtin control commands and/or in |
| 591 | external product documentation. |
| 592 | .PP |
| 593 | \&\fIIssuing control commands to an \s-1ENGINE\s0\fR |
| 594 | .PP |
| 595 | Let's illustrate by example; a function for which the caller supplies the |
| 596 | name of the \s-1ENGINE\s0 it wishes to use, a table of string-pairs for use before |
| 597 | initialisation, and another table for use after initialisation. Note that |
| 598 | the string-pairs used for control commands consist of a command \*(L"name\*(R" |
| 599 | followed by the command \*(L"parameter\*(R" \- the parameter could be \s-1NULL\s0 in some |
| 600 | cases but the name can not. This function should initialise the \s-1ENGINE\s0 |
| 601 | (issuing the \*(L"pre\*(R" commands beforehand and the \*(L"post\*(R" commands afterwards) |
| 602 | and set it as the default for everything except \s-1RAND\s0 and then return a |
| 603 | boolean success or failure. |
| 604 | .PP |
| 605 | .Vb 10 |
| 606 | \& int generic_load_engine_fn(const char *engine_id, |
| 607 | \& const char **pre_cmds, int pre_num, |
| 608 | \& const char **post_cmds, int post_num) |
| 609 | \& { |
| 610 | \& ENGINE *e = ENGINE_by_id(engine_id); |
| 611 | \& if(!e) return 0; |
| 612 | \& while(pre_num\-\-) { |
| 613 | \& if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) { |
| 614 | \& fprintf(stderr, "Failed command (%s \- %s:%s)\en", engine_id, |
| 615 | \& pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)"); |
| 616 | \& ENGINE_free(e); |
| 617 | \& return 0; |
| 618 | \& } |
| 619 | \& pre_cmds += 2; |
| 620 | \& } |
| 621 | \& if(!ENGINE_init(e)) { |
| 622 | \& fprintf(stderr, "Failed initialisation\en"); |
| 623 | \& ENGINE_free(e); |
| 624 | \& return 0; |
| 625 | \& } |
| 626 | \& /* ENGINE_init() returned a functional reference, so free the structural |
| 627 | \& * reference from ENGINE_by_id(). */ |
| 628 | \& ENGINE_free(e); |
| 629 | \& while(post_num\-\-) { |
| 630 | \& if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) { |
| 631 | \& fprintf(stderr, "Failed command (%s \- %s:%s)\en", engine_id, |
| 632 | \& post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)"); |
| 633 | \& ENGINE_finish(e); |
| 634 | \& return 0; |
| 635 | \& } |
| 636 | \& post_cmds += 2; |
| 637 | \& } |
| 638 | \& ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); |
| 639 | \& /* Success */ |
| 640 | \& return 1; |
| 641 | \& } |
| 642 | .Ve |
| 643 | .PP |
| 644 | Note that \fIENGINE_ctrl_cmd_string()\fR accepts a boolean argument that can |
| 645 | relax the semantics of the function \- if set non-zero it will only return |
| 646 | failure if the \s-1ENGINE\s0 supported the given command name but failed while |
| 647 | executing it, if the \s-1ENGINE\s0 doesn't support the command name it will simply |
| 648 | return success without doing anything. In this case we assume the user is |
| 649 | only supplying commands specific to the given \s-1ENGINE\s0 so we set this to |
| 650 | \&\s-1FALSE\s0. |
| 651 | .PP |
| 652 | \&\fIDiscovering supported control commands\fR |
| 653 | .PP |
| 654 | It is possible to discover at run-time the names, numerical-ids, descriptions |
| 655 | and input parameters of the control commands supported by an \s-1ENGINE\s0 using a |
| 656 | structural reference. Note that some control commands are defined by OpenSSL |
| 657 | itself and it will intercept and handle these control commands on behalf of the |
| 658 | \&\s-1ENGINE\s0, ie. the \s-1ENGINE\s0's \fIctrl()\fR handler is not used for the control command. |
| 659 | openssl/engine.h defines an index, \s-1ENGINE_CMD_BASE\s0, that all control commands |
| 660 | implemented by ENGINEs should be numbered from. Any command value lower than |
| 661 | this symbol is considered a \*(L"generic\*(R" command is handled directly by the |
| 662 | OpenSSL core routines. |
| 663 | .PP |
| 664 | It is using these \*(L"core\*(R" control commands that one can discover the the control |
| 665 | commands implemented by a given \s-1ENGINE\s0, specifically the commands; |
| 666 | .PP |
| 667 | .Vb 9 |
| 668 | \& #define ENGINE_HAS_CTRL_FUNCTION 10 |
| 669 | \& #define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11 |
| 670 | \& #define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12 |
| 671 | \& #define ENGINE_CTRL_GET_CMD_FROM_NAME 13 |
| 672 | \& #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14 |
| 673 | \& #define ENGINE_CTRL_GET_NAME_FROM_CMD 15 |
| 674 | \& #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16 |
| 675 | \& #define ENGINE_CTRL_GET_DESC_FROM_CMD 17 |
| 676 | \& #define ENGINE_CTRL_GET_CMD_FLAGS 18 |
| 677 | .Ve |
| 678 | .PP |
| 679 | Whilst these commands are automatically processed by the OpenSSL framework code, |
| 680 | they use various properties exposed by each \s-1ENGINE\s0 to process these |
| 681 | queries. An \s-1ENGINE\s0 has 3 properties it exposes that can affect how this behaves; |
| 682 | it can supply a \fIctrl()\fR handler, it can specify \s-1ENGINE_FLAGS_MANUAL_CMD_CTRL\s0 in |
| 683 | the \s-1ENGINE\s0's flags, and it can expose an array of control command descriptions. |
| 684 | If an \s-1ENGINE\s0 specifies the \s-1ENGINE_FLAGS_MANUAL_CMD_CTRL\s0 flag, then it will |
| 685 | simply pass all these \*(L"core\*(R" control commands directly to the \s-1ENGINE\s0's \fIctrl()\fR |
| 686 | handler (and thus, it must have supplied one), so it is up to the \s-1ENGINE\s0 to |
| 687 | reply to these \*(L"discovery\*(R" commands itself. If that flag is not set, then the |
| 688 | OpenSSL framework code will work with the following rules; |
| 689 | .PP |
| 690 | .Vb 9 |
| 691 | \& if no ctrl() handler supplied; |
| 692 | \& ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero), |
| 693 | \& all other commands fail. |
| 694 | \& if a ctrl() handler was supplied but no array of control commands; |
| 695 | \& ENGINE_HAS_CTRL_FUNCTION returns TRUE, |
| 696 | \& all other commands fail. |
| 697 | \& if a ctrl() handler and array of control commands was supplied; |
| 698 | \& ENGINE_HAS_CTRL_FUNCTION returns TRUE, |
| 699 | \& all other commands proceed processing ... |
| 700 | .Ve |
| 701 | .PP |
| 702 | If the \s-1ENGINE\s0's array of control commands is empty then all other commands will |
| 703 | fail, otherwise; \s-1ENGINE_CTRL_GET_FIRST_CMD_TYPE\s0 returns the identifier of |
| 704 | the first command supported by the \s-1ENGINE\s0, \s-1ENGINE_GET_NEXT_CMD_TYPE\s0 takes the |
| 705 | identifier of a command supported by the \s-1ENGINE\s0 and returns the next command |
| 706 | identifier or fails if there are no more, \s-1ENGINE_CMD_FROM_NAME\s0 takes a string |
| 707 | name for a command and returns the corresponding identifier or fails if no such |
| 708 | command name exists, and the remaining commands take a command identifier and |
| 709 | return properties of the corresponding commands. All except |
| 710 | \&\s-1ENGINE_CTRL_GET_FLAGS\s0 return the string length of a command name or description, |
| 711 | or populate a supplied character buffer with a copy of the command name or |
| 712 | description. \s-1ENGINE_CTRL_GET_FLAGS\s0 returns a bitwise-OR'd mask of the following |
| 713 | possible values; |
| 714 | .PP |
| 715 | .Vb 4 |
| 716 | \& #define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001 |
| 717 | \& #define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002 |
| 718 | \& #define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 |
| 719 | \& #define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 |
| 720 | .Ve |
| 721 | .PP |
| 722 | If the \s-1ENGINE_CMD_FLAG_INTERNAL\s0 flag is set, then any other flags are purely |
| 723 | informational to the caller \- this flag will prevent the command being usable |
| 724 | for any higher-level \s-1ENGINE\s0 functions such as \fIENGINE_ctrl_cmd_string()\fR. |
| 725 | \&\*(L"\s-1INTERNAL\s0\*(R" commands are not intended to be exposed to text-based configuration |
| 726 | by applications, administrations, users, etc. These can support arbitrary |
| 727 | operations via \fIENGINE_ctrl()\fR, including passing to and/or from the control |
| 728 | commands data of any arbitrary type. These commands are supported in the |
| 729 | discovery mechanisms simply to allow applications determinie if an \s-1ENGINE\s0 |
| 730 | supports certain specific commands it might want to use (eg. application \*(L"foo\*(R" |
| 731 | might query various ENGINEs to see if they implement \*(L"\s-1FOO_GET_VENDOR_LOGO_GIF\s0\*(R" \- |
| 732 | and \s-1ENGINE\s0 could therefore decide whether or not to support this \*(L"foo\*(R"\-specific |
| 733 | extension). |
| 734 | .Sh "Future developments" |
| 735 | .IX Subsection "Future developments" |
| 736 | The \s-1ENGINE\s0 \s-1API\s0 and internal architecture is currently being reviewed. Slated for |
| 737 | possible release in 0.9.8 is support for transparent loading of \*(L"dynamic\*(R" |
| 738 | ENGINEs (built as self-contained shared-libraries). This would allow \s-1ENGINE\s0 |
| 739 | implementations to be provided independently of OpenSSL libraries and/or |
| 740 | OpenSSL-based applications, and would also remove any requirement for |
| 741 | applications to explicitly use the \*(L"dynamic\*(R" \s-1ENGINE\s0 to bind to shared-library |
| 742 | implementations. |
| 743 | .SH "SEE ALSO" |
| 744 | .IX Header "SEE ALSO" |
| 745 | \&\fIrsa\fR\|(3), \fIdsa\fR\|(3), \fIdh\fR\|(3), \fIrand\fR\|(3) |