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 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 |
18 | extern "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 */ |
30 | typedef struct ossl_core_handle_st OSSL_CORE_HANDLE; |
31 | typedef struct openssl_core_ctx_st OPENSSL_CORE_CTX; |
32 | typedef 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 | */ |
40 | struct 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 dispatch |
49 | * tables remain tables with function pointers only. |
50 | * |
51 | * This is used whenever we need to pass things like a table of error reason |
52 | * 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 == NULL |
57 | */ |
58 | struct ossl_item_st { |
59 | unsigned int id; |
60 | void *ptr; |
61 | }; |
62 | |
63 | /* |
64 | * Type to tie together algorithm names, property definition string and |
65 | * the algorithm implementation in the form of a dispatch table. |
66 | * |
67 | * An array of these is always terminated by algorithm_names == NULL |
68 | */ |
69 | struct 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 object |
78 | * structure. |
79 | * |
80 | * An array of these is always terminated by key == NULL |
81 | */ |
82 | struct 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_INTEGER |
93 | * are arbitrary length and therefore require an arbitrarily sized buffer, |
94 | * since they may be used to pass numbers larger than what is natively |
95 | * available. |
96 | * |
97 | * The number must be buffered in native form, i.e. MSB first on B_ENDIAN |
98 | * systems and LSB first on L_ENDIAN systems. This means that arbitrary |
99 | * native integers can be stored in the buffer, just make sure that the |
100 | * buffer size is correct and the buffer itself is properly aligned (for |
101 | * example by having the buffer field point at a C integer). |
102 | */ |
103 | # define OSSL_PARAM_INTEGER 1 |
104 | # define OSSL_PARAM_UNSIGNED_INTEGER 2 |
105 | /*- |
106 | * OSSL_PARAM_REAL |
107 | * is a C binary floating point values in native form and alignment. |
108 | */ |
109 | # define OSSL_PARAM_REAL 3 |
110 | /*- |
111 | * OSSL_PARAM_UTF8_STRING |
112 | * is a printable string. It is expected to be printed as it is. |
113 | */ |
114 | # define OSSL_PARAM_UTF8_STRING 4 |
115 | /*- |
116 | * OSSL_PARAM_OCTET_STRING |
117 | * is a string of bytes with no further specification. It is expected to be |
118 | * printed as a hexdump. |
119 | */ |
120 | # define OSSL_PARAM_OCTET_STRING 5 |
121 | /*- |
122 | * OSSL_PARAM_UTF8_PTR |
123 | * 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 pointers |
126 | * are manipulated for this type. |
127 | * |
128 | * This is more relevant for parameter requests, where the responding |
129 | * function doesn't need to copy the data to the provided buffer, but |
130 | * sets the provided buffer to point at the actual data instead. |
131 | * |
132 | * WARNING! Using these is FRAGILE, as it assumes that the actual |
133 | * data and its location are constant. |
134 | * |
135 | * EXTRA WARNING! If you are not completely sure you most likely want |
136 | * to use the OSSL_PARAM_UTF8_STRING type. |
137 | */ |
138 | # define OSSL_PARAM_UTF8_PTR 6 |
139 | /*- |
140 | * OSSL_PARAM_OCTET_PTR |
141 | * is a pointer to a string of bytes with no further specification. It is |
142 | * expected to be printed as a hexdump. |
143 | * |
144 | * The difference between this and OSSL_PARAM_OCTET_STRING is that only pointers |
145 | * are manipulated for this type. |
146 | * |
147 | * This is more relevant for parameter requests, where the responding |
148 | * function doesn't need to copy the data to the provided buffer, but |
149 | * sets the provided buffer to point at the actual data instead. |
150 | * |
151 | * WARNING! Using these is FRAGILE, as it assumes that the actual |
152 | * data and its location are constant. |
153 | * |
154 | * EXTRA WARNING! If you are not completely sure you most likely want |
155 | * to use the OSSL_PARAM_OCTET_STRING type. |
156 | */ |
157 | # define OSSL_PARAM_OCTET_PTR 7 |
158 | |
159 | /* |
160 | * Typedef for the thread stop handling callback. Used both internally and by |
161 | * providers. |
162 | * |
163 | * Providers may register for notifications about threads stopping by |
164 | * registering a callback to hear about such events. Providers register the |
165 | * callback using the OSSL_FUNC_CORE_THREAD_START function in the |in| dispatch |
166 | * table passed to OSSL_provider_init(). The arg passed back to a provider will |
167 | * be the provider side context object. |
168 | */ |
169 | typedef void (*OSSL_thread_stop_handler_fn)(void *arg); |
170 | |
171 | |
172 | /*- |
173 | * Provider entry point |
174 | * -------------------- |
175 | * |
176 | * This function is expected to be present in any dynamically loadable |
177 | * provider module. By definition, if this function doesn't exist in a |
178 | * module, that module is not an OpenSSL provider module. |
179 | */ |
180 | /*- |
181 | * |handle| pointer to opaque type OSSL_CORE_HANDLE. This can be used |
182 | * 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 passes |
185 | * back to the Core. |
186 | * |provctx| a provider side context object, optionally created if the |
187 | * provider needs it. This value is passed to other provider |
188 | * functions, notably other context constructors. |
189 | */ |
190 | typedef 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 __VMS |
195 | # pragma names save |
196 | # pragma names uppercase,truncated |
197 | # endif |
198 | OPENSSL_EXPORT OSSL_provider_init_fn OSSL_provider_init; |
199 | # ifdef __VMS |
200 | # pragma names restore |
201 | # endif |
202 | |
203 | /* |
204 | * Generic callback function signature. |
205 | * |
206 | * The expectation is that any provider function that wants to offer |
207 | * 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 the |
209 | * callback, the provider function can populate an OSSL_PARAM array |
210 | * with data of its choice and pass that in the callback call, along |
211 | * with the caller data argument. |
212 | * |
213 | * libcrypto may use the OSSL_PARAM array to create arguments for an |
214 | * application callback it knows about. |
215 | */ |
216 | typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg); |
217 | typedef int (OSSL_INOUT_CALLBACK)(const OSSL_PARAM in_params[], |
218 | OSSL_PARAM out_params[], void *arg); |
219 | /* |
220 | * Passphrase callback function signature |
221 | * |
222 | * This is similar to the generic callback function above, but adds a |
223 | * result parameter. |
224 | */ |
225 | typedef 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 __cplusplus |
230 | } |
231 | # endif |
232 | |
233 | #endif |
234 | |