EVP_PKEY_SET1_RSA(3ossl)

📦
version 15.1 · 3 versions
, in freebsd 15.1

💖 EVP_PKEY_SET1_RSA 💖

okay so this is the 3ossl manual page (yes, OpenSSL, we're in it now) and it's all about the EVP_PKEY assignment functions. grab a snack, we're going through every single one 🍓

🌸 NAME 🌸

EVP_PKEY assignment functions — that's the whole vibe, bestie. here is literally every function documented on this page, grouped up so it's not one giant wall of text:

  • the set1 girlies: EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY
  • the get1 girlies: EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY
  • the get0 typed squad: EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY
  • the assign crew: EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH
  • the hash-y ones: EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash
  • and the misc icons: EVP_PKEY_get0, EVP_PKEY_type, EVP_PKEY_get_id, EVP_PKEY_get_base_id, EVP_PKEY_set1_engine, EVP_PKEY_get0_engine, EVP_PKEY_id, EVP_PKEY_base_id

✨ SYNOPSIS ✨

the header you need, periodt:

#include <openssl/evp.h>

these three are still living their best non-deprecated life:

int EVP_PKEY_get_id(const EVP_PKEY *pkey);
int EVP_PKEY_get_base_id(const EVP_PKEY *pkey);
int EVP_PKEY_type(int type);

#define EVP_PKEY_id EVP_PKEY_get_id
#define EVP_PKEY_base_id EVP_PKEY_get_base_id

then there's the deprecated corner 😭 — the following functions have been deprecated since OpenSSL 3.0, and you can hide them entirely by defining OPENSSL_API_COMPAT with a suitable version value, see openssl_user_macros(7):

int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key);
int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key);
int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key);
int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);

RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);
DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);
DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);
EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);

const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len);
const unsigned char *EVP_PKEY_get0_poly1305(const EVP_PKEY *pkey, size_t *len);
const unsigned char *EVP_PKEY_get0_siphash(const EVP_PKEY *pkey, size_t *len);
const RSA *EVP_PKEY_get0_RSA(const EVP_PKEY *pkey);
const DSA *EVP_PKEY_get0_DSA(const EVP_PKEY *pkey);
const DH *EVP_PKEY_get0_DH(const EVP_PKEY *pkey);
const EC_KEY *EVP_PKEY_get0_EC_KEY(const EVP_PKEY *pkey);
void *EVP_PKEY_get0(const EVP_PKEY *pkey);

int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key);
int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key);
int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key);
int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
int EVP_PKEY_assign_POLY1305(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);
int EVP_PKEY_assign_SIPHASH(EVP_PKEY *pkey, ASN1_OCTET_STRING *key);

ENGINE *EVP_PKEY_get0_engine(const EVP_PKEY *pkey);
int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine);

💅 DESCRIPTION 💅

let's go, section by section, no skips 💖

🦋 the type-checking trio

EVP_PKEY_get_base_id() returns the type of pkey. like, for example, an RSA key will return EVP_PKEY_RSA. simple, iconic.

EVP_PKEY_get_id() returns the actual NID associated with pkey — but only if the pkey type isn't implemented just in a provider(7). and here's the history lesson bestie: back in the day, keys using the same algorithm could use different NIDs. like, an RSA key could use the NIDs corresponding to the NIDs NID_rsaEncryption (equivalent to EVP_PKEY_RSA) or NID_rsa (equivalent to EVP_PKEY_RSA2). the use of alternative non-standard NIDs is now rare, so EVP_PKEY_RSA2 et al are not often seen in practice. and if the pkey is only implemented in a provider(7), EVP_PKEY_get_id() returns -1 (EVP_PKEY_KEYMGMT). 💀

EVP_PKEY_type() returns the underlying type of the NID type. for example, EVP_PKEY_type(EVP_PKEY_RSA2) will return EVP_PKEY_RSA. slay.

🎀 the set1 functions (deprecated, sorry babe)

EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and EVP_PKEY_set1_EC_KEY() set the key referenced by pkey to key.

these functions are deprecated. applications should instead use EVP_PKEY_fromdata(3). 🚩

🌈 the assign family (also deprecated)

EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(), EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() and EVP_PKEY_assign_SIPHASH() set the referenced key to key — however these use the supplied key internally, and so key will be freed when the parent pkey is freed. 📌

these macros are deprecated. applications should instead read an EVP_PKEY directly using the OSSL_DECODER APIs (see OSSL_DECODER_CTX_new_for_pkey(3)), or construct an EVP_PKEY from data using EVP_PKEY_fromdata(3).

🧚 the get1 squad

EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() return the referenced key in pkey, or NULL if the key is not of the correct type. the returned key must be freed after use 🔥

these functions are deprecated. applications should instead use the EVP_PKEY directly where possible. if access to the low level key parameters is required then applications should use EVP_PKEY_get_params(3) and other similar functions. and to write an EVP_PKEY out, use the OSSL_ENCODER APIs (see OSSL_ENCODER_CTX_new_for_pkey(3)).

💜 the get0 gang

EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(), EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() return the referenced key in pkey, or NULL if the key is not of the correct type. but — the reference count of the returned key is not incremented, and so the key must not be freed after use 🙅‍♀️

these functions are deprecated. applications should instead use the EVP_PKEY directly where possible. if access to the low level key parameters is required then applications should use EVP_PKEY_get_params(3) and other similar functions. to write an EVP_PKEY out, use the OSSL_ENCODER APIs (see OSSL_ENCODER_CTX_new_for_pkey(3)).

EVP_PKEY_get0() returns a pointer to the legacy key, or NULL if the key is not legacy.

⚠️ the provider cache situation (read this twice, bestie)

note that if an EVP_PKEY was not constructed using one of the deprecated functions such as EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() or EVP_PKEY_set1_EC_KEY(), or via the similarly named EVP_PKEY_assign macros described above, then the internal key will be managed by a provider (see provider(7)).

in that case, the key returned by EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH(), EVP_PKEY_get1_EC_KEY(), EVP_PKEY_get0_hmac(), EVP_PKEY_get0_poly1305(), EVP_PKEY_get0_siphash(), EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() or EVP_PKEY_get0_EC_KEY() will be a cached copy of the provider's key. and listen 👀:

  • subsequent updates to the provider's key will not be reflected back in the cached copy
  • and updates made by an application to the returned key will not be reflected back in the provider's key
  • subsequent calls to EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() will always return the cached copy returned by the first call

it's giving "you get one snapshot and that's it" 📸

🫶 the ENGINE pair

EVP_PKEY_get0_engine() returns a reference to the ENGINE handling pkey.

deprecated. applications should use providers instead of engines (see provider(7) for details).

EVP_PKEY_set1_engine() sets the ENGINE handling pkey to engine. it must be called after the key algorithm and components are set up. if engine does not include an EVP_PKEY_METHOD for pkey, an error occurs. 🚨

deprecated. applications should use providers instead of engines (see provider(7) for details).

🚨 WARNINGS 🚨

the following functions are only reliable with EVP_PKEYs that have been assigned an internal key with EVP_PKEY_assign_*():

  • EVP_PKEY_get_id(), EVP_PKEY_get_base_id(), EVP_PKEY_type()

for EVP_PKEY key type checking purposes, EVP_PKEY_is_a(3) is more generic. ✨

for purposes of retrieving the name of the EVP_PKEY, the function EVP_PKEY_get0_type_name(3) is more generally useful.

and now the big one 😭 — the keys returned from EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() were changed to have a const return type in OpenSSL 3.0. as described above, the keys returned may be cached copies of the key held in a provider. because of this — and unlike in earlier versions of OpenSSL — they should be considered read-only copies of the key. updates to these keys will not be reflected back in the provider side key. 🔒

the EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() functions were not changed to have a const return type, in order that applications can "free" the return value. however, applications should still consider them as read-only copies. don't get it twisted 💅

📝 NOTES 📝

in accordance with the OpenSSL naming convention, the key obtained from or assigned to the pkey using the 1 functions must be freed as well as pkey. yes, both. two frees. no cap 🫠

EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(), EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() and EVP_PKEY_assign_SIPHASH() are implemented as macros.

EVP_PKEY_assign_EC_KEY() looks at the curve name id to determine if the passed EC_KEY is an SM2(7) key, and will set the EVP_PKEY type to EVP_PKEY_SM2 in that case, instead of EVP_PKEY_EC. the plot twist ✨

most applications wishing to know a key type will simply call EVP_PKEY_get_base_id() and will not care about the actual type — which will be identical in almost all cases.

previous versions of this document suggested using EVP_PKEY_type(pkey->type) to determine the type of a key. since EVP_PKEY is now opaque, this is no longer possible: the equivalent is EVP_PKEY_get_base_id(pkey). rip to the old ways 🪦

EVP_PKEY_set1_engine() is typically used by an ENGINE returning an HSM key as part of its routine to load a private key.

🎀 RETURN VALUES 🎀

  • EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure.
  • EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() return the referenced key or NULL if an error occurred.
  • EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH(), EVP_PKEY_assign_EC_KEY(), EVP_PKEY_assign_POLY1305() and EVP_PKEY_assign_SIPHASH() return 1 for success and 0 for failure.
  • EVP_PKEY_get_base_id(), EVP_PKEY_get_id() and EVP_PKEY_type() return a key type or NID_undef (equivalently EVP_PKEY_NONE) on error.
  • EVP_PKEY_set1_engine() returns 1 for success and 0 for failure.

👀 SEE ALSO 👀

🦋 HISTORY 🦋

the EVP_PKEY_id() and EVP_PKEY_base_id() functions were renamed to include "get" in their names in OpenSSL 3.0, respectively. the old names are kept as non-deprecated alias macros. glow-up complete ✨

these ones were deprecated in OpenSSL 3.0:

  • EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY
  • EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY
  • EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY
  • EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY, EVP_PKEY_assign_POLY1305, EVP_PKEY_assign_SIPHASH
  • EVP_PKEY_get0_hmac, EVP_PKEY_get0_poly1305, EVP_PKEY_get0_siphash
  • EVP_PKEY_set1_engine and EVP_PKEY_get0_engine

the return value from EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY were made const in OpenSSL 3.0.

and the function EVP_PKEY_set_alias_type() was previously documented on this page. it was removed in OpenSSL 3.0. gone but not forgotten 🕊️

okay so legally we gotta say this and honestly it's giving "required reading before the fun part" but we're gonna slay it anyway 💅

Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved. — like, all of them, every single author, reserved, no cap ✨

This file is licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License — fr fr, this is a real legal vibe check, don't skip it 🙈

You can obtain a copy of the License in the file LICENSE in the source distribution, or at <https://www.openssl.org/source/license.html> — like, it's literally right there, bestie, go read it 🎀

ngl the lawyers made us put this here and honestly? iconic of them for protecting the whole project 🫶

and that's the whole page, bestie!! you made it to the end 🎉💖

This gorgeous little manual page is from OpenSSL 3.5.6, dated 2026-04-07, and its name is EVP_PKEY_SET1_RSA(3ossl) — she's got main character energy and she knows it 👑✨ Go forth and EVP_PKEY_set1_RSA responsibly, mwah 💋🌸

📦 where this page comes from