OSSL_ENCODER..._NEW_FOR_PKEY(3ossl)

📦
version 15.1 · 2 versions
, in freebsd 15.1

💅 OSSL_ENCODER..._NEW_FOR_PKEY 💅

okay bestie, welcome to the 3ossl corner of the OpenSSL manual — this one's all about the encoder routines that turn your EVP_PKEYs into actual bytes. no cap, it's a good one.

✨ 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 — the encoder girlies that encode your 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 🌸

OSSL_ENCODER_CTX_new_for_pkey() is that girl ✨ it's a utility function that creates an OSSL_ENCODER_CTX, finds all the applicable encoder implementations and sets them up for you — so basically almost all you have to do next is call functions like OSSL_ENCODER_to_bio(3). like, the work is done, bestie.

output_type determines the final output encoding, and selection is what you use to pick which parts of the pkey get included in the output. output_type gets its own whole moment in "Output types" below, and selection is further described in "Selections" (also below, obviously 💅).

Internally, OSSL_ENCODER_CTX_new_for_pkey() uses the names from the EVP_KEYMGMT(3) implementation associated with pkey to build a 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 relevant. all these implementations are implicitly fetched, with propquery for finer selection. iykyk 🦋

If no suitable encoder implementation is found, OSSL_ENCODER_CTX_new_for_pkey() still creates an OSSL_ENCODER_CTX, but with no associated encoder (OSSL_ENCODER_CTX_get_num_encoders(3) returns zero). and honestly? that's a feature. it helps you distinguish between an error when creating the OSSL_ENCODER_CTX and a missing encoder implementation, so you can act accordingly. not me being grateful for good error design 😭

⚠️ heads up bestie: 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) shouldn't be called. like, don't. periodt. 💀

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. the interpretation of that cipher_name is implementation dependent — the implementation may implement the cipher directly itself, or by other implementations, or it may choose to fetch it. if the implementation supports fetching the cipher, then it may use propquery as properties to be queried for when fetching. cipher_name may also be NULL, which will result in unencrypted encoding. (lowkey the no-lock era 🔓)

OSSL_ENCODER_CTX_set_passphrase() gives the implementation a pass phrase to use when encrypting the encoded private key. alternatively, a pass phrase callback may be specified 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. very demure, very indirect 🎀

🌈 Output types 🌈

the possible EVP_PKEY output types depend on the available implementations. (so like, vibe check your providers first, bestie.)

OpenSSL has built in implementations for the following output types:

  • "TEXT" — the output is a human readable description of the key. EVP_PKEY_print_private(3), EVP_PKEY_print_public(3) and EVP_PKEY_print_params(3) use this for their output. it's giving "explain it to me like I'm five" energy 🫶
  • "DER" — the output is the DER encoding of the selection of the pkey. crunchy binary moment 🔥
  • "PEM" — the output is the selection of the pkey in PEM format. the iconic base64-with-fences look 👑

🦋 Selections 🦋

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

these are only 'hints' — since the encoder implementations are free to determine what makes sense to include in the output, and this may depend on the desired output. for example, an EC key in a PKCS#8 structure doesn't usually include the public key. so like, don't come for the encoder if it leaves something out, it's just doing what makes sense 💅

⭐ 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 girl hours 😭)

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, no notes 💖

🔥 SEE ALSO 🔥

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

go read those next, bestie, they're the whole friend group 🫶

👑 HISTORY 👑

the functions described here were added in OpenSSL 3.0. so they're not new-new, but they're still iconic.

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 was OpenSSL 3.5.6, dated 2026-04-0, and I'm obsessed with you for reading all the way to the end. slay, hydrate, and go encode something cute 🌸💅✨

📦 where this page comes from