remove end of line spaces
[openssl.git] / include / openssl / core.h
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 */
78     void *data;                  /* value being passed in or out */
79     size_t data_size;            /* data size */
80     size_t return_size;          /* returned content size */
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
114 /*-
115  * OSSL_PARAM_UTF8_PTR
116  * is a pointer to a printable string.  Is expteced to be printed as it is.
117  *
118  * The difference between this and OSSL_PARAM_UTF8_STRING is that only pointers
119  * are manipulated for this type.
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  */
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.
143  */
144 # define OSSL_PARAM_OCTET_PTR            7
145
146 /*
147  * Typedef for the thread stop handling callback. Used both internally and by
148  * providers.
149  *
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
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.
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.
176  */
177 typedef int (OSSL_provider_init_fn)(const OSSL_PROVIDER *provider,
178                                     const OSSL_DISPATCH *in,
179                                     const OSSL_DISPATCH **out,
180                                     void **provctx);
181 # ifdef __VMS
182 #  pragma names save
183 #  pragma names uppercase,truncated
184 # endif
185 extern OSSL_provider_init_fn OSSL_provider_init;
186 # ifdef __VMS
187 #  pragma names restore
188 # endif
189
190 # ifdef __cplusplus
191 }
192 # endif
193
194 #endif