include/openssl/core.h

   1 /*
   2  * Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.
   3  *
   4  * Licensed under the Apache License 2.0 (the "License").  You may not use
   5  * this file except in compliance with the License.  You can obtain a copy
   6  * in the file LICENSE in the source distribution or at
   7  * https://www.openssl.org/source/license.html
   8  */
   9
  10 #ifndef OSSL_CORE_H
  11 # define OSSL_CORE_H
  12
  13 # include <stddef.h>
  14 # include <openssl/ossl_typ.h>
  15
  16 # ifdef __cplusplus
  17 extern "C" {
  18 # endif
  19
  20 /*-
  21  * Base types
  22  * ----------
  23  *
  24  * These are the types that the OpenSSL core and providers have in common
  25  * to communicate data between them.
  26  */
  27
  28 /*
  29  * Dispatch table element.  function_id numbers are defined further down,
  30  * see macros with '_FUNC' in their names.
  31  *
  32  * An array of these is always terminated by function_id == 0
  33  */
  34 struct ossl_dispatch_st {
  35     int function_id;
  36     void (*function)(void);
  37 };
  38
  39 /*
  40  * Other items, essentially an int<->pointer map element.
  41  *
  42  * We make this type distinct from OSSL_DISPATCH to ensure that dispatch
  43  * tables remain tables with function pointers only.
  44  *
  45  * This is used whenever we need to pass things like a table of error reason
  46  * codes <-> reason string maps, parameter name <-> parameter type maps, ...
  47  *
  48  * Usage determines which field works as key if any, rather than field order.
  49  *
  50  * An array of these is always terminated by id == 0 && ptr == NULL
  51  */
  52 struct ossl_item_st {
  53     unsigned int id;
  54     void *ptr;
  55 };
  56
  57 /*
  58  * Type to tie together algorithm name, property definition string and
  59  * the algorithm implementation in the form of a dispatch table.
  60  *
  61  * An array of these is always terminated by algorithm_name == NULL
  62  */
  63 struct ossl_algorithm_st {
  64     const char *algorithm_name;      /* key */
  65     const char *property_definition; /* key */
  66     const OSSL_DISPATCH *implementation;
  67 };
  68
  69 /*
  70  * Type to pass object data in a uniform way, without exposing the object
  71  * structure.
  72  *
  73  * An array of these is always terminated by key == NULL
  74  */
  75 struct ossl_param_st {
  76     const char *key;             /* the name of the parameter */
  77     unsigned int data_type;      /* declare what kind of content is in buffer */
  78     void *data;                  /* value being passed in or out */
  79     size_t data_size;            /* data size */
  80     size_t *return_size;         /* OPTIONAL: address to content size */
  81 };
  82
  83 /* Currently supported OSSL_PARAM data types */
  84 /*
  85  * OSSL_PARAM_INTEGER and OSSL_PARAM_UNSIGNED_INTEGER
  86  * are arbitrary length and therefore require an arbitrarily sized buffer,
  87  * since they may be used to pass numbers larger than what is natively
  88  * available.
  89  *
  90  * The number must be buffered in native form, i.e. MSB first on B_ENDIAN
  91  * systems and LSB first on L_ENDIAN systems.  This means that arbitrary
  92  * native integers can be stored in the buffer, just make sure that the
  93  * buffer size is correct and the buffer itself is properly aligned (for
  94  * example by having the buffer field point at a C integer).
  95  */
  96 # define OSSL_PARAM_INTEGER              1
  97 # define OSSL_PARAM_UNSIGNED_INTEGER     2
  98 /*-
  99  * OSSL_PARAM_REAL
 100  * is a C binary floating point values in native form and alignment.
 101  */
 102 # define OSSL_PARAM_REAL                 3
 103 /*-
 104  * OSSL_PARAM_UTF8_STRING
 105  * is a printable string.  Is expteced to be printed as it is.
 106  */
 107 # define OSSL_PARAM_UTF8_STRING          4
 108 /*-
 109  * OSSL_PARAM_OCTET_STRING
 110  * is a string of bytes with no further specification.  Is expected to be
 111  * printed as a hexdump.
 112  */
 113 # define OSSL_PARAM_OCTET_STRING         5
 114 /*-
 115  * OSSL_PARAM_UTF8_PTR
 116  * is a pointer to a printable string.  Is expteced to be printed as it is.
 117  *
 118  * The difference between this and OSSL_PARAM_UTF8_STRING is that only pointers
 119  * are manipulated for this type.
 120  *
 121  * This is more relevant for parameter requests, where the responding
 122  * function doesn't need to copy the data to the provided buffer, but
 123  * sets the provided buffer to point at the actual data instead.
 124  *
 125  * WARNING!  Using these is FRAGILE, as it assumes that the actual
 126  * data and its location are constant.
 127  */
 128 # define OSSL_PARAM_UTF8_PTR             6
 129 /*-
 130  * OSSL_PARAM_OCTET_PTR
 131  * is a pointer to a string of bytes with no further specification.  It is
 132  * expected to be printed as a hexdump.
 133  *
 134  * The difference between this and OSSL_PARAM_OCTET_STRING is that only pointers
 135  * are manipulated for this type.
 136  *
 137  * This is more relevant for parameter requests, where the responding
 138  * function doesn't need to copy the data to the provided buffer, but
 139  * sets the provided buffer to point at the actual data instead.
 140  *
 141  * WARNING!  Using these is FRAGILE, as it assumes that the actual
 142  * data and its location are constant.
 143  */
 144 # define OSSL_PARAM_OCTET_PTR            7
 145
 146 /*-
 147  * Provider entry point
 148  * --------------------
 149  *
 150  * This function is expected to be present in any dynamically loadable
 151  * provider module.  By definition, if this function doesn't exist in a
 152  * module, that module is not an OpenSSL provider module.
 153  */
 154 /*-
 155  * |provider|   pointer to opaque type OSSL_PROVIDER.  This can be used
 156  *              together with some functions passed via |in| to query data.
 157  * |in|         is the array of functions that the Core passes to the provider.
 158  * |out|        will be the array of base functions that the provider passes
 159  *              back to the Core.
 160  */
 161 typedef int (OSSL_provider_init_fn)(const OSSL_PROVIDER *provider,
 162                                     const OSSL_DISPATCH *in,
 163                                     const OSSL_DISPATCH **out);
 164 # ifdef __VMS
 165 #  pragma names save
 166 #  pragma names uppercase,truncated
 167 # endif
 168 extern OSSL_provider_init_fn OSSL_provider_init;
 169 # ifdef __VMS
 170 #  pragma names restore
 171 # endif
 172
 173 # ifdef __cplusplus
 174 }
 175 # endif
 176
 177 #endif