PROVIDER-DECODER(7ossl)

💅 PROVIDER-DECODER 💅

okay bestie, buckle up — this is the provider-decoder page from the OpenSSL manual (7ossl), and it's literally the whole scoop on the OSSL_DECODER library ↔ provider functions situation. it's giving "backstage pass to how decoding actually works" ✨

✨ NAME ✨

provider-decoder — the OSSL_DECODER library ↔ provider functions. that's the whole vibe, no cap 🫶

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

like, none of these are actual functions bestie — they're just displayed in this shape so you can see the signatures of the function pointers that live inside OSSL_DISPATCH arrays 💖

🌸 DESCRIPTION 🌸

so, the word "decode" gets used all over this manual, and it's a big umbrella term. it covers deserialization, sure, but that's not all — individual decoders can also decode into intermediate data formats. so don't pigeonhole it 🦋

the DECODER operation is the generic way to make a provider-native object reference, or intermediate decoded data, out of an encoded form that gets read from the given OSSL_CORE_BIO. if the caller wants to decode data straight out of memory, they should hand over a BIO_s_mem(3) BIO — easy. the decoded data, or the object reference, gets passed along with whatever metadata came with it to the metadata_cb as OSSL_PARAM(3) parameters ✨

the decoder is not out here needing to know secrets about the OSSL_CORE_BIO pointer — literally all it needs is to be able to pass that pointer to the appropriate BIO upcalls (peep "Core functions" in provider-base(7), iykyk).

a DECODER implementation can be part of a chain, where the data just gets handed from one to the next, relay-race style 🏃‍♀️ for example, you might have one implementation that decodes an object from PEM to DER, and then another one that decodes DER into a provider-native object. teamwork, honestly.

the last decoding step in the chain is usually supposed to be the one that creates a provider-native object, referenced by an object reference. and to import that object into a different provider, you can call OSSL_FUNC_decoder_export_object() as the final step of the decoding process 👑

okay and — every "function" mentioned on this page is passed as a function pointer between libcrypto and the provider, inside OSSL_DISPATCH(3) arrays, via OSSL_ALGORITHM(3) arrays that come back from the provider's provider_query_operation() function (again: "Provider Functions" in provider-base(7), go look 💜).

each of these "functions" has a matching function type definition named OSSL_FUNC_{name}_fn, plus a helper function that fetches the function pointer out of an OSSL_DISPATCH(3) element, named OSSL_FUNC_{name}. for example, the "function" OSSL_FUNC_decoder_decode() has these two besties:

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), like so:

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 🦋

so the name of an implementation should match the target type of the object it decodes. like, an implementation that decodes an RSA key should be named "RSA". and an implementation that decodes DER data from PEM input should be named "DER". naming is literally the whole personality here 💅

properties, as defined in the OSSL_ALGORITHM(3) array element of each decoder implementation, can be used to get more specific about what an implementation actually does:

• input — this property says what format of input the implementation can decode. this property is mandatory, so don't skip it 🙈 OpenSSL providers recognise 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.
• structure — this property says what structure the decoded data is expected to have. this property is optional ✨ 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 are open ended, fr fr. a provider may absolutely specify input types and structures that libcrypto doesn't know a single thing about. main character energy 🎀

💀 Subset selections 💀

sometimes an object has more than one subset of data that's interesting to treat separately (or together, why not). it's possible to specify which subsets get decoded, using a set of bits — a selection — that gets passed in an int.

and this set of bits depends entirely on what kind of provider-side object is being decoded. for example, those bits are assumed to be the same ones used with provider-keymgmt(7) (peep "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 you whether a particular implementation supports any of the combinations given by selection. simple as that 🫶

🧚 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 gets created by a decoder, it would be unsuitable for direct use with a foreign provider. rude, honestly. but 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. so it's a whole compatibility slay 🌈

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 ✨

⭐ 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 a reference in an OSSL_PARAM(3) array, along with any other metadata that was decoded from the input. that OSSL_PARAM(3) array then gets passed to the data_cb callback. the selection bits, if relevant, should determine what the input data should contain. and 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 🔑

now, it's important to get how the return value from this function is interpreted, so pay attention bestie:

• True (1) — this means "carry on the decoding process", and it's 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. 🫶
• False (0) — this means "stop the decoding process", and it's 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. so like, stopping is the honest move 💀

the conditions to stop the decoding process are at the discretion of the implementation. no rules, just vibes (but consistent ones, please).

🍓 Decoder operation parameters 🍓

there are currently no operation parameters currently recognised by the built-in decoders. none. zero. empty set 💅

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 info on what kind of object it's being prompted for. so thoughtful 🥺

👑 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, in which case 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) — that's it, that's the list 💖

🎀 HISTORY 🎀

the DECODER interface was introduced in OpenSSL 3.0 ✨

🎀 COPYRIGHT 🎀

okay bestie, legal era 💅 this part is the boring-but-important one, but we're gonna get through it together.

Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved. ✨

This file is licensed under the Apache License 2.0 (that's "the License" for short, iykyk). So here's the vibe check on what that actually means for you:

• You may not use this file except in compliance with the License 🫶 no cap, that's the whole rule
• Wanna read the whole thing? You can grab a copy of the License in the file LICENSE in the source distribution
• Or just pull it up online at <https://www.openssl.org/source/license.html> 🌐

---

and that's the page, bestie! 🦋 you made it to the end, so proud of you fr fr 💖

cute little sign-off: this page ships with OpenSSL 3.5.0 and the date stamped on it is 2026-09-25. iconic. periodt. 🎀⭐