OSSL_ENCODER..._NEW_FOR_PKEY(3ossl)

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

💖 OSSL_ENCODER..._NEW_FOR_PKEY 💖

okay bestie, welcome to the 3ossl manual, this one's about encoding EVP_PKEYs 💅

✨ 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 — encoder routines to encode EVP_PKEYs 🎀

🌸 SYNOPSIS 🌸

#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 🦋

So OSSL_ENCODER_CTX_new_for_pkey() is basically the little utility that does the heavy lifting for you, fr fr. It creates an OSSL_ENCODER_CTX, sniffs out all the applicable encoder implementations, and sets them up — so once you've called it, almost all you have left to do is call stuff like OSSL_ENCODER_to_bio(3). Iconic, honestly. ✨

The output_type decides the final output encoding, and selection lets you pick which parts of the pkey actually get included in the output. output_type gets its own lil deep-dive down in "Output types", and selection is explained in "Selections". 👑

Under the hood, OSSL_ENCODER_CTX_new_for_pkey() takes the names from the EVP_KEYMGMT(3) implementation that's associated with pkey and uses them to build a whole list of applicable encoder implementations. Those get used to process the pkey into the encoding named by output_type, with the outermost structure named by output_structure — if that's even relevant. All of these implementations get implicitly fetched, with propquery there for finer selection. 🧚

And listen, if no suitable encoder implementation is found, OSSL_ENCODER_CTX_new_for_pkey() still creates an OSSL_ENCODER_CTX — just with no associated encoder (so OSSL_ENCODER_CTX_get_num_encoders(3) returns zero). That's on purpose, bestie: it lets the caller tell the difference between an error while creating the OSSL_ENCODER_CTX and a straight-up missing encoder implementation, so it can act accordingly. 🫶

Heads up: OSSL_ENCODER_CTX_new_for_pkey() finalises the OSSL_ENCODER_CTX. After that, the OSSL_ENCODER_CTX_set_* and OSSL_ENCODER_CTX_add_* functions described in OSSL_ENCODER_CTX(3) should not be called. No takebacks. 💀

OSSL_ENCODER_CTX_set_cipher() tells the implementation which cipher should be used to encrypt encoded keys. The cipher is given by name, cipher_name. How that cipher_name gets interpreted is implementation dependent — the implementation might implement the cipher itself directly, or through other implementations, or it might just choose to fetch it. If it does support fetching the cipher, then it may use propquery as the properties to query for while fetching. Oh, and cipher_name can also be NULL, which results in unencrypted encoding. 🙈

OSSL_ENCODER_CTX_set_passphrase() hands the implementation a pass phrase to use when encrypting the encoded private key. Or, 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 their preferred pass phrase callback form. These get called indirectly, through an internal OSSL_PASSPHRASE_CALLBACK(3) function. 🌈

🎀 Output types 🎀

The possible EVP_PKEY output types depend on the implementations you've got available. (vibe check: no implementations, no output types, iykyk 😭)

OpenSSL has built-in implementations for these output types:

💖 Selections 💖

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

These are only 'hints' though, because the encoder implementations are free to decide 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. Slay. 💅

⭐ RETURN VALUES ⭐

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

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. Simple as that, periodt. ✨

👑 SEE ALSO 👑

provider(7), OSSL_ENCODER(3), OSSL_ENCODER_CTX(3)

🌈 HISTORY 🌈

The functions described here were added in OpenSSL 3.0. So yes, they're giving modern, they're giving new era. 🦋

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, you ate that 🫶 this was 3.5.9, dated 2026-09-2, and it's the OSSL_ENCODER..._NEW_FOR_PKEY(3ossl) manual — now go encrypt something responsibly 💖🌸✨

📦 where this page comes from