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