diff options
Diffstat (limited to 'include/openssl/core.h')
| -rw-r--r-- | include/openssl/core.h | 233 |
1 files changed, 233 insertions, 0 deletions
diff --git a/include/openssl/core.h b/include/openssl/core.h new file mode 100644 index 00000000..9683ac70 --- /dev/null +++ b/include/openssl/core.h @@ -0,0 +1,233 @@ +/* + * Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. + * + * Licensed under the Apache License 2.0 (the "License"). You may not use + * this file except in compliance with the License. You can obtain a copy + * in the file LICENSE in the source distribution or at + * https://www.openssl.org/source/license.html + */ + +#ifndef OPENSSL_CORE_H +# define OPENSSL_CORE_H +# pragma once + +# include <stddef.h> +# include <openssl/types.h> + +# ifdef __cplusplus +extern "C" { +# endif + +/*- + * Base types + * ---------- + * + * These are the types that the OpenSSL core and providers have in common + * to communicate data between them. + */ + +/* Opaque handles to be used with core upcall functions from providers */ +typedef struct ossl_core_handle_st OSSL_CORE_HANDLE; +typedef struct openssl_core_ctx_st OPENSSL_CORE_CTX; +typedef struct ossl_core_bio_st OSSL_CORE_BIO; + +/* + * Dispatch table element. function_id numbers and the functions are defined + * in core_dispatch.h, see macros with 'OSSL_CORE_MAKE_FUNC' in their names. + * + * An array of these is always terminated by function_id == 0 + */ +struct ossl_dispatch_st { + int function_id; + void (*function)(void); +}; + +/* + * Other items, essentially an int<->pointer map element. + * + * We make this type distinct from OSSL_DISPATCH to ensure that dispatch + * tables remain tables with function pointers only. + * + * This is used whenever we need to pass things like a table of error reason + * codes <-> reason string maps, ... + * + * Usage determines which field works as key if any, rather than field order. + * + * An array of these is always terminated by id == 0 && ptr == NULL + */ +struct ossl_item_st { + unsigned int id; + void *ptr; +}; + +/* + * Type to tie together algorithm names, property definition string and + * the algorithm implementation in the form of a dispatch table. + * + * An array of these is always terminated by algorithm_names == NULL + */ +struct ossl_algorithm_st { + const char *algorithm_names; /* key */ + const char *property_definition; /* key */ + const OSSL_DISPATCH *implementation; + const char *algorithm_description; +}; + +/* + * Type to pass object data in a uniform way, without exposing the object + * structure. + * + * An array of these is always terminated by key == NULL + */ +struct ossl_param_st { + const char *key; /* the name of the parameter */ + unsigned int data_type; /* declare what kind of content is in buffer */ + void *data; /* value being passed in or out */ + size_t data_size; /* data size */ + size_t return_size; /* returned content size */ +}; + +/* Currently supported OSSL_PARAM data types */ +/* + * OSSL_PARAM_INTEGER and OSSL_PARAM_UNSIGNED_INTEGER + * are arbitrary length and therefore require an arbitrarily sized buffer, + * since they may be used to pass numbers larger than what is natively + * available. + * + * The number must be buffered in native form, i.e. MSB first on B_ENDIAN + * systems and LSB first on L_ENDIAN systems. This means that arbitrary + * native integers can be stored in the buffer, just make sure that the + * buffer size is correct and the buffer itself is properly aligned (for + * example by having the buffer field point at a C integer). + */ +# define OSSL_PARAM_INTEGER 1 +# define OSSL_PARAM_UNSIGNED_INTEGER 2 +/*- + * OSSL_PARAM_REAL + * is a C binary floating point values in native form and alignment. + */ +# define OSSL_PARAM_REAL 3 +/*- + * OSSL_PARAM_UTF8_STRING + * is a printable string. It is expected to be printed as it is. + */ +# define OSSL_PARAM_UTF8_STRING 4 +/*- + * OSSL_PARAM_OCTET_STRING + * is a string of bytes with no further specification. It is expected to be + * printed as a hexdump. + */ +# define OSSL_PARAM_OCTET_STRING 5 +/*- + * OSSL_PARAM_UTF8_PTR + * is a pointer to a printable string. It is expected to be printed as it is. + * + * The difference between this and OSSL_PARAM_UTF8_STRING is that only pointers + * are manipulated for this type. + * + * This is more relevant for parameter requests, where the responding + * function doesn't need to copy the data to the provided buffer, but + * sets the provided buffer to point at the actual data instead. + * + * WARNING! Using these is FRAGILE, as it assumes that the actual + * data and its location are constant. + * + * EXTRA WARNING! If you are not completely sure you most likely want + * to use the OSSL_PARAM_UTF8_STRING type. + */ +# define OSSL_PARAM_UTF8_PTR 6 +/*- + * OSSL_PARAM_OCTET_PTR + * is a pointer to a string of bytes with no further specification. It is + * expected to be printed as a hexdump. + * + * The difference between this and OSSL_PARAM_OCTET_STRING is that only pointers + * are manipulated for this type. + * + * This is more relevant for parameter requests, where the responding + * function doesn't need to copy the data to the provided buffer, but + * sets the provided buffer to point at the actual data instead. + * + * WARNING! Using these is FRAGILE, as it assumes that the actual + * data and its location are constant. + * + * EXTRA WARNING! If you are not completely sure you most likely want + * to use the OSSL_PARAM_OCTET_STRING type. + */ +# define OSSL_PARAM_OCTET_PTR 7 + +/* + * Typedef for the thread stop handling callback. Used both internally and by + * providers. + * + * Providers may register for notifications about threads stopping by + * registering a callback to hear about such events. Providers register the + * callback using the OSSL_FUNC_CORE_THREAD_START function in the |in| dispatch + * table passed to OSSL_provider_init(). The arg passed back to a provider will + * be the provider side context object. + */ +typedef void (*OSSL_thread_stop_handler_fn)(void *arg); + + +/*- + * Provider entry point + * -------------------- + * + * This function is expected to be present in any dynamically loadable + * provider module. By definition, if this function doesn't exist in a + * module, that module is not an OpenSSL provider module. + */ +/*- + * |handle| pointer to opaque type OSSL_CORE_HANDLE. This can be used + * together with some functions passed via |in| to query data. + * |in| is the array of functions that the Core passes to the provider. + * |out| will be the array of base functions that the provider passes + * back to the Core. + * |provctx| a provider side context object, optionally created if the + * provider needs it. This value is passed to other provider + * functions, notably other context constructors. + */ +typedef int (OSSL_provider_init_fn)(const OSSL_CORE_HANDLE *handle, + const OSSL_DISPATCH *in, + const OSSL_DISPATCH **out, + void **provctx); +# ifdef __VMS +# pragma names save +# pragma names uppercase,truncated +# endif +OPENSSL_EXPORT OSSL_provider_init_fn OSSL_provider_init; +# ifdef __VMS +# pragma names restore +# endif + +/* + * Generic callback function signature. + * + * The expectation is that any provider function that wants to offer + * a callback / hook can do so by taking an argument with this type, + * as well as a pointer to caller-specific data. When calling the + * callback, the provider function can populate an OSSL_PARAM array + * with data of its choice and pass that in the callback call, along + * with the caller data argument. + * + * libcrypto may use the OSSL_PARAM array to create arguments for an + * application callback it knows about. + */ +typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg); +typedef int (OSSL_INOUT_CALLBACK)(const OSSL_PARAM in_params[], + OSSL_PARAM out_params[], void *arg); +/* + * Passphrase callback function signature + * + * This is similar to the generic callback function above, but adds a + * result parameter. + */ +typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size, + size_t *pass_len, + const OSSL_PARAM params[], void *arg); + +# ifdef __cplusplus +} +# endif + +#endif |