PROVIDER-DECODER(7SSL)

📦

version 4.0.3 · 13 versions

🦋 provider-decoder 🦋

okay so this is the provider-decoder page from the 7SSL (OpenSSL) manual, and it's literally all about the <-> situationship between the OSSL_DECODER library and your provider's functions. buckle up bestie, we're going deep 💅

🌸 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);

quick heads up: none of those are real, callable functions — they're just vibing there to show you the signatures of functions that get handed around as function pointers inside OSSL_DISPATCH arrays. no cap. 🙈

💜 DESCRIPTION 💜

so when we say "decode" all over this page, it's a big-tent word on purpose. it includes, but is absolutely not limited to, deserialization — because individual decoders can also decode into intermediate data formats. it's giving versatility, honestly. ✨

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). that's the whole assignment. iconic, low-effort-high-impact behavior fr fr.

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. chefs kiss. 🤌

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. the way that the pipeline just... resolves itself. 😭

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 — peep "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

🎀 Names and properties 🎀

the name of an implementation should match the target type of object it decodes. for example, an implementation that decodes an RSA key should be named "RSA". likewise, an implementation that decodes DER data from PEM input should be named "DER". name-to-match, no notes. 💅

Properties, as defined in the OSSL_ALGORITHM(3) array element of each decoder implementation, can be used to further specify details about an implementation:

input — this property is used to specify what format of input the implementation can decode.

this property is mandatory. you literally cannot skip it, bestie. 🫶

OpenSSL providers recognize the following input types:

pem — an implementation with that input type decodes PEM formatted data.
der — an implementation with that input type decodes DER formatted data.
msblob — an implementation with that input type decodes MSBLOB formatted data.
pvk — an implementation with that input type decodes PVK formatted data.
raw — an implementation with that input type decodes the provided data as raw bytes. this is currently used for symmetric keys.

structure — this property is used to specify the structure that the decoded data is expected to have.

this property is optional. it's giving "if you want to". ✨

Structures currently recognised by built-in decoders:

"type-specific" — type specific structure.
"pkcs8" — structure according to the PKCS#8 specification.
"SubjectPublicKeyInfo" — encoding of public keys according to the Subject Public Key Info of RFC 5280.

the possible values of both these properties is open ended. a provider may very well specify input types and structures that libcrypto doesn't know anything about. live your truth, provider. 🦋

🍓 Subset selections 🍓

sometimes, an object has more than one subset of data that is interesting to treat separately or together. it's possible to specify what subsets are to be decoded, with a set of bits selection that are passed in an int.

this set of bits depend entirely on what kind of provider-side object is to be decoded. for example, those bits are assumed to be the same as those used with provider-keymgmt(7) (see "Key Objects" in provider-keymgmt(7)) when the object is an asymmetric keypair — e.g., OSSL_KEYMGMT_SELECT_PRIVATE_KEY if the object to be decoded is supposed to contain private key components.

OSSL_FUNC_decoder_does_selection() should tell if a particular implementation supports any of the combinations given by selection. it's the vibe check function. ✅

🧚 Context functions 🧚

OSSL_FUNC_decoder_newctx() — returns a context to be used with the rest of the functions.
OSSL_FUNC_decoder_freectx() — frees the given ctx as created by OSSL_FUNC_decoder_newctx().
OSSL_FUNC_decoder_set_ctx_params() — sets context data according to parameters from params that it recognises. unrecognised parameters should be ignored. passing NULL for params should return true.
OSSL_FUNC_decoder_settable_ctx_params() — returns a constant OSSL_PARAM(3) array describing the parameters that OSSL_FUNC_decoder_set_ctx_params() can handle.

see OSSL_PARAM(3) for further details on the parameters structure used by OSSL_FUNC_decoder_set_ctx_params() and OSSL_FUNC_decoder_settable_ctx_params(). 📚

👑 Export function 👑

when a provider-native object is created by a decoder it would be unsuitable for direct use with a foreign provider. (not me being unimportable 😭) the export function allows for exporting the object into that foreign provider if the foreign provider supports the type of the object and provides an import function.

OSSL_FUNC_decoder_export_object() should export the object of size objref_sz referenced by objref as an OSSL_PARAM(3) array and pass that into the export_cb as well as the given export_cbarg. slay, that's the interoperability moment. 🔥

🌈 Decoding functions 🌈

OSSL_FUNC_decoder_decode() should decode the data as read from the OSSL_CORE_BIO in to produce decoded data or an object to be passed as reference in an OSSL_PARAM(3) array along with possible other metadata that was decoded from the input. this OSSL_PARAM(3) array is then passed to the data_cb callback. the selection bits, if relevant, should determine what the input data should contain. the decoding functions also take an OSSL_PASSPHRASE_CALLBACK(3) function pointer along with a pointer to application data cbarg, which should be used when a pass phrase prompt is needed. 🔐

it's important to understand that the return value from this function is interpreted as follows:

True (1) — this means "carry on the decoding process", and is meaningful even though this function couldn't decode the input into anything, because there may be another decoder implementation that can decode it into something.

the data_cb callback should never be called when this function can't decode the input into anything. don't do it bestie, that's not the move. 🙈

False (0) — this means "stop the decoding process", and is meaningful when the input could be decoded into some sort of object that this function understands, but further treatment of that object results into errors that won't be possible for some other decoder implementation to get a different result.

the conditions to stop the decoding process are at the discretion of the implementation. your implementation, your rules. 🎀

💫 Decoder operation parameters 💫

there are currently no operation parameters currently recognised by the built-in decoders. (yes, zero. empty. it's giving minimalist. 💀)

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. very "hey girlie, we need the password for this thing specifically". 💖

✨ RETURN VALUES ✨

okay bestie, here's the vibe check on what these bad boys hand back 👑

OSSL_FUNC_decoder_newctx() — returns a pointer to a context, or NULL if it flopped. 😭 No context, no slay.
OSSL_FUNC_decoder_set_ctx_params() — returns 1, unless a recognised parameter was invalid or caused an error, in which case you get 0. So like, 1 = we ate, 0 = something went wrong. (Key word: recognised. Only the recognised ones can drag you down.)
OSSL_FUNC_decoder_settable_ctx_params() — returns a pointer to an array of constant OSSL_PARAM(3) elements. Iconic little array, fr fr.
OSSL_FUNC_decoder_does_selection() — returns 1 if the decoder implementation supports any of the selection bits, otherwise 0. Any single one counts, that's the rule 💅
OSSL_FUNC_decoder_decode() — returns 1 to signal that the decoding process should continue, or 0 to signal that it should stop. That's it, that's the whole mood — keep going or pull the plug 🛑

🌸 SEE ALSO 🌸

provider(7)

🦋 HISTORY 🦋

The DECODER interface was introduced in OpenSSL 3.0. So she's not new new, but she's still very much in her era ✨

🎀 COPYRIGHT 🎀

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.

and that's the whole page, bestie 🫶 you made it to the end, genuinely iconic behavior. this little scroll lived in OpenSSL 4.0.3, dated 2026-09-29 — go forth and decode responsibly 💜🌸

📦 where this page comes from

ubuntu stonking: openssl 4.0.3-1ubuntu1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms