EVP_PKEY-RSA(7ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💖 EVP_PKEY-RSA, EVP_KEYMGMT-RSA, RSA

okay so welcome to the OpenSSL manual page for EVP_PKEY-RSA, section 7ossl — this is the whole lore drop on the RSA keytype and its algorithm support, and honestly it ate. all three names (EVP_PKEY-RSA, EVP_KEYMGMT-RSA, RSA) are the same thing, they're just different handles for the same main character 💅

🌸 NAME

EVP_PKEY-RSA, EVP_KEYMGMT-RSA, RSA — the EVP_PKEY RSA keytype and algorithm support, periodt.

✨ DESCRIPTION

The RSA keytype is implemented in OpenSSL's default and FIPS providers. That implementation supports the basic RSA keys: the modulus n, the public exponent e, the private exponent d, and a whole little collection of prime factors, exponents and coefficients for CRT calculations — of which the first few are the ones you've definitely heard of: p and q, dP and dQ, and qInv. 🎀

🧸 Common RSA parameters

on top of the common parameters that all keytypes should support (go peek at "Common parameters" in provider-keymgmt(7)), the RSA keytype implementation also supports the following, bestie:

  • "n" (OSSL_PKEY_PARAM_RSA_N) <unsigned integer> — the RSA modulus n value. the big one. the moment. 🌈
  • "e" (OSSL_PKEY_PARAM_RSA_E) <unsigned integer> — the RSA public exponent e value. This value must always be set when you're creating a raw key using EVP_PKEY_fromdata(3). and heads up: when a decryption operation happens, this value gets used for blinding purposes to prevent timing attacks. she's not just a number, she's security 🛡️
  • "d" (OSSL_PKEY_PARAM_RSA_D) <unsigned integer> — the RSA private exponent d value. keep her secret fr fr 🙈
  • "rsa-factor1" (OSSL_PKEY_PARAM_RSA_FACTOR1), "rsa-factor2" (OSSL_PKEY_PARAM_RSA_FACTOR2), "rsa-factor3" (OSSL_PKEY_PARAM_RSA_FACTOR3), "rsa-factor4" (OSSL_PKEY_PARAM_RSA_FACTOR4), "rsa-factor5" (OSSL_PKEY_PARAM_RSA_FACTOR5), "rsa-factor6" (OSSL_PKEY_PARAM_RSA_FACTOR6), "rsa-factor7" (OSSL_PKEY_PARAM_RSA_FACTOR7), "rsa-factor8" (OSSL_PKEY_PARAM_RSA_FACTOR8), "rsa-factor9" (OSSL_PKEY_PARAM_RSA_FACTOR9), "rsa-factor10" (OSSL_PKEY_PARAM_RSA_FACTOR10) — all <unsigned integer>, all the RSA prime factors. The factors are known as "p", "q" and "r_i" in RFC8017. Up to eight additional "r_i" prime factors are supported. 🍓
  • "rsa-exponent1" (OSSL_PKEY_PARAM_RSA_EXPONENT1), "rsa-exponent2" (OSSL_PKEY_PARAM_RSA_EXPONENT2), "rsa-exponent3" (OSSL_PKEY_PARAM_RSA_EXPONENT3), "rsa-exponent4" (OSSL_PKEY_PARAM_RSA_EXPONENT4), "rsa-exponent5" (OSSL_PKEY_PARAM_RSA_EXPONENT5), "rsa-exponent6" (OSSL_PKEY_PARAM_RSA_EXPONENT6), "rsa-exponent7" (OSSL_PKEY_PARAM_RSA_EXPONENT7), "rsa-exponent8" (OSSL_PKEY_PARAM_RSA_EXPONENT8), "rsa-exponent9" (OSSL_PKEY_PARAM_RSA_EXPONENT9), "rsa-exponent10" (OSSL_PKEY_PARAM_RSA_EXPONENT10) — all <unsigned integer>, the RSA CRT (Chinese Remainder Theorem) exponents. The exponents are known as "dP", "dQ" and "d_i" in RFC8017. Up to eight additional "d_i" exponents are supported. ✨
  • "rsa-coefficient1" (OSSL_PKEY_PARAM_RSA_COEFFICIENT1), "rsa-coefficient2" (OSSL_PKEY_PARAM_RSA_COEFFICIENT2), "rsa-coefficient3" (OSSL_PKEY_PARAM_RSA_COEFFICIENT3), "rsa-coefficient4" (OSSL_PKEY_PARAM_RSA_COEFFICIENT4), "rsa-coefficient5" (OSSL_PKEY_PARAM_RSA_COEFFICIENT5), "rsa-coefficient6" (OSSL_PKEY_PARAM_RSA_COEFFICIENT6), "rsa-coefficient7" (OSSL_PKEY_PARAM_RSA_COEFFICIENT7), "rsa-coefficient8" (OSSL_PKEY_PARAM_RSA_COEFFICIENT8), "rsa-coefficient9" (OSSL_PKEY_PARAM_RSA_COEFFICIENT9) — all <unsigned integer>, the RSA CRT (Chinese Remainder Theorem) coefficients. The coefficients are known as "qInv" and "t_i". Up to eight additional "t_i" exponents are supported. 🦋

🔐 RSA key generation parameters

when you're generating RSA keys, these key generation parameters are the ones you can use:

  • "bits" (OSSL_PKEY_PARAM_RSA_BITS) <unsigned integer> — The value should be the cryptographic length for the RSA cryptosystem, in bits. 📏
  • "primes" (OSSL_PKEY_PARAM_RSA_PRIMES) <unsigned integer> — The value should be the number of primes for the generated RSA key. The default is 2. It isn't permitted to specify a larger number of primes than 10. Also, the number of primes is limited by the length of the key being generated, so the maximum number could be less. Some providers may only support a value of 2. 🫶
  • "e" (OSSL_PKEY_PARAM_RSA_E) <unsigned integer> — The RSA "e" value. The value may be any odd number greater than or equal to 65537. The default value is 65537. For legacy reasons a value of 3 is currently accepted but is deprecated. ⚠️
  • "rsa-derive-from-pq" (OSSL_PKEY_PARAM_RSA_DERIVE_FROM_PQ) <unsigned integer> — Indicate that missing parameters not passed in the parameter list should be derived if not provided. Setting a nonzero value will cause all needed exponents and coefficients to be derived if not available. Setting this option requires at least OSSL_PARAM_RSA_FACTOR1, OSSL_PARAM_RSA_FACTOR2, and OSSL_PARAM_RSA_N to be provided. This option is ignored if OSSL_KEYMGMT_SELECT_PRIVATE_KEY is not set in the selection parameter. 🧚

🧪 RSA key generation parameters for FIPS module testing

🚨 bestie listen to me: when generating RSA keys, the following additional key generation parameters may be used for algorithm testing purposes only. Do not use these to generate RSA keys for a production environment. i'm so serious 😭
  • "xp" (OSSL_PKEY_PARAM_RSA_TEST_XP) <unsigned integer>, "xq" (OSSL_PKEY_PARAM_RSA_TEST_XQ) <unsigned integer> — These 2 fields are normally randomly generated and are used to generate "p" and "q". 🎲
  • "xp1" (OSSL_PKEY_PARAM_RSA_TEST_XP1) <unsigned integer>, "xp2" (OSSL_PKEY_PARAM_RSA_TEST_XP2) <unsigned integer>, "xq1" (OSSL_PKEY_PARAM_RSA_TEST_XQ1) <unsigned integer>, "xq2" (OSSL_PKEY_PARAM_RSA_TEST_XQ2) <unsigned integer> — These 4 fields are normally randomly generated. The prime factors "p1", "p2", "q1" and "q2" are determined from these values. 💫

🔬 RSA key parameters for FIPS module testing

The following intermediate values can be retrieved only if the values specified in "RSA key generation parameters for FIPS module testing" are set. These should not be accessed in a production environment. 🙅‍♀️

  • "p1" (OSSL_PKEY_PARAM_RSA_TEST_P1) <unsigned integer>, "p2" (OSSL_PKEY_PARAM_RSA_TEST_P2) <unsigned integer>, "q1" (OSSL_PKEY_PARAM_RSA_TEST_Q1) <unsigned integer>, "q2" (OSSL_PKEY_PARAM_RSA_TEST_Q2) <unsigned integer> — The auxiliary probable primes. 🌸

✅ RSA key validation

okay so vibe check time, here's how the checks behave for RSA keys:

📜 CONFORMING TO

  • FIPS186-4 — Section B.3.6 Generation of Probable Primes with Conditions Based on Auxiliary Probable Primes
  • RFC 8017, excluding RSA-PSS and RSA-OAEP

💻 EXAMPLES

An EVP_PKEY context can be obtained by calling:

EVP_PKEY_CTX *pctx =
    EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);

An RSA key can be generated simply like this:

pkey = EVP_RSA_gen(4096);

or like this:

EVP_PKEY *pkey = NULL;
EVP_PKEY_CTX *pctx =
    EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);

EVP_PKEY_keygen_init(pctx);
EVP_PKEY_generate(pctx, &pkey);
EVP_PKEY_CTX_free(pctx);

An RSA key can be generated with key generation parameters:

unsigned int primes = 3;
unsigned int bits = 4096;
OSSL_PARAM params[3];
EVP_PKEY *pkey = NULL;
EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_from_name(NULL, "RSA", NULL);

EVP_PKEY_keygen_init(pctx);

params[0] = OSSL_PARAM_construct_uint("bits", &bits);
params[1] = OSSL_PARAM_construct_uint("primes", &primes);
params[2] = OSSL_PARAM_construct_end();
EVP_PKEY_CTX_set_params(pctx, params);

EVP_PKEY_generate(pctx, &pkey);
EVP_PKEY_print_private(bio_out, pkey, 0, NULL);
EVP_PKEY_CTX_free(pctx);

👀 SEE ALSO

EVP_RSA_gen(3), EVP_KEYMGMT(3), EVP_PKEY(3), provider-keymgmt(7) — go read them, iykyk 🫶

Copyright 2020-2024 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 page bestie!! this one's from OpenSSL version 3.5.0, dated 2026-09-25, and it's EVP_PKEY-RSA(7ossl) — go forth and generate some primes, you've got this 🦋🎀✨💜

📦 where this page comes from