OSSL_DECODER..._NEW_FOR_PKEY(3ossl)

💅 OSSL_DECODER..._NEW_FOR_PKEY ✨

okay bestie, you're reading OSSL_DECODER..._NEW_FOR_PKEY(3ossl) — yes that's the whole manual name, it's giving "my group chat name when everyone's typing at once". Anyway. This is the page for the decoder routines that decode EVP_PKEYs, so buckle up 🎀

🌸 NAME 🌸

OSSL_DECODER_CTX_new_for_pkey, OSSL_DECODER_CTX_set_passphrase, OSSL_DECODER_CTX_set_pem_password_cb, OSSL_DECODER_CTX_set_passphrase_ui, OSSL_DECODER_CTX_set_passphrase_cb — literally the decoder routines for decoding EVP_PKEYs. that's the vibe 💖

✨ SYNOPSIS ✨

#include <openssl/decoder.h>

OSSL_DECODER_CTX *
OSSL_DECODER_CTX_new_for_pkey(EVP_PKEY **pkey,
                              const char *input_type,
                              const char *input_struct,
                              const char *keytype, int selection,
                              OSSL_LIB_CTX *libctx, const char *propquery);

int OSSL_DECODER_CTX_set_passphrase(OSSL_DECODER_CTX *ctx,
                                    const unsigned char *kstr,
                                    size_t klen);
int OSSL_DECODER_CTX_set_pem_password_cb(OSSL_DECODER_CTX *ctx,
                                         pem_password_cb *cb,
                                         void *cbarg);
int OSSL_DECODER_CTX_set_passphrase_ui(OSSL_DECODER_CTX *ctx,
                                       const UI_METHOD *ui_method,
                                       void *ui_data);
int OSSL_DECODER_CTX_set_passphrase_cb(OSSL_DECODER_CTX *ctx,
                                       OSSL_PASSPHRASE_CALLBACK *cb,
                                       void *cbarg);

🦋 DESCRIPTION 🦋

OSSL_DECODER_CTX_new_for_pkey() is that girl who does all the setup work for you: she creates a OSSL_DECODER_CTX, hunts down every applicable decoder implementation, and sets them all up — so literally all you have to do next is call stuff like OSSL_DECODER_from_bio(3). main character energy from you, honestly 👑

You, the caller, can use the optional input_type, input_struct, keytype and selection to say what you expect the input to contain. And pkey must reference an EVP_PKEY * variable that will get set to the newly created EVP_PKEY on successful decoding. Heads up: that referenced variable must be initialized to NULL before you call the function. no cap, do it 🙈

Internally, OSSL_DECODER_CTX_new_for_pkey() goes looking for all the available EVP_KEYMGMT(3) implementations, and then builds a whole list of potential decoder implementations that might be able to process the encoded input into data suitable for EVP_PKEYs. All of these implementations get implicitly fetched using libctx and propquery. like, they're all pulled up to the function's party 💅

The search for decoder implementations can be limited with input_type and input_struct, which specify a starting input type and input structure. NULL is valid for both of them, and it means "the decoder implementations will figure out the input type on their own, tyvm". Those two get set with OSSL_DECODER_CTX_set_input_type(3) and OSSL_DECODER_CTX_set_input_structure(3). Peep "Input Types" and "Input Structures" below for the details 🔍

The search can also be limited with keytype and selection, which specify the expected resulting keytype and contents. NULL and zero are valid here too — they mean the decoder implementations will suss out the keytype and key contents on their own from whatever input they get. independent queens ✨

If no suitable decoder implementation is found, OSSL_DECODER_CTX_new_for_pkey() still creates a OSSL_DECODER_CTX — just with no associated decoder (OSSL_DECODER_CTX_get_num_decoders(3) returns zero). This helps the caller tell the difference between an error when creating the OSSL_ENCODER_CTX and a missing encoder implementation, so it can act accordingly.

💀 yes, the docs really do say OSSL_ENCODER_CTX and "encoder implementation" right there in the decoder page. that's what it says, we're not editing it, iykyk 🫶

OSSL_DECODER_CTX_set_passphrase() hands the implementation a pass phrase to use when decrypting the encoded private key. Alternatively, you can specify a pass phrase callback with the following functions. pick your fighter 🎀

OSSL_DECODER_CTX_set_pem_password_cb(), OSSL_DECODER_CTX_set_passphrase_ui() and OSSL_DECODER_CTX_set_passphrase_cb() set up a callback method that the implementation can use to prompt for a pass phrase — so you get to choose your preferred pass phrase callback form. These get called indirectly, through an internal OSSL_PASSPHRASE_CALLBACK(3) function.

The internal OSSL_PASSPHRASE_CALLBACK(3) function caches the pass phrase, so it can be reused in all decodings performed in the same decoding run (for example, within one OSSL_DECODER_from_bio(3) call). reuse, reduce, recycle 🧚💜

🌈 Input Types

The available input types depend on what implementations the available providers offer, and the provider documentation should have the details.

Among the known input types that OpenSSL decoder implementations offer for EVP_PKEYs are "DER", "PEM", "MSBLOB" and "PVK". See openssl-glossary(7) for further info on what these input types actually mean 🍓

🌸 Input Structures

The available input structures also depend on what implementations the available providers offer, and provider documentation should have the details. yes, same deal, go read the provider docs 💖

Among the known input structures that OpenSSL decoder implementations offer for EVP_PKEYs are "pkcs8" and "SubjectPublicKeyInfo".

OpenSSL decoder implementations also support the input structure "type-specific". That's the structure used for keys encoded according to key type specific specifications — for example, RSA keys encoded according to PKCS#1. it's giving bespoke, it's giving custom-fit 👑

⭐ Selections

selection can be any one of the values described in "Selections" in EVP_PKEY_fromdata(3). Additionally, selection can also be set to 0 to indicate that the code will auto detect the selection. let the code choose, we love a decisive algorithm 💅

🔥 RETURN VALUES 🔥

OSSL_DECODER_CTX_new_for_pkey() returns a pointer to a OSSL_DECODER_CTX, or NULL if it couldn't be created. 😭

OSSL_DECODER_CTX_set_passphrase(), OSSL_DECODER_CTX_set_pem_password_cb(), OSSL_DECODER_CTX_set_passphrase_ui() and OSSL_DECODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on failure. one or zero, slay or flop, that's the whole system 🫶

🎀 HISTORY 🎀

The functions described here were added in OpenSSL 3.0. vintage but still iconic ✨

💜 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>.

okay that's the whole page bestie, go decode something gorgeous 🌸 and for the record, this was OpenSSL 3.5.0, dated 2026-09-2 — mwah, take care, drink water, initialize your pointers to NULL 💅💖🦋

📦 where this page comes from

opensuse-leap 16.0: openssl-3-doc 3.5.0-160000.11.1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

OSSL_DECODER..._NEW_FOR_PKEY(3ossl)