rsa: document deprecated low level functions
authorPauli <paul.dale@oracle.com>
Wed, 12 Feb 2020 05:23:01 +0000 (15:23 +1000)
committerPauli <paul.dale@oracle.com>
Thu, 20 Feb 2020 08:58:40 +0000 (18:58 +1000)
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11063)

doc/man3/RSA_check_key.pod
doc/man3/RSA_generate_key.pod
doc/man3/RSA_meth_new.pod
doc/man3/RSA_padding_add_PKCS1_type_1.pod
doc/man3/RSA_private_encrypt.pod
doc/man3/RSA_public_encrypt.pod
doc/man3/RSA_set_method.pod
doc/man3/RSA_sign.pod
doc/man3/RSA_sign_ASN1_OCTET_STRING.pod
doc/man3/RSA_size.pod

index fb7bd23..137ec7e 100644 (file)
@@ -8,12 +8,20 @@ RSA_check_key_ex, RSA_check_key - validate private RSA keys
 
  #include <openssl/rsa.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  int RSA_check_key_ex(RSA *rsa, BN_GENCB *cb);
 
  int RSA_check_key(RSA *rsa);
 
 =head1 DESCRIPTION
 
+Both of the functions described on this page are deprecated.
+Applications should instead use L<EVP_PKEY_public_check(3)>,
+L<EVP_PKEY_private_check(3)> and L<EVP_PKEY_pairwise_check(3)>.
+
 RSA_check_key_ex() function validates RSA keys.
 It checks that B<p> and B<q> are
 in fact prime, and that B<n = p*q>.
@@ -70,6 +78,8 @@ L<ERR_get_error(3)>
 
 =head1 HISTORY
 
+All of these functions were deprecated in OpenSSL 3.0.
+
 RSA_check_key_ex() appeared after OpenSSL 1.0.2.
 
 =head1 COPYRIGHT
index 9d8b422..110880f 100644 (file)
@@ -9,6 +9,10 @@ RSA_generate_multi_prime_key - generate RSA key pair
 
  #include <openssl/rsa.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb);
  int RSA_generate_multi_prime_key(RSA *rsa, int bits, int primes, BIGNUM *e, BN_GENCB *cb);
 
@@ -21,6 +25,10 @@ L<openssl_user_macros(7)>:
 
 =head1 DESCRIPTION
 
+All of the functions described on this page are deprecated.
+Applications should instead use L<EVP_PKEY_keygen_init(3)> and
+L<EVP_PKEY_keygen(3)>.
+
 RSA_generate_key_ex() generates a 2-prime RSA key pair and stores it in the
 B<RSA> structure provided in B<rsa>. The pseudo-random number generator must
 be seeded prior to calling RSA_generate_key_ex().
@@ -95,6 +103,8 @@ L<RAND(7)>
 
 =head1 HISTORY
 
+All of these functions were deprecated in OpenSSL 3.0.
+
 RSA_generate_key() was deprecated in OpenSSL 0.9.8; use
 RSA_generate_key_ex() instead.
 
index 100c64c..a6a5f47 100644 (file)
@@ -20,6 +20,10 @@ RSA_meth_get_multi_prime_keygen, RSA_meth_set_multi_prime_keygen
 
  #include <openssl/rsa.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  RSA_METHOD *RSA_meth_new(const char *name, int flags);
  void RSA_meth_free(RSA_METHOD *meth);
 
@@ -123,6 +127,9 @@ RSA_meth_get_multi_prime_keygen, RSA_meth_set_multi_prime_keygen
 
 =head1 DESCRIPTION
 
+All of the functions described on this page are deprecated.
+Applications should instead use the OSSL_PROVIDER APIs.
+
 The B<RSA_METHOD> type is a structure used for the provision of custom
 RSA implementations. It provides a set of functions used by OpenSSL
 for the implementation of the various RSA capabilities.
@@ -244,6 +251,8 @@ L<RSA_generate_multi_prime_key(3)>
 
 =head1 HISTORY
 
+All of these functions were deprecated in OpenSSL 3.0.
+
 RSA_meth_get_multi_prime_keygen() and RSA_meth_set_multi_prime_keygen() were
 added in OpenSSL 1.1.1.
 
index 6e679bb..0a7b5c3 100644 (file)
@@ -14,6 +14,10 @@ padding
 
  #include <openssl/rsa.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  int RSA_padding_add_PKCS1_type_1(unsigned char *to, int tlen,
                                   const unsigned char *f, int fl);
 
@@ -58,6 +62,9 @@ padding
 
 =head1 DESCRIPTION
 
+All of the functions described on this page are deprecated.
+Applications should instead use the EVP PKEY APIs.
+
 The RSA_padding_xxx_xxx() functions are called from the RSA encrypt,
 decrypt, sign and verify functions. Normally they should not be called
 from application programs.
@@ -148,6 +155,10 @@ L<RSA_private_decrypt(3)>,
 L<RSA_sign(3)>, L<RSA_verify(3)>,
 L<RAND(7)>
 
+=head1 HISTORY
+
+All of these functions were deprecated in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
index 2df8bce..6589bb6 100644 (file)
@@ -8,6 +8,10 @@ RSA_private_encrypt, RSA_public_decrypt - low level signature operations
 
  #include <openssl/rsa.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  int RSA_private_encrypt(int flen, unsigned char *from,
                          unsigned char *to, RSA *rsa, int padding);
 
@@ -16,6 +20,10 @@ RSA_private_encrypt, RSA_public_decrypt - low level signature operations
 
 =head1 DESCRIPTION
 
+Both of the functions described on this page are deprecated.
+Applications should instead use L<EVP_PKEY_encrypt_init(3)>,
+L<EVP_PKEY_encrypt(3)>, L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)>.
+
 These functions handle RSA signatures at a low level.
 
 RSA_private_encrypt() signs the B<flen> bytes at B<from> (usually a
@@ -62,6 +70,10 @@ obtained by L<ERR_get_error(3)>.
 L<ERR_get_error(3)>,
 L<RSA_sign(3)>, L<RSA_verify(3)>
 
+=head1 HISTORY
+
+Both of these functions were deprecated in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
index 09f26eb..dbd4c55 100644 (file)
@@ -8,6 +8,10 @@ RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography
 
  #include <openssl/rsa.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  int RSA_public_encrypt(int flen, const unsigned char *from,
                         unsigned char *to, RSA *rsa, int padding);
 
@@ -16,6 +20,10 @@ RSA_public_encrypt, RSA_private_decrypt - RSA public key cryptography
 
 =head1 DESCRIPTION
 
+Both of the functions described on this page are deprecated.
+Applications should instead use L<EVP_PKEY_encrypt_init(3)>,
+L<EVP_PKEY_encrypt(3)>, L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)>.
+
 RSA_public_encrypt() encrypts the B<flen> bytes at B<from> (usually a
 session key) using the public key B<rsa> and stores the ciphertext in
 B<to>. B<to> must point to RSA_size(B<rsa>) bytes of memory.
@@ -97,6 +105,10 @@ SSL, PKCS #1 v2.0
 L<ERR_get_error(3)>, L<RAND_bytes(3)>,
 L<RSA_size(3)>
 
+=head1 HISTORY
+
+Both of these functions were deprecated in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
index 77af35f..7296378 100644 (file)
@@ -10,6 +10,10 @@ RSA_new_method - select RSA method
 
  #include <openssl/rsa.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  void RSA_set_default_method(const RSA_METHOD *meth);
 
  RSA_METHOD *RSA_get_default_method(void);
@@ -26,6 +30,9 @@ RSA_new_method - select RSA method
 
 =head1 DESCRIPTION
 
+All of the functions described on this page are deprecated.
+Applications should instead use the OSSL_PROVIDER APIs.
+
 An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA
 operations. By modifying the method, alternative implementations such as
 hardware accelerators may be used. IMPORTANT: See the NOTES section for
@@ -171,6 +178,8 @@ L<RSA_new(3)>
 
 =head1 HISTORY
 
+All of these functions were deprecated in OpenSSL 3.0.
+
 The RSA_null_method(), which was a partial attempt to avoid patent issues,
 was replaced to always return NULL in OpenSSL 1.1.1.
 
index a459f2b..2cc50a6 100644 (file)
@@ -8,6 +8,10 @@ RSA_sign, RSA_verify - RSA signatures
 
  #include <openssl/rsa.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  int RSA_sign(int type, const unsigned char *m, unsigned int m_len,
               unsigned char *sigret, unsigned int *siglen, RSA *rsa);
 
@@ -16,6 +20,10 @@ RSA_sign, RSA_verify - RSA signatures
 
 =head1 DESCRIPTION
 
+All of the functions described on this page are deprecated.
+Applications should instead use L<EVP_PKEY_sign_init(3)>, L<EVP_PKEY_sign(3)>,
+L<EVP_PKEY_verify_init(3)> and L<EVP_PKEY_verify(3)>.
+
 RSA_sign() signs the message digest B<m> of size B<m_len> using the
 private key B<rsa> using RSASSA-PKCS1-v1_5 as specified in RFC 3447. It
 stores the signature in B<sigret> and the signature size in B<siglen>.
@@ -53,6 +61,10 @@ L<ERR_get_error(3)>,
 L<RSA_private_encrypt(3)>,
 L<RSA_public_decrypt(3)>
 
+=head1 HISTORY
+
+All of these functions were deprecated in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
index 27e7cdf..7a15686 100644 (file)
@@ -8,6 +8,10 @@ RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA signatures
 
  #include <openssl/rsa.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m,
                                 unsigned int m_len, unsigned char *sigret,
                                 unsigned int *siglen, RSA *rsa);
@@ -18,6 +22,9 @@ RSA_sign_ASN1_OCTET_STRING, RSA_verify_ASN1_OCTET_STRING - RSA signatures
 
 =head1 DESCRIPTION
 
+All of the functions described on this page are deprecated.
+Applications should instead use EVP PKEY APIs.
+
 RSA_sign_ASN1_OCTET_STRING() signs the octet string B<m> of size
 B<m_len> using the private key B<rsa> represented in DER using PKCS #1
 padding. It stores the signature in B<sigret> and the signature size
@@ -55,6 +62,10 @@ L<RAND_bytes(3)>, L<RSA_sign(3)>,
 L<RSA_verify(3)>,
 L<RAND(7)>
 
+=head1 HISTORY
+
+All of these functions were deprecated in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
index ccc11ba..15db17c 100644 (file)
@@ -8,6 +8,10 @@ RSA_size, RSA_bits, RSA_security_bits - get RSA modulus size or security bits
 
  #include <openssl/rsa.h>
 
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  int RSA_size(const RSA *rsa);
 
  int RSA_bits(const RSA *rsa);
@@ -16,6 +20,10 @@ RSA_size, RSA_bits, RSA_security_bits - get RSA modulus size or security bits
 
 =head1 DESCRIPTION
 
+All of the functions described on this page are deprecated.
+Applications should instead use L<EVP_PKEY_size(3)>, L<EVP_PKEY_bits(3)>
+and L<EVP_PKEY_security_bits(3)>.
+
 RSA_size() returns the RSA modulus size in bytes. It can be used to
 determine how much memory must be allocated for an RSA encrypted
 value.
@@ -41,6 +49,8 @@ L<BN_num_bits(3)>
 
 =head1 HISTORY
 
+All of these functions were deprecated in OpenSSL 3.0.
+
 The RSA_bits() function was added in OpenSSL 1.1.0.
 
 =head1 COPYRIGHT