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