Replumbing: Add include/openssl/core.h, initially with core types

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8286)

1 files changed, 96 insertions, 0 deletions

diff --git a/doc/man7/openssl-core.h.pod b/doc/man7/openssl-core.h.pod
new file mode 100644
index 0000000000..7fd4dfb24e
--- /dev/null
+++ b/doc/man7/openssl-core.h.pod
@@ -0,0 +1,96 @@
+=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