Deprecate the EC curve type specific functions in 1.2.0
[openssl.git] / doc / man3 / EC_POINT_new.pod
index 206648c..796f666 100644 (file)
@@ -2,16 +2,30 @@
 
 =head1 NAME
 
-EC_POINT_set_Jprojective_coordinates_GFp, EC_POINT_point2buf,
-EC_POINT_new, EC_POINT_free, EC_POINT_clear_free,
-EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of,
+EC_POINT_set_Jprojective_coordinates_GFp,
+EC_POINT_point2buf,
+EC_POINT_new,
+EC_POINT_free,
+EC_POINT_clear_free,
+EC_POINT_copy,
+EC_POINT_dup,
+EC_POINT_method_of,
 EC_POINT_set_to_infinity,
 EC_POINT_get_Jprojective_coordinates_GFp,
+EC_POINT_set_affine_coordinates,
+EC_POINT_get_affine_coordinates,
+EC_POINT_set_compressed_coordinates,
 EC_POINT_set_affine_coordinates_GFp,
-EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp,
-EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m,
-EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct,
-EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex,
+EC_POINT_get_affine_coordinates_GFp,
+EC_POINT_set_compressed_coordinates_GFp,
+EC_POINT_set_affine_coordinates_GF2m,
+EC_POINT_get_affine_coordinates_GF2m,
+EC_POINT_set_compressed_coordinates_GF2m,
+EC_POINT_point2oct,
+EC_POINT_oct2point,
+EC_POINT_point2bn,
+EC_POINT_bn2point,
+EC_POINT_point2hex,
 EC_POINT_hex2point
 - Functions for creating, destroying and manipulating EC_POINT objects
 
@@ -34,6 +48,14 @@ EC_POINT_hex2point
                                               const EC_POINT *p,
                                               BIGNUM *x, BIGNUM *y, BIGNUM *z,
                                               BN_CTX *ctx);
+ int EC_POINT_set_affine_coordinates(const EC_GROUP *group, EC_POINT *p,
+                                     const BIGNUM *x, const BIGNUM *y,
+                                     BN_CTX *ctx);
+ int EC_POINT_get_affine_coordinates(const EC_GROUP *group, const EC_POINT *p,
+                                     BIGNUM *x, BIGNUM *y, BN_CTX *ctx);
+ int EC_POINT_set_compressed_coordinates(const EC_GROUP *group, EC_POINT *p,
+                                         const BIGNUM *x, int y_bit,
+                                         BN_CTX *ctx);
  int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p,
                                          const BIGNUM *x, const BIGNUM *y,
                                          BN_CTX *ctx);
@@ -97,9 +119,20 @@ 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().
 
 The affine co-ordinates for a point describe a point in terms of its x and y
-position. The functions EC_POINT_set_affine_coordinates_GFp() and
-EC_POINT_set_affine_coordinates_GF2m() set the B<x> and B<y> co-ordinates for
-the point B<p> defined over the curve given in B<group>.
+position. The function EC_POINT_set_affine_coordinates() sets the B<x> and B<y>
+co-ordinates for the point B<p> defined over the curve given in B<group>. The
+function EC_POINT_get_affine_coordinates() sets B<x> and B<y>, either of which
+may be NULL, to the corresponding coordinates of B<p>.
+
+The functions EC_POINT_set_affine_coordinates_GFp() and
+EC_POINT_set_affine_coordinates_GF2m() are synonyms for
+EC_POINT_set_affine_coordinates(). They are defined for backwards compatibility
+only and should not be used.
+
+The functions EC_POINT_get_affine_coordinates_GFp() and
+EC_POINT_get_affine_coordinates_GF2m() are synonyms for
+EC_POINT_get_affine_coordinates(). They are defined for backwards compatibility
+only and should not be used.
 
 As well as the affine co-ordinates, a point can alternatively be described in
 terms of its Jacobian projective co-ordinates (for Fp curves only). Jacobian
@@ -116,11 +149,15 @@ EC_POINT_get_Jprojective_coordinates_GFp() respectively.
 Points can also be described in terms of their compressed co-ordinates. For a
 point (x, y), for any given value for x such that the point is on the curve
 there will only ever be two possible values for y. Therefore a point can be set
-using the EC_POINT_set_compressed_coordinates_GFp() and
-EC_POINT_set_compressed_coordinates_GF2m() functions where B<x> is the x
+using the EC_POINT_set_compressed_coordinates() function where B<x> is the x
 co-ordinate and B<y_bit> is a value 0 or 1 to identify which of the two
 possible values for y should be used.
 
+The functions EC_POINT_set_compressed_coordinates_GFp() and
+EC_POINT_set_compressed_coordinates_GF2m() are synonyms for
+EC_POINT_set_compressed_coordinates(). They are defined for backwards
+compatibility only and should not be used.
+
 In addition B<EC_POINT> can be converted to and from various external
 representations. The octet form is the binary encoding of the B<ECPoint>
 structure (as defined in RFC5480 and used in certificates and TLS records):
@@ -164,7 +201,7 @@ EC_POINT_set_compressed_coordinates_GF2m() and EC_POINT_oct2point().
 
 EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT.
 
-EC_POINT_point2oct() and EC_point2buf() return the length of the required
+EC_POINT_point2oct() and EC_POINT_point2buf() return the length of the required
 buffer or 0 on error.
 
 EC_POINT_point2bn() returns the pointer to the BIGNUM supplied, or NULL on
@@ -180,13 +217,13 @@ error.
 
 =head1 SEE ALSO
 
-L<crypto(3)>, L<ec(3)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
+L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>,
 L<EC_POINT_add(3)>, L<EC_KEY_new(3)>,
 L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy