mirror of
https://github.com/openssl/openssl.git
synced 2024-12-27 06:21:43 +08:00
0d003c52d3
Serialization is needed to be able to take a provider object (such as
the provider side key data) and output it in PEM form, DER form, text
form (for display), and possibly other future forms (XML? JSON? JWK?)
The idea is that a serializer should be able to handle objects it has
intimate knowledge of, as well as object data in OSSL_PARAM form. The
latter will allow libcrypto to serialize some object with a different
provider than the one holding the data, if exporting of that data is
allowed and there is a serializer that can handle it.
We will provide serializers for the types of objects we know about,
which should be useful together with any other provider that provides
implementations of the same type of object.
Serializers are selected by method name and a couple of additional
properties:
- format used to tell what format the output should be in.
Possibilities could include "format=text",
"format=pem", "format=der", "format=pem-pkcs1"
(traditional), "format=der-pkcs1" (traditional)
- type used to tell exactly what type of data should be
output, for example "type=public" (the public part of
a key), "type=private" (the private part of a key),
"type=domainparams" (domain parameters).
This also adds a passphrase callback function type,
OSSL_PASSPHRASE_CALLBACK, which is a bit like OSSL_CALLBACK, but it
takes a few extra arguments to place the result in.
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10394)
130 lines
4.2 KiB
Plaintext
130 lines
4.2 KiB
Plaintext
=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
|