OSSL_ENCODER..._NEW_FOR_PKEY(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

✨ OSSL_ENCODER..._NEW_FOR_PKEY ✨

okay so bestie, this is one of those OpenSSL 3ossl manual pages, and today we're talking about the encoder squad — the little gang of functions that take your EVP_PKEY and turn it into actual bytes you can shove in a file. it's giving "glow-up for your key" honestly 💅

🌸 NAME 🌸

OSSL_ENCODER_CTX_new_for_pkey, OSSL_ENCODER_CTX_set_cipher, OSSL_ENCODER_CTX_set_passphrase, OSSL_ENCODER_CTX_set_pem_password_cb, OSSL_ENCODER_CTX_set_passphrase_cb, OSSL_ENCODER_CTX_set_passphrase_ui — these are the encoder routines that encode EVP_PKEYs. that's the whole job. iconic.

🎀 SYNOPSIS 🎀

like, copy this exactly bestie, no typos:

#include <openssl/encoder.h>

OSSL_ENCODER_CTX *
OSSL_ENCODER_CTX_new_for_pkey(const EVP_PKEY *pkey, int selection,
                              const char *output_type,
                              const char *output_structure,
                              const char *propquery);

int OSSL_ENCODER_CTX_set_cipher(OSSL_ENCODER_CTX *ctx,
                                const char *cipher_name,
                                const char *propquery);
int OSSL_ENCODER_CTX_set_passphrase(OSSL_ENCODER_CTX *ctx,
                                    const unsigned char *kstr,
                                    size_t klen);
int OSSL_ENCODER_CTX_set_pem_password_cb(OSSL_ENCODER_CTX *ctx,
                                         pem_password_cb *cb, void *cbarg);
int OSSL_ENCODER_CTX_set_passphrase_ui(OSSL_ENCODER_CTX *ctx,
                                       const UI_METHOD *ui_method,
                                       void *ui_data);
int OSSL_ENCODER_CTX_set_passphrase_cb(OSSL_ENCODER_CTX *ctx,
                                       OSSL_PASSPHRASE_CALLBACK *cb,
                                       void *cbarg);

🦋 DESCRIPTION 🦋

okay so the main character here is OSSL_ENCODER_CTX_new_for_pkey(). it's a utility function, and it's lowkey doing a LOT: it creates an OSSL_ENCODER_CTX, finds all the applicable encoder implementations, and sets them all up for you. so basically after you call it, almost all you gotta do next is call stuff like OSSL_ENCODER_to_bio(3) and you're done. slay 💖

output_type decides the final output encoding. selection lets you choose what parts of the pkey should be in the output. output_type gets its own little section below under "Output types", and selection is elaborated on in "Selections". iykyk.

internally — and this is the nerdy part, but stay with me — OSSL_ENCODER_CTX_new_for_pkey() grabs the names from the EVP_KEYMGMT(3) implementation associated with pkey, and uses them to build a list of applicable encoder implementations. those implementations process pkey into the encoding named by output_type, with the outermost structure named by output_structure if that's relevant. all of these implementations are implicitly fetched, and you pass propquery for finer selection. fancy, right? ✨

and here's the cute bit: if no suitable encoder implementation is found, OSSL_ENCODER_CTX_new_for_pkey() still creates an OSSL_ENCODER_CTX, just with no associated encoder (meaning OSSL_ENCODER_CTX_get_num_encoders(3) returns zero). this is on purpose! it helps the caller tell the difference between "error when creating the OSSL_ENCODER_CTX" and "missing encoder implementation" so they can act accordingly. thoughtful queen behavior 👑

OSSL_ENCODER_CTX_set_cipher() tells the implementation what cipher should be used to encrypt encoded keys. the cipher is given by name, cipher_name. how that cipher_name is interpreted is implementation dependent — the implementation might implement the cipher directly itself, or by other implementations, or it might choose to fetch it. if the implementation supports fetching the cipher, then it may use propquery as properties to be queried for when fetching. and cipher_name may also be NULL, which results in unencrypted encoding. (bestie, note that. unencrypted. 🙈)

OSSL_ENCODER_CTX_set_passphrase() gives the implementation a pass phrase to use when encrypting the encoded private key. alternatively, you can specify a pass phrase callback with the following functions.

OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui() and OSSL_ENCODER_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. indirect communication, very mysterious of them 🧚

🌈 Output types 🌈

so the possible EVP_PKEY output types depend on what implementations you have available. OpenSSL has built-in implementations for these three:

💜 Selections 💜

selection can be any one of the values described in "Selections" in EVP_PKEY_fromdata(3).

and real talk: these are only hints 👀 because the encoder implementations are free to determine what actually makes sense to include in the output, and that may depend on the desired output. for example, an EC key in a PKCS#8 structure doesn't usually include the public key. so yeah. hints. not promises. 😭

🔥 RETURN VALUES 🔥

OSSL_ENCODER_CTX_new_for_pkey() returns a pointer to an OSSL_ENCODER_CTX, or NULL if it couldn't be created. (sad but true.)

OSSL_ENCODER_CTX_set_cipher(), OSSL_ENCODER_CTX_set_passphrase(), OSSL_ENCODER_CTX_set_pem_password_cb(), OSSL_ENCODER_CTX_set_passphrase_ui() and OSSL_ENCODER_CTX_set_passphrase_cb() all return 1 on success, or 0 on failure. classic. 💀

👑 SEE ALSO 👑

provider(7), OSSL_ENCODER(3), OSSL_ENCODER_CTX(3) — go read these next bestie, they're the supporting cast 🫶

⭐ HISTORY ⭐

the functions described here were added in OpenSSL 3.0. vintage-ish but make it modern ✨

Copyright 2019-2022 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 🎀 this one's from OpenSSL version 3.5.0, dated 2026-09-2, so keep that in mind when you cite it — periodt 💅🌈

📦 where this page comes from