Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OSSL_DESERIALIZER_FROM_BIO(3)	    OpenSSL	 OSSL_DESERIALIZER_FROM_BIO(3)

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

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:

       OSSL_DESERIALIZER_from_fp() is only available when OPENSSL_NO_STDIO is
       undefined.

DESCRIPTION
       The 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 "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().

       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.

   Functions
       OSSL_DESERIALIZER_from_bio() runs the deserialization process for the
       context ctx, with the input coming from the BIO 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
       FILE fp.

       OSSL_DESERIALIZER_CTX_add_deserializer()	populates the
       OSSL_DESERIALIZER_CTX 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 ctx.

       OSSL_DESERIALIZER_CTX_set_construct() sets the constructor 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 cleanup
       function.  This is called by 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 deser_inst	that the constructor got and
       an object reference, unpacks the	object which it	refers to, and exports
       it by creating an OSSL_PARAM(3) array that it then passes to export_cb,
       along with export_arg.

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

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

   Constructor
       A OSSL_DESERIALIZER_CONSTRUCT gets the following	arguments:

       deser_inst
	   The OSSL_DESERIALIZER_INSTANCE for the deserializer from which the
	   constructor gets its	data.

       params
	   The data produced by	the deserializer, further described below.

       construct_data
	   The pointer that was	set with
	   OSSL_DESERIALIZE_CTX_set_construct_data().

       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 params
       are:

       "data-type" (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.

       "data" (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.

       "reference" (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 deser.

       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.

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 ctx is NULL.

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

       OSSL_DESERIALIZER_INSTANCE_deserializer() returns an 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.>

SEE ALSO
       provider(7), OSSL_DESERIALIZER_CTX(3)

HISTORY
       The functions described here were added in OpenSSL 3.0.

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
       <https://www.openssl.org/source/license.html>.

3.0.0-alpha6			  2020-08-06	 OSSL_DESERIALIZER_FROM_BIO(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=OSSL_DESERIALIZER_from_bio&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help