123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280 |
- =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
|