Move EC_METHOD to internal-only

Reviewed-by: Nicola Tuveri <nic.tuv@gmail.com>
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11928)

4 files changed, 46 insertions, 18 deletions

diff --git a/doc/man3/EC_GFp_simple_method.pod b/doc/man3/EC_GFp_simple_method.pod
index 4d8f1fbaf0..cbdb6ec1c3 100644
--- a/doc/man3/EC_GFp_simple_method.pod
+++ b/doc/man3/EC_GFp_simple_method.pod
@@ -8,6 +8,8 @@ EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_me
 
  #include <openssl/ec.h>
 
+Deprecated since OpenSSL 3.0:
+
  const EC_METHOD *EC_GFp_simple_method(void);
  const EC_METHOD *EC_GFp_mont_method(void);
  const EC_METHOD *EC_GFp_nist_method(void);
@@ -21,6 +23,10 @@ EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_me
 
 =head1 DESCRIPTION
 
+
+All const EC_METHOD *EC_GF* functions were deprecated in OpenSSL 3.0, since
+EC_METHOD is no longer a public concept.
+
 The Elliptic Curve library provides a number of different implementations through a single common interface.
 When constructing a curve using EC_GROUP_new (see L<EC_GROUP_new(3)>) an
 implementation method must be provided. The functions described here all return a const pointer to an
@@ -39,10 +45,8 @@ The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521
 optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these
 implementations are not available on all platforms.
 
-EC_METHOD_get_field_type identifies what type of field the EC_METHOD structure supports, which will be either
-F2^m or Fp. If the field type is Fp then the value B<NID_X9_62_prime_field> is returned. If the field type is
-F2^m then the value B<NID_X9_62_characteristic_two_field> is returned. These values are defined in the
-obj_mac.h header file.
+EC_METHOD_get_field_type() was deprecated in OpenSSL 3.0.
+Applications should use EC_GROUP_get_field_type() as a replacement (see L<EC_GROUP_copy(3)>).
 
 =head1 RETURN VALUES
 
@@ -57,6 +61,14 @@ L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
 L<d2i_ECPKParameters(3)>,
 L<BN_mod_mul_montgomery(3)>
 
+=head1 HISTORY
+
+EC_GFp_simple_method(), EC_GFp_mont_method(void),
+EC_GFp_nist_method(), EC_GFp_nistp224_method(),
+EC_GFp_nistp256_method(), EC_GFp_nistp521_method(),
+EC_GF2m_simple_method(), and EC_METHOD_get_field_type()
+were deprecated in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/EC_GROUP_copy.pod b/doc/man3/EC_GROUP_copy.pod
index e9a1d183ca..6f33481856 100644
--- a/doc/man3/EC_GROUP_copy.pod
+++ b/doc/man3/EC_GROUP_copy.pod
@@ -22,8 +22,6 @@ EC_GROUP_get_pentanomial_basis, EC_GROUP_get0_field
  int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src);
  EC_GROUP *EC_GROUP_dup(const EC_GROUP *src);
 
- const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group);
-
  int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator,
                             const BIGNUM *order, const BIGNUM *cofactor);
  const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group);
@@ -63,6 +61,10 @@ EC_GROUP_get_pentanomial_basis, EC_GROUP_get0_field
  int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1,
                                     unsigned int *k2, unsigned int *k3);
 
+Deprecated since OpenSSL 3.0:
+
+ const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group);
+
 =head1 DESCRIPTION
 
 EC_GROUP_copy() copies the curve B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD.
@@ -71,6 +73,7 @@ EC_GROUP_dup() creates a new EC_GROUP object and copies the content from B<src>
 EC_GROUP object.
 
 EC_GROUP_method_of() obtains the EC_METHOD of B<group>.
+This function was deprecated in OpenSSL 3.0, since EC_METHOD is no longer a public concept.
 
 EC_GROUP_set_generator() sets curve parameters that must be agreed by all participants using the curve. These
 parameters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the
@@ -140,8 +143,12 @@ built-in curves within the library provide seed values that can be obtained. It
 EC_GROUP_set_seed() and passing a pointer to a memory block, along with the length of the seed. Again, the EC library will not use
 this seed value, although it will be preserved in any ASN1 based communications.
 
-EC_GROUP_get_degree() gets the degree of the field. For Fp fields this will be the number of bits in p.  For F2^m fields this will be
-the value m.
+EC_GROUP_get_degree() gets the degree of the field.
+For Fp fields this will be the number of bits in p.
+For F2^m fields this will be the value m.
+
+EC_GROUP_get_field_type() identifies what type of field the EC_GROUP structure supports,
+which will be either F2^m or Fp.
 
 The function EC_GROUP_check_discriminant() calculates the discriminant for the curve and verifies that it is valid.
 For a curve defined over Fp the discriminant is given by the formula 4*a^3 + 27*b^2 whilst for F2^m curves the discriminant is
@@ -202,6 +209,10 @@ EC_GROUP_get_point_conversion_form() returns the point_conversion_form for B<gro
 
 EC_GROUP_get_degree() returns the degree for B<group> or 0 if the operation is not supported by the underlying group implementation.
 
+EC_GROUP_get_field_type() returns either B<NID_X9_62_prime_field> for prime curves
+or B<NID_X9_62_characteristic_two_field> for binary curves;
+these values are defined in the obj_mac.h header file.
+
 EC_GROUP_check_named_curve() returns the nid of the matching named curve, otherwise it returns 0 for no match, or -1 on error.
 
 EC_GROUP_get0_order() returns an internal pointer to the group order.
@@ -229,7 +240,9 @@ L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
 
 =head1 HISTORY
 
-The EC_GROUP_check_named_curve() function was added in OpenSSL 3.0.
+EC_GROUP_method_of() was deprecated in OpenSSL 3.0.
+
+EC_GROUP_check_named_curve() and EC_GROUP_get_field_type() were added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/EC_GROUP_new.pod b/doc/man3/EC_GROUP_new.pod
index 08bbd80b08..7bea1dd061 100644
--- a/doc/man3/EC_GROUP_new.pod
+++ b/doc/man3/EC_GROUP_new.pod
@@ -4,7 +4,6 @@
 
 EC_GROUP_get_ecparameters,
 EC_GROUP_get_ecpkparameters,
-EC_GROUP_new_ex,
 EC_GROUP_new,
 EC_GROUP_new_from_ecparameters,
 EC_GROUP_new_from_ecpkparameters,
@@ -27,8 +26,6 @@ objects
 
  #include <openssl/ec.h>
 
- EC_GROUP *EC_GROUP_new_ex(OPENSSL_CTX *libctx, const EC_METHOD *meth);
- EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
  EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params)
  EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params)
  void EC_GROUP_free(EC_GROUP *group);
@@ -62,6 +59,7 @@ 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)>:
 
+ EC_GROUP *EC_GROUP_new(const EC_METHOD *meth);
  void EC_GROUP_clear_free(EC_GROUP *group);
 
 =head1 DESCRIPTION
@@ -83,20 +81,20 @@ Operations in a binary field are performed relative to an
 B<irreducible polynomial>. All such curves with OpenSSL use a trinomial or a
 pentanomial for this parameter.
 
-A new curve can be constructed by calling EC_GROUP_new_ex(), using the
+Although deprecated since OpenSSL 3.0 and should no longer be used,
+a new curve can be constructed by calling EC_GROUP_new(), using the
 implementation provided by B<meth> (see L<EC_GFp_simple_method(3)>) and
 associated with the library context B<ctx> (see L<OPENSSL_CTX(3)>).
 The B<ctx> parameter may be NULL in which case the default library context is
 used.
 It is then necessary to call EC_GROUP_set_curve() to set the curve parameters.
+Applications should instead use one of the other EC_GROUP_new_* constructors.
+
 EC_GROUP_new_from_ecparameters() will create a group from the
 specified B<params> and
 EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK
 B<params>.
 
-EC_GROUP_new() is the same as EC_GROUP_new_ex() except that the library context
-used is always the default library context.
-
 EC_GROUP_set_curve() sets the curve parameters B<p>, B<a> and B<b>. For a curve
 over Fp B<p> is the prime for the field. For a curve over F2^m B<p> represents
 the irreducible polynomial - each bit represents a term in the polynomial.
@@ -182,7 +180,9 @@ L<OPENSSL_CTX(3)>
 
 =item *
 
-EC_GROUP_new_ex() and EC_GROUP_new_by_curve_name_ex() were added in OpenSSL 3.0.
+EC_GROUP_new() was deprecated in OpenSSL 3.0.
+
+EC_GROUP_new_by_curve_name_ex() was added in OpenSSL 3.0.
 
 =item *
 
diff --git a/doc/man3/EC_POINT_new.pod b/doc/man3/EC_POINT_new.pod
index ab02d607cd..84b11ee0c0 100644
--- a/doc/man3/EC_POINT_new.pod
+++ b/doc/man3/EC_POINT_new.pod
@@ -38,7 +38,6 @@ EC_POINT_hex2point
  void EC_POINT_clear_free(EC_POINT *point);
  int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src);
  EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group);
- const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);
  int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point);
  int EC_POINT_set_affine_coordinates(const EC_GROUP *group, EC_POINT *p,
                                      const BIGNUM *x, const BIGNUM *y,
@@ -68,6 +67,7 @@ EC_POINT_hex2point
 
 Deprecated since OpenSSL 3.0:
 
+ const EC_METHOD *EC_POINT_method_of(const EC_POINT *point);
  int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group,
                                               EC_POINT *p,
                                               const BIGNUM *x, const BIGNUM *y,
@@ -116,6 +116,8 @@ EC_POINT_dup() creates a new B<EC_POINT> object and copies the content from
 B<src> to the newly created B<EC_POINT> object.
 
 EC_POINT_method_of() obtains the B<EC_METHOD> associated with B<point>.
+This function was deprecated in OpenSSL 3.0, since EC_METHOD is no longer a
+public concept.
 
 A valid point on a curve is the special point at infinity. A point is set to
 be at infinity by calling EC_POINT_set_to_infinity().
@@ -249,6 +251,7 @@ L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
 
 =head1 HISTORY
 
+EC_POINT_method_of(),
 EC_POINT_set_Jprojective_coordinates_GFp(),
 EC_POINT_get_Jprojective_coordinates_GFp(),
 EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(),