engine.h

All headers

Engines are collections of methods. Methods are tables of function pointers, defined for certain algorithms, that allow operations on those algorithms to be overridden via a callback. This can be used, for example, to implement an RSA* that forwards operations to a hardware module.

Methods are reference counted but ENGINEs are not. When creating a method, you should zero the whole structure and fill in the function pointers that you wish before setting it on an ENGINE. Any functions pointers that are NULL indicate that the default behaviour should be used.

  1. Allocation and destruction
  2. ENGINE_new
  3. ENGINE_free
  4. Method accessors
  5. ENGINE_set_RSA_method
  6. ENGINE_get_RSA_method
  7. ENGINE_set_ECDSA_method
  8. ENGINE_get_ECDSA_method
  9. Generic method functions
  10. METHOD_ref
  11. METHOD_unref

Allocation and destruction.

ENGINE_new returns an empty ENGINE that uses the default method for all algorithms.

OPENSSL_EXPORT ENGINE *ENGINE_new(void);

ENGINE_free decrements the reference counts for all methods linked from engine and frees engine itself. It returns one.

OPENSSL_EXPORT int ENGINE_free(ENGINE *engine);

Method accessors.

Method accessors take a method pointer and the size of the structure. The size allows for ABI compatibility in the case that the method structure is extended with extra elements at the end. Methods are always copied by the set functions.

Set functions return one on success and zero on allocation failure.

OPENSSL_EXPORT int ENGINE_set_RSA_method(ENGINE *engine,
                                         const RSA_METHOD *method,
                                         size_t method_size);
OPENSSL_EXPORT RSA_METHOD *ENGINE_get_RSA_method(const ENGINE *engine);
OPENSSL_EXPORT int ENGINE_set_ECDSA_method(ENGINE *engine,
                                           const ECDSA_METHOD *method,
                                           size_t method_size);
OPENSSL_EXPORT ECDSA_METHOD *ENGINE_get_ECDSA_method(const ENGINE *engine);

Generic method functions.

These functions take a void* type but actually operate on all method structures.

METHOD_ref increments the reference count of method. This is a no-op for now because all methods are currently static.

void METHOD_ref(void *method);

METHOD_unref decrements the reference count of method and frees it if the reference count drops to zero. This is a no-op for now because all methods are currently static.

void METHOD_unref(void *method);