1109998Smarkm=pod 2109998Smarkm 3109998Smarkm=head1 NAME 4109998Smarkm 5109998Smarkmengine - ENGINE cryptographic module support 6109998Smarkm 7109998Smarkm=head1 SYNOPSIS 8109998Smarkm 9109998Smarkm #include <openssl/engine.h> 10109998Smarkm 11109998Smarkm ENGINE *ENGINE_get_first(void); 12109998Smarkm ENGINE *ENGINE_get_last(void); 13109998Smarkm ENGINE *ENGINE_get_next(ENGINE *e); 14109998Smarkm ENGINE *ENGINE_get_prev(ENGINE *e); 15109998Smarkm 16109998Smarkm int ENGINE_add(ENGINE *e); 17109998Smarkm int ENGINE_remove(ENGINE *e); 18109998Smarkm 19109998Smarkm ENGINE *ENGINE_by_id(const char *id); 20109998Smarkm 21109998Smarkm int ENGINE_init(ENGINE *e); 22109998Smarkm int ENGINE_finish(ENGINE *e); 23109998Smarkm 24109998Smarkm void ENGINE_load_openssl(void); 25109998Smarkm void ENGINE_load_dynamic(void); 26160814Ssimon #ifndef OPENSSL_NO_STATIC_ENGINE 27160814Ssimon void ENGINE_load_4758cca(void); 28160814Ssimon void ENGINE_load_aep(void); 29160814Ssimon void ENGINE_load_atalla(void); 30160814Ssimon void ENGINE_load_chil(void); 31109998Smarkm void ENGINE_load_cswift(void); 32160814Ssimon void ENGINE_load_gmp(void); 33109998Smarkm void ENGINE_load_nuron(void); 34160814Ssimon void ENGINE_load_sureware(void); 35109998Smarkm void ENGINE_load_ubsec(void); 36160814Ssimon #endif 37160814Ssimon void ENGINE_load_cryptodev(void); 38109998Smarkm void ENGINE_load_builtin_engines(void); 39109998Smarkm 40109998Smarkm void ENGINE_cleanup(void); 41109998Smarkm 42109998Smarkm ENGINE *ENGINE_get_default_RSA(void); 43109998Smarkm ENGINE *ENGINE_get_default_DSA(void); 44160814Ssimon ENGINE *ENGINE_get_default_ECDH(void); 45160814Ssimon ENGINE *ENGINE_get_default_ECDSA(void); 46109998Smarkm ENGINE *ENGINE_get_default_DH(void); 47109998Smarkm ENGINE *ENGINE_get_default_RAND(void); 48109998Smarkm ENGINE *ENGINE_get_cipher_engine(int nid); 49109998Smarkm ENGINE *ENGINE_get_digest_engine(int nid); 50109998Smarkm 51109998Smarkm int ENGINE_set_default_RSA(ENGINE *e); 52109998Smarkm int ENGINE_set_default_DSA(ENGINE *e); 53160814Ssimon int ENGINE_set_default_ECDH(ENGINE *e); 54160814Ssimon int ENGINE_set_default_ECDSA(ENGINE *e); 55109998Smarkm int ENGINE_set_default_DH(ENGINE *e); 56109998Smarkm int ENGINE_set_default_RAND(ENGINE *e); 57109998Smarkm int ENGINE_set_default_ciphers(ENGINE *e); 58109998Smarkm int ENGINE_set_default_digests(ENGINE *e); 59109998Smarkm int ENGINE_set_default_string(ENGINE *e, const char *list); 60109998Smarkm 61109998Smarkm int ENGINE_set_default(ENGINE *e, unsigned int flags); 62109998Smarkm 63109998Smarkm unsigned int ENGINE_get_table_flags(void); 64109998Smarkm void ENGINE_set_table_flags(unsigned int flags); 65109998Smarkm 66109998Smarkm int ENGINE_register_RSA(ENGINE *e); 67109998Smarkm void ENGINE_unregister_RSA(ENGINE *e); 68109998Smarkm void ENGINE_register_all_RSA(void); 69109998Smarkm int ENGINE_register_DSA(ENGINE *e); 70109998Smarkm void ENGINE_unregister_DSA(ENGINE *e); 71109998Smarkm void ENGINE_register_all_DSA(void); 72160814Ssimon int ENGINE_register_ECDH(ENGINE *e); 73160814Ssimon void ENGINE_unregister_ECDH(ENGINE *e); 74160814Ssimon void ENGINE_register_all_ECDH(void); 75160814Ssimon int ENGINE_register_ECDSA(ENGINE *e); 76160814Ssimon void ENGINE_unregister_ECDSA(ENGINE *e); 77160814Ssimon void ENGINE_register_all_ECDSA(void); 78109998Smarkm int ENGINE_register_DH(ENGINE *e); 79109998Smarkm void ENGINE_unregister_DH(ENGINE *e); 80109998Smarkm void ENGINE_register_all_DH(void); 81109998Smarkm int ENGINE_register_RAND(ENGINE *e); 82109998Smarkm void ENGINE_unregister_RAND(ENGINE *e); 83109998Smarkm void ENGINE_register_all_RAND(void); 84160814Ssimon int ENGINE_register_STORE(ENGINE *e); 85160814Ssimon void ENGINE_unregister_STORE(ENGINE *e); 86160814Ssimon void ENGINE_register_all_STORE(void); 87109998Smarkm int ENGINE_register_ciphers(ENGINE *e); 88109998Smarkm void ENGINE_unregister_ciphers(ENGINE *e); 89109998Smarkm void ENGINE_register_all_ciphers(void); 90109998Smarkm int ENGINE_register_digests(ENGINE *e); 91109998Smarkm void ENGINE_unregister_digests(ENGINE *e); 92109998Smarkm void ENGINE_register_all_digests(void); 93109998Smarkm int ENGINE_register_complete(ENGINE *e); 94109998Smarkm int ENGINE_register_all_complete(void); 95109998Smarkm 96160814Ssimon int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)(void)); 97109998Smarkm int ENGINE_cmd_is_executable(ENGINE *e, int cmd); 98109998Smarkm int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name, 99160814Ssimon long i, void *p, void (*f)(void), int cmd_optional); 100109998Smarkm int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, 101160814Ssimon int cmd_optional); 102109998Smarkm 103109998Smarkm int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg); 104109998Smarkm void *ENGINE_get_ex_data(const ENGINE *e, int idx); 105109998Smarkm 106109998Smarkm int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, 107109998Smarkm CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); 108109998Smarkm 109109998Smarkm ENGINE *ENGINE_new(void); 110109998Smarkm int ENGINE_free(ENGINE *e); 111160814Ssimon int ENGINE_up_ref(ENGINE *e); 112109998Smarkm 113109998Smarkm int ENGINE_set_id(ENGINE *e, const char *id); 114109998Smarkm int ENGINE_set_name(ENGINE *e, const char *name); 115109998Smarkm int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth); 116109998Smarkm int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth); 117160814Ssimon int ENGINE_set_ECDH(ENGINE *e, const ECDH_METHOD *dh_meth); 118160814Ssimon int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *dh_meth); 119109998Smarkm int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth); 120109998Smarkm int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); 121160814Ssimon int ENGINE_set_STORE(ENGINE *e, const STORE_METHOD *rand_meth); 122109998Smarkm int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); 123109998Smarkm int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); 124109998Smarkm int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); 125109998Smarkm int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f); 126109998Smarkm int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f); 127109998Smarkm int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f); 128109998Smarkm int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f); 129109998Smarkm int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f); 130109998Smarkm int ENGINE_set_flags(ENGINE *e, int flags); 131109998Smarkm int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns); 132109998Smarkm 133109998Smarkm const char *ENGINE_get_id(const ENGINE *e); 134109998Smarkm const char *ENGINE_get_name(const ENGINE *e); 135109998Smarkm const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e); 136109998Smarkm const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e); 137160814Ssimon const ECDH_METHOD *ENGINE_get_ECDH(const ENGINE *e); 138160814Ssimon const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e); 139109998Smarkm const DH_METHOD *ENGINE_get_DH(const ENGINE *e); 140109998Smarkm const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); 141160814Ssimon const STORE_METHOD *ENGINE_get_STORE(const ENGINE *e); 142109998Smarkm ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); 143109998Smarkm ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); 144109998Smarkm ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); 145109998Smarkm ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e); 146109998Smarkm ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e); 147109998Smarkm ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e); 148109998Smarkm ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e); 149109998Smarkm ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e); 150109998Smarkm const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid); 151109998Smarkm const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid); 152109998Smarkm int ENGINE_get_flags(const ENGINE *e); 153109998Smarkm const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e); 154109998Smarkm 155109998Smarkm EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id, 156109998Smarkm UI_METHOD *ui_method, void *callback_data); 157109998Smarkm EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, 158109998Smarkm UI_METHOD *ui_method, void *callback_data); 159109998Smarkm 160109998Smarkm void ENGINE_add_conf_module(void); 161109998Smarkm 162109998Smarkm=head1 DESCRIPTION 163109998Smarkm 164109998SmarkmThese functions create, manipulate, and use cryptographic modules in the 165109998Smarkmform of B<ENGINE> objects. These objects act as containers for 166109998Smarkmimplementations of cryptographic algorithms, and support a 167109998Smarkmreference-counted mechanism to allow them to be dynamically loaded in and 168109998Smarkmout of the running application. 169109998Smarkm 170109998SmarkmThe cryptographic functionality that can be provided by an B<ENGINE> 171109998Smarkmimplementation includes the following abstractions; 172109998Smarkm 173109998Smarkm RSA_METHOD - for providing alternative RSA implementations 174160814Ssimon DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD, 175160814Ssimon STORE_METHOD - similarly for other OpenSSL APIs 176109998Smarkm EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid') 177109998Smarkm EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid') 178109998Smarkm key-loading - loading public and/or private EVP_PKEY keys 179109998Smarkm 180109998Smarkm=head2 Reference counting and handles 181109998Smarkm 182109998SmarkmDue to the modular nature of the ENGINE API, pointers to ENGINEs need to be 183109998Smarkmtreated as handles - ie. not only as pointers, but also as references to 184160814Ssimonthe underlying ENGINE object. Ie. one should obtain a new reference when 185109998Smarkmmaking copies of an ENGINE pointer if the copies will be used (and 186194206Ssimonreleased) independently. 187109998Smarkm 188109998SmarkmENGINE objects have two levels of reference-counting to match the way in 189109998Smarkmwhich the objects are used. At the most basic level, each ENGINE pointer is 190160814Ssimoninherently a B<structural> reference - a structural reference is required 191160814Ssimonto use the pointer value at all, as this kind of reference is a guarantee 192160814Ssimonthat the structure can not be deallocated until the reference is released. 193109998Smarkm 194160814SsimonHowever, a structural reference provides no guarantee that the ENGINE is 195291719Sjkiminitialised and able to use any of its cryptographic 196160814Ssimonimplementations. Indeed it's quite possible that most ENGINEs will not 197160814Ssimoninitialise at all in typical environments, as ENGINEs are typically used to 198109998Smarkmsupport specialised hardware. To use an ENGINE's functionality, you need a 199109998SmarkmB<functional> reference. This kind of reference can be considered a 200109998Smarkmspecialised form of structural reference, because each functional reference 201109998Smarkmimplicitly contains a structural reference as well - however to avoid 202109998Smarkmdifficult-to-find programming bugs, it is recommended to treat the two 203194206Ssimonkinds of reference independently. If you have a functional reference to an 204291719SjkimENGINE, you have a guarantee that the ENGINE has been initialised and 205291719Sjkimis ready to perform cryptographic operations, and will remain initialised 206160814Ssimonuntil after you have released your reference. 207109998Smarkm 208109998SmarkmI<Structural references> 209109998Smarkm 210160814SsimonThis basic type of reference is used for instantiating new ENGINEs, 211160814Ssimoniterating across OpenSSL's internal linked-list of loaded 212109998SmarkmENGINEs, reading information about an ENGINE, etc. Essentially a structural 213109998Smarkmreference is sufficient if you only need to query or manipulate the data of 214109998Smarkman ENGINE implementation rather than use its functionality. 215109998Smarkm 216109998SmarkmThe ENGINE_new() function returns a structural reference to a new (empty) 217160814SsimonENGINE object. There are other ENGINE API functions that return structural 218160814Ssimonreferences such as; ENGINE_by_id(), ENGINE_get_first(), ENGINE_get_last(), 219160814SsimonENGINE_get_next(), ENGINE_get_prev(). All structural references should be 220160814Ssimonreleased by a corresponding to call to the ENGINE_free() function - the 221160814SsimonENGINE object itself will only actually be cleaned up and deallocated when 222160814Ssimonthe last structural reference is released. 223109998Smarkm 224109998SmarkmIt should also be noted that many ENGINE API function calls that accept a 225109998Smarkmstructural reference will internally obtain another reference - typically 226109998Smarkmthis happens whenever the supplied ENGINE will be needed by OpenSSL after 227109998Smarkmthe function has returned. Eg. the function to add a new ENGINE to 228109998SmarkmOpenSSL's internal list is ENGINE_add() - if this function returns success, 229109998Smarkmthen OpenSSL will have stored a new structural reference internally so the 230109998Smarkmcaller is still responsible for freeing their own reference with 231109998SmarkmENGINE_free() when they are finished with it. In a similar way, some 232109998Smarkmfunctions will automatically release the structural reference passed to it 233109998Smarkmif part of the function's job is to do so. Eg. the ENGINE_get_next() and 234109998SmarkmENGINE_get_prev() functions are used for iterating across the internal 235109998SmarkmENGINE list - they will return a new structural reference to the next (or 236109998Smarkmprevious) ENGINE in the list or NULL if at the end (or beginning) of the 237109998Smarkmlist, but in either case the structural reference passed to the function is 238109998Smarkmreleased on behalf of the caller. 239109998Smarkm 240109998SmarkmTo clarify a particular function's handling of references, one should 241109998Smarkmalways consult that function's documentation "man" page, or failing that 242109998Smarkmthe openssl/engine.h header file includes some hints. 243109998Smarkm 244109998SmarkmI<Functional references> 245109998Smarkm 246109998SmarkmAs mentioned, functional references exist when the cryptographic 247109998Smarkmfunctionality of an ENGINE is required to be available. A functional 248109998Smarkmreference can be obtained in one of two ways; from an existing structural 249109998Smarkmreference to the required ENGINE, or by asking OpenSSL for the default 250109998Smarkmoperational ENGINE for a given cryptographic purpose. 251109998Smarkm 252109998SmarkmTo obtain a functional reference from an existing structural reference, 253109998Smarkmcall the ENGINE_init() function. This returns zero if the ENGINE was not 254109998Smarkmalready operational and couldn't be successfully initialised (eg. lack of 255109998Smarkmsystem drivers, no special hardware attached, etc), otherwise it will 256109998Smarkmreturn non-zero to indicate that the ENGINE is now operational and will 257160814Ssimonhave allocated a new B<functional> reference to the ENGINE. All functional 258160814Ssimonreferences are released by calling ENGINE_finish() (which removes the 259160814Ssimonimplicit structural reference as well). 260109998Smarkm 261109998SmarkmThe second way to get a functional reference is by asking OpenSSL for a 262109998Smarkmdefault implementation for a given task, eg. by ENGINE_get_default_RSA(), 263109998SmarkmENGINE_get_default_cipher_engine(), etc. These are discussed in the next 264109998Smarkmsection, though they are not usually required by application programmers as 265109998Smarkmthey are used automatically when creating and using the relevant 266109998Smarkmalgorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc. 267109998Smarkm 268109998Smarkm=head2 Default implementations 269109998Smarkm 270109998SmarkmFor each supported abstraction, the ENGINE code maintains an internal table 271109998Smarkmof state to control which implementations are available for a given 272109998Smarkmabstraction and which should be used by default. These implementations are 273160814Ssimonregistered in the tables and indexed by an 'nid' value, because 274109998Smarkmabstractions like EVP_CIPHER and EVP_DIGEST support many distinct 275160814Ssimonalgorithms and modes, and ENGINEs can support arbitrarily many of them. 276160814SsimonIn the case of other abstractions like RSA, DSA, etc, there is only one 277160814Ssimon"algorithm" so all implementations implicitly register using the same 'nid' 278160814Ssimonindex. 279109998Smarkm 280160814SsimonWhen a default ENGINE is requested for a given abstraction/algorithm/mode, (eg. 281160814Ssimonwhen calling RSA_new_method(NULL)), a "get_default" call will be made to the 282160814SsimonENGINE subsystem to process the corresponding state table and return a 283160814Ssimonfunctional reference to an initialised ENGINE whose implementation should be 284160814Ssimonused. If no ENGINE should (or can) be used, it will return NULL and the caller 285160814Ssimonwill operate with a NULL ENGINE handle - this usually equates to using the 286160814Ssimonconventional software implementation. In the latter case, OpenSSL will from 287160814Ssimonthen on behave the way it used to before the ENGINE API existed. 288109998Smarkm 289109998SmarkmEach state table has a flag to note whether it has processed this 290109998Smarkm"get_default" query since the table was last modified, because to process 291109998Smarkmthis question it must iterate across all the registered ENGINEs in the 292109998Smarkmtable trying to initialise each of them in turn, in case one of them is 293109998Smarkmoperational. If it returns a functional reference to an ENGINE, it will 294109998Smarkmalso cache another reference to speed up processing future queries (without 295109998Smarkmneeding to iterate across the table). Likewise, it will cache a NULL 296109998Smarkmresponse if no ENGINE was available so that future queries won't repeat the 297109998Smarkmsame iteration unless the state table changes. This behaviour can also be 298109998Smarkmchanged; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using 299109998SmarkmENGINE_set_table_flags()), no attempted initialisations will take place, 300109998Smarkminstead the only way for the state table to return a non-NULL ENGINE to the 301109998Smarkm"get_default" query will be if one is expressly set in the table. Eg. 302109998SmarkmENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except 303109998Smarkmthat it also sets the state table's cached response for the "get_default" 304160814Ssimonquery. In the case of abstractions like EVP_CIPHER, where implementations are 305160814Ssimonindexed by 'nid', these flags and cached-responses are distinct for each 'nid' 306160814Ssimonvalue. 307109998Smarkm 308109998Smarkm=head2 Application requirements 309109998Smarkm 310109998SmarkmThis section will explain the basic things an application programmer should 311109998Smarkmsupport to make the most useful elements of the ENGINE functionality 312109998Smarkmavailable to the user. The first thing to consider is whether the 313109998Smarkmprogrammer wishes to make alternative ENGINE modules available to the 314109998Smarkmapplication and user. OpenSSL maintains an internal linked list of 315109998Smarkm"visible" ENGINEs from which it has to operate - at start-up, this list is 316109998Smarkmempty and in fact if an application does not call any ENGINE API calls and 317109998Smarkmit uses static linking against openssl, then the resulting application 318109998Smarkmbinary will not contain any alternative ENGINE code at all. So the first 319109998Smarkmconsideration is whether any/all available ENGINE implementations should be 320109998Smarkmmade visible to OpenSSL - this is controlled by calling the various "load" 321109998Smarkmfunctions, eg. 322109998Smarkm 323109998Smarkm /* Make the "dynamic" ENGINE available */ 324109998Smarkm void ENGINE_load_dynamic(void); 325109998Smarkm /* Make the CryptoSwift hardware acceleration support available */ 326109998Smarkm void ENGINE_load_cswift(void); 327109998Smarkm /* Make support for nCipher's "CHIL" hardware available */ 328109998Smarkm void ENGINE_load_chil(void); 329109998Smarkm ... 330109998Smarkm /* Make ALL ENGINE implementations bundled with OpenSSL available */ 331109998Smarkm void ENGINE_load_builtin_engines(void); 332109998Smarkm 333109998SmarkmHaving called any of these functions, ENGINE objects would have been 334109998Smarkmdynamically allocated and populated with these implementations and linked 335109998Smarkminto OpenSSL's internal linked list. At this point it is important to 336109998Smarkmmention an important API function; 337109998Smarkm 338109998Smarkm void ENGINE_cleanup(void); 339109998Smarkm 340109998SmarkmIf no ENGINE API functions are called at all in an application, then there 341109998Smarkmare no inherent memory leaks to worry about from the ENGINE functionality, 342160814Ssimonhowever if any ENGINEs are loaded, even if they are never registered or 343109998Smarkmused, it is necessary to use the ENGINE_cleanup() function to 344109998Smarkmcorrespondingly cleanup before program exit, if the caller wishes to avoid 345109998Smarkmmemory leaks. This mechanism uses an internal callback registration table 346109998Smarkmso that any ENGINE API functionality that knows it requires cleanup can 347109998Smarkmregister its cleanup details to be called during ENGINE_cleanup(). This 348109998Smarkmapproach allows ENGINE_cleanup() to clean up after any ENGINE functionality 349109998Smarkmat all that your program uses, yet doesn't automatically create linker 350109998Smarkmdependencies to all possible ENGINE functionality - only the cleanup 351109998Smarkmcallbacks required by the functionality you do use will be required by the 352109998Smarkmlinker. 353109998Smarkm 354109998SmarkmThe fact that ENGINEs are made visible to OpenSSL (and thus are linked into 355109998Smarkmthe program and loaded into memory at run-time) does not mean they are 356109998Smarkm"registered" or called into use by OpenSSL automatically - that behaviour 357160814Ssimonis something for the application to control. Some applications 358109998Smarkmwill want to allow the user to specify exactly which ENGINE they want used 359109998Smarkmif any is to be used at all. Others may prefer to load all support and have 360109998SmarkmOpenSSL automatically use at run-time any ENGINE that is able to 361109998Smarkmsuccessfully initialise - ie. to assume that this corresponds to 362109998Smarkmacceleration hardware attached to the machine or some such thing. There are 363109998Smarkmprobably numerous other ways in which applications may prefer to handle 364109998Smarkmthings, so we will simply illustrate the consequences as they apply to a 365109998Smarkmcouple of simple cases and leave developers to consider these and the 366109998Smarkmsource code to openssl's builtin utilities as guides. 367109998Smarkm 368109998SmarkmI<Using a specific ENGINE implementation> 369109998Smarkm 370109998SmarkmHere we'll assume an application has been configured by its user or admin 371109998Smarkmto want to use the "ACME" ENGINE if it is available in the version of 372109998SmarkmOpenSSL the application was compiled with. If it is available, it should be 373291719Sjkimused by default for all RSA, DSA, and symmetric cipher operations, otherwise 374109998SmarkmOpenSSL should use its builtin software as per usual. The following code 375109998Smarkmillustrates how to approach this; 376109998Smarkm 377109998Smarkm ENGINE *e; 378109998Smarkm const char *engine_id = "ACME"; 379109998Smarkm ENGINE_load_builtin_engines(); 380109998Smarkm e = ENGINE_by_id(engine_id); 381109998Smarkm if(!e) 382109998Smarkm /* the engine isn't available */ 383109998Smarkm return; 384109998Smarkm if(!ENGINE_init(e)) { 385109998Smarkm /* the engine couldn't initialise, release 'e' */ 386109998Smarkm ENGINE_free(e); 387109998Smarkm return; 388109998Smarkm } 389109998Smarkm if(!ENGINE_set_default_RSA(e)) 390109998Smarkm /* This should only happen when 'e' can't initialise, but the previous 391109998Smarkm * statement suggests it did. */ 392109998Smarkm abort(); 393109998Smarkm ENGINE_set_default_DSA(e); 394109998Smarkm ENGINE_set_default_ciphers(e); 395109998Smarkm /* Release the functional reference from ENGINE_init() */ 396109998Smarkm ENGINE_finish(e); 397109998Smarkm /* Release the structural reference from ENGINE_by_id() */ 398109998Smarkm ENGINE_free(e); 399109998Smarkm 400109998SmarkmI<Automatically using builtin ENGINE implementations> 401109998Smarkm 402109998SmarkmHere we'll assume we want to load and register all ENGINE implementations 403109998Smarkmbundled with OpenSSL, such that for any cryptographic algorithm required by 404291719SjkimOpenSSL - if there is an ENGINE that implements it and can be initialised, 405109998Smarkmit should be used. The following code illustrates how this can work; 406109998Smarkm 407109998Smarkm /* Load all bundled ENGINEs into memory and make them visible */ 408109998Smarkm ENGINE_load_builtin_engines(); 409109998Smarkm /* Register all of them for every algorithm they collectively implement */ 410109998Smarkm ENGINE_register_all_complete(); 411109998Smarkm 412109998SmarkmThat's all that's required. Eg. the next time OpenSSL tries to set up an 413109998SmarkmRSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to 414109998SmarkmENGINE_init() and if any of those succeed, that ENGINE will be set as the 415160814Ssimondefault for RSA use from then on. 416109998Smarkm 417109998Smarkm=head2 Advanced configuration support 418109998Smarkm 419109998SmarkmThere is a mechanism supported by the ENGINE framework that allows each 420109998SmarkmENGINE implementation to define an arbitrary set of configuration 421109998Smarkm"commands" and expose them to OpenSSL and any applications based on 422109998SmarkmOpenSSL. This mechanism is entirely based on the use of name-value pairs 423160814Ssimonand assumes ASCII input (no unicode or UTF for now!), so it is ideal if 424109998Smarkmapplications want to provide a transparent way for users to provide 425109998Smarkmarbitrary configuration "directives" directly to such ENGINEs. It is also 426109998Smarkmpossible for the application to dynamically interrogate the loaded ENGINE 427109998Smarkmimplementations for the names, descriptions, and input flags of their 428109998Smarkmavailable "control commands", providing a more flexible configuration 429109998Smarkmscheme. However, if the user is expected to know which ENGINE device he/she 430109998Smarkmis using (in the case of specialised hardware, this goes without saying) 431109998Smarkmthen applications may not need to concern themselves with discovering the 432160814Ssimonsupported control commands and simply prefer to pass settings into ENGINEs 433160814Ssimonexactly as they are provided by the user. 434109998Smarkm 435109998SmarkmBefore illustrating how control commands work, it is worth mentioning what 436109998Smarkmthey are typically used for. Broadly speaking there are two uses for 437109998Smarkmcontrol commands; the first is to provide the necessary details to the 438109998Smarkmimplementation (which may know nothing at all specific to the host system) 439109998Smarkmso that it can be initialised for use. This could include the path to any 440109998Smarkmdriver or config files it needs to load, required network addresses, 441160814Ssimonsmart-card identifiers, passwords to initialise protected devices, 442109998Smarkmlogging information, etc etc. This class of commands typically needs to be 443109998Smarkmpassed to an ENGINE B<before> attempting to initialise it, ie. before 444109998Smarkmcalling ENGINE_init(). The other class of commands consist of settings or 445109998Smarkmoperations that tweak certain behaviour or cause certain operations to take 446109998Smarkmplace, and these commands may work either before or after ENGINE_init(), or 447160814Ssimonin some cases both. ENGINE implementations should provide indications of 448109998Smarkmthis in the descriptions attached to builtin control commands and/or in 449109998Smarkmexternal product documentation. 450109998Smarkm 451109998SmarkmI<Issuing control commands to an ENGINE> 452109998Smarkm 453109998SmarkmLet's illustrate by example; a function for which the caller supplies the 454109998Smarkmname of the ENGINE it wishes to use, a table of string-pairs for use before 455109998Smarkminitialisation, and another table for use after initialisation. Note that 456109998Smarkmthe string-pairs used for control commands consist of a command "name" 457109998Smarkmfollowed by the command "parameter" - the parameter could be NULL in some 458109998Smarkmcases but the name can not. This function should initialise the ENGINE 459109998Smarkm(issuing the "pre" commands beforehand and the "post" commands afterwards) 460109998Smarkmand set it as the default for everything except RAND and then return a 461109998Smarkmboolean success or failure. 462109998Smarkm 463109998Smarkm int generic_load_engine_fn(const char *engine_id, 464109998Smarkm const char **pre_cmds, int pre_num, 465109998Smarkm const char **post_cmds, int post_num) 466109998Smarkm { 467109998Smarkm ENGINE *e = ENGINE_by_id(engine_id); 468109998Smarkm if(!e) return 0; 469109998Smarkm while(pre_num--) { 470109998Smarkm if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) { 471109998Smarkm fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id, 472109998Smarkm pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)"); 473109998Smarkm ENGINE_free(e); 474109998Smarkm return 0; 475109998Smarkm } 476109998Smarkm pre_cmds += 2; 477109998Smarkm } 478109998Smarkm if(!ENGINE_init(e)) { 479109998Smarkm fprintf(stderr, "Failed initialisation\n"); 480109998Smarkm ENGINE_free(e); 481109998Smarkm return 0; 482109998Smarkm } 483109998Smarkm /* ENGINE_init() returned a functional reference, so free the structural 484109998Smarkm * reference from ENGINE_by_id(). */ 485109998Smarkm ENGINE_free(e); 486109998Smarkm while(post_num--) { 487109998Smarkm if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) { 488109998Smarkm fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id, 489109998Smarkm post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)"); 490109998Smarkm ENGINE_finish(e); 491109998Smarkm return 0; 492109998Smarkm } 493109998Smarkm post_cmds += 2; 494109998Smarkm } 495109998Smarkm ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); 496109998Smarkm /* Success */ 497109998Smarkm return 1; 498109998Smarkm } 499109998Smarkm 500109998SmarkmNote that ENGINE_ctrl_cmd_string() accepts a boolean argument that can 501109998Smarkmrelax the semantics of the function - if set non-zero it will only return 502109998Smarkmfailure if the ENGINE supported the given command name but failed while 503109998Smarkmexecuting it, if the ENGINE doesn't support the command name it will simply 504109998Smarkmreturn success without doing anything. In this case we assume the user is 505109998Smarkmonly supplying commands specific to the given ENGINE so we set this to 506109998SmarkmFALSE. 507109998Smarkm 508109998SmarkmI<Discovering supported control commands> 509109998Smarkm 510109998SmarkmIt is possible to discover at run-time the names, numerical-ids, descriptions 511160814Ssimonand input parameters of the control commands supported by an ENGINE using a 512160814Ssimonstructural reference. Note that some control commands are defined by OpenSSL 513160814Ssimonitself and it will intercept and handle these control commands on behalf of the 514160814SsimonENGINE, ie. the ENGINE's ctrl() handler is not used for the control command. 515160814Ssimonopenssl/engine.h defines an index, ENGINE_CMD_BASE, that all control commands 516160814Ssimonimplemented by ENGINEs should be numbered from. Any command value lower than 517160814Ssimonthis symbol is considered a "generic" command is handled directly by the 518160814SsimonOpenSSL core routines. 519109998Smarkm 520237658SjkimIt is using these "core" control commands that one can discover the control 521109998Smarkmcommands implemented by a given ENGINE, specifically the commands; 522109998Smarkm 523109998Smarkm #define ENGINE_HAS_CTRL_FUNCTION 10 524109998Smarkm #define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11 525109998Smarkm #define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12 526109998Smarkm #define ENGINE_CTRL_GET_CMD_FROM_NAME 13 527109998Smarkm #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14 528109998Smarkm #define ENGINE_CTRL_GET_NAME_FROM_CMD 15 529109998Smarkm #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16 530109998Smarkm #define ENGINE_CTRL_GET_DESC_FROM_CMD 17 531109998Smarkm #define ENGINE_CTRL_GET_CMD_FLAGS 18 532109998Smarkm 533109998SmarkmWhilst these commands are automatically processed by the OpenSSL framework code, 534160814Ssimonthey use various properties exposed by each ENGINE to process these 535160814Ssimonqueries. An ENGINE has 3 properties it exposes that can affect how this behaves; 536109998Smarkmit can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in 537109998Smarkmthe ENGINE's flags, and it can expose an array of control command descriptions. 538109998SmarkmIf an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will 539109998Smarkmsimply pass all these "core" control commands directly to the ENGINE's ctrl() 540109998Smarkmhandler (and thus, it must have supplied one), so it is up to the ENGINE to 541109998Smarkmreply to these "discovery" commands itself. If that flag is not set, then the 542109998SmarkmOpenSSL framework code will work with the following rules; 543109998Smarkm 544109998Smarkm if no ctrl() handler supplied; 545109998Smarkm ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero), 546109998Smarkm all other commands fail. 547109998Smarkm if a ctrl() handler was supplied but no array of control commands; 548109998Smarkm ENGINE_HAS_CTRL_FUNCTION returns TRUE, 549109998Smarkm all other commands fail. 550109998Smarkm if a ctrl() handler and array of control commands was supplied; 551109998Smarkm ENGINE_HAS_CTRL_FUNCTION returns TRUE, 552109998Smarkm all other commands proceed processing ... 553109998Smarkm 554109998SmarkmIf the ENGINE's array of control commands is empty then all other commands will 555109998Smarkmfail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of 556109998Smarkmthe first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the 557109998Smarkmidentifier of a command supported by the ENGINE and returns the next command 558109998Smarkmidentifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string 559109998Smarkmname for a command and returns the corresponding identifier or fails if no such 560109998Smarkmcommand name exists, and the remaining commands take a command identifier and 561109998Smarkmreturn properties of the corresponding commands. All except 562109998SmarkmENGINE_CTRL_GET_FLAGS return the string length of a command name or description, 563109998Smarkmor populate a supplied character buffer with a copy of the command name or 564109998Smarkmdescription. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following 565109998Smarkmpossible values; 566109998Smarkm 567109998Smarkm #define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001 568109998Smarkm #define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002 569109998Smarkm #define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 570109998Smarkm #define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 571109998Smarkm 572109998SmarkmIf the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely 573109998Smarkminformational to the caller - this flag will prevent the command being usable 574109998Smarkmfor any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string(). 575109998Smarkm"INTERNAL" commands are not intended to be exposed to text-based configuration 576109998Smarkmby applications, administrations, users, etc. These can support arbitrary 577109998Smarkmoperations via ENGINE_ctrl(), including passing to and/or from the control 578109998Smarkmcommands data of any arbitrary type. These commands are supported in the 579109998Smarkmdiscovery mechanisms simply to allow applications determinie if an ENGINE 580109998Smarkmsupports certain specific commands it might want to use (eg. application "foo" 581109998Smarkmmight query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - 582109998Smarkmand ENGINE could therefore decide whether or not to support this "foo"-specific 583109998Smarkmextension). 584109998Smarkm 585109998Smarkm=head2 Future developments 586109998Smarkm 587109998SmarkmThe ENGINE API and internal architecture is currently being reviewed. Slated for 588109998Smarkmpossible release in 0.9.8 is support for transparent loading of "dynamic" 589109998SmarkmENGINEs (built as self-contained shared-libraries). This would allow ENGINE 590194206Ssimonimplementations to be provided independently of OpenSSL libraries and/or 591109998SmarkmOpenSSL-based applications, and would also remove any requirement for 592109998Smarkmapplications to explicitly use the "dynamic" ENGINE to bind to shared-library 593109998Smarkmimplementations. 594109998Smarkm 595109998Smarkm=head1 SEE ALSO 596109998Smarkm 597160814SsimonL<rsa(3)|rsa(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rand(3)|rand(3)> 598109998Smarkm 599109998Smarkm=cut 600