OSSL_DECODER..._NEW_FOR_PKEY(3ossl)

📦
version 3.5.9 · 8 versions
, in fedora 43, fedora 44

🌸 NAME 🌸

welcome to the OSSL_DECODER..._NEW_FOR_PKEY(3ossl) page, bestie 💖 this is the 3ossl manual and it's all about the decoder glow-up that turns raw encoded bytes into a whole EVP_PKEY 👑

the icons we're stanning today:

  • 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

and together they're the Decoder routines to decode EVP_PKEYs ✨ periodt.

✨ SYNOPSIS ✨

okay so first you gotta invite the header in, like:

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

slay, that's the whole cast 💅

💫 DESCRIPTION 💫

OSSL_DECODER_CTX_new_for_pkey() is the little utility function that does the main character work: it creates an OSSL_DECODER_CTX, finds all the applicable decoder implementations, and sets them all up for you 🫶 so literally the only thing the caller has to do next is call functions like OSSL_DECODER_from_bio(3). that's it. that's the vibe.

the caller may use the optional input_type, input_struct, keytype and selection to specify what the input is expected to contain 👀 and heads up: pkey must reference an EVP_PKEY * variable that will be set to the newly created EVP_PKEY on successful decoding. the referenced variable must be initialized to NULL before calling the function.

⚠️ not me forgetting to set it to NULL... don't be like me bestie, initialize it or the whole thing goes sideways 💀

internally, OSSL_DECODER_CTX_new_for_pkey() searches for all available EVP_KEYMGMT(3) implementations, and then builds a list of all potential decoder implementations that may be able to process the encoded input into data suitable for EVP_PKEYs. all of these implementations are implicitly fetched using libctx and propquery 🌈

the search of decoder implementations can be limited with input_type and input_struct, which specifies a starting input type and input structure. NULL is valid for both of them, and it signifies that the decoder implementations will find out the input type on their own (independent queen behavior ✨). they are set with OSSL_DECODER_CTX_set_input_type(3) and OSSL_DECODER_CTX_set_input_structure(3). see "Input Types" and "Input Structures" below for further information 👇

the search can also be limited with keytype and selection, which specifies the expected resulting keytype and contents. NULL and zero are valid, and they signify that the decoder implementations will find out the keytype and key contents on their own from the input they get.

if no suitable decoder implementation is found, OSSL_DECODER_CTX_new_for_pkey() still creates an OSSL_DECODER_CTX, but with no associated decoder (OSSL_DECODER_CTX_get_num_decoders(3) returns zero). this helps the caller to distinguish between an error when creating the OSSL_ENCODER_CTX and missing encoder implementation, and allows it to act accordingly 🧠✨

📌 note that OSSL_DECODER_CTX_new_for_pkey() finalises the OSSL_DECODER_CTX; after that, the OSSL_DECODER_CTX_set_* and OSSL_DECODER_CTX_add_* functions described in OSSL_DECODER_CTX(3) shouldn't be called. like, it's done, it's sealed, move on bestie 🙈

OSSL_DECODER_CTX_set_passphrase() gives the implementation a pass phrase to use when decrypting the encoded private key 🔐 alternatively, a pass phrase callback may be specified with the following functions 👇

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, giving the caller the choice of preferred pass phrase callback form 💖 these are called indirectly, through an internal OSSL_PASSPHRASE_CALLBACK(3) function.

the internal OSSL_PASSPHRASE_CALLBACK(3) function caches the pass phrase, to be reused in all decodings that are performed in the same decoding run (for example, within one OSSL_DECODER_from_bio(3) call). efficient. iconic. obsessed 🌟

🦋 Input Types 🦋

available input types depend on the implementations that available providers offer, and 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 information on what these input types mean 💅

🎀 Input Structures 🎀

available input structures depend on the implementations that available providers offer, and provider documentation should have the details 📚 (yes, same energy as above, the providers are the ones holding the lore)

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". this is the structure used for keys encoded according to key type specific specifications. for example, RSA keys encoded according to PKCS#1 👑

🌈 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 🤖✨

💖 RETURN VALUES 💖

  • OSSL_DECODER_CTX_new_for_pkey() returns a pointer to an 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. no in-between, it's giving binary 💅

👀 SEE ALSO 👀

provider(7), OSSL_DECODER(3), OSSL_DECODER_CTX(3) — go read these too, they're the supporting cast 🫶

📜 HISTORY 📜

the functions described here were added in OpenSSL 3.0. glow-up era ✨

Copyright 2020-2024 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>.

okay that's the whole page bestie, ily, go decode something 💜 this was the OpenSSL 3.5.9 manual page, dated 2026-09-2, and yes the version and date are part of the lore so I'm mentioning them like a good host 🎀 mwah, bye 👑

📦 where this page comes from