=pod

=head1 NAME

OSSL_DESERIALIZER_from_bio,
OSSL_DESERIALIZER_from_fp,
OSSL_DESERIALIZER_CTX_set_input_type,
OSSL_DESERIALIZER_CTX_add_deserializer,
OSSL_DESERIALIZER_CTX_add_extra,
OSSL_DESERIALIZER_CTX_num_deserializers,
OSSL_DESERIALIZER_INSTANCE,
OSSL_DESERIALIZER_CONSTRUCT,
OSSL_DESERIALIZER_CLEANUP,
OSSL_DESERIALIZER_CTX_set_construct,
OSSL_DESERIALIZER_CTX_set_construct_data,
OSSL_DESERIALIZER_CTX_set_cleanup,
OSSL_DESERIALIZER_CTX_get_construct,
OSSL_DESERIALIZER_CTX_get_construct_data,
OSSL_DESERIALIZER_CTX_get_cleanup,
OSSL_DESERIALIZER_export,
OSSL_DESERIALIZER_INSTANCE_deserializer,
OSSL_DESERIALIZER_INSTANCE_deserializer_ctx
- Routines to perform a deserialization

=head1 SYNOPSIS

 #include <openssl/deserializer.h>

 int OSSL_DESERIALIZER_from_bio(OSSL_DESERIALIZER_CTX *ctx, BIO *in);
 int OSSL_DESERIALIZER_from_fp(OSSL_DESERIALIZER_CTX *ctx, FILE *fp);

 int OSSL_DESERIALIZER_CTX_set_input_type(OSSL_DESERIALIZER_CTX *ctx,
                                          const char *input_type);
 int OSSL_DESERIALIZER_CTX_add_deserializer(OSSL_DESERIALIZER_CTX *ctx,
                                            OSSL_DESERIALIZER *deser);
 int OSSL_DESERIALIZER_CTX_add_extra(OSSL_DESERIALIZER_CTX *ctx);
 int OSSL_DESERIALIZER_CTX_num_deserializers(OSSL_DESERIALIZER_CTX *ctx);

 typedef struct ossl_deserializer_instance_st OSSL_DESERIALIZER_INSTANCE;
 OSSL_DESERIALIZER *OSSL_DESERIALIZER_INSTANCE_deserializer
     (OSSL_DESERIALIZER_INSTANCE *deser_inst);
 void *OSSL_DESERIALIZER_INSTANCE_deserializer_ctx
     (OSSL_DESERIALIZER_INSTANCE *deser_inst);

 typedef int (OSSL_DESERIALIZER_CONSTRUCT)
     (OSSL_DESERIALIZER_INSTANCE *deser_inst,
      const OSSL_PARAM *params, void *construct_data);
 typedef void (OSSL_DESERIALIZER_CLEANUP)(void *construct_data);

 int OSSL_DESERIALIZER_CTX_set_construct
     (OSSL_DESERIALIZER_CTX *ctx, OSSL_DESERIALIZER_CONSTRUCT *construct);
 int OSSL_DESERIALIZER_CTX_set_construct_data
     (OSSL_DESERIALIZER_CTX *ctx, void *construct_data);
 int OSSL_DESERIALIZER_CTX_set_cleanup(OSSL_DESERIALIZER_CTX *ctx,
                                       OSSL_DESERIALIZER_CLEANUP *cleanup);
 OSSL_DESERIALIZER_CONSTRUCT *
 OSSL_DESERIALIZER_CTX_get_construct(OSSL_DESERIALIZER_CTX *ctx);
 void *OSSL_DESERIALIZER_CTX_get_construct_data(OSSL_DESERIALIZER_CTX *ctx);
 OSSL_DESERIALIZER_CLEANUP *
 OSSL_DESERIALIZER_CTX_get_cleanup(OSSL_DESERIALIZER_CTX *ctx);

 int OSSL_DESERIALIZER_export(OSSL_DESERIALIZER_INSTANCE *deser_inst,
                              void *reference, size_t reference_sz,
                              OSSL_CALLBACK *export_cb, void *export_cbarg);

Feature availability macros:

=over 4

=item OSSL_DESERIALIZER_from_fp() is only available when B<OPENSSL_NO_STDIO>
is undefined.

=back

=head1 DESCRIPTION

The B<OSSL_DESERIALIZER_CTX> holds data about multiple deserializers, as
needed to figure out what the input data is and to attempt to unpack it into
one of several possible related results.  This also includes chaining
deserializers, so the output from one can become the input for another.
This allows having generic format deserializers such as PEM to DER, as well
as more specialized deserializers like DER to RSA.

The chains may be limited by specifying an input type, which is considered a
starting point.
This is both considered by OSSL_DESERIALIZER_CTX_add_extra(), which will
stop adding on more deserializer implementations when it has already added
those that take the specified input type, and OSSL_DESERIALIZER_from_bio(),
which will only start the deserializing process with the deserializer
implementations that take that input type.  For example, if the input type
is set to C<DER>, a PEM to DER deserializer will be ignored.

The input type can also be NULL, which means that the caller doesn't know
what type of input they have.  In this case, OSSL_DESERIALIZER_from_bio()
will simply try with one deserializer implementation after the other, and
thereby discover what kind of input the caller gave it.

For every deserialization done, even an intermediary one, a constructor
provided by the caller is called to attempt to construct an appropriate type
/ structure that the caller knows how to handle from the current
deserialization result.
The constructor is set with OSSL_DESERIALIZER_CTX_set_construct().

B<OSSL_DESERIALIZER_INSTANCE> is an opaque structure that contains
data about the deserializer that was just used, and that may be
useful for the constructor.  There are some functions to extract data
from this type, described further down.

=head2 Functions

OSSL_DESERIALIZER_from_bio() runs the deserialization process for the
context I<ctx>, with the input coming from the B<BIO> I<in>.  Should
it make a difference, it's recommended to have the BIO set in binary
mode rather than text mode.

OSSL_DESERIALIZER_from_fp() does the same thing as OSSL_DESERIALIZER_from_bio(),
except that the input is coming from the B<FILE> I<fp>.

OSSL_DESERIALIZER_CTX_add_deserializer() populates the B<OSSL_DESERIALIZER_CTX>
I<ctx> with a deserializer, to be used to attempt to deserialize some
serialized input.

OSSL_DESERIALIZER_CTX_add_extra() finds deserializers that generate
input for already added deserializers, and adds them as well.  This is
used to build deserializer chains.

OSSL_DESERIALIZER_CTX_set_input_type() sets the starting input type.  This
limits the deserializer chains to be considered, as explained in the general
description above.

OSSL_DESERIALIZER_CTX_num_deserializers() gets the number of
deserializers currently added to the context I<ctx>.

OSSL_DESERIALIZER_CTX_set_construct() sets the constructor I<construct>.

OSSL_DESERIALIZER_CTX_set_construct_data() sets the constructor data that is
passed to the constructor every time it's called.

OSSL_DESERIALIZER_CTX_set_cleanup() sets the constructor data I<cleanup>
function.  This is called by L<OSSL_DESERIALIZER_CTX_free(3)>.

OSSL_DESERIALIZER_CTX_get_construct(),
OSSL_DESERIALIZER_CTX_get_construct_data() and
OSSL_DESERIALIZER_CTX_get_cleanup()
return the values that have been set by
OSSL_DESERIALIZER_CTX_set_construct(),
OSSL_DESERIALIZER_CTX_set_construct_data() and
OSSL_DESERIALIZER_CTX_set_cleanup() respectively.

OSSL_DESERIALIZER_export() is a fallback function for constructors that
cannot use the data they get directly for diverse reasons.  It takes the same
deserialize instance I<deser_inst> that the constructor got and an object
I<reference>, unpacks the object which it refers to, and exports it by creating
an L<OSSL_PARAM(3)> array that it then passes to I<export_cb>, along with
I<export_arg>.

OSSL_DESERIALIZER_INSTANCE_deserializer() can be used to get the
deserializer method from a deserializer instance I<deser_inst>.

OSSL_DESERIALIZER_INSTANCE_deserializer-ctx() can be used to get the
deserializer method's provider context from a deserializer instance
I<deser_inst>.

=head2 Constructor

A B<OSSL_DESERIALIZER_CONSTRUCT> gets the following arguments:

=over 4

=item I<deser_inst>

The B<OSSL_DESERIALIZER_INSTANCE> for the deserializer from which
the constructor gets its data.

=item I<params>

The data produced by the deserializer, further described below.

=item I<construct_data>

The pointer that was set with OSSL_DESERIALIZE_CTX_set_construct_data().

=back

The constructor is expected to return 1 when the data it receives can
be constructed, otherwise 0.

The globally known parameters that the constructor can get in I<params>
are:

=over 4

=item "data-type" (B<OSSL_DESERIALIZER_PARAM_DATA_TYPE>) <UTF8 string>

This is a detected content type that some deserializers may provide.
For example, PEM input sometimes has a type specified in its header,
and some deserializers may add that information as this parameter.
This is an optional parameter, but may be useful for extra checks in
the constructor.

=item "data" (B<OSSL_DESERIALIZER_PARAM_DATA>) <octet string>

The deserialized data itself, as an octet string.  This is produced by
deserializers when it's possible to pass an object in this form.  Most
often, this is simply meant to be passed to the next deserializer in a
chain, but could be considered final data as well, at the discretion
of the constructor.

=item "reference" (B<OSSL_DESERIALIZER_PARAM_DATA>) <octet string>

The deserialized data itself, as a reference to an object.  The
reference itself is an octet string, and can be passed to other
operations and functions within the same provider as the one that
provides I<deser>.

=back

At least one of "data" or "reference" must be present, and it's
possible that both can be.  A constructor should choose to use the
"reference" parameter if possible, otherwise it should use the "data"
parameter.

If it's not possible to use the "reference" parameter, but that's
still what a constructor wants to do, it is possible to use
OSSL_DESERIALIZER_export() as a fallback.

=head1 RETURN VALUES

OSSL_DESERIALIZER_from_bio() and OSSL_DESERIALIZER_from_fp() return 1 on
success, or 0 on failure.

OSSL_DESERIALIZER_CTX_add_deserializer(),
OSSL_DESERIALIZER_CTX_add_extra(),
OSSL_DESERIALIZER_CTX_set_construct(),
OSSL_DESERIALIZER_CTX_set_construct_data() and
OSSL_DESERIALIZER_CTX_set_cleanup() return 1 on success, or 0 on
failure.

OSSL_DESERIALIZER_CTX_get_construct(),
OSSL_DESERIALIZER_CTX_get_construct_data() and
OSSL_DESERIALIZER_CTX_get_cleanup() return the current pointers to the
cosntructor, the constructor data and the cleanup functions, respectively.

OSSL_DESERIALIZER_CTX_num_deserializers() returns the current
number of deserializers.  It returns 0 if I<ctx> is NULL.

OSSL_DESERIALIZER_export() returns 1 on success, or 0 on failure.

OSSL_DESERIALIZER_INSTANCE_deserializer() returns an
B<OSSL_DESERIALIZER> pointer on success, or NULL on failure.

OSSL_DESERIALIZER_INSTANCE_deserializer_ctx() returns a provider
context pointer on success, or NULL on failure.>

=begin comment TODO(3.0) Add examples!

=head1 EXAMPLES

Text, because pod2xxx doesn't like empty sections

=end comment

=head1 SEE ALSO

L<provider(7)>, L<OSSL_DESERIALIZER_CTX(3)>

=head1 HISTORY

The functions described here were added in OpenSSL 3.0.

=head1 COPYRIGHT

Copyright 2020 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