rsa.h

All headers

rsa.h contains functions for handling encryption and signature using RSA.

  1. Allocation and destruction
  2. RSA_new_public_key
  3. RSA_new_private_key
  4. RSA_new
  5. RSA_new_method
  6. RSA_free
  7. RSA_up_ref
  8. Properties
  9. OPENSSL_RSA_MAX_MODULUS_BITS
  10. RSA_bits
  11. RSA_get0_n
  12. RSA_get0_e
  13. RSA_get0_d
  14. RSA_get0_p
  15. RSA_get0_q
  16. RSA_get0_dmp1
  17. RSA_get0_dmq1
  18. RSA_get0_iqmp
  19. RSA_get0_key
  20. RSA_get0_factors
  21. RSA_get0_crt_params
  22. Setting individual properties
  23. RSA_set0_key
  24. RSA_set0_factors
  25. RSA_set0_crt_params
  26. Key generation
  27. RSA_generate_key_ex
  28. RSA_generate_key_fips
  29. Encryption / Decryption
  30. RSA_PKCS1_PADDING
  31. RSA_NO_PADDING
  32. RSA_PKCS1_OAEP_PADDING
  33. RSA_PKCS1_PSS_PADDING
  34. RSA_encrypt
  35. RSA_decrypt
  36. RSA_public_encrypt
  37. RSA_private_decrypt
  38. Signing / Verification
  39. RSA_sign
  40. RSA_sign_pss_mgf1
  41. RSA_sign_raw
  42. RSA_verify
  43. RSA_verify_pss_mgf1
  44. RSA_verify_raw
  45. RSA_private_encrypt
  46. RSA_public_decrypt
  47. Utility functions
  48. RSA_size
  49. RSA_is_opaque
  50. RSAPublicKey_dup
  51. RSAPrivateKey_dup
  52. RSA_check_key
  53. RSA_check_fips
  54. RSA_verify_PKCS1_PSS_mgf1
  55. RSA_padding_add_PKCS1_PSS_mgf1
  56. RSA_padding_add_PKCS1_OAEP_mgf1
  57. RSA_add_pkcs1_prefix
  58. ASN.1 functions
  59. RSA_parse_public_key
  60. RSA_public_key_from_bytes
  61. RSA_marshal_public_key
  62. RSA_public_key_to_bytes
  63. RSA_parse_private_key
  64. RSA_private_key_from_bytes
  65. RSA_marshal_private_key
  66. RSA_private_key_to_bytes
  67. Obscure RSA variants
  68. RSA_new_private_key_no_crt
  69. RSA_new_private_key_no_e
  70. RSA_new_public_key_large_e
  71. RSA_new_private_key_large_e
  72. ex_data functions
  73. RSA_get_ex_new_index
  74. RSA_set_ex_data
  75. RSA_get_ex_data
  76. Flags
  77. RSA_FLAG_OPAQUE
  78. RSA_FLAG_NO_BLINDING
  79. RSA_FLAG_EXT_PKEY
  80. RSA_FLAG_NO_PUBLIC_EXPONENT
  81. RSA_FLAG_LARGE_PUBLIC_EXPONENT
  82. RSA public exponent values
  83. RSA_3
  84. RSA_F4
  85. Deprecated functions
  86. RSA_METHOD_FLAG_NO_CHECK
  87. RSA_flags
  88. RSA_test_flags
  89. RSA_blinding_on
  90. RSA_blinding_off
  91. RSA_generate_key
  92. d2i_RSAPublicKey
  93. i2d_RSAPublicKey
  94. d2i_RSAPrivateKey
  95. i2d_RSAPrivateKey
  96. RSA_padding_add_PKCS1_PSS
  97. RSA_verify_PKCS1_PSS
  98. RSA_padding_add_PKCS1_OAEP
  99. RSA_print
  100. RSA_get0_pss_params
  101. RSA_new_method_no_e
  102. rsa_meth_st

Allocation and destruction.

An RSA object represents a public or private RSA key. A given object may be used concurrently on multiple threads by non-mutating functions, provided no other thread is concurrently calling a mutating function. Unless otherwise documented, functions which take a const pointer are non-mutating and functions which take a non-const pointer are mutating.

RSA_new_public_key returns a new RSA object containing a public key with the specified parameters, or NULL on error or invalid input.

OPENSSL_EXPORT RSA *RSA_new_public_key(const BIGNUM *n, const BIGNUM *e);

RSA_new_private_key returns a new RSA object containing a private key with the specified parameters, or NULL on error or invalid input. All parameters are mandatory and may not be NULL.

This function creates standard RSA private keys with CRT parameters.

OPENSSL_EXPORT RSA *RSA_new_private_key(const BIGNUM *n, const BIGNUM *e,
                                        const BIGNUM *d, const BIGNUM *p,
                                        const BIGNUM *q, const BIGNUM *dmp1,
                                        const BIGNUM *dmq1, const BIGNUM *iqmp);

