=pod

=head1 NAME

openssl/core.h - OpenSSL Core types

=head1 SYNOPSIS

 #include <openssl/core.h>

=head1 DESCRIPTION

The <openssl/core.h> header file defines a number of public types that
are used to communicate between the OpenSSL libraries and
implementation providers.
These types are designed to minimise the need for intimate knowledge
of internal structures between the OpenSSL libraries and the providers.

The types are:

=over 4

=item C<OSSL_DISPATCH>

This type is a tuple of function identity and function pointer.
Arrays of this type are passed between the OpenSSL libraries and the
providers to describe what functionality one side provides to the
other.
Arrays of this type must be terminated with a tuple having function
identity zero and function pointer C<NULL>.

The available function identities and corresponding function
signatures are defined by L<openssl-core_numbers.h(7)>.

Any function identity not recognised by the recipient of this type
will be ignored.
This ensures that providers built with one OpenSSL version in mind
will work together with any other OpenSSL version that supports this
mechanism.

=item C<OSSL_ITEM>

This type is a tuple of integer and pointer.
It's a generic type used as a generic descriptor, its exact meaning
being defined by how it's used.
Arrays of this type are passed between the OpenSSL libraries and the
providers, and must be terminated with a tuple where the integer is
zero and the pointer C<NULL>.

=item C<OSSL_ALGORITHM>

This type is a tuple of an algorithm name (string), a property
definition (string) and a dispatch table (array of C<OSSL_DISPATCH>).
Arrays of this type are passed on demand from the providers to the
OpenSSL libraries to describe what algorithms the providers provide
implementations of, and with what properties.
Arrays of this type must be terminated with a tuple having function
identity zero and function pointer C<NULL>.

The algorithm names and property definitions are defined by the
providers.

=item C<OSSL_PARAM>

This type is a structure that allows passing arbitrary object data
between two parties that have no or very little shared knowledge about
their respective internal structures for that object. 
It's normally passed in arrays, where the array is terminated with an
element where all fields are zero (for non-pointers) or C<NULL> (for
pointers).

These arrays can be used both to set parameters for some object, and
to request parameters.

C<OSSL_PARAM> is further described in L<OSSL_PARAM(3)>

=back

=head1 SEE ALSO

L<openssl-core_numbers.h(7)>

=head1 HISTORY

The types described here were added in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut