NAME¶

provider-decoder - The OSSL_DECODER 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.
  */
 /* Decoder parameter accessor and descriptor */
 const OSSL_PARAM *OSSL_FUNC_decoder_gettable_params(void *provctx);
 int OSSL_FUNC_decoder_get_params(OSSL_PARAM params[]);
 /* Functions to construct / destruct / manipulate the decoder context */
 void *OSSL_FUNC_decoder_newctx(void *provctx);
 void OSSL_FUNC_decoder_freectx(void *ctx);
 const OSSL_PARAM *OSSL_FUNC_decoder_settable_ctx_params(void *provctx);
 int OSSL_FUNC_decoder_set_ctx_params(void *ctx, const OSSL_PARAM params[]);
 /* Functions to check selection support */
 int OSSL_FUNC_decoder_does_selection(void *provctx, int selection);
 /* Functions to decode object data */
 int OSSL_FUNC_decoder_decode(void *ctx, OSSL_CORE_BIO *in,
                              int selection,
                              OSSL_CALLBACK *data_cb, void *data_cbarg,
                              OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
 /* Functions to export a decoded object */
 int OSSL_FUNC_decoder_export_object(void *ctx,
                                       const void *objref, size_t objref_sz,
                                       OSSL_CALLBACK *export_cb,
                                       void *export_cbarg);

DESCRIPTION¶

The term "decode" is used throughout this manual. This includes but is not limited to deserialization as individual decoders can also do decoding into intermediate data formats.

The DECODER operation is a generic method to create a provider-native object reference or intermediate decoded data from an encoded form read from the given OSSL_CORE_BIO. If the caller wants to decode data from memory, it should provide a BIO_s_mem(3) BIO. The decoded data or object reference is passed along with eventual metadata to the metadata_cb as OSSL_PARAM(3) parameters.

The decoder 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 DECODER implementation may be part of a chain, where data is passed from one to the next. For example, there may be an implementation to decode an object from PEM to DER, and another one that decodes DER to a provider-native object.

The last decoding step in the decoding chain is usually supposed to create a provider-native object referenced by an object reference. To import that object into a different provider the OSSL_FUNC_decoder_export_object() can be called as the final step of the decoding process.

All "functions" mentioned here are passed as function pointers between libcrypto and the provider in OSSL_DISPATCH(3) arrays via OSSL_ALGORITHM(3) 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_FUNC_{name}_fn, and a helper function to retrieve the function pointer from an OSSL_DISPATCH(3) element named OSSL_FUNC_{name}. For example, the "function" OSSL_FUNC_decoder_decode() has these:

 typedef int
     (OSSL_FUNC_decoder_decode_fn)(void *ctx, OSSL_CORE_BIO *in,
                                   int selection,
                                   OSSL_CALLBACK *data_cb, void *data_cbarg,
                                   OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
 static ossl_inline OSSL_FUNC_decoder_decode_fn*
     OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf);

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

 OSSL_FUNC_decoder_get_params          OSSL_FUNC_DECODER_GET_PARAMS
 OSSL_FUNC_decoder_gettable_params     OSSL_FUNC_DECODER_GETTABLE_PARAMS
 OSSL_FUNC_decoder_newctx              OSSL_FUNC_DECODER_NEWCTX
 OSSL_FUNC_decoder_freectx             OSSL_FUNC_DECODER_FREECTX
 OSSL_FUNC_decoder_set_ctx_params      OSSL_FUNC_DECODER_SET_CTX_PARAMS
 OSSL_FUNC_decoder_settable_ctx_params OSSL_FUNC_DECODER_SETTABLE_CTX_PARAMS
 OSSL_FUNC_decoder_does_selection      OSSL_FUNC_DECODER_DOES_SELECTION
 OSSL_FUNC_decoder_decode              OSSL_FUNC_DECODER_DECODE
 OSSL_FUNC_decoder_export_object       OSSL_FUNC_DECODER_EXPORT_OBJECT

RETURN VALUES¶

OSSL_FUNC_decoder_newctx() returns a pointer to a context, or NULL on failure.

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

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

OSSL_FUNC_decoder_does_selection() returns 1 if the decoder implementation supports any of the selection bits, otherwise 0.

OSSL_FUNC_decoder_decode() returns 1 to signal that the decoding process should continue, or 0 to signal that it should stop.

SEE ALSO¶

provider(7)

HISTORY¶

The DECODER interface was introduced in OpenSSL 3.0.

COPYRIGHT¶

Copyright 2019-2023 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>.