RSA_NEW(3)

💖 RSA_NEW(3) — allocate-and-free RSA era, bestie 💖

okay so welcome to RSA_NEW(3) from the Library Functions Manual — this whole page is about allocating and freeing RSA objects, and it’s lowkey foundational crypto business ✨.

🎀 NAME 🎀

RSA_new, RSAPrivateKey_dup, RSAPublicKey_dup, RSA_up_ref, RSA_free — allocate and free RSA objects. that’s the whole squad, no cap 💅.

🌸 SYNOPSIS 🌸

#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 🦋

The RSA functions implement RSA public key encryption and signatures as defined in PKCS #1 v2.0 (RFC 2437). here’s the function-by-function tea ☕:

• RSA_new() — allocates and initializes an RSA structure, setting the reference count to 1. It is equivalent to calling RSA_new_method(3) with a NULL argument. iconic allocation behavior, honestly.
• RSAPrivateKey_dup() — calls RSA_new() and copies the public and private key components from rsa into the new structure. yes bestie, both public and private key components.
• RSAPublicKey_dup() — does the same except that it copies the public key components only 🫶.
• RSA_up_ref() — increments the reference count by 1. tiny but mighty.
• RSA_free() — decrements the reference count by 1. If it reaches 0, it calls the optional finish function set up with RSA_meth_set_finish(3) and frees the RSA structure and its components. The key is erased before the memory is returned to the system. If rsa is a NULL pointer, no action occurs. clean exit energy 💀✨.

🧚 the RSA struct, aka the vibe check 🧚

The RSA structure consists of several BIGNUM components. It can contain 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.

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… they’re optional but highkey worth it 🔥.

🚨 real talk bestie: 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. don’t go poking the struct directly, iykyk.

⭐ RETURN VALUES ⭐

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

🌈 SEE ALSO 🌈

go read these too, bestie: 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).

👑 STANDARDS 👑

SSL, PKCS #1 v2.0.

RSA was covered by a US patent which expired in September 2000. periodt, the patent is gone 💅.

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

RSA_up_ref() first appeared in OpenSSL 0.9.7 and has been available since OpenBSD 3.2.

xoxo bestie, this page is from Debian, dated November 19, 2023 💖