OSSL_DECODER_CTX_NEW_FOR_PKEY(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

🌸 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 — decoder routines to decode EVP_PKEYs

okay so this is the 3SSL manual page, bestie, and it's all about the glow-up where raw encoded key bytes become a whole EVP_PKEY. 💅

✨ 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 the little utility function with main character energy: it creates an OSSL_DECODER_CTX, hunts down every applicable decoder implementation, and sets them all up for you. So after you call it, literally all you have to do next is call functions like OSSL_DECODER_from_bio(3). That's it. That's the whole job. 🫶

You can use the optional input_type, input_struct, keytype and selection to tell it what you expect the input to contain. And here's the tea: pkey must reference an EVP_PKEY * variable that gets set to the newly created EVP_PKEY on successful decoding. That referenced variable must be initialized to NULL before calling the function — no cap, do it. 🙈

Under the hood, OSSL_DECODER_CTX_new_for_pkey() goes looking for all available EVP_KEYMGMT(3) implementations, then builds up a list of every potential decoder implementation that might be able to turn that encoded input into data suitable for EVP_PKEYs. All of these implementations are implicitly fetched using libctx and propquery. Lowkey elegant.

The search can be narrowed down 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". They 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 more. 👀

You can also narrow the search with keytype and selection, which specify the expected resulting keytype and contents. NULL and zero are valid here too, and they signify that the decoder implementations will work out the keytype and key contents on their own from the input they get. So independent of you. Slay.

If no suitable decoder implementation is found, OSSL_DECODER_CTX_new_for_pkey() still creates an OSSL_DECODER_CTX, just with no associated decoder (OSSL_DECODER_CTX_get_num_decoders(3) returns zero). This is actually so helpful — it lets the caller tell the difference between "error when creating the OSSL_DECODER_CTX" and "missing decoder implementation", and act accordingly. 🔥

There's a little orphan sentence in the source that just says: and OSSL_DECODER_CTX_set_selection(), and honestly bestie, it's giving stray thought. We're leaving it exactly where we found it. 💀

Heads up: OSSL_DECODER_CTX_new_for_pkey() freezes some fields of the OSSL_DECODER_CTX. So as a result, these functions all return an error if you call them on the resulting context:

But OSSL_DECODER_CTX_set_params(3) remains available to set decoder parameters, so you're not fully locked out. 😌

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.

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 their preferred pass phrase callback form. Iconic, honestly. These get called indirectly, through an internal OSSL_PASSPHRASE_CALLBACK(3) function.

And that internal OSSL_PASSPHRASE_CALLBACK(3) function caches the pass phrase, so it can be reused in all the decodings performed in the same decoding run (like, for example, within one OSSL_DECODER_from_bio(3) call). Efficiency queen. 👑

🌈 Input Types

Which input types you get depends on what the available providers' implementations offer, so check the provider documentation for the details, bestie.

Among the known input types that OpenSSL decoder implementations offer for EVP_PKEYs are:

  • "DER"
  • "PEM"
  • "MSBLOB"
  • "PVK"

See openssl-glossary(7) for further info on what these input types actually mean. ✨

🎀 Input Structures

Same deal — available input structures depend on what the available providers' implementations offer, and provider documentation should have the details.

Among the known input structures that OpenSSL decoder implementations offer for EVP_PKEYs are:

  • "pkcs8"
  • "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. 💖

🧚 Selections

selection can be any one of the values described in "Selections" in EVP_PKEY_fromdata(3). And on top of that, selection can also be set to 0 to indicate that the code will auto-detect the selection. Letting the code decide? Very demure, very mindful.

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

⭐ SEE ALSO ⭐

provider(7), OSSL_DECODER(3), OSSL_DECODER_CTX(3), OSSL_DECODER_CTX_set_params(3).

🌸 HISTORY 🌸

The functions described here were added in OpenSSL 3.0. Baby's first release, we love to see it. 🎀

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

and that's the whole page bestie, from the OpenSSL 4.0.3 era, dated 2026-09-2 — 3SSL gang forever, mwah 💖✨🦋

📦 where this page comes from