1=pod 2 3=head1 NAME 4 5openssl/core.h - OpenSSL Core types 6 7=head1 SYNOPSIS 8 9 #include <openssl/core.h> 10 11=head1 DESCRIPTION 12 13The F<< <openssl/core.h> >> header defines a number of public types that 14are used to communicate between the OpenSSL libraries and 15implementation providers. 16These types are designed to minimise the need for intimate knowledge 17of internal structures between the OpenSSL libraries and the providers. 18 19The types are: 20 21=over 4 22 23=item B<OSSL_DISPATCH> 24 25This type is a tuple of function identity and function pointer. 26Arrays of this type are passed between the OpenSSL libraries and the 27providers to describe what functionality one side provides to the 28other. 29Arrays of this type must be terminated with a tuple having function 30identity zero and function pointer NULL. 31 32The available function identities and corresponding function 33signatures are defined in L<openssl-core_dispatch.h(7)>. 34 35Any function identity not recognised by the recipient of this type 36will be ignored. 37This ensures that providers built with one OpenSSL version in mind 38will work together with any other OpenSSL version that supports this 39mechanism. 40 41=item B<OSSL_ITEM> 42 43This type is a tuple of integer and pointer. 44It's a generic type used as a generic descriptor, its exact meaning 45being defined by how it's used. 46Arrays of this type are passed between the OpenSSL libraries and the 47providers, and must be terminated with a tuple where the integer is 48zero and the pointer NULL. 49 50=item B<OSSL_ALGORITHM> 51 52This type is a tuple of an algorithm name (string), a property 53definition (string) and a dispatch table (array of B<OSSL_DISPATCH>). 54Arrays of this type are passed on demand from the providers to the 55OpenSSL libraries to describe what algorithms the providers provide 56implementations of, and with what properties. 57Arrays of this type must be terminated with a tuple having function 58identity zero and function pointer NULL. 59 60The algorithm names and property definitions are defined by the 61providers. 62 63The OpenSSL libraries use the first of the algorithm names as the main 64or canonical name, on a per algorithm implementation basis. 65 66=item B<OSSL_PARAM> 67 68This type is a structure that allows passing arbitrary object data 69between two parties that have no or very little shared knowledge about 70their respective internal structures for that object. 71It's normally passed in arrays, where the array is terminated with an 72element where all fields are zero (for non-pointers) or NULL (for 73pointers). 74 75These arrays can be used to set parameters for some object, to request 76parameters, and to describe parameters. 77 78B<OSSL_PARAM> is further described in L<OSSL_PARAM(3)> 79 80=item B<OSSL_CALLBACK> 81 82This is a function type for a generic feedback callback function: 83 84 typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg); 85 86A function that takes a pointer of this type should also take a 87pointer to caller data. When calling this callback, the function is 88expected to build an B<OSSL_PARAM> array of data it wants or is 89expected to pass back, and pass that as I<params>, as well as 90the caller data pointer it received, as I<arg>. 91 92=item B<OSSL_PASSPHRASE_CALLBACK> 93 94This is a function type for a generic pass phrase callback function: 95 96 typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size, 97 size_t *pass_len, 98 const OSSL_PARAM params[], 99 void *arg); 100 101This callback can be used to prompt the user for a passphrase. When 102calling it, a buffer to store the pass phrase needs to be given with 103I<pass>, and its size with I<pass_size>. The length of the prompted 104pass phrase will be given back in I<*pass_len>. 105 106Additional parameters can be passed with the B<OSSL_PARAM> array 107I<params>. 108 109A function that takes a pointer of this type should also take a 110pointer to caller data, which should be passed as I<arg> to this 111callback. 112 113=back 114 115=head1 SEE ALSO 116 117L<openssl-core_dispatch.h(7)> 118 119=head1 HISTORY 120 121The types described here were added in OpenSSL 3.0. 122 123=head1 COPYRIGHT 124 125Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 126 127Licensed under the Apache License 2.0 (the "License"). You may not use 128this file except in compliance with the License. You can obtain a copy 129in the file LICENSE in the source distribution or at 130L<https://www.openssl.org/source/license.html>. 131 132=cut 133
