[thirdparty/openssl.git] / doc / man7 / openssl-core.h.pod

=pod

=head1 NAME

openssl/core.h - OpenSSL Core types

=head1 SYNOPSIS

 #include <openssl/core.h>

=head1 DESCRIPTION

The F<< <openssl/core.h> >> header 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 B<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 NULL.

The available function identities and corresponding function
signatures are defined in 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 B<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 NULL.

=item B<OSSL_ALGORITHM>

This type is a tuple of an algorithm name (string), a property
definition (string) and a dispatch table (array of B<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 NULL.

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

=item B<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 NULL (for
pointers).

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

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

=item B<OSSL_CALLBACK>

This is a function type for a generic feedback callback function:

    typedef int (OSSL_CALLBACK)(const OSSL_PARAM params[], void *arg);

A function that takes a pointer of this type should also take a
pointer to caller data.  When calling this callback, the function is
expected to build an B<OSSL_PARAM> array of data it wants or is
expected to pass back, and pass that as I<params>, as well as
the caller data pointer it received, as I<arg>.

=item B<OSSL_PASSPHRASE_CALLBACK>

This is a function type for a generic pass phrase callback function:

    typedef int (OSSL_PASSPHRASE_CALLBACK)(char *pass, size_t pass_size,
                                           size_t *pass_len,
                                           const OSSL_PARAM params[],
                                           void *arg);

This callback can be used to prompt the user for a passphrase.  When
calling it, a buffer to store the pass phrase needs to be given with
I<pass>, and its size with I<pass_size>.  The length of the prompted
pass phrase will be given back in I<*pass_len>.

Additional parameters can be passed with the B<OSSL_PARAM> array
I<params>.

A function that takes a pointer of this type should also take a
pointer to caller data, which should be passed as I<arg> to this
callback.

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