diff options
Diffstat (limited to 'secure/lib/libcrypto/man/man3/EC_POINT_new.3')
| -rw-r--r-- | secure/lib/libcrypto/man/man3/EC_POINT_new.3 | 132 |
1 files changed, 91 insertions, 41 deletions
diff --git a/secure/lib/libcrypto/man/man3/EC_POINT_new.3 b/secure/lib/libcrypto/man/man3/EC_POINT_new.3 index 38541d7f5210..7fd7ce29e88c 100644 --- a/secure/lib/libcrypto/man/man3/EC_POINT_new.3 +++ b/secure/lib/libcrypto/man/man3/EC_POINT_new.3 @@ -68,8 +68,6 @@ . \} .\} .rr rF -.\" -.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ @@ -132,14 +130,39 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "EC_POINT_NEW 3" -.TH EC_POINT_NEW 3 "2021-03-25" "1.1.1k" "OpenSSL" +.IX Title "EC_POINT_NEW 3ossl" +.TH EC_POINT_NEW 3ossl "2023-09-19" "3.0.11" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "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_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_hex2point \&\- Functions for creating, destroying and manipulating EC_POINT objects +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_hex2point +\&\- Functions for creating, destroying and manipulating EC_POINT objects .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 @@ -150,16 +173,7 @@ EC_POINT_set_Jprojective_coordinates_GFp, EC_POINT_point2buf, EC_POINT_new, EC_P \& 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_Jprojective_coordinates_GFp(const EC_GROUP *group, -\& EC_POINT *p, -\& const BIGNUM *x, const BIGNUM *y, -\& const BIGNUM *z, BN_CTX *ctx); -\& int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, -\& 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); @@ -168,6 +182,34 @@ EC_POINT_set_Jprojective_coordinates_GFp, EC_POINT_point2buf, EC_POINT_new, EC_P \& int EC_POINT_set_compressed_coordinates(const EC_GROUP *group, EC_POINT *p, \& const BIGNUM *x, int y_bit, \& BN_CTX *ctx); +\& size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, +\& point_conversion_form_t form, +\& unsigned char *buf, size_t len, BN_CTX *ctx); +\& size_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point, +\& point_conversion_form_t form, +\& unsigned char **pbuf, BN_CTX *ctx); +\& int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, +\& const unsigned char *buf, size_t len, BN_CTX *ctx); +\& char *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p, +\& point_conversion_form_t form, BN_CTX *ctx); +\& EC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex, +\& EC_POINT *p, BN_CTX *ctx); +.Ve +.PP +The following functions have been deprecated since OpenSSL 3.0, and can be +hidden entirely by defining \fB\s-1OPENSSL_API_COMPAT\s0\fR with a suitable version value, +see \fBopenssl_user_macros\fR\|(7): +.PP +.Vb 10 +\& 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, +\& const BIGNUM *z, BN_CTX *ctx); +\& int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, +\& const EC_POINT *p, +\& BIGNUM *x, BIGNUM *y, BIGNUM *z, +\& 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); @@ -188,23 +230,11 @@ EC_POINT_set_Jprojective_coordinates_GFp, EC_POINT_point2buf, EC_POINT_new, EC_P \& EC_POINT *p, \& const BIGNUM *x, int y_bit, \& BN_CTX *ctx); -\& size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, -\& point_conversion_form_t form, -\& unsigned char *buf, size_t len, BN_CTX *ctx); -\& size_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point, -\& point_conversion_form_t form, -\& unsigned char **pbuf, BN_CTX *ctx); -\& int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, -\& const unsigned char *buf, size_t len, BN_CTX *ctx); \& BIGNUM *EC_POINT_point2bn(const EC_GROUP *group, const EC_POINT *p, \& point_conversion_form_t form, BIGNUM *bn, \& BN_CTX *ctx); \& EC_POINT *EC_POINT_bn2point(const EC_GROUP *group, const BIGNUM *bn, \& EC_POINT *p, BN_CTX *ctx); -\& char *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p, -\& point_conversion_form_t form, BN_CTX *ctx); -\& EC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex, -\& EC_POINT *p, BN_CTX *ctx); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" @@ -225,13 +255,15 @@ must use the same \fB\s-1EC_METHOD\s0\fR. \&\fBsrc\fR to the newly created \fB\s-1EC_POINT\s0\fR object. .PP \&\fBEC_POINT_method_of()\fR obtains the \fB\s-1EC_METHOD\s0\fR associated with \fBpoint\fR. +This function was deprecated in OpenSSL 3.0, since \s-1EC_METHOD\s0 is no longer a +public concept. .PP A valid point on a curve is the special point at infinity. A point is set to be at infinity by calling \fBEC_POINT_set_to_infinity()\fR. .PP -The affine co-ordinates for a point describe a point in terms of its x and y +The affine coordinates for a point describe a point in terms of its x and y position. The function \fBEC_POINT_set_affine_coordinates()\fR sets the \fBx\fR and \fBy\fR -co-ordinates for the point \fBp\fR defined over the curve given in \fBgroup\fR. The +coordinates for the point \fBp\fR defined over the curve given in \fBgroup\fR. The function \fBEC_POINT_get_affine_coordinates()\fR sets \fBx\fR and \fBy\fR, either of which may be \s-1NULL,\s0 to the corresponding coordinates of \fBp\fR. .PP @@ -245,23 +277,27 @@ The functions \fBEC_POINT_get_affine_coordinates_GFp()\fR and \&\fBEC_POINT_get_affine_coordinates()\fR. They are defined for backwards compatibility only and should not be used. .PP -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 -projective co-ordinates are expressed as three values x, y and z. Working in -this co-ordinate system provides more efficient point multiplication -operations. A mapping exists between Jacobian projective co-ordinates and -affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written -as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian -projective from affine co-ordinates is simple. The co-ordinate (x, y) is mapped -to (x, y, 1). To set or get the projective co-ordinates use +As well as the affine coordinates, a point can alternatively be described in +terms of its Jacobian projective coordinates (for Fp curves only). Jacobian +projective coordinates are expressed as three values x, y and z. Working in +this coordinate system provides more efficient point multiplication +operations. A mapping exists between Jacobian projective coordinates and +affine coordinates. A Jacobian projective coordinate (x, y, z) can be written +as an affine coordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian +projective from affine coordinates is simple. The coordinate (x, y) is mapped +to (x, y, 1). Although deprecated in OpenSSL 3.0 and should no longer be used, +to set or get the projective coordinates in older versions use \&\fBEC_POINT_set_Jprojective_coordinates_GFp()\fR and \&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR respectively. +Modern versions should instead use \fBEC_POINT_set_affine_coordinates()\fR and +\&\fBEC_POINT_get_affine_coordinates()\fR, performing the conversion manually using the +above maps in such rare circumstances. .PP -Points can also be described in terms of their compressed co-ordinates. For a +Points can also be described in terms of their compressed coordinates. 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 \fBEC_POINT_set_compressed_coordinates()\fR function where \fBx\fR is the x -co-ordinate and \fBy_bit\fR is a value 0 or 1 to identify which of the two +coordinate and \fBy_bit\fR is a value 0 or 1 to identify which of the two possible values for y should be used. .PP The functions \fBEC_POINT_set_compressed_coordinates_GFp()\fR and @@ -349,11 +385,25 @@ error. \&\fBcrypto\fR\|(7), \fBEC_GROUP_new\fR\|(3), \fBEC_GROUP_copy\fR\|(3), \&\fBEC_POINT_add\fR\|(3), \fBEC_KEY_new\fR\|(3), \&\fBEC_GFp_simple_method\fR\|(3), \fBd2i_ECPKParameters\fR\|(3) +.SH "HISTORY" +.IX Header "HISTORY" +\&\fBEC_POINT_method_of()\fR, +\&\fBEC_POINT_set_Jprojective_coordinates_GFp()\fR, +\&\fBEC_POINT_get_Jprojective_coordinates_GFp()\fR, +\&\fBEC_POINT_set_affine_coordinates_GFp()\fR, \fBEC_POINT_get_affine_coordinates_GFp()\fR, +\&\fBEC_POINT_set_compressed_coordinates_GFp()\fR, +\&\fBEC_POINT_set_affine_coordinates_GF2m()\fR, \fBEC_POINT_get_affine_coordinates_GF2m()\fR, +\&\fBEC_POINT_set_compressed_coordinates_GF2m()\fR, +\&\fBEC_POINT_point2bn()\fR, and \fBEC_POINT_bn2point()\fR were deprecated in OpenSSL 3.0. +.PP +\&\fBEC_POINT_set_affine_coordinates\fR, \fBEC_POINT_get_affine_coordinates\fR, +and \fBEC_POINT_set_compressed_coordinates\fR were +added in OpenSSL 1.1.1. .SH "COPYRIGHT" .IX Header "COPYRIGHT" -Copyright 2013\-2020 The OpenSSL Project Authors. All Rights Reserved. +Copyright 2013\-2023 The OpenSSL Project Authors. All Rights Reserved. .PP -Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use +Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>. |