2 * Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
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
10 #ifndef OPENSSL_CORE_H
11 # define OPENSSL_CORE_H
14 # include <openssl/types.h>
24 * These are the types that the OpenSSL core and providers have in common
25 * to communicate data between them.
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
;
34 * Dispatch table element. function_id numbers are defined further down,
35 * see macros with '_FUNC' in their names.
37 * An array of these is always terminated by function_id == 0
39 struct ossl_dispatch_st
{
41 void (*function
)(void);
45 * Other items, essentially an int<->pointer map element.
47 * We make this type distinct from OSSL_DISPATCH to ensure that dispatch
48 * tables remain tables with function pointers only.
50 * This is used whenever we need to pass things like a table of error reason
51 * codes <-> reason string maps, ...
53 * Usage determines which field works as key if any, rather than field order.
55 * An array of these is always terminated by id == 0 && ptr == NULL
63 * Type to tie together algorithm names, property definition string and
64 * the algorithm implementation in the form of a dispatch table.
66 * An array of these is always terminated by algorithm_names == NULL
68 struct ossl_algorithm_st
{
69 const char *algorithm_names
; /* key */
70 const char *property_definition
; /* key */
71 const OSSL_DISPATCH
*implementation
;
75 * Type to pass object data in a uniform way, without exposing the object
78 * An array of these is always terminated by key == NULL
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 */
83 void *data
; /* value being passed in or out */
84 size_t data_size
; /* data size */
85 size_t return_size
; /* returned content size */
88 /* Currently supported OSSL_PARAM data types */
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
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).
101 # define OSSL_PARAM_INTEGER 1
102 # define OSSL_PARAM_UNSIGNED_INTEGER 2
105 * is a C binary floating point values in native form and alignment.
107 # define OSSL_PARAM_REAL 3
109 * OSSL_PARAM_UTF8_STRING
110 * is a printable string. Is expteced to be printed as it is.
112 # define OSSL_PARAM_UTF8_STRING 4
114 * OSSL_PARAM_OCTET_STRING
115 * is a string of bytes with no further specification. Is expected to be
116 * printed as a hexdump.
118 # define OSSL_PARAM_OCTET_STRING 5
120 * OSSL_PARAM_UTF8_PTR
121 * is a pointer to a printable string. Is expteced to be printed as it is.
123 * The difference between this and OSSL_PARAM_UTF8_STRING is that only pointers
124 * are manipulated for this type.
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.
130 * WARNING! Using these is FRAGILE, as it assumes that the actual
131 * data and its location are constant.
133 * EXTRA WARNING! If you are not completely sure you most likely want
134 * to use the OSSL_PARAM_UTF8_STRING type.
136 # define OSSL_PARAM_UTF8_PTR 6
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.
142 * The difference between this and OSSL_PARAM_OCTET_STRING is that only pointers
143 * are manipulated for this type.
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.
149 * WARNING! Using these is FRAGILE, as it assumes that the actual
150 * data and its location are constant.
152 * EXTRA WARNING! If you are not completely sure you most likely want
153 * to use the OSSL_PARAM_OCTET_STRING type.
155 # define OSSL_PARAM_OCTET_PTR 7
158 * Typedef for the thread stop handling callback. Used both internally and by
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.
167 typedef void (*OSSL_thread_stop_handler_fn
)(void *arg
);
171 * Provider entry point
172 * --------------------
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.
179 * |handle| pointer to opaque type OSSL_CORE_HANDLE. This can be used
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
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.
188 typedef int (OSSL_provider_init_fn
)(const OSSL_CORE_HANDLE
*handle
,
189 const OSSL_DISPATCH
*in
,
190 const OSSL_DISPATCH
**out
,
194 # pragma names uppercase,truncated
196 extern OSSL_provider_init_fn OSSL_provider_init
;
198 # pragma names restore
202 * Generic callback function signature.
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.
211 * libcrypto may use the OSSL_PARAM array to create arguments for an
212 * application callback it knows about.
214 typedef int (OSSL_CALLBACK
)(const OSSL_PARAM params
[], void *arg
);
217 * Passphrase callback function signature
219 * This is similar to the generic callback function above, but adds a
222 typedef int (OSSL_PASSPHRASE_CALLBACK
)(char *pass
, size_t pass_size
,
224 const OSSL_PARAM params
[], void *arg
);