| /* |
| * 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 |