codekingpro/portable-devtools

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 use5 * this file except in compliance with the License.  You can obtain a copy6 * in the file LICENSE in the source distribution or at7 * https://www.openssl.org/source/license.html8 */9 10#ifndef OPENSSL_CORE_H11# define OPENSSL_CORE_H12# pragma once13 14# include <stddef.h>15# include <openssl/types.h>16 17# ifdef __cplusplus18extern "C" {19# endif20 21/*-22 * Base types23 * ----------24 *25 * These are the types that the OpenSSL core and providers have in common26 * to communicate data between them.27 */28 29/* Opaque handles to be used with core upcall functions from providers */30typedef struct ossl_core_handle_st OSSL_CORE_HANDLE;31typedef struct openssl_core_ctx_st OPENSSL_CORE_CTX;32typedef struct ossl_core_bio_st OSSL_CORE_BIO;33 34/*35 * Dispatch table element.  function_id numbers and the functions are defined36 * 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 == 039 */40struct 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 dispatch49 * tables remain tables with function pointers only.50 *51 * This is used whenever we need to pass things like a table of error reason52 * 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 == NULL57 */58struct ossl_item_st {59    unsigned int id;60    void *ptr;61};62 63/*64 * Type to tie together algorithm names, property definition string and65 * the algorithm implementation in the form of a dispatch table.66 *67 * An array of these is always terminated by algorithm_names == NULL68 */69struct 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 object78 * structure.79 *80 * An array of these is always terminated by key == NULL81 */82struct 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_INTEGER93 * are arbitrary length and therefore require an arbitrarily sized buffer,94 * since they may be used to pass numbers larger than what is natively95 * available.96 *97 * The number must be buffered in native form, i.e. MSB first on B_ENDIAN98 * systems and LSB first on L_ENDIAN systems.  This means that arbitrary99 * native integers can be stored in the buffer, just make sure that the100 * buffer size is correct and the buffer itself is properly aligned (for101 * example by having the buffer field point at a C integer).102 */103# define OSSL_PARAM_INTEGER              1104# define OSSL_PARAM_UNSIGNED_INTEGER     2105/*-106 * OSSL_PARAM_REAL107 * is a C binary floating point values in native form and alignment.108 */109# define OSSL_PARAM_REAL                 3110/*-111 * OSSL_PARAM_UTF8_STRING112 * is a printable string.  It is expected to be printed as it is.113 */114# define OSSL_PARAM_UTF8_STRING          4115/*-116 * OSSL_PARAM_OCTET_STRING117 * is a string of bytes with no further specification.  It is expected to be118 * printed as a hexdump.119 */120# define OSSL_PARAM_OCTET_STRING         5121/*-122 * OSSL_PARAM_UTF8_PTR123 * 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 pointers126 * are manipulated for this type.127 *128 * This is more relevant for parameter requests, where the responding129 * function doesn't need to copy the data to the provided buffer, but130 * sets the provided buffer to point at the actual data instead.131 *132 * WARNING!  Using these is FRAGILE, as it assumes that the actual133 * data and its location are constant.134 *135 * EXTRA WARNING!  If you are not completely sure you most likely want136 * to use the OSSL_PARAM_UTF8_STRING type.137 */138# define OSSL_PARAM_UTF8_PTR             6139/*-140 * OSSL_PARAM_OCTET_PTR141 * is a pointer to a string of bytes with no further specification.  It is142 * expected to be printed as a hexdump.143 *144 * The difference between this and OSSL_PARAM_OCTET_STRING is that only pointers145 * are manipulated for this type.146 *147 * This is more relevant for parameter requests, where the responding148 * function doesn't need to copy the data to the provided buffer, but149 * sets the provided buffer to point at the actual data instead.150 *151 * WARNING!  Using these is FRAGILE, as it assumes that the actual152 * data and its location are constant.153 *154 * EXTRA WARNING!  If you are not completely sure you most likely want155 * to use the OSSL_PARAM_OCTET_STRING type.156 */157# define OSSL_PARAM_OCTET_PTR            7158 159/*160 * Typedef for the thread stop handling callback. Used both internally and by161 * providers.162 *163 * Providers may register for notifications about threads stopping by164 * registering a callback to hear about such events. Providers register the165 * callback using the OSSL_FUNC_CORE_THREAD_START function in the |in| dispatch166 * table passed to OSSL_provider_init(). The arg passed back to a provider will167 * be the provider side context object.168 */169typedef void (*OSSL_thread_stop_handler_fn)(void *arg);170 171 172/*-173 * Provider entry point174 * --------------------175 *176 * This function is expected to be present in any dynamically loadable177 * provider module.  By definition, if this function doesn't exist in a178 * module, that module is not an OpenSSL provider module.179 */180/*-181 * |handle|     pointer to opaque type OSSL_CORE_HANDLE.  This can be used182 *              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 passes185 *              back to the Core.186 * |provctx|    a provider side context object, optionally created if the187 *              provider needs it.  This value is passed to other provider188 *              functions, notably other context constructors.189 */190typedef 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 __VMS195#  pragma names save196#  pragma names uppercase,truncated197# endif198OPENSSL_EXPORT OSSL_provider_init_fn OSSL_provider_init;199# ifdef __VMS200#  pragma names restore201# endif202 203/*204 * Generic callback function signature.205 *206 * The expectation is that any provider function that wants to offer207 * 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 the209 * callback, the provider function can populate an OSSL_PARAM array210 * with data of its choice and pass that in the callback call, along211 * with the caller data argument.212 *213 * libcrypto may use the OSSL_PARAM array to create arguments for an214 * application callback it knows about.215 */216typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);217typedef int (OSSL_INOUT_CALLBACK)(const OSSL_PARAM in_params[],218                                  OSSL_PARAM out_params[], void *arg);219/*220 * Passphrase callback function signature221 *222 * This is similar to the generic callback function above, but adds a223 * result parameter.224 */225typedef 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 __cplusplus230}231# endif232 233#endif234