Home | History | Annotate | Download | only in openssl
      1 /* Copyright (c) 2014, Google Inc.
      2  *
      3  * Permission to use, copy, modify, and/or distribute this software for any
      4  * purpose with or without fee is hereby granted, provided that the above
      5  * copyright notice and this permission notice appear in all copies.
      6  *
      7  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
      8  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
      9  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
     10  * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
     11  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
     12  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
     13  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
     14 
     15 #ifndef OPENSSL_HEADER_ENGINE_H
     16 #define OPENSSL_HEADER_ENGINE_H
     17 
     18 #include <openssl/base.h>
     19 
     20 #if defined(__cplusplus)
     21 extern "C" {
     22 #endif
     23 
     24 
     25 // Engines are collections of methods. Methods are tables of function pointers,
     26 // defined for certain algorithms, that allow operations on those algorithms to
     27 // be overridden via a callback. This can be used, for example, to implement an
     28 // RSA* that forwards operations to a hardware module.
     29 //
     30 // Methods are reference counted but |ENGINE|s are not. When creating a method,
     31 // you should zero the whole structure and fill in the function pointers that
     32 // you wish before setting it on an |ENGINE|. Any functions pointers that
     33 // are NULL indicate that the default behaviour should be used.
     34 
     35 
     36 // Allocation and destruction.
     37 
     38 // ENGINE_new returns an empty ENGINE that uses the default method for all
     39 // algorithms.
     40 OPENSSL_EXPORT ENGINE *ENGINE_new(void);
     41 
     42 // ENGINE_free decrements the reference counts for all methods linked from
     43 // |engine| and frees |engine| itself.
     44 OPENSSL_EXPORT void ENGINE_free(ENGINE *engine);
     45 
     46 
     47 // Method accessors.
     48 //
     49 // Method accessors take a method pointer and the size of the structure. The
     50 // size allows for ABI compatibility in the case that the method structure is
     51 // extended with extra elements at the end. Methods are always copied by the
     52 // set functions.
     53 //
     54 // Set functions return one on success and zero on allocation failure.
     55 
     56 OPENSSL_EXPORT int ENGINE_set_RSA_method(ENGINE *engine,
     57                                          const RSA_METHOD *method,
     58                                          size_t method_size);
     59 OPENSSL_EXPORT RSA_METHOD *ENGINE_get_RSA_method(const ENGINE *engine);
     60 
     61 OPENSSL_EXPORT int ENGINE_set_ECDSA_method(ENGINE *engine,
     62                                            const ECDSA_METHOD *method,
     63                                            size_t method_size);
     64 OPENSSL_EXPORT ECDSA_METHOD *ENGINE_get_ECDSA_method(const ENGINE *engine);
     65 
     66 
     67 // Generic method functions.
     68 //
     69 // These functions take a void* type but actually operate on all method
     70 // structures.
     71 
     72 // METHOD_ref increments the reference count of |method|. This is a no-op for
     73 // now because all methods are currently static.
     74 void METHOD_ref(void *method);
     75 
     76 // METHOD_unref decrements the reference count of |method| and frees it if the
     77 // reference count drops to zero. This is a no-op for now because all methods
     78 // are currently static.
     79 void METHOD_unref(void *method);
     80 
     81 
     82 // Private functions.
     83 
     84 // openssl_method_common_st contains the common part of all method structures.
     85 // This must be the first member of all method structures.
     86 struct openssl_method_common_st {
     87   int references;  // dummy  not used.
     88   char is_static;
     89 };
     90 
     91 
     92 #if defined(__cplusplus)
     93 }  // extern C
     94 
     95 extern "C++" {
     96 
     97 BSSL_NAMESPACE_BEGIN
     98 
     99 BORINGSSL_MAKE_DELETER(ENGINE, ENGINE_free)
    100 
    101 BSSL_NAMESPACE_END
    102 
    103 }  // extern C++
    104 
    105 #endif
    106 
    107 #define ENGINE_R_OPERATION_NOT_SUPPORTED 100
    108 
    109 #endif  // OPENSSL_HEADER_ENGINE_H
    110