openssl/doc/man3/OSSL_DESERIALIZER_from_bio.pod

=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_FINALIZER,
OSSL_DESERIALIZER_CLEANER,
OSSL_DESERIALIZER_CTX_set_finalizer,
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;
 typedef int (OSSL_DESERIALIZER_FINALIZER)
     (OSSL_DESERIALIZER_INSTANCE *deser_inst,
      const OSSL_PARAM *params, void *finalize_arg);
 typedef void (OSSL_DESERIALIZER_CLEANER)(void *finalize_arg);

 int OSSL_DESERIALIZER_CTX_set_finalizer(OSSL_DESERIALIZER_CTX *ctx,
                                         OSSL_DESRIALIZER_FINALIZER *finalizer,
                                         OSSL_DESERIALIZER_CLEANER *cleaner,
                                         void *finalize_arg);

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

 OSSL_DESERIALIZER *OSSL_DESERIALIZER_INSTANCE_deserializer
     (OSSL_DESERIALIZER_INSTANCE *deser_inst);
 void *OSSL_DESERIALIZER_INSTANCE_deserializer_ctx
     (OSSL_DESERIALIZER_INSTANCE *deser_inst);

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 intermediary, a I<finalizer>
provided by the caller is used to attempt to "finalize" the current
deserialization output, which is always a provider side object of some
sort, by "wrapping" it into some appropriate type or structure that
the caller knows how to handle.  Exactly what this "wrapping" consists
of is entirely at the discretion of the I<finalizer>.

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 I<finalizer>.  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>.  The
application is required to set up the B<BIO> properly, for example to
have it in text or binary mode if that's appropriate.

=for comment Know your deserializer!

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_finalizer() sets the I<finalizer> function
together with the caller argument for the finalizer, I<finalize_arg>,
as well as I<cleaner>, the function to clean up I<finalize_arg> when
the deserialization has concluded.

OSSL_DESERIALIZER_export() is a fallback function for I<finalizers>
that can't use the data they get directly for diverse reasons.  It
takes the same deserialize instance I<deser_inst> that the
I<finalizer> got and an object I<reference>, unpacks the object that
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 Finalizer

The I<finalizer> gets the following arguments:

=over 4

=item I<deser_inst>

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

=item I<params>

The data produced by the deserializer, further described below.

=item I<finalize_arg>

The pointer that was set with OSSL_DESERIALIZE_CTX_set_finalizer() as
I<finalize_arg>.

=back

The I<finalizer> is expected to return 1 when the data it receives can
be "finalized", otherwise 0.

The globally known parameters that I<finalize> 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 I<finalizer>.

=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 I<finalizer>.

=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 I<finalizer> should choose to use the
"reference" parameter if possible, otherwise the "data" parameter.

If it's not possible to use the "reference" parameter, but that's
still what a I<finalizer> 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(), and
OSSL_DESERIALIZER_CTX_set_finalizer() return 1 on success, or 0 on
failure.

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