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

FreeBSD Manual Pages

  
 
  

home | help
PROVIDER-SERIALIZER(7)		    OpenSSL		PROVIDER-SERIALIZER(7)

NAME
       provider-serializer - The SERIALIZER library <->	provider functions

SYNOPSIS
	#include <openssl/core_dispatch.h>

	/*
	 * None	of these are actual functions, but are displayed like this for
	 * the function	signatures for functions that are offered as function
	 * pointers in OSSL_DISPATCH arrays.
	 */

	/* Functions to	construct / destruct / manipulate the serializer context */
	void *OSSL_FUNC_serializer_newctx(void *provctx);
	void OSSL_FUNC_serializer_freectx(void *ctx);
	int OSSL_FUNC_serializer_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
	const OSSL_PARAM *OSSL_FUNC_serializer_settable_ctx_params(void)

	/* Functions to	serialize object data */
	int OSSL_FUNC_serializer_serialize_data(void *ctx, const OSSL_PARAM *data,
						OSSL_CORE_BIO *out,
						OSSL_PASSPHRASE_CALLBACK *cb,
						void *cbarg);
	int OSSL_FUNC_serializer_serialize_object(void *ctx, void *obj,	OSSL_CORE_BIO *out,
						  OSSL_PASSPHRASE_CALLBACK *cb,
						  void *cbarg);

DESCRIPTION
       The SERIALIZER is a generic method to serialize any set of object data
       in OSSL_PARAM(3)	array form, or any provider side object	into
       serialized form,	and write it to	the given OSSL_CORE_BIO.  If the
       caller wants to get the serialized stream to memory, it should provide
       a BIO_s_membuf(3).

       The serializer doesn't need to know more	about the OSSL_CORE_BIO
       pointer than being able to pass it to the appropriate BIO upcalls (see
       "Core functions"	in provider-base(7)).

       The serialization using the OSSL_PARAM(3) array form allows a
       serializer to be	used for data that's been exported from	another
       provider, and thereby allow them	to exist independently of each other.

       The serialization using a provider side object can only be safely used
       with provider data coming from the same provider, for example keys with
       the KEYMGMT provider.

       All "functions" mentioned here are passed as function pointers between
       libcrypto and the provider in OSSL_DISPATCH arrays via OSSL_ALGORITHM
       arrays that are returned	by the provider's provider_query_operation()
       function	(see "Provider Functions" in provider-base(7)).

       All these "functions" have a corresponding function type	definition
       named OSSL_{name}_fn, and a helper function to retrieve the function
       pointer from a OSSL_DISPATCH element named OSSL_FUNC_{name}.  For
       example,	the "function" OSSL_FUNC_serializer_serialize_data() has
       these:

	typedef	int
	    (OSSL_FUNC_serializer_serialize_data_fn)(void *provctx,
						   const OSSL_PARAM params[],
						   OSSL_CORE_BIO *out);
	static ossl_inline OSSL_FUNC_serializer_serialize_data_fn
	    OSSL_FUNC_serializer_serialize_data(const OSSL_DISPATCH *opf);

       OSSL_DISPATCH arrays are	indexed	by numbers that	are provided as	macros
       in openssl-core_dispatch.h(7), as follows:

	OSSL_FUNC_serializer_newctx		 OSSL_FUNC_SERIALIZER_NEWCTX
	OSSL_FUNC_serializer_freectx		 OSSL_FUNC_SERIALIZER_FREECTX
	OSSL_FUNC_serializer_set_ctx_params	 OSSL_FUNC_SERIALIZER_SET_CTX_PARAMS
	OSSL_FUNC_serializer_settable_ctx_params OSSL_FUNC_SERIALIZER_SETTABLE_CTX_PARAMS

	OSSL_FUNC_serializer_serialize_data	 OSSL_FUNC_SERIALIZER_SERIALIZE_DATA
	OSSL_FUNC_serializer_serialize_object	 OSSL_FUNC_SERIALIZER_SERIALIZE_OBJECT

   Names and properties
       The name	of an implementation should match the type of object it
       handles.	 For example, an implementation	that serializes	an RSA key
       should be named accordingly.

       To be able to specify exactly what serialization	format and what	type
       of data a serializer implementation is expected to handle, two
       additional properties may be given:

       format
	   This	property is used to specify what kind of output	format the
	   implementation produces.  Currently known formats are:

	   text
	       An implementation with that format property value outputs human
	       readable	text, making that implementation suitable for "-text"
	       output in diverse openssl(1) commands.

	   pem An implementation with that format property value outputs PEM
	       formatted data.

	   der An implementation with that format property value outputs DER
	       formatted data.

       type
	   With	objects	that have multiple purposes, this can be used to
	   specify the purpose type.  The currently known use cases are
	   asymmetric keys and key parameters, where the type can be one of:

	   private
	       An implementation with that format property value outputs a
	       private key.

	   public
	       An implementation with that format property value outputs a
	       public key.

	   parameters
	       An implementation with that format property value outputs key
	       parameters.

       The possible values of both these properties is open ended.  A provider
       may very	well specify other formats that	libcrypto doesn't know
       anything	about.

   Context functions
       OSSL_FUNC_serializer_newctx() returns a context to be used with the
       rest of the functions.

       OSSL_FUNC_serializer_freectx() frees the	given ctx, if it was created
       by OSSL_FUNC_serializer_newctx().

       OSSL_FUNC_serializer_set_ctx_params() sets context data according to
       parameters from params that it recognises.  Unrecognised	parameters
       should be ignored.

       OSSL_FUNC_serializer_settable_ctx_params() returns a constant
       OSSL_PARAM array	describing the parameters that
       OSSL_FUNC_serializer_set_ctx_params() can handle.

       See OSSL_PARAM(3) for further details on	the parameters structure used
       by OSSL_FUNC_serializer_set_ctx_params()	and
       OSSL_FUNC_serializer_settable_ctx_params().

   Serializing functions
       OSSL_FUNC_serializer_serialize_data() should take an array of
       OSSL_PARAM, data, and if	it contains the	data necessary for the object
       type that the implementation handles, it	should output the object in
       serialized form to the OSSL_CORE_BIO.

       OSSL_FUNC_serializer_serialize_object() should take a pointer to	an
       object that it knows intimately,	and output that	object in serialized
       form to the OSSL_CORE_BIO.  The caller must ensure that this function
       is called with a	pointer	that the provider of this function is familiar
       with.  It is not	suitable to use	with object pointers coming from other
       providers.

       Both serialization functions also take an OSSL_PASSPHRASE_CALLBACK
       function	pointer	along with a pointer to	application data cbarg,	which
       should be used when a pass phrase prompt	is needed.

   Serializer parameters
       Parameters currently recognised by built-in serializers are as follows:

       "cipher"	(OSSL_SERIALIZER_PARAM_CIPHER) <UTF8 string>
	   The name of the encryption cipher to	be used	when generating
	   encrypted serialization.  This is used when serializing private
	   keys, as well as other objects that need protection.

	   If this name	is invalid for the serialization implementation, the
	   implementation should refuse	to perform the serialization, i.e.
	   OSSL_FUNC_serializer_serialize_data() and
	   OSSL_FUNC_serializer_serialize_object() should return an error.

       "properties" (OSSL_SERIALIZER_PARAM_PROPERTIES) <UTF8 string>
	   The properties to be	queried	when trying to fetch the algorithm
	   given with the "cipher" parameter.  This must be given together
	   with	the "cipher" parameter to be considered	valid.

	   The serialization implementation isn't obligated to use this	value.
	   However, it is recommended that implementations that	do not handle
	   property strings return an error on receiving this parameter	unless
	   its value NULL or the empty string.

       "passphrase" (OSSL_SERIALIZER_PARAM_PASS) <octet	string>
	   A pass phrase provided by the application.  When this is given, the
	   built-in serializers	will not attempt to use	the passphrase
	   callback.

       Parameters currently recognised by the built-in pass phrase callback:

       "info" (OSSL_PASSPHRASE_PARAM_INFO) <UTF8 string>
	   A string of information that	will become part of the	pass phrase
	   prompt.  This could be used to give the user	information on what
	   kind	of object it's being prompted for.

RETURN VALUES
       OSSL_FUNC_serializer_newctx() returns a pointer to a context, or	NULL
       on failure.

       OSSL_FUNC_serializer_set_ctx_params() returns 1,	unless a recognised
       parameters was invalid or caused	an error, for which 0 is returned.

       OSSL_FUNC_serializer_settable_ctx_params() returns a pointer to an
       array of	constant OSSL_PARAM elements.

       OSSL_FUNC_serializer_serialize_data() and
       OSSL_FUNC_serializer_serialize_object() return 1	on success, or 0 on
       failure.

SEE ALSO
       provider(7)

HISTORY
       The SERIALIZER interface	was introduced in OpenSSL 3.0.

COPYRIGHT
       Copyright 2019-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		PROVIDER-SERIALIZER(7)

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=provider-serializer&sektion=7&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help