man > EVP_KEYMGMT-RSA(7ssl)

man perldoc info pydoc3 ri search

📖 NAME

EVP_PKEY-RSA, EVP_KEYMGMT-RSA, RSA — EVP_PKEY RSA keytype and algorithm support

🚀 Quick Reference

Use Case	Command	Description
🔑 Generate RSA key pair (simple)	EVP_RSA_gen(4096)	Generate a 4096-bit RSA key pair
🔑 Generate RSA key pair (context)	EVP_PKEY_keygen_init + EVP_PKEY_generate	Generate RSA key using EVP_PKEY_CTX
⚙️ Generate RSA key with custom params	EVP_PKEY_CTX_set_params(pctx, params)	Set bits, primes, e before generation
🔍 Access RSA key components	EVP_PKEY_get_bn_param(pkey, "n", &n)	Retrieve modulus, exponent, factors, CRT params

📝 Description

The RSA keytype is implemented in OpenSSL's default and FIPS providers. That implementation supports the basic RSA keys, containing the modulus n, the public exponent e, the private exponent d, and a collection of prime factors, exponents and coefficient for CRT calculations, of which the first few are known as p and q, dP and dQ, and qInv.

🔧 Common RSA parameters

In addition to the common parameters that all keytypes should support (see provider-keymgmt(7)), the RSA keytype implementation supports the following.

• "n" (OSSL_PKEY_PARAM_RSA_N) <unsigned integer> — The RSA n value.
• "e" (OSSL_PKEY_PARAM_RSA_E) <unsigned integer> — The RSA e value.
• "d" (OSSL_PKEY_PARAM_RSA_D) <unsigned integer> — The RSA d value.
• "rsa-factor1" through "rsa-factor10" (<b>OSSL_PKEY_PARAM_RSA_FACTOR1</b>–<b>FACTOR10</b>) <unsigned integer> — RSA prime factors. Known as p, q and r_i in RFC 8017. Up to eight additional r_i prime factors are supported.
• "rsa-exponent1" through "rsa-exponent10" (<b>OSSL_PKEY_PARAM_RSA_EXPONENT1</b>–<b>EXPONENT10</b>) <unsigned integer> — RSA CRT exponents. Known as dP, dQ and d_i in RFC 8017. Up to eight additional d_i exponents are supported.
• "rsa-coefficient1" through "rsa-coefficient10" (<b>OSSL_PKEY_PARAM_RSA_COEFFICIENT1</b>–<b>COEFFICIENT10</b>) <unsigned integer> — RSA CRT coefficients. Known as qInv and t_i. Up to eight additional t_i exponents are supported.

⚙️ RSA key generation parameters

When generating RSA keys, the following key generation parameters may be used.

• "bits" (OSSL_PKEY_PARAM_RSA_BITS) <unsigned integer> — Cryptographic length for the RSA cryptosystem, in bits.
• "primes" (OSSL_PKEY_PARAM_RSA_PRIMES) <unsigned integer> — Number of primes for the generated RSA key. Default is 2. Maximum is 10, though limited by key length. Some providers may only support a value of 2.
• "e" (OSSL_PKEY_PARAM_RSA_E) <unsigned integer> — The RSA e value. May be any odd number ≥ 65537. Default is 65537. A value of 3 is accepted but deprecated.

🧪 RSA key generation parameters for FIPS module testing

⚠️ For algorithm testing purposes only. Do not use these to generate RSA keys for a production environment.

• "xp" (OSSL_PKEY_PARAM_RSA_TEST_XP) <unsigned integer> — Normally randomly generated; used to generate p.
• "xq" (OSSL_PKEY_PARAM_RSA_TEST_XQ) <unsigned integer> — Normally randomly generated; used to generate 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

⚠️ For testing only. The following intermediate values can be retrieved only if the FIPS test values above are set. 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.

📜 Conforming to

• FIPS 186-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)

©️ Copyright

Copyright 2020-2021 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.

📖 NAME 🚀 Quick Reference 📝 Description 📜 Conforming to 💡 Examples 📚 See also ©️ Copyright