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