include/openssl/core.h

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