]>
Commit | Line | Data |
---|---|---|
7753be74 | 1 | /* |
33388b44 | 2 | * Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. |
7753be74 RL |
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 | ||
ae4186b0 DMSP |
10 | #ifndef OPENSSL_CORE_H |
11 | # define OPENSSL_CORE_H | |
7753be74 RL |
12 | |
13 | # include <stddef.h> | |
50cd4768 | 14 | # include <openssl/types.h> |
7753be74 RL |
15 | |
16 | # ifdef __cplusplus | |
17 | extern "C" { | |
18 | # endif | |
19 | ||
20 | /*- | |
21 | * Base types | |
22 | * ---------- | |
23 | * | |
24 | * These are the types that the OpenSSL core and providers have in common | |
25 | * to communicate data between them. | |
26 | */ | |
27 | ||
d40b42ab MC |
28 | /* Opaque handles to be used with core upcall functions from providers */ |
29 | typedef struct ossl_core_handle_st OSSL_CORE_HANDLE; | |
30 | typedef struct openssl_core_ctx_st OPENSSL_CORE_CTX; | |
31 | typedef struct ossl_core_bio_st OSSL_CORE_BIO; | |
32 | ||
7753be74 RL |
33 | /* |
34 | * Dispatch table element. function_id numbers are defined further down, | |
35 | * see macros with '_FUNC' in their names. | |
36 | * | |
37 | * An array of these is always terminated by function_id == 0 | |
38 | */ | |
39 | struct ossl_dispatch_st { | |
40 | int function_id; | |
41 | void (*function)(void); | |
42 | }; | |
43 | ||
44 | /* | |
45 | * Other items, essentially an int<->pointer map element. | |
46 | * | |
47 | * We make this type distinct from OSSL_DISPATCH to ensure that dispatch | |
48 | * tables remain tables with function pointers only. | |
49 | * | |
50 | * This is used whenever we need to pass things like a table of error reason | |
26175013 | 51 | * codes <-> reason string maps, ... |
7753be74 RL |
52 | * |
53 | * Usage determines which field works as key if any, rather than field order. | |
54 | * | |
55 | * An array of these is always terminated by id == 0 && ptr == NULL | |
56 | */ | |
57 | struct ossl_item_st { | |
58 | unsigned int id; | |
59 | void *ptr; | |
60 | }; | |
61 | ||
62 | /* | |
695d195b | 63 | * Type to tie together algorithm names, property definition string and |
7753be74 RL |
64 | * the algorithm implementation in the form of a dispatch table. |
65 | * | |
695d195b | 66 | * An array of these is always terminated by algorithm_names == NULL |
7753be74 RL |
67 | */ |
68 | struct ossl_algorithm_st { | |
695d195b | 69 | const char *algorithm_names; /* key */ |
7753be74 RL |
70 | const char *property_definition; /* key */ |
71 | const OSSL_DISPATCH *implementation; | |
72 | }; | |
73 | ||
74 | /* | |
75 | * Type to pass object data in a uniform way, without exposing the object | |
76 | * structure. | |
77 | * | |
78 | * An array of these is always terminated by key == NULL | |
79 | */ | |
80 | struct ossl_param_st { | |
81 | const char *key; /* the name of the parameter */ | |
82 | unsigned int data_type; /* declare what kind of content is in buffer */ | |
8c4412ed RL |
83 | void *data; /* value being passed in or out */ |
84 | size_t data_size; /* data size */ | |
4e7991b4 | 85 | size_t return_size; /* returned content size */ |
7753be74 RL |
86 | }; |
87 | ||
88 | /* Currently supported OSSL_PARAM data types */ | |
89 | /* | |
90 | * OSSL_PARAM_INTEGER and OSSL_PARAM_UNSIGNED_INTEGER | |
91 | * are arbitrary length and therefore require an arbitrarily sized buffer, | |
92 | * since they may be used to pass numbers larger than what is natively | |
93 | * available. | |
94 | * | |
95 | * The number must be buffered in native form, i.e. MSB first on B_ENDIAN | |
96 | * systems and LSB first on L_ENDIAN systems. This means that arbitrary | |
97 | * native integers can be stored in the buffer, just make sure that the | |
98 | * buffer size is correct and the buffer itself is properly aligned (for | |
99 | * example by having the buffer field point at a C integer). | |
100 | */ | |
101 | # define OSSL_PARAM_INTEGER 1 | |
102 | # define OSSL_PARAM_UNSIGNED_INTEGER 2 | |
103 | /*- | |
104 | * OSSL_PARAM_REAL | |
105 | * is a C binary floating point values in native form and alignment. | |
106 | */ | |
107 | # define OSSL_PARAM_REAL 3 | |
108 | /*- | |
109 | * OSSL_PARAM_UTF8_STRING | |
c0f39ded | 110 | * is a printable string. It is expected to be printed as it is. |
7753be74 RL |
111 | */ |
112 | # define OSSL_PARAM_UTF8_STRING 4 | |
113 | /*- | |
114 | * OSSL_PARAM_OCTET_STRING | |
c0f39ded | 115 | * is a string of bytes with no further specification. It is expected to be |
7753be74 RL |
116 | * printed as a hexdump. |
117 | */ | |
118 | # define OSSL_PARAM_OCTET_STRING 5 | |
7753be74 | 119 | /*- |
7ffbd7ca | 120 | * OSSL_PARAM_UTF8_PTR |
c0f39ded | 121 | * is a pointer to a printable string. It is expected to be printed as it is. |
7753be74 | 122 | * |
7ffbd7ca P |
123 | * The difference between this and OSSL_PARAM_UTF8_STRING is that only pointers |
124 | * are manipulated for this type. | |
7753be74 RL |
125 | * |
126 | * This is more relevant for parameter requests, where the responding | |
127 | * function doesn't need to copy the data to the provided buffer, but | |
128 | * sets the provided buffer to point at the actual data instead. | |
129 | * | |
130 | * WARNING! Using these is FRAGILE, as it assumes that the actual | |
131 | * data and its location are constant. | |
82e1fc1b P |
132 | * |
133 | * EXTRA WARNING! If you are not completely sure you most likely want | |
134 | * to use the OSSL_PARAM_UTF8_STRING type. | |
7753be74 | 135 | */ |
7ffbd7ca P |
136 | # define OSSL_PARAM_UTF8_PTR 6 |
137 | /*- | |
138 | * OSSL_PARAM_OCTET_PTR | |
139 | * is a pointer to a string of bytes with no further specification. It is | |
140 | * expected to be printed as a hexdump. | |
141 | * | |
142 | * The difference between this and OSSL_PARAM_OCTET_STRING is that only pointers | |
143 | * are manipulated for this type. | |
144 | * | |
145 | * This is more relevant for parameter requests, where the responding | |
146 | * function doesn't need to copy the data to the provided buffer, but | |
147 | * sets the provided buffer to point at the actual data instead. | |
148 | * | |
149 | * WARNING! Using these is FRAGILE, as it assumes that the actual | |
150 | * data and its location are constant. | |
82e1fc1b P |
151 | * |
152 | * EXTRA WARNING! If you are not completely sure you most likely want | |
153 | * to use the OSSL_PARAM_OCTET_STRING type. | |
7753be74 | 154 | */ |
7ffbd7ca | 155 | # define OSSL_PARAM_OCTET_PTR 7 |
7753be74 | 156 | |
da747958 MC |
157 | /* |
158 | * Typedef for the thread stop handling callback. Used both internally and by | |
159 | * providers. | |
4bd8b240 | 160 | * |
da747958 MC |
161 | * Providers may register for notifications about threads stopping by |
162 | * registering a callback to hear about such events. Providers register the | |
163 | * callback using the OSSL_FUNC_CORE_THREAD_START function in the |in| dispatch | |
164 | * table passed to OSSL_provider_init(). The arg passed back to a provider will | |
165 | * be the provider side context object. | |
166 | */ | |
167 | typedef void (*OSSL_thread_stop_handler_fn)(void *arg); | |
168 | ||
169 | ||
4c2883a9 RL |
170 | /*- |
171 | * Provider entry point | |
172 | * -------------------- | |
173 | * | |
174 | * This function is expected to be present in any dynamically loadable | |
175 | * provider module. By definition, if this function doesn't exist in a | |
176 | * module, that module is not an OpenSSL provider module. | |
177 | */ | |
178 | /*- | |
d40b42ab | 179 | * |handle| pointer to opaque type OSSL_CORE_HANDLE. This can be used |
4c2883a9 RL |
180 | * together with some functions passed via |in| to query data. |
181 | * |in| is the array of functions that the Core passes to the provider. | |
182 | * |out| will be the array of base functions that the provider passes | |
183 | * back to the Core. | |
a39eb840 RL |
184 | * |provctx| a provider side context object, optionally created if the |
185 | * provider needs it. This value is passed to other provider | |
186 | * functions, notably other context constructors. | |
4c2883a9 | 187 | */ |
d40b42ab | 188 | typedef int (OSSL_provider_init_fn)(const OSSL_CORE_HANDLE *handle, |
4c2883a9 | 189 | const OSSL_DISPATCH *in, |
a39eb840 RL |
190 | const OSSL_DISPATCH **out, |
191 | void **provctx); | |
d88736df RL |
192 | # ifdef __VMS |
193 | # pragma names save | |
194 | # pragma names uppercase,truncated | |
195 | # endif | |
4c2883a9 | 196 | extern OSSL_provider_init_fn OSSL_provider_init; |
d88736df RL |
197 | # ifdef __VMS |
198 | # pragma names restore | |
199 | # endif | |
4c2883a9 | 200 | |
10e7216e RL |
201 | /* |
202 | * Generic callback function signature. | |
203 | * | |
204 | * The expectation is that any provider function that wants to offer | |
205 | * a callback / hook can do so by taking an argument with this type, | |
206 | * as well as a pointer to caller-specific data. When calling the | |
207 | * callback, the provider function can populate an OSSL_PARAM array | |
208 | * with data of its choice and pass that in the callback call, along | |
209 | * with the caller data argument. | |
210 | * | |
211 | * libcrypto may use the OSSL_PARAM array to create arguments for an | |
212 | * application callback it knows about. | |
213 | */ | |
214 | typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg); | |
c3fc2c53 P |
215 | typedef int (OSSL_INOUT_CALLBACK)(const OSSL_PARAM in_params[], |
216 | OSSL_PARAM out_params[], void *arg); | |
0d003c52 RL |
217 | /* |
218 | * Passphrase callback function signature | |
219 | * | |
220 | * This is similar to the generic callback function above, but adds a | |
221 | * result parameter. | |
222 | */ | |
223 | typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size, | |
224 | size_t *pass_len, | |
225 | const OSSL_PARAM params[], void *arg); | |
226 | ||
7753be74 RL |
227 | # ifdef __cplusplus |
228 | } | |
229 | # endif | |
230 | ||
231 | #endif |