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
18extern "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 */
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 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 */
40struct 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 */
61struct 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 */
72struct 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 */
85struct 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 */
172typedef 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 */
193typedef 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
201OPENSSL_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 */
219typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);
220typedef 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 */
228typedef 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