EVP_PKEY_CTX_NEW(3SSL)

📦
version 4.0.3 · 14 versions
, in ubuntu stonking

💖 EVP_PKEY_CTX_NEW — public key algorithm context functions 💖

okay bestie, sit down, hydrate, and let's talk about contexts, because this is the OpenSSL 3SSL manual and it's lowkey iconic. this one's all about making (and yeeting) your public key algorithm contexts. no cap, it's giving "plumbing that everything else sits on top of" energy. ✨

🦋 SYNOPSIS 🦋

#include <openssl/evp.h>

EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e);
EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e);
EVP_PKEY_CTX *EVP_PKEY_CTX_new_from_name(OSSL_LIB_CTX *libctx,
                                         const char *name,
                                         const char *propquery);
EVP_PKEY_CTX *EVP_PKEY_CTX_new_from_pkey(OSSL_LIB_CTX *libctx,
                                         EVP_PKEY *pkey,
                                         const char *propquery);
EVP_PKEY_CTX *EVP_PKEY_CTX_dup(const EVP_PKEY_CTX *ctx);
void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx);
int EVP_PKEY_CTX_is_a(EVP_PKEY_CTX *ctx, const char *keytype);

🌸 DESCRIPTION 🌸

So here's the tea, function by function:

  • EVP_PKEY_CTX_new() allocates a public key algorithm context using the pkey key type. and <italic>e</italic> must be NULL. that's not a suggestion, that's the rule. 💅
  • EVP_PKEY_CTX_new_id() allocates a public key algorithm context using the key type specified by id. same deal: <italic>e</italic> must be NULL.
  • EVP_PKEY_CTX_new_from_name() allocates a public key algorithm context using the library context libctx (peep OSSL_LIB_CTX(3)), the key type specified by name, and the property query propquery. ⚠️ none of the arguments are duplicated, so they must remain unchanged for the lifetime of the returned EVP_PKEY_CTX or of any of its duplicates. want the deets on possible names? scroll to NOTES below, bestie.
  • EVP_PKEY_CTX_new_from_pkey() allocates a public key algorithm context using the library context libctx (yep, OSSL_LIB_CTX(3) again) and the algorithm specified by pkey, plus the property query propquery. and again: none of the arguments are duplicated, so they must remain unchanged for the lifetime of the returned EVP_PKEY_CTX or any of its duplicates. 🫶
  • EVP_PKEY_CTX_new_id() and EVP_PKEY_CTX_new_from_name() are normally the ones you reach for when there's no EVP_PKEY structure chillin' with the operations — like during parameter generation, or key generation for some algorithms. and listen: the key that EVP_PKEY_generate(3) hands back is not associated with the generation context. so if you wanna actually do stuff with that key, you make a fresh context with EVP_PKEY_CTX_new_from_pkey(3). periodt.
  • EVP_PKEY_CTX_dup() duplicates the context ctx. it is not supported for a keygen operation. but!!! it is possible to duplicate a context that was freshly created via any of the above "new" functions — provided EVP_PKEY_keygen_init(3) has not yet been called on the source context — and then use the copy for key generation. sneaky but legal. 😌
  • EVP_PKEY_CTX_free() frees up the context ctx. and if ctx is NULL? nothing happens. no drama, no crash, just vibes. ✨
  • EVP_PKEY_is_a() checks if the key type associated with ctx is keytype.

👑 NOTES 👑

🌈 On EVP_PKEY_CTX 🌈

The EVP_PKEY_CTX structure is an opaque public key algorithm context used by the OpenSSL high-level public key API.

⚠️ Contexts MUST NOT be shared between threads. like, it is not permissible to use the same context simultaneously in two threads. do not do it. don't even think about it. 💀

🧚 On Key Types 🧚

We say "key type" in this manual, which is the same as "algorithm" in most cases — either term is fine, they're interchangeable, slay. but heads up: there are algorithms where the key type and the algorithm of the operations that use those keys are not the same. prime example: EC keys being used for ECDSA and ECDH operations. 🦋

Key types come in two different flavors:

⭐ Legacy NID or EVP_PKEY type

This is the id used with EVP_PKEY_CTX_new_id().

These are EVP_PKEY_RSA, EVP_PKEY_RSA_PSS, EVP_PKEY_DSA, EVP_PKEY_DH, EVP_PKEY_EC, EVP_PKEY_SM2, EVP_PKEY_X25519, EVP_PKEY_X448, and they're used by legacy methods.

⭐ Name strings

This is the name used with EVP_PKEY_CTX_new_from_name().

These are names like "RSA", "DSA", and what's available depends on what providers are currently accessible. 🔥

The OpenSSL providers offer a set of key types available this way — please see OSSL_PROVIDER-FIPS(7) and OSSL_PROVIDER-default(7) and related documentation for more information. iykyk.

💅 RETURN VALUES 💅

  • EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id() and EVP_PKEY_CTX_dup() return either the newly allocated EVP_PKEY_CTX structure or NULL if an error occurred. 😭
  • EVP_PKEY_CTX_free() does not return a value. it just. does the thing. 🎀
  • EVP_PKEY_CTX_is_a() returns 1 for true and 0 for false. ✨

🔥 SEE ALSO 🔥

🎀 HISTORY 🎀

  • EVP_PKEY_CTX_new(), EVP_PKEY_CTX_new_id(), EVP_PKEY_CTX_dup() and EVP_PKEY_CTX_free() were added in OpenSSL 1.0.0.
  • EVP_PKEY_CTX_new_from_name() and EVP_PKEY_CTX_new_from_pkey() were added in OpenSSL 3.0.

Copyright 2006-2026 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>.

okay bestie that's the whole page, you ate it, no crumbs left. 💖 go forth and make your contexts (and remember to free them, the memory leak allegations are not the vibe 🙈).

version 4.0.3 · dated 2026-09-29 · from your favorite EVP_PKEY_CTX_NEW(3SSL) manual, mwah 💋

📦 where this page comes from