]>
Commit | Line | Data |
---|---|---|
7753be74 RL |
1 | /* |
2 | * Copyright 2019 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 OSSL_CORE_H | |
11 | # define OSSL_CORE_H | |
12 | ||
13 | # include <stddef.h> | |
14 | # include <openssl/ossl_typ.h> | |
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 | ||
28 | /* | |
29 | * Dispatch table element. function_id numbers are defined further down, | |
30 | * see macros with '_FUNC' in their names. | |
31 | * | |
32 | * An array of these is always terminated by function_id == 0 | |
33 | */ | |
34 | struct ossl_dispatch_st { | |
35 | int function_id; | |
36 | void (*function)(void); | |
37 | }; | |
38 | ||
39 | /* | |
40 | * Other items, essentially an int<->pointer map element. | |
41 | * | |
42 | * We make this type distinct from OSSL_DISPATCH to ensure that dispatch | |
43 | * tables remain tables with function pointers only. | |
44 | * | |
45 | * This is used whenever we need to pass things like a table of error reason | |
46 | * codes <-> reason string maps, parameter name <-> parameter type maps, ... | |
47 | * | |
48 | * Usage determines which field works as key if any, rather than field order. | |
49 | * | |
50 | * An array of these is always terminated by id == 0 && ptr == NULL | |
51 | */ | |
52 | struct ossl_item_st { | |
53 | unsigned int id; | |
54 | void *ptr; | |
55 | }; | |
56 | ||
57 | /* | |
58 | * Type to tie together algorithm name, property definition string and | |
59 | * the algorithm implementation in the form of a dispatch table. | |
60 | * | |
61 | * An array of these is always terminated by algorithm_name == NULL | |
62 | */ | |
63 | struct ossl_algorithm_st { | |
64 | const char *algorithm_name; /* key */ | |
65 | const char *property_definition; /* key */ | |
66 | const OSSL_DISPATCH *implementation; | |
67 | }; | |
68 | ||
69 | /* | |
70 | * Type to pass object data in a uniform way, without exposing the object | |
71 | * structure. | |
72 | * | |
73 | * An array of these is always terminated by key == NULL | |
74 | */ | |
75 | struct ossl_param_st { | |
76 | const char *key; /* the name of the parameter */ | |
77 | unsigned int data_type; /* declare what kind of content is in buffer */ | |
8c4412ed RL |
78 | void *data; /* value being passed in or out */ |
79 | size_t data_size; /* data size */ | |
4e7991b4 | 80 | size_t return_size; /* returned content size */ |
7753be74 RL |
81 | }; |
82 | ||
83 | /* Currently supported OSSL_PARAM data types */ | |
84 | /* | |
85 | * OSSL_PARAM_INTEGER and OSSL_PARAM_UNSIGNED_INTEGER | |
86 | * are arbitrary length and therefore require an arbitrarily sized buffer, | |
87 | * since they may be used to pass numbers larger than what is natively | |
88 | * available. | |
89 | * | |
90 | * The number must be buffered in native form, i.e. MSB first on B_ENDIAN | |
91 | * systems and LSB first on L_ENDIAN systems. This means that arbitrary | |
92 | * native integers can be stored in the buffer, just make sure that the | |
93 | * buffer size is correct and the buffer itself is properly aligned (for | |
94 | * example by having the buffer field point at a C integer). | |
95 | */ | |
96 | # define OSSL_PARAM_INTEGER 1 | |
97 | # define OSSL_PARAM_UNSIGNED_INTEGER 2 | |
98 | /*- | |
99 | * OSSL_PARAM_REAL | |
100 | * is a C binary floating point values in native form and alignment. | |
101 | */ | |
102 | # define OSSL_PARAM_REAL 3 | |
103 | /*- | |
104 | * OSSL_PARAM_UTF8_STRING | |
105 | * is a printable string. Is expteced to be printed as it is. | |
106 | */ | |
107 | # define OSSL_PARAM_UTF8_STRING 4 | |
108 | /*- | |
109 | * OSSL_PARAM_OCTET_STRING | |
110 | * is a string of bytes with no further specification. Is expected to be | |
111 | * printed as a hexdump. | |
112 | */ | |
113 | # define OSSL_PARAM_OCTET_STRING 5 | |
7753be74 | 114 | /*- |
7ffbd7ca P |
115 | * OSSL_PARAM_UTF8_PTR |
116 | * is a pointer to a printable string. Is expteced to be printed as it is. | |
7753be74 | 117 | * |
7ffbd7ca P |
118 | * The difference between this and OSSL_PARAM_UTF8_STRING is that only pointers |
119 | * are manipulated for this type. | |
7753be74 RL |
120 | * |
121 | * This is more relevant for parameter requests, where the responding | |
122 | * function doesn't need to copy the data to the provided buffer, but | |
123 | * sets the provided buffer to point at the actual data instead. | |
124 | * | |
125 | * WARNING! Using these is FRAGILE, as it assumes that the actual | |
126 | * data and its location are constant. | |
127 | */ | |
7ffbd7ca P |
128 | # define OSSL_PARAM_UTF8_PTR 6 |
129 | /*- | |
130 | * OSSL_PARAM_OCTET_PTR | |
131 | * is a pointer to a string of bytes with no further specification. It is | |
132 | * expected to be printed as a hexdump. | |
133 | * | |
134 | * The difference between this and OSSL_PARAM_OCTET_STRING is that only pointers | |
135 | * are manipulated for this type. | |
136 | * | |
137 | * This is more relevant for parameter requests, where the responding | |
138 | * function doesn't need to copy the data to the provided buffer, but | |
139 | * sets the provided buffer to point at the actual data instead. | |
140 | * | |
141 | * WARNING! Using these is FRAGILE, as it assumes that the actual | |
142 | * data and its location are constant. | |
7753be74 | 143 | */ |
7ffbd7ca | 144 | # define OSSL_PARAM_OCTET_PTR 7 |
7753be74 | 145 | |
da747958 MC |
146 | /* |
147 | * Typedef for the thread stop handling callback. Used both internally and by | |
148 | * providers. | |
4bd8b240 | 149 | * |
da747958 MC |
150 | * Providers may register for notifications about threads stopping by |
151 | * registering a callback to hear about such events. Providers register the | |
152 | * callback using the OSSL_FUNC_CORE_THREAD_START function in the |in| dispatch | |
153 | * table passed to OSSL_provider_init(). The arg passed back to a provider will | |
154 | * be the provider side context object. | |
155 | */ | |
156 | typedef void (*OSSL_thread_stop_handler_fn)(void *arg); | |
157 | ||
158 | ||
4c2883a9 RL |
159 | /*- |
160 | * Provider entry point | |
161 | * -------------------- | |
162 | * | |
163 | * This function is expected to be present in any dynamically loadable | |
164 | * provider module. By definition, if this function doesn't exist in a | |
165 | * module, that module is not an OpenSSL provider module. | |
166 | */ | |
167 | /*- | |
168 | * |provider| pointer to opaque type OSSL_PROVIDER. This can be used | |
169 | * together with some functions passed via |in| to query data. | |
170 | * |in| is the array of functions that the Core passes to the provider. | |
171 | * |out| will be the array of base functions that the provider passes | |
172 | * back to the Core. | |
a39eb840 RL |
173 | * |provctx| a provider side context object, optionally created if the |
174 | * provider needs it. This value is passed to other provider | |
175 | * functions, notably other context constructors. | |
4c2883a9 RL |
176 | */ |
177 | typedef int (OSSL_provider_init_fn)(const OSSL_PROVIDER *provider, | |
178 | const OSSL_DISPATCH *in, | |
a39eb840 RL |
179 | const OSSL_DISPATCH **out, |
180 | void **provctx); | |
d88736df RL |
181 | # ifdef __VMS |
182 | # pragma names save | |
183 | # pragma names uppercase,truncated | |
184 | # endif | |
4c2883a9 | 185 | extern OSSL_provider_init_fn OSSL_provider_init; |
d88736df RL |
186 | # ifdef __VMS |
187 | # pragma names restore | |
188 | # endif | |
4c2883a9 | 189 | |
7753be74 RL |
190 | # ifdef __cplusplus |
191 | } | |
192 | # endif | |
193 | ||
194 | #endif |