1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
/*
* Copyright 2019-2020 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
# 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 are defined further down,
* see macros with '_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;
};
/*
* 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. Is expteced 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. 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. Is expteced 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
extern 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
|
