1OPENSSL-CORE.H(7ossl)               OpenSSL              OPENSSL-CORE.H(7ossl)
2
3
4

NAME

6       openssl/core.h - OpenSSL Core types
7

SYNOPSIS

9        #include <openssl/core.h>
10

DESCRIPTION

12       The <openssl/core.h> header defines a number of public types that are
13       used to communicate between the OpenSSL libraries and implementation
14       providers.  These types are designed to minimise the need for intimate
15       knowledge of internal structures between the OpenSSL libraries and the
16       providers.
17
18       The types are:
19
20       OSSL_DISPATCH
21           This type is a tuple of function identity and function pointer.
22           Arrays of this type are passed between the OpenSSL libraries and
23           the providers to describe what functionality one side provides to
24           the other.  Arrays of this type must be terminated with a tuple
25           having function identity zero and function pointer NULL.
26
27           The available function identities and corresponding function
28           signatures are defined in openssl-core_dispatch.h(7).
29
30           Any function identity not recognised by the recipient of this type
31           will be ignored.  This ensures that providers built with one
32           OpenSSL version in mind will work together with any other OpenSSL
33           version that supports this mechanism.
34
35       OSSL_ITEM
36           This type is a tuple of integer and pointer.  It's a generic type
37           used as a generic descriptor, its exact meaning being defined by
38           how it's used.  Arrays of this type are passed between the OpenSSL
39           libraries and the providers, and must be terminated with a tuple
40           where the integer is zero and the pointer NULL.
41
42       OSSL_ALGORITHM
43           This type is a tuple of an algorithm name (string), a property
44           definition (string) and a dispatch table (array of OSSL_DISPATCH).
45           Arrays of this type are passed on demand from the providers to the
46           OpenSSL libraries to describe what algorithms the providers provide
47           implementations of, and with what properties.  Arrays of this type
48           must be terminated with a tuple having function identity zero and
49           function pointer NULL.
50
51           The algorithm names and property definitions are defined by the
52           providers.
53
54           The OpenSSL libraries use the first of the algorithm names as the
55           main or canonical name, on a per algorithm implementation basis.
56
57       OSSL_PARAM
58           This type is a structure that allows passing arbitrary object data
59           between two parties that have no or very little shared knowledge
60           about their respective internal structures for that object.  It's
61           normally passed in arrays, where the array is terminated with an
62           element where all fields are zero (for non-pointers) or NULL (for
63           pointers).
64
65           These arrays can be used to set parameters for some object, to
66           request parameters, and to describe parameters.
67
68           OSSL_PARAM is further described in OSSL_PARAM(3)
69
70       OSSL_CALLBACK
71           This is a function type for a generic feedback callback function:
72
73               typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);
74
75           A function that takes a pointer of this type should also take a
76           pointer to caller data.  When calling this callback, the function
77           is expected to build an OSSL_PARAM array of data it wants or is
78           expected to pass back, and pass that as params, as well as the
79           caller data pointer it received, as arg.
80
81       OSSL_PASSPHRASE_CALLBACK
82           This is a function type for a generic pass phrase callback
83           function:
84
85               typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size,
86                                                      size_t *pass_len,
87                                                      const OSSL_PARAM params[],
88                                                      void *arg);
89
90           This callback can be used to prompt the user for a passphrase.
91           When calling it, a buffer to store the pass phrase needs to be
92           given with pass, and its size with pass_size.  The length of the
93           prompted pass phrase will be given back in *pass_len.
94
95           Additional parameters can be passed with the OSSL_PARAM array
96           params.
97
98           A function that takes a pointer of this type should also take a
99           pointer to caller data, which should be passed as arg to this
100           callback.
101

SEE ALSO

103       openssl-core_dispatch.h(7)
104

HISTORY

106       The types described here were added in OpenSSL 3.0.
107

109       Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
110
111       Licensed under the Apache License 2.0 (the "License").  You may not use
112       this file except in compliance with the License.  You can obtain a copy
113       in the file LICENSE in the source distribution or at
114       <https://www.openssl.org/source/license.html>.
115
116
117
1183.0.5                             2022-11-01             OPENSSL-CORE.H(7ossl)
Impressum