OSSL_ENCODER_CTX_NEW_FOR_PKEY(3SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

✨ OSSL_ENCODER_CTX_NEW_FOR_PKEY ✨

okay bestie, so this is the OpenSSL man page for OSSL_ENCODER_CTX_new_for_pkey(3SSL) and its little friend group of setter functions — OSSL_ENCODER_CTX_set_cipher, OSSL_ENCODER_CTX_set_passphrase, OSSL_ENCODER_CTX_set_pem_password_cb, OSSL_ENCODER_CTX_set_passphrase_cb and OSSL_ENCODER_CTX_set_passphrase_ui. These are the Encoder routines to encode EVP_PKEYs 💖 like literally they take your key and make it into bytes you can ship somewhere.

🌸 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 the girlboss utility function that literally spawns an OSSL_ENCODER_CTX, hunts down every encoder implementation that's applicable, and sets them all up for you. So bestie, after you call this, almost all you have to do next is call stuff like OSSL_ENCODER_to_bio(3). That's it. That's the gig. 🫶

output_type decides the final output encoding, and selection lets you pick what parts of the pkey should be included in the output. output_type gets its own little section below ("Output types"), and selection is discussed in "Selections" too. iykyk.

Internally? OSSL_ENCODER_CTX_new_for_pkey() grabs the names from the EVP_KEYMGMT(3) implementation that's associated with pkey, and uses those to build a list of applicable encoder implementations. Those implementations are what process the pkey into the encoding named by output_type — with the outermost structure named by output_structure, if that's even relevant. And all of these implementations are implicitly fetched, with propquery available for finer selection. ✨

If no suitable encoder implementation is found, don't panic — OSSL_ENCODER_CTX_new_for_pkey() still creates an OSSL_ENCODER_CTX, it just has no associated encoder (OSSL_ENCODER_CTX_get_num_encoders(3) returns zero). This is actually a gift 🎀 because it helps the caller tell the difference between an error when creating the OSSL_ENCODER_CTX and a missing encoder implementation, and act accordingly.

⚠️ real talk: OSSL_ENCODER_CTX_new_for_pkey() freezes some fields of the OSSL_ENCODER_CTX. Which means these functions return an error if you call them on the resulting context: OSSL_ENCODER_CTX_add_encoder(3), OSSL_ENCODER_CTX_add_extra(3), OSSL_ENCODER_CTX_set_cleanup(3), OSSL_ENCODER_CTX_set_construct(3), OSSL_ENCODER_CTX_set_construct_data(3), OSSL_ENCODER_CTX_set_output_structure(3), OSSL_ENCODER_CTX_set_output_type(3) and OSSL_ENCODER_CTX_set_selection(3). That said, OSSL_ENCODER_CTX_set_params(3) remains available to set encoder parameters. so you're not fully locked out. 💀

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. The interpretation of that cipher_name is implementation dependent — like the implementation might implement the cipher itself directly, or through other implementations, or it might just choose to fetch it. If it supports fetching the cipher, it may use propquery as the properties to be queried for when fetching. Also cipher_name may 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. Alternatively, a pass phrase callback may be specified with the following functions. choose your fighter 💖

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. sneaky but iconic. ✨

🎀 Output types 🎀

The possible EVP_PKEY output types depend on the available implementations. no cap.

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

But heads up bestie — these are only 'hints', because the encoder implementations are free to determine what 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. the audacity. 🙈

💖 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. no in-between, periodt.

🌈 SEE ALSO 🌈

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

⭐ HISTORY ⭐

The functions described here were added in OpenSSL 3.0. she's new-ish but she's thriving.

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 vibe check bestie 🫶 this was OpenSSL 4.0.3, dated 2026-09-2, and you can find her under OSSL_ENCODER_CTX_NEW_FOR_PKEY(3SSL). go encode something iconic. 💅✨

📦 where this page comes from