RSA_NEW(3)

🌸 RSA_NEW(3) — Library Functions Manual 🌸

okay bestie, welcome to the RSA allocation page 💅 this one's a whole family of functions: RSA_new, RSAPrivateKey_dup, RSAPublicKey_dup, RSA_up_ref, and RSA_free. They're all about making RSA objects and yeeting them into the void when you're done. Iconic behavior honestly.

---

✨ NAME ✨

RSA_new, RSAPrivateKey_dup, RSAPublicKey_dup, RSA_up_ref, RSA_free — allocate and free RSA objects 🎀

---

✨ SYNOPSIS ✨

library “libcrypto” #include <openssl/rsa.h>

RSA *
RSA_new(void);

RSA *
RSAPrivateKey_dup(RSA *rsa);

RSA *
RSAPublicKey_dup(RSA *rsa);

int
RSA_up_ref(RSA *rsa);

void
RSA_free(RSA *rsa);

---

✨ DESCRIPTION ✨

so the RSA functions implement RSA public key encryption and signatures, as defined in PKCS #1 v2.0 (RFC 2437). that's the whole vibe 🔥

RSA_new() allocates and initializes an RSA structure, and sets the reference count to 1. it's literally equivalent to calling RSA_new_method(3) with a NULL argument. same energy, no cap.

RSAPrivateKey_dup() calls RSA_new() and copies the public and private key components from rsa into the shiny new structure 🫶 RSAPublicKey_dup() does the exact same thing except it copies the public key components only. keeping it modest, we respect it.

RSA_up_ref() increments the reference count by 1. that's it. that's the whole job. ✨

RSA_free() decrements the reference count by 1. if it hits 0, it calls the optional finish function set up with RSA_meth_set_finish(3), and then frees the RSA structure and its components. the key is erased before the memory is returned to the system (yes, erased erased, we don't leave secrets lying around 🧹). and if rsa is a NULL pointer, literally nothing happens. no action. zero. nada. you're fine bestie.

The RSA structure consists of several BIGNUM components. It can hold public as well as private RSA keys:

typedef struct {
        BIGNUM *n;              // public modulus
        BIGNUM *e;              // public exponent
        BIGNUM *d;              // private exponent
        BIGNUM *p;              // secret prime factor
        BIGNUM *q;              // secret prime factor
        BIGNUM *dmp1;           // d mod (p-1)
        BIGNUM *dmq1;           // d mod (q-1)
        BIGNUM *iqmp;           // q^-1 mod p
        // ...
} RSA;

In public keys, the private exponent d and the related secret values p, q, dmp1, dmp2, and iqmp are NULL. they're just not invited to the public key party 🙈

p, q, dmp1, dmq1, and iqmp may be NULL in private keys — but the RSA operations are much faster when these values are available. so like, technically optional, but your performance said "please don't" 😭

⚠️ note that RSA keys may use non-standard RSA_METHOD implementations. in some cases, these BIGNUM values will not be used by the implementation, or may be used for alternative data storage. for this reason, applications should generally avoid using RSA structure elements directly, and instead use API functions to query or modify keys. like, i'm begging you — use the API. don't reach into the struct. 💀

---

✨ RETURN VALUES ✨

• RSA_new(), RSAPrivateKey_dup(), and RSAPublicKey_dup() return a pointer to the newly allocated structure, or NULL if an error occurs. you can grab an error code with ERR_get_error(3).
• RSA_up_ref() returns 1 for success or 0 for failure.

---

✨ SEE ALSO ✨

BN_new(3), crypto(3), d2i_RSAPublicKey(3), DH_new(3), DSA_new(3), EVP_PKEY_set1_RSA(3), RSA_blinding_on(3), RSA_check_key(3), RSA_generate_key(3), RSA_get0_key(3), RSA_get_ex_new_index(3), RSA_meth_new(3), RSA_padding_add_PKCS1_type_1(3), RSA_pkey_ctx_ctrl(3), RSA_print(3), RSA_private_encrypt(3), RSA_PSS_PARAMS_new(3), RSA_public_encrypt(3), RSA_security_bits(3), RSA_set_method(3), RSA_sign(3), RSA_sign_ASN1_OCTET_STRING(3), RSA_size(3) — the whole friend group, go say hi 🦋

---

✨ STANDARDS ✨

SSL, PKCS #1 v2.0

fun fact: RSA was covered by a US patent which expired in September 2000. we love a expired patent moment 👑

---

✨ HISTORY ✨

RSA_new() and RSA_free() appeared in SSLeay 0.4 or earlier. RSAPrivateKey_dup() first appeared in SSLeay 0.5.1, and RSAPublicKey_dup() in SSLeay 0.5.2. these functions have been available since OpenBSD 2.4. ancient. legendary. main character energy since forever ⭐

RSA_up_ref() first appeared in OpenSSL 0.9.7 and has been available since OpenBSD 3.2. a slightly younger icon, still iconic 💜

---

💖 ok that's the whole page bestie, now go RSA_free() your keys responsibly and don't leak memory, i'm watching 🫶✨

Debian · June 8, 2025 · RSA_NEW(3) — mwah, that's the tea 🍓💅