RSA_new returns a new, empty RSA object or NULL on error. Prefer using RSA_new_public_key or RSA_new_private_key to import an RSA key.

OPENSSL_EXPORT RSA *RSA_new(void);

RSA_new_method acts the same as RSA_new but takes an explicit ENGINE.

OPENSSL_EXPORT RSA *RSA_new_method(const ENGINE *engine);

RSA_free decrements the reference count of rsa and frees it if the reference count drops to zero.

OPENSSL_EXPORT void RSA_free(RSA *rsa);

RSA_up_ref increments the reference count of rsa and returns one. It does not mutate rsa for thread-safety purposes and may be used concurrently.

OPENSSL_EXPORT int RSA_up_ref(RSA *rsa);

Properties.

OPENSSL_RSA_MAX_MODULUS_BITS is the maximum supported RSA modulus, in bits.

TODO(davidben): Reduce this to 8192.

#define OPENSSL_RSA_MAX_MODULUS_BITS 16384

RSA_bits returns the size of rsa, in bits.

OPENSSL_EXPORT unsigned RSA_bits(const RSA *rsa);

RSA_get0_n returns rsa's public modulus.

OPENSSL_EXPORT const BIGNUM *RSA_get0_n(const RSA *rsa);

RSA_get0_e returns rsa's public exponent.

OPENSSL_EXPORT const BIGNUM *RSA_get0_e(const RSA *rsa);

RSA_get0_d returns rsa's private exponent. If rsa is a public key, this value will be NULL.

OPENSSL_EXPORT const BIGNUM *RSA_get0_d(const RSA *rsa);

RSA_get0_p returns rsa's first private prime factor. If rsa is a public key or lacks its prime factors, this value will be NULL.

OPENSSL_EXPORT const BIGNUM *RSA_get0_p(const RSA *rsa);

RSA_get0_q returns rsa's second private prime factor. If rsa is a public key or lacks its prime factors, this value will be NULL.

OPENSSL_EXPORT const BIGNUM *RSA_get0_q(const RSA *rsa);

RSA_get0_dmp1 returns d (mod p-1) for rsa. If rsa is a public key or lacks CRT parameters, this value will be NULL.

OPENSSL_EXPORT const BIGNUM *RSA_get0_dmp1(const RSA *rsa);

RSA_get0_dmq1 returns d (mod q-1) for rsa. If rsa is a public key or lacks CRT parameters, this value will be NULL.

OPENSSL_EXPORT const BIGNUM *RSA_get0_dmq1(const RSA *rsa);

RSA_get0_iqmp returns q^-1 (mod p). If rsa is a public key or lacks CRT parameters, this value will be NULL.

OPENSSL_EXPORT const BIGNUM *RSA_get0_iqmp(const RSA *rsa);

RSA_get0_key sets *out_n, *out_e, and *out_d, if non-NULL, to rsa's modulus, public exponent, and private exponent, respectively. If rsa is a public key, the private exponent will be set to NULL.

OPENSSL_EXPORT void RSA_get0_key(const RSA *rsa, const BIGNUM **out_n,
                                 const BIGNUM **out_e, const BIGNUM **out_d);

RSA_get0_factors sets *out_p and *out_q, if non-NULL, to rsa's prime factors. If rsa is a public key, they will be set to NULL.

OPENSSL_EXPORT void RSA_get0_factors(const RSA *rsa, const BIGNUM **out_p,
                                     const BIGNUM **out_q);

RSA_get0_crt_params sets *out_dmp1, *out_dmq1, and *out_iqmp, if non-NULL, to rsa's CRT parameters. These are d (mod p-1), d (mod q-1) and q^-1 (mod p), respectively. If rsa is a public key, each parameter will be set to NULL.

OPENSSL_EXPORT void RSA_get0_crt_params(const RSA *rsa, const BIGNUM **out_dmp1,
                                        const BIGNUM **out_dmq1,
                                        const BIGNUM **out_iqmp);

Setting individual properties.

These functions allow setting individual properties of an RSA object. This is typically used with RSA_new to construct an RSA key field by field. Prefer instead to use RSA_new_public_key and RSA_new_private_key. These functions defer some initialization to the first use of an RSA object. This means invalid inputs may be caught late.

TODO(crbug.com/boringssl/316): This deferred initialization also causes performance problems in multi-threaded applications. The preferred APIs currently have the same issues, but they will initialize eagerly in the future.

RSA_set0_key sets rsa's modulus, public exponent, and private exponent to n, e, and d respectively, if non-NULL. On success, it takes ownership of each argument and returns one. Otherwise, it returns zero.

d may be NULL, but n and e must either be non-NULL or already configured on rsa.

It is an error to call this function after rsa has been used for a cryptographic operation. Construct a new RSA object instead.

OPENSSL_EXPORT int RSA_set0_key(RSA *rsa, BIGNUM *n, BIGNUM *e, BIGNUM *d);

RSA_set0_factors sets rsa's prime factors to p and q, if non-NULL, and takes ownership of them. On success, it takes ownership of each argument and returns one. Otherwise, it returns zero.

Each argument must either be non-NULL or already configured on rsa.

It is an error to call this function after rsa has been used for a cryptographic operation. Construct a new RSA object instead.

OPENSSL_EXPORT int RSA_set0_factors(RSA *rsa, BIGNUM *p, BIGNUM *q);

RSA_set0_crt_params sets rsa's CRT parameters to dmp1, dmq1, and iqmp, if non-NULL, and takes ownership of them. On success, it takes ownership of its parameters and returns one. Otherwise, it returns zero.

Each argument must either be non-NULL or already configured on rsa.

It is an error to call this function after rsa has been used for a cryptographic operation. Construct a new RSA object instead.

OPENSSL_EXPORT int RSA_set0_crt_params(RSA *rsa, BIGNUM *dmp1, BIGNUM *dmq1,
                                       BIGNUM *iqmp);

Key generation.

RSA_generate_key_ex generates a new RSA key where the modulus has size bits and the public exponent is e. If unsure, RSA_F4 is a good value for e. If cb is not NULL then it is called during the key generation process. In addition to the calls documented for BN_generate_prime_ex, it is called with event=2 when the n'th prime is rejected as unsuitable and with event=3 when a suitable value for p is found.

It returns one on success or zero on error.

OPENSSL_EXPORT int RSA_generate_key_ex(RSA *rsa, int bits, const BIGNUM *e,
                                       BN_GENCB *cb);

RSA_generate_key_fips behaves like RSA_generate_key_ex but performs additional checks for FIPS compliance. The public exponent is always 65537 and bits must be either 2048 or 3072.

OPENSSL_EXPORT int RSA_generate_key_fips(RSA *rsa, int bits, BN_GENCB *cb);

Encryption / Decryption

These functions are considered non-mutating for thread-safety purposes and may be used concurrently.

RSA_PKCS1_PADDING denotes PKCS#1 v1.5 padding. When used with encryption, this is RSAES-PKCS1-v1_5. When used with signing, this is RSASSA-PKCS1-v1_5.

WARNING: The RSAES-PKCS1-v1_5 encryption scheme is vulnerable to a chosen-ciphertext attack. Decrypting attacker-supplied ciphertext with RSAES-PKCS1-v1_5 may give the attacker control over your private key. This does not impact the RSASSA-PKCS1-v1_5 signature scheme. See "Chosen Ciphertext Attacks Against Protocols Based on the RSA Encryption Standard PKCS #1", Daniel Bleichenbacher, Advances in Cryptology (Crypto '98).

#define RSA_PKCS1_PADDING 1

RSA_NO_PADDING denotes a raw RSA operation.

#define RSA_NO_PADDING 3

RSA_PKCS1_OAEP_PADDING denotes the RSAES-OAEP encryption scheme.

#define RSA_PKCS1_OAEP_PADDING 4

RSA_PKCS1_PSS_PADDING denotes the RSASSA-PSS signature scheme. This value may not be passed into RSA_sign_raw, only EVP_PKEY_CTX_set_rsa_padding. See also RSA_sign_pss_mgf1 and RSA_verify_pss_mgf1.

#define RSA_PKCS1_PSS_PADDING 6

RSA_encrypt encrypts in_len bytes from in to the public key from rsa and writes, at most, max_out bytes of encrypted data to out. The max_out argument must be, at least, RSA_size in order to ensure success.

It returns 1 on success or zero on error.

The padding argument must be one of the RSA_*_PADDING values. If in doubt, use RSA_PKCS1_OAEP_PADDING for new protocols.

OPENSSL_EXPORT int RSA_encrypt(RSA *rsa, size_t *out_len, uint8_t *out,
                               size_t max_out, const uint8_t *in, size_t in_len,
                               int padding);

RSA_decrypt decrypts in_len bytes from in with the private key from rsa and writes, at most, max_out bytes of plaintext to out. The max_out argument must be, at least, RSA_size in order to ensure success.

It returns 1 on success or zero on error.

The padding argument must be one of the RSA_*_PADDING values. If in doubt, use RSA_PKCS1_OAEP_PADDING for new protocols.

WARNING: Passing RSA_PKCS1_PADDING into this function is deprecated and insecure. RSAES-PKCS1-v1_5 is vulnerable to a chosen-ciphertext attack. Decrypting attacker-supplied ciphertext with RSAES-PKCS1-v1_5 may give the attacker control over your private key. See "Chosen Ciphertext Attacks Against Protocols Based on the RSA Encryption Standard PKCS #1", Daniel Bleichenbacher, Advances in Cryptology (Crypto '98).

In some limited cases, such as TLS RSA key exchange, it is possible to mitigate this flaw with custom, protocol-specific padding logic. This should be implemented with RSA_NO_PADDING, not RSA_PKCS1_PADDING.

OPENSSL_EXPORT int RSA_decrypt(RSA *rsa, size_t *out_len, uint8_t *out,
                               size_t max_out, const uint8_t *in, size_t in_len,
                               int padding);

RSA_public_encrypt encrypts flen bytes from from to the public key in rsa and writes the encrypted data to to. The to buffer must have at least RSA_size bytes of space. It returns the number of bytes written, or -1 on error. The padding argument must be one of the RSA_*_PADDING values. If in doubt, use RSA_PKCS1_OAEP_PADDING for new protocols.

WARNING: this function is dangerous because it breaks the usual return value convention. Use RSA_encrypt instead.

OPENSSL_EXPORT int RSA_public_encrypt(size_t flen, const uint8_t *from,
                                      uint8_t *to, RSA *rsa, int padding);

RSA_private_decrypt decrypts flen bytes from from with the public key in rsa and writes the plaintext to to. The to buffer must have at least RSA_size bytes of space. It returns the number of bytes written, or -1 on error. The padding argument must be one of the RSA_*_PADDING values. If in doubt, use RSA_PKCS1_OAEP_PADDING for new protocols. Passing RSA_PKCS1_PADDING into this function is deprecated and insecure. See RSA_decrypt.

WARNING: this function is dangerous because it breaks the usual return value convention. Use RSA_decrypt instead.

OPENSSL_EXPORT int RSA_private_decrypt(size_t flen, const uint8_t *from,
                                       uint8_t *to, RSA *rsa, int padding);

Signing / Verification

These functions are considered non-mutating for thread-safety purposes and may be used concurrently.

RSA_sign signs digest_len bytes of digest from digest with rsa using RSASSA-PKCS1-v1_5. It writes, at most, RSA_size(rsa) bytes to out. On successful return, the actual number of bytes written is written to *out_len.

The hash_nid argument identifies the hash function used to calculate digest and is embedded in the resulting signature. For example, it might be NID_sha256.

It returns 1 on success and zero on error.

WARNING: digest must be the result of hashing the data to be signed with hash_nid. Passing unhashed inputs will not result in a secure signature scheme.

OPENSSL_EXPORT int RSA_sign(int hash_nid, const uint8_t *digest,
                            size_t digest_len, uint8_t *out, unsigned *out_len,
                            RSA *rsa);

RSA_sign_pss_mgf1 signs digest_len bytes from digest with the public key from rsa using RSASSA-PSS with MGF1 as the mask generation function. It writes, at most, max_out bytes of signature data to out. The max_out argument must be, at least, RSA_size in order to ensure success. It returns 1 on success or zero on error.

The md and mgf1_md arguments identify the hash used to calculate digest and the MGF1 hash, respectively. If mgf1_md is NULL, md is used.

salt_len specifies the expected salt length in bytes. If salt_len is -1, then the salt length is the same as the hash length. If -2, then the salt length is maximal given the size of rsa. If unsure, use -1.

WARNING: digest must be the result of hashing the data to be signed with md. Passing unhashed inputs will not result in a secure signature scheme.

OPENSSL_EXPORT int RSA_sign_pss_mgf1(RSA *rsa, size_t *out_len, uint8_t *out,
                                     size_t max_out, const uint8_t *digest,
                                     size_t digest_len, const EVP_MD *md,
                                     const EVP_MD *mgf1_md, int salt_len);

RSA_sign_raw performs the private key portion of computing a signature with rsa. It writes, at most, max_out bytes of signature data to out. The max_out argument must be, at least, RSA_size in order to ensure the output fits. It returns 1 on success or zero on error.

If padding is RSA_PKCS1_PADDING, this function wraps in with the padding portion of RSASSA-PKCS1-v1_5 and then performs the raw private key operation. The caller is responsible for hashing the input and wrapping it in a DigestInfo structure.

If padding is RSA_NO_PADDING, this function only performs the raw private key operation, interpreting in as a integer modulo n. The caller is responsible for hashing the input and encoding it for the signature scheme being implemented.

WARNING: This function is a building block for a signature scheme, not a complete one. in must be the result of hashing and encoding the data as needed for the scheme being implemented. Passing in arbitrary inputs will not result in a secure signature scheme.

OPENSSL_EXPORT int RSA_sign_raw(RSA *rsa, size_t *out_len, uint8_t *out,
                                size_t max_out, const uint8_t *in,
                                size_t in_len, int padding);

RSA_verify verifies that sig_len bytes from sig are a valid, RSASSA-PKCS1-v1_5 signature of digest_len bytes at digest by rsa.

The hash_nid argument identifies the hash function used to calculate digest and is embedded in the resulting signature in order to prevent hash confusion attacks. For example, it might be NID_sha256.

It returns one if the signature is valid and zero otherwise.

WARNING: this differs from the original, OpenSSL function which additionally returned -1 on error.

WARNING: digest must be the result of hashing the data to be verified with hash_nid. Passing unhashed input will not result in a secure signature scheme.

OPENSSL_EXPORT int RSA_verify(int hash_nid, const uint8_t *digest,
                              size_t digest_len, const uint8_t *sig,
                              size_t sig_len, RSA *rsa);

RSA_verify_pss_mgf1 verifies that sig_len bytes from sig are a valid, RSASSA-PSS signature of digest_len bytes at digest by rsa. It returns one if the signature is valid and zero otherwise. MGF1 is used as the mask generation function.

The md and mgf1_md arguments identify the hash used to calculate digest and the MGF1 hash, respectively. If mgf1_md is NULL, md is used. salt_len specifies the expected salt length in bytes.

If salt_len is -1, then the salt length is the same as the hash length. If -2, then the salt length is recovered and all values accepted. If unsure, use -1.

WARNING: digest must be the result of hashing the data to be verified with md. Passing unhashed input will not result in a secure signature scheme.

OPENSSL_EXPORT int RSA_verify_pss_mgf1(RSA *rsa, const uint8_t *digest,
                                       size_t digest_len, const EVP_MD *md,
                                       const EVP_MD *mgf1_md, int salt_len,
                                       const uint8_t *sig, size_t sig_len);

RSA_verify_raw performs the public key portion of verifying in_len bytes of signature from in using the public key from rsa. On success, it returns one and writes, at most, max_out bytes of output to out. The max_out argument must be, at least, RSA_size in order to ensure the output fits. On failure or invalid input, it returns zero.

If padding is RSA_PKCS1_PADDING, this function checks the padding portion of RSASSA-PKCS1-v1_5 and outputs the remainder of the encoded digest. The caller is responsible for checking the output is a DigestInfo-wrapped digest of the message.

If padding is RSA_NO_PADDING, this function only performs the raw public key operation. The caller is responsible for checking the output is a valid result for the signature scheme being implemented.

WARNING: This function is a building block for a signature scheme, not a complete one. Checking for arbitrary strings in out will not result in a secure signature scheme.

OPENSSL_EXPORT int RSA_verify_raw(RSA *rsa, size_t *out_len, uint8_t *out,
                                  size_t max_out, const uint8_t *in,
                                  size_t in_len, int padding);

RSA_private_encrypt performs the private key portion of computing a signature with rsa. It takes flen bytes from from as input and writes the result to to. The to buffer must have at least RSA_size bytes of space. It returns the number of bytes written, or -1 on error.

For the interpretation of padding and the input, see RSA_sign_raw.

WARNING: This function is a building block for a signature scheme, not a complete one. See RSA_sign_raw for details.

WARNING: This function is dangerous because it breaks the usual return value convention. Use RSA_sign_raw instead.

OPENSSL_EXPORT int RSA_private_encrypt(size_t flen, const uint8_t *from,
                                       uint8_t *to, RSA *rsa, int padding);

RSA_public_decrypt performs the public key portion of verifying flen bytes of signature from from using the public key from rsa. It writes the result to to, which must have at least RSA_size bytes of space. It returns the number of bytes written, or -1 on error.

For the interpretation of padding and the result, see RSA_verify_raw.

WARNING: This function is a building block for a signature scheme, not a complete one. See RSA_verify_raw for details.

WARNING: This function is dangerous because it breaks the usual return value convention. Use RSA_verify_raw instead.

OPENSSL_EXPORT int RSA_public_decrypt(size_t flen, const uint8_t *from,
                                      uint8_t *to, RSA *rsa, int padding);

Utility functions.

RSA_size returns the number of bytes in the modulus, which is also the size of a signature or encrypted value using rsa.

OPENSSL_EXPORT unsigned RSA_size(const RSA *rsa);

RSA_is_opaque returns one if rsa is opaque and doesn't expose its key material. Otherwise it returns zero.

OPENSSL_EXPORT int RSA_is_opaque(const RSA *rsa);

RSAPublicKey_dup allocates a fresh RSA and copies the public key from rsa into it. It returns the fresh RSA object, or NULL on error.

OPENSSL_EXPORT RSA *RSAPublicKey_dup(const RSA *rsa);

RSAPrivateKey_dup allocates a fresh RSA and copies the private key from rsa into it. It returns the fresh RSA object, or NULL on error.

OPENSSL_EXPORT RSA *RSAPrivateKey_dup(const RSA *rsa);

RSA_check_key performs basic validity tests on rsa. It returns one if they pass and zero otherwise. Opaque keys and public keys always pass. If it returns zero then a more detailed error is available on the error queue.

OPENSSL_EXPORT int RSA_check_key(const RSA *rsa);

RSA_check_fips performs public key validity tests on key. It returns one if they pass and zero otherwise. Opaque keys always fail. This function does not mutate rsa for thread-safety purposes and may be used concurrently.

OPENSSL_EXPORT int RSA_check_fips(RSA *key);

RSA_verify_PKCS1_PSS_mgf1 verifies that EM is a correct PSS padding of mHash, where mHash is a digest produced by Hash. EM must point to exactly RSA_size(rsa) bytes of data. The mgf1Hash argument specifies the hash function for generating the mask. If NULL, Hash is used. The sLen argument specifies the expected salt length in bytes. If sLen is -1 then the salt length is the same as the hash length. If -2, then the salt length is recovered and all values accepted.

If unsure, use -1.

It returns one on success or zero on error.

This function implements only the low-level padding logic. Use RSA_verify_pss_mgf1 instead.

OPENSSL_EXPORT int RSA_verify_PKCS1_PSS_mgf1(const RSA *rsa,
                                             const uint8_t *mHash,
                                             const EVP_MD *Hash,
                                             const EVP_MD *mgf1Hash,
                                             const uint8_t *EM, int sLen);

RSA_padding_add_PKCS1_PSS_mgf1 writes a PSS padding of mHash to EM, where mHash is a digest produced by Hash. RSA_size(rsa) bytes of output will be written to EM. The mgf1Hash argument specifies the hash function for generating the mask. If NULL, Hash is used. The sLen argument specifies the expected salt length in bytes. If sLen is -1 then the salt length is the same as the hash length. If -2, then the salt length is maximal given the space in EM.

It returns one on success or zero on error.

This function implements only the low-level padding logic. Use RSA_sign_pss_mgf1 instead.

OPENSSL_EXPORT int RSA_padding_add_PKCS1_PSS_mgf1(const RSA *rsa, uint8_t *EM,
                                                  const uint8_t *mHash,
                                                  const EVP_MD *Hash,
                                                  const EVP_MD *mgf1Hash,
                                                  int sLen);

RSA_padding_add_PKCS1_OAEP_mgf1 writes an OAEP padding of from to to with the given parameters and hash functions. If md is NULL then SHA-1 is used. If mgf1md is NULL then the value of md is used (which means SHA-1 if that, in turn, is NULL).

It returns one on success or zero on error.

OPENSSL_EXPORT int RSA_padding_add_PKCS1_OAEP_mgf1(
    uint8_t *to, size_t to_len, const uint8_t *from, size_t from_len,
    const uint8_t *param, size_t param_len, const EVP_MD *md,
    const EVP_MD *mgf1md);

RSA_add_pkcs1_prefix builds a version of digest prefixed with the DigestInfo header for the given hash function and sets out_msg to point to it. On successful return, if *is_alloced is one, the caller must release *out_msg with OPENSSL_free.

OPENSSL_EXPORT int RSA_add_pkcs1_prefix(uint8_t **out_msg, size_t *out_msg_len,
                                        int *is_alloced, int hash_nid,
                                        const uint8_t *digest,
                                        size_t digest_len);

ASN.1 functions.

RSA_parse_public_key parses a DER-encoded RSAPublicKey structure (RFC 8017) from cbs and advances cbs. It returns a newly-allocated RSA or NULL on error.

OPENSSL_EXPORT RSA *RSA_parse_public_key(CBS *cbs);

RSA_public_key_from_bytes parses in as a DER-encoded RSAPublicKey structure (RFC 8017). It returns a newly-allocated RSA or NULL on error.

OPENSSL_EXPORT RSA *RSA_public_key_from_bytes(const uint8_t *in, size_t in_len);

RSA_marshal_public_key marshals rsa as a DER-encoded RSAPublicKey structure (RFC 8017) and appends the result to cbb. It returns one on success and zero on failure.

OPENSSL_EXPORT int RSA_marshal_public_key(CBB *cbb, const RSA *rsa);

RSA_public_key_to_bytes marshals rsa as a DER-encoded RSAPublicKey structure (RFC 8017) and, on success, sets *out_bytes to a newly allocated buffer containing the result and returns one. Otherwise, it returns zero. The result should be freed with OPENSSL_free.

OPENSSL_EXPORT int RSA_public_key_to_bytes(uint8_t **out_bytes, size_t *out_len,
                                           const RSA *rsa);

RSA_parse_private_key parses a DER-encoded RSAPrivateKey structure (RFC 8017) from cbs and advances cbs. It returns a newly-allocated RSA or NULL on error.

OPENSSL_EXPORT RSA *RSA_parse_private_key(CBS *cbs);

RSA_private_key_from_bytes parses in as a DER-encoded RSAPrivateKey structure (RFC 8017). It returns a newly-allocated RSA or NULL on error.

OPENSSL_EXPORT RSA *RSA_private_key_from_bytes(const uint8_t *in,
                                               size_t in_len);

RSA_marshal_private_key marshals rsa as a DER-encoded RSAPrivateKey structure (RFC 8017) and appends the result to cbb. It returns one on success and zero on failure.

OPENSSL_EXPORT int RSA_marshal_private_key(CBB *cbb, const RSA *rsa);

RSA_private_key_to_bytes marshals rsa as a DER-encoded RSAPrivateKey structure (RFC 8017) and, on success, sets *out_bytes to a newly allocated buffer containing the result and returns one. Otherwise, it returns zero. The result should be freed with OPENSSL_free.

OPENSSL_EXPORT int RSA_private_key_to_bytes(uint8_t **out_bytes,
                                            size_t *out_len, const RSA *rsa);

Obscure RSA variants.

These functions allow creating RSA keys with obscure combinations of parameters.

RSA_new_private_key_no_crt behaves like RSA_new_private_key but constructs an RSA key without CRT coefficients.

Keys created by this function will be less performant and cannot be serialized.

OPENSSL_EXPORT RSA *RSA_new_private_key_no_crt(const BIGNUM *n, const BIGNUM *e,
                                               const BIGNUM *d);

RSA_new_private_key_no_e behaves like RSA_new_private_key but constructs an RSA key without CRT parameters or public exponent.

Keys created by this function will be less performant, cannot be serialized, and lack hardening measures that protect against side channels and fault attacks.

OPENSSL_EXPORT RSA *RSA_new_private_key_no_e(const BIGNUM *n, const BIGNUM *d);

RSA_new_public_key_large_e behaves like RSA_new_public_key but allows any e up to n.

BoringSSL typically bounds public exponents as a denial-of-service mitigation. Keys created by this function may perform worse than those created by RSA_new_public_key.

OPENSSL_EXPORT RSA *RSA_new_public_key_large_e(const BIGNUM *n,
                                               const BIGNUM *e);

RSA_new_private_key_large_e behaves like RSA_new_private_key but allows any e up to n.

BoringSSL typically bounds public exponents as a denial-of-service mitigation. Keys created by this function may perform worse than those created by RSA_new_private_key.

OPENSSL_EXPORT RSA *RSA_new_private_key_large_e(
    const BIGNUM *n, const BIGNUM *e, const BIGNUM *d, const BIGNUM *p,
    const BIGNUM *q, const BIGNUM *dmp1, const BIGNUM *dmq1,
    const BIGNUM *iqmp);

ex_data functions.

See ex_data.h for details.

OPENSSL_EXPORT int RSA_get_ex_new_index(long argl, void *argp,
                                        CRYPTO_EX_unused *unused,
                                        CRYPTO_EX_dup *dup_unused,
                                        CRYPTO_EX_free *free_func);
OPENSSL_EXPORT int RSA_set_ex_data(RSA *rsa, int idx, void *arg);
OPENSSL_EXPORT void *RSA_get_ex_data(const RSA *rsa, int idx);

Flags.

RSA_FLAG_OPAQUE specifies that this RSA_METHOD does not expose its key material. This may be set if, for instance, it is wrapping some other crypto API, like a platform key store.

#define RSA_FLAG_OPAQUE 1

RSA_FLAG_NO_BLINDING disables blinding of private operations, which is a dangerous thing to do. This flag is set internally as part of self-tests but is otherwise impossible to set externally.

#define RSA_FLAG_NO_BLINDING 8

RSA_FLAG_EXT_PKEY is deprecated and ignored.

#define RSA_FLAG_EXT_PKEY 0x20

RSA_FLAG_NO_PUBLIC_EXPONENT indicates that private keys without a public exponent are allowed. This is an internal constant. Use RSA_new_private_key_no_e to construct such keys.

#define RSA_FLAG_NO_PUBLIC_EXPONENT 0x40

RSA_FLAG_LARGE_PUBLIC_EXPONENT indicates that keys with a large public exponent are allowed. This is an internal constant. Use RSA_new_public_key_large_e and RSA_new_private_key_large_e to construct such keys.

#define RSA_FLAG_LARGE_PUBLIC_EXPONENT 0x80

RSA public exponent values.

#define RSA_3 0x3
#define RSA_F4 0x10001

Deprecated functions.

#define RSA_METHOD_FLAG_NO_CHECK RSA_FLAG_OPAQUE

RSA_flags returns the flags for rsa. These are a bitwise OR of RSA_FLAG_* constants.

OPENSSL_EXPORT int RSA_flags(const RSA *rsa);

RSA_test_flags returns the subset of flags in flags which are set in rsa.

OPENSSL_EXPORT int RSA_test_flags(const RSA *rsa, int flags);

RSA_blinding_on returns one.

OPENSSL_EXPORT int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);

RSA_blinding_off does nothing.

OPENSSL_EXPORT void RSA_blinding_off(RSA *rsa);

RSA_generate_key behaves like RSA_generate_key_ex, which is what you should use instead. It returns NULL on error, or a newly-allocated RSA on success. This function is provided for compatibility only. The callback and cb_arg parameters must be NULL.

OPENSSL_EXPORT RSA *RSA_generate_key(int bits, uint64_t e, void *callback,
                                     void *cb_arg);

d2i_RSAPublicKey parses a DER-encoded RSAPublicKey structure (RFC 8017) from len bytes at *inp, as described in d2i_SAMPLE.

Use RSA_parse_public_key instead.

OPENSSL_EXPORT RSA *d2i_RSAPublicKey(RSA **out, const uint8_t **inp, long len);

i2d_RSAPublicKey marshals in to a DER-encoded RSAPublicKey structure (RFC 8017), as described in i2d_SAMPLE.

Use RSA_marshal_public_key instead.

OPENSSL_EXPORT int i2d_RSAPublicKey(const RSA *in, uint8_t **outp);

d2i_RSAPrivateKey parses a DER-encoded RSAPrivateKey structure (RFC 8017) from len bytes at *inp, as described in d2i_SAMPLE.

Use RSA_parse_private_key instead.

OPENSSL_EXPORT RSA *d2i_RSAPrivateKey(RSA **out, const uint8_t **inp, long len);

i2d_RSAPrivateKey marshals in to a DER-encoded RSAPrivateKey structure (RFC 8017), as described in i2d_SAMPLE.

Use RSA_marshal_private_key instead.

OPENSSL_EXPORT int i2d_RSAPrivateKey(const RSA *in, uint8_t **outp);

RSA_padding_add_PKCS1_PSS acts like RSA_padding_add_PKCS1_PSS_mgf1 but the mgf1Hash parameter of the latter is implicitly set to Hash.

This function implements only the low-level padding logic. Use RSA_sign_pss_mgf1 instead.

OPENSSL_EXPORT int RSA_padding_add_PKCS1_PSS(const RSA *rsa, uint8_t *EM,
                                             const uint8_t *mHash,
                                             const EVP_MD *Hash, int sLen);

RSA_verify_PKCS1_PSS acts like RSA_verify_PKCS1_PSS_mgf1 but the mgf1Hash parameter of the latter is implicitly set to Hash.

This function implements only the low-level padding logic. Use RSA_verify_pss_mgf1 instead.

OPENSSL_EXPORT int RSA_verify_PKCS1_PSS(const RSA *rsa, const uint8_t *mHash,
                                        const EVP_MD *Hash, const uint8_t *EM,
                                        int sLen);

RSA_padding_add_PKCS1_OAEP acts like RSA_padding_add_PKCS1_OAEP_mgf1 but the md and mgf1md parameters of the latter are implicitly set to NULL, which means SHA-1.

OPENSSL_EXPORT int RSA_padding_add_PKCS1_OAEP(uint8_t *to, size_t to_len,
                                              const uint8_t *from,
                                              size_t from_len,
                                              const uint8_t *param,
                                              size_t param_len);

RSA_print prints a textual representation of rsa to bio. It returns one on success or zero otherwise.

OPENSSL_EXPORT int RSA_print(BIO *bio, const RSA *rsa, int indent);

RSA_get0_pss_params returns NULL. In OpenSSL, this function retries RSA-PSS parameters associated with RSA objects, but BoringSSL does not support the id-RSASSA-PSS key encoding.

OPENSSL_EXPORT const RSA_PSS_PARAMS *RSA_get0_pss_params(const RSA *rsa);

RSA_new_method_no_e returns a newly-allocated RSA object backed by engine, with a public modulus of n and no known public exponent.

Do not use this function. It exists only to support Conscrypt, whose use should be replaced with a more sound mechanism. See https://crbug.com/boringssl/602.

OPENSSL_EXPORT RSA *RSA_new_method_no_e(const ENGINE *engine, const BIGNUM *n);
struct rsa_meth_st {
  struct openssl_method_common_st common;

  void *app_data;

  int (*init)(RSA *rsa);
  int (*finish)(RSA *rsa);

  // size returns the size of the RSA modulus in bytes.
  size_t (*size)(const RSA *rsa);

  int (*sign)(int type, const uint8_t *m, unsigned int m_length,
              uint8_t *sigret, unsigned int *siglen, const RSA *rsa);

  // These functions mirror the |RSA_*| functions of the same name.
  int (*sign_raw)(RSA *rsa, size_t *out_len, uint8_t *out, size_t max_out,
                  const uint8_t *in, size_t in_len, int padding);
  int (*decrypt)(RSA *rsa, size_t *out_len, uint8_t *out, size_t max_out,
                 const uint8_t *in, size_t in_len, int padding);

  // private_transform takes a big-endian integer from |in|, calculates the
  // d'th power of it, modulo the RSA modulus and writes the result as a
  // big-endian integer to |out|. Both |in| and |out| are |len| bytes long and
  // |len| is always equal to |RSA_size(rsa)|. If the result of the transform
  // can be represented in fewer than |len| bytes, then |out| must be zero
  // padded on the left.
  //
  // It returns one on success and zero otherwise.
  //
  // RSA decrypt and sign operations will call this, thus an ENGINE might wish
  // to override it in order to avoid having to implement the padding
  // functionality demanded by those, higher level, operations.
  int (*private_transform)(RSA *rsa, uint8_t *out, const uint8_t *in,
                           size_t len);

  int flags;
};