include/openssl/core.h

   1 /*
   2  * Copyright 2019-2020 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 OPENSSL_CORE_H
  11 # define OPENSSL_CORE_H
  12
  13 # include <stddef.h>
  14 # include <openssl/types.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 /* Opaque handles to be used with core upcall functions from providers */
  29 typedef struct ossl_core_handle_st OSSL_CORE_HANDLE;
  30 typedef struct openssl_core_ctx_st OPENSSL_CORE_CTX;
  31 typedef struct ossl_core_bio_st OSSL_CORE_BIO;
  32
  33 /*
  34  * Dispatch table element.  function_id numbers are defined further down,
  35  * see macros with '_FUNC' in their names.
  36  *
  37  * An array of these is always terminated by function_id == 0
  38  */
  39 struct ossl_dispatch_st {
  40     int function_id;
  41     void (*function)(void);
  42 };
  43
  44 /*
  45  * Other items, essentially an int<->pointer map element.
  46  *
  47  * We make this type distinct from OSSL_DISPATCH to ensure that dispatch
  48  * tables remain tables with function pointers only.
  49  *
  50  * This is used whenever we need to pass things like a table of error reason
  51  * codes <-> reason string maps, ...
  52  *
  53  * Usage determines which field works as key if any, rather than field order.
  54  *
  55  * An array of these is always terminated by id == 0 && ptr == NULL
  56  */
  57 struct ossl_item_st {
  58     unsigned int id;
  59     void *ptr;
  60 };
  61
  62 /*
  63  * Type to tie together algorithm names, property definition string and
  64  * the algorithm implementation in the form of a dispatch table.
  65  *
  66  * An array of these is always terminated by algorithm_names == NULL
  67  */
  68 struct ossl_algorithm_st {
  69     const char *algorithm_names;     /* key */
  70     const char *property_definition; /* key */
  71     const OSSL_DISPATCH *implementation;
  72 };
  73
  74 /*
  75  * Type to pass object data in a uniform way, without exposing the object
  76  * structure.
  77  *
  78  * An array of these is always terminated by key == NULL
  79  */
  80 struct ossl_param_st {
  81     const char *key;             /* the name of the parameter */
  82     unsigned int data_type;      /* declare what kind of content is in buffer */
  83     void *data;                  /* value being passed in or out */
  84     size_t data_size;            /* data size */
  85     size_t return_size;          /* returned content size */
  86 };
  87
  88 /* Currently supported OSSL_PARAM data types */
  89 /*
  90  * OSSL_PARAM_INTEGER and OSSL_PARAM_UNSIGNED_INTEGER
  91  * are arbitrary length and therefore require an arbitrarily sized buffer,
  92  * since they may be used to pass numbers larger than what is natively
  93  * available.
  94  *
  95  * The number must be buffered in native form, i.e. MSB first on B_ENDIAN
  96  * systems and LSB first on L_ENDIAN systems.  This means that arbitrary
  97  * native integers can be stored in the buffer, just make sure that the
  98  * buffer size is correct and the buffer itself is properly aligned (for
  99  * example by having the buffer field point at a C integer).
 100  */
 101 # define OSSL_PARAM_INTEGER              1
 102 # define OSSL_PARAM_UNSIGNED_INTEGER     2
 103 /*-
 104  * OSSL_PARAM_REAL
 105  * is a C binary floating point values in native form and alignment.
 106  */
 107 # define OSSL_PARAM_REAL                 3
 108 /*-
 109  * OSSL_PARAM_UTF8_STRING
 110  * is a printable string.  Is expteced to be printed as it is.
 111  */
 112 # define OSSL_PARAM_UTF8_STRING          4
 113 /*-
 114  * OSSL_PARAM_OCTET_STRING
 115  * is a string of bytes with no further specification.  Is expected to be
 116  * printed as a hexdump.
 117  */
 118 # define OSSL_PARAM_OCTET_STRING         5
 119 /*-
 120  * OSSL_PARAM_UTF8_PTR
 121  * is a pointer to a printable string.  Is expteced to be printed as it is.
 122  *
 123  * The difference between this and OSSL_PARAM_UTF8_STRING is that only pointers
 124  * are manipulated for this type.
 125  *
 126  * This is more relevant for parameter requests, where the responding
 127  * function doesn't need to copy the data to the provided buffer, but
 128  * sets the provided buffer to point at the actual data instead.
 129  *
 130  * WARNING!  Using these is FRAGILE, as it assumes that the actual
 131  * data and its location are constant.
 132  *
 133  * EXTRA WARNING!  If you are not completely sure you most likely want
 134  * to use the OSSL_PARAM_UTF8_STRING type.
 135  */
 136 # define OSSL_PARAM_UTF8_PTR             6
 137 /*-
 138  * OSSL_PARAM_OCTET_PTR
 139  * is a pointer to a string of bytes with no further specification.  It is
 140  * expected to be printed as a hexdump.
 141  *
 142  * The difference between this and OSSL_PARAM_OCTET_STRING is that only pointers
 143  * are manipulated for this type.
 144  *
 145  * This is more relevant for parameter requests, where the responding
 146  * function doesn't need to copy the data to the provided buffer, but
 147  * sets the provided buffer to point at the actual data instead.
 148  *
 149  * WARNING!  Using these is FRAGILE, as it assumes that the actual
 150  * data and its location are constant.
 151  *
 152  * EXTRA WARNING!  If you are not completely sure you most likely want
 153  * to use the OSSL_PARAM_OCTET_STRING type.
 154  */
 155 # define OSSL_PARAM_OCTET_PTR            7
 156
 157 /*
 158  * Typedef for the thread stop handling callback. Used both internally and by
 159  * providers.
 160  *
 161  * Providers may register for notifications about threads stopping by
 162  * registering a callback to hear about such events. Providers register the
 163  * callback using the OSSL_FUNC_CORE_THREAD_START function in the |in| dispatch
 164  * table passed to OSSL_provider_init(). The arg passed back to a provider will
 165  * be the provider side context object.
 166  */
 167 typedef void (*OSSL_thread_stop_handler_fn)(void *arg);
 168
 169
 170 /*-
 171  * Provider entry point
 172  * --------------------
 173  *
 174  * This function is expected to be present in any dynamically loadable
 175  * provider module.  By definition, if this function doesn't exist in a
 176  * module, that module is not an OpenSSL provider module.
 177  */
 178 /*-
 179  * |handle|     pointer to opaque type OSSL_CORE_HANDLE.  This can be used
 180  *              together with some functions passed via |in| to query data.
 181  * |in|         is the array of functions that the Core passes to the provider.
 182  * |out|        will be the array of base functions that the provider passes
 183  *              back to the Core.
 184  * |provctx|    a provider side context object, optionally created if the
 185  *              provider needs it.  This value is passed to other provider
 186  *              functions, notably other context constructors.
 187  */
 188 typedef int (OSSL_provider_init_fn)(const OSSL_CORE_HANDLE *handle,
 189                                     const OSSL_DISPATCH *in,
 190                                     const OSSL_DISPATCH **out,
 191                                     void **provctx);
 192 # ifdef __VMS
 193 #  pragma names save
 194 #  pragma names uppercase,truncated
 195 # endif
 196 extern OSSL_provider_init_fn OSSL_provider_init;
 197 # ifdef __VMS
 198 #  pragma names restore
 199 # endif
 200
 201 /*
 202  * Generic callback function signature.
 203  *
 204  * The expectation is that any provider function that wants to offer
 205  * a callback / hook can do so by taking an argument with this type,
 206  * as well as a pointer to caller-specific data.  When calling the
 207  * callback, the provider function can populate an OSSL_PARAM array
 208  * with data of its choice and pass that in the callback call, along
 209  * with the caller data argument.
 210  *
 211  * libcrypto may use the OSSL_PARAM array to create arguments for an
 212  * application callback it knows about.
 213  */
 214 typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);
 215
 216 /*
 217  * Passphrase callback function signature
 218  *
 219  * This is similar to the generic callback function above, but adds a
 220  * result parameter.
 221  */
 222 typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size,
 223                                        size_t *pass_len,
 224                                        const OSSL_PARAM params[], void *arg);
 225
 226 # ifdef __cplusplus
 227 }
 228 # endif
 229
 230 #endif