diff options
Diffstat (limited to 'secure/lib/libcrypto/man/EC_POINT_new.3')
-rw-r--r-- | secure/lib/libcrypto/man/EC_POINT_new.3 | 225 |
1 files changed, 152 insertions, 73 deletions
diff --git a/secure/lib/libcrypto/man/EC_POINT_new.3 b/secure/lib/libcrypto/man/EC_POINT_new.3 index d9e5be60515e0..8fbf2daf71e56 100644 --- a/secure/lib/libcrypto/man/EC_POINT_new.3 +++ b/secure/lib/libcrypto/man/EC_POINT_new.3 @@ -128,19 +128,18 @@ .rm #[ #] #H #V #F C .\" ======================================================================== .\" -.IX Title "EC_POINT_new 3" -.TH EC_POINT_new 3 "2018-08-14" "1.0.2p" "OpenSSL" +.IX Title "EC_POINT_NEW 3" +.TH EC_POINT_NEW 3 "2018-09-11" "1.1.1" "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_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_set_Jprojective_coordinates, EC_POINT_get_Jprojective_coordinates_GFp, 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 2 +.Vb 1 \& #include <openssl/ec.h> -\& #include <openssl/bn.h> \& \& EC_POINT *EC_POINT_new(const EC_GROUP *group); \& void EC_POINT_free(EC_POINT *point); @@ -149,108 +148,188 @@ EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup, E \& 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_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); +\& 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); +\& const BIGNUM *x, const BIGNUM *y, +\& BN_CTX *ctx); \& int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, -\& const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); -\& int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, -\& const BIGNUM *x, int y_bit, BN_CTX *ctx); +\& const EC_POINT *p, +\& BIGNUM *x, BIGNUM *y, BN_CTX *ctx); +\& int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, +\& EC_POINT *p, +\& const BIGNUM *x, int y_bit, +\& BN_CTX *ctx); \& int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, -\& const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); +\& const BIGNUM *x, const BIGNUM *y, +\& BN_CTX *ctx); \& int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, -\& const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); -\& int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, -\& const BIGNUM *x, int y_bit, BN_CTX *ctx); +\& const EC_POINT *p, +\& BIGNUM *x, BIGNUM *y, BN_CTX *ctx); +\& int EC_POINT_set_compressed_coordinates_GF2m(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); +\& 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 *, const EC_POINT *, -\& point_conversion_form_t form, BIGNUM *, BN_CTX *); -\& EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *, -\& EC_POINT *, BN_CTX *); -\& char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *, -\& point_conversion_form_t form, BN_CTX *); -\& EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *, -\& EC_POINT *, BN_CTX *); +\& 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" -An \s-1EC_POINT\s0 represents a point on a curve. A new point is constructed by calling the function EC_POINT_new and providing the \fBgroup\fR -object that the point relates to. +An \fB\s-1EC_POINT\s0\fR structure represents a point on a curve. A new point is +constructed by calling the function \fIEC_POINT_new()\fR and providing the +\&\fBgroup\fR object that the point relates to. .PP -EC_POINT_free frees the memory associated with the \s-1EC_POINT.\s0 +\&\fIEC_POINT_free()\fR frees the memory associated with the \fB\s-1EC_POINT\s0\fR. +if \fBpoint\fR is \s-1NULL\s0 nothing is done. .PP -EC_POINT_clear_free destroys any sensitive data held within the \s-1EC_POINT\s0 and then frees its memory. +\&\fIEC_POINT_clear_free()\fR destroys any sensitive data held within the \s-1EC_POINT\s0 and +then frees its memory. If \fBpoint\fR is \s-1NULL\s0 nothing is done. .PP -EC_POINT_copy copies the point \fBsrc\fR into \fBdst\fR. Both \fBsrc\fR and \fBdst\fR must use the same \s-1EC_METHOD.\s0 +\&\fIEC_POINT_copy()\fR copies the point \fBsrc\fR into \fBdst\fR. Both \fBsrc\fR and \fBdst\fR +must use the same \fB\s-1EC_METHOD\s0\fR. .PP -EC_POINT_dup creates a new \s-1EC_POINT\s0 object and copies the content from \fBsrc\fR to the newly created -\&\s-1EC_POINT\s0 object. +\&\fIEC_POINT_dup()\fR creates a new \fB\s-1EC_POINT\s0\fR object and copies the content from +\&\fBsrc\fR to the newly created \fB\s-1EC_POINT\s0\fR object. .PP -EC_POINT_method_of obtains the \s-1EC_METHOD\s0 associated with \fBpoint\fR. +\&\fIEC_POINT_method_of()\fR obtains the \fB\s-1EC_METHOD\s0\fR associated with \fBpoint\fR. .PP -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. +A valid point on a curve is the special point at infinity. A point is set to +be at infinity by calling \fIEC_POINT_set_to_infinity()\fR. .PP -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 \fBx\fR and \fBy\fR co-ordinates for the point -\&\fBp\fR defined over the curve given in \fBgroup\fR. +The affine co-ordinates for a point describe a point in terms of its x and y +position. The function \fIEC_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 +function \fIEC_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 -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 to 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 EC_POINT_set_Jprojective_coordinates_GFp and -EC_POINT_get_Jprojective_coordinates_GFp respectively. +The functions \fIEC_POINT_set_affine_coordinates_GFp()\fR and +\&\fIEC_POINT_set_affine_coordinates_GF2m()\fR are synonyms for +\&\fIEC_POINT_set_affine_coordinates()\fR. They are defined for backwards compatibility +only and should not be used. .PP -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 \fBx\fR is the x co-ordinate and \fBy_bit\fR is a value 0 or 1 to identify which of -the two possible values for y should be used. +The functions \fIEC_POINT_get_affine_coordinates_GFp()\fR and +\&\fIEC_POINT_get_affine_coordinates_GF2m()\fR are synonyms for +\&\fIEC_POINT_get_affine_coordinates()\fR. They are defined for backwards compatibility +only and should not be used. .PP -In addition EC_POINTs can be converted to and from various external -representations. Supported representations are octet strings, BIGNUMs and -hexadecimal. Octet strings are stored in a buffer along with an associated -buffer length. A point held in a \s-1BIGNUM\s0 is calculated by converting the point to -an octet string and then converting that octet string into a \s-1BIGNUM\s0 integer. -Points in hexadecimal format are stored in a \s-1NULL\s0 terminated character string -where each character is one of the printable values 0\-9 or A\-F (or a\-f). +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 +\&\fIEC_POINT_set_Jprojective_coordinates_GFp()\fR and +\&\fIEC_POINT_get_Jprojective_coordinates_GFp()\fR respectively. .PP -The functions EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex and EC_POINT_hex2point convert -from and to EC_POINTs for the formats: octet string, \s-1BIGNUM\s0 and hexadecimal 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 \fIEC_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 +possible values for y should be used. .PP -The function EC_POINT_point2oct must be supplied with a buffer long enough to store the octet string. The return value provides the number of -octets stored. Calling the function with a \s-1NULL\s0 buffer will not perform the conversion but will still return the required buffer length. +The functions \fIEC_POINT_set_compressed_coordinates_GFp()\fR and +\&\fIEC_POINT_set_compressed_coordinates_GF2m()\fR are synonyms for +\&\fIEC_POINT_set_compressed_coordinates()\fR. They are defined for backwards +compatibility only and should not be used. .PP -The function EC_POINT_point2hex will allocate sufficient memory to store the hexadecimal string. It is the caller's responsibility to free -this memory with a subsequent call to \fIOPENSSL_free()\fR. +In addition \fB\s-1EC_POINT\s0\fR can be converted to and from various external +representations. The octet form is the binary encoding of the \fBECPoint\fR +structure (as defined in \s-1RFC5480\s0 and used in certificates and \s-1TLS\s0 records): +only the content octets are present, the \fB\s-1OCTET STRING\s0\fR tag and length are +not included. \fB\s-1BIGNUM\s0\fR form is the octet form interpreted as a big endian +integer converted to a \fB\s-1BIGNUM\s0\fR structure. Hexadecimal form is the octet +form converted to a \s-1NULL\s0 terminated character string where each character +is one of the printable values 0\-9 or A\-F (or a\-f). +.PP +The functions \fIEC_POINT_point2oct()\fR, \fIEC_POINT_oct2point()\fR, \fIEC_POINT_point2bn()\fR, +\&\fIEC_POINT_bn2point()\fR, \fIEC_POINT_point2hex()\fR and \fIEC_POINT_hex2point()\fR convert from +and to EC_POINTs for the formats: octet, \s-1BIGNUM\s0 and hexadecimal respectively. +.PP +The function \fIEC_POINT_point2oct()\fR must be supplied with a buffer long enough to +store the octet form. The return value provides the number of octets stored. +Calling the function with a \s-1NULL\s0 buffer will not perform the conversion but +will still return the required buffer length. +.PP +The function \fIEC_POINT_point2buf()\fR allocates a buffer of suitable length and +writes an \s-1EC_POINT\s0 to it in octet format. The allocated buffer is written to +\&\fB*pbuf\fR and its length is returned. The caller must free up the allocated +buffer with a call to \fIOPENSSL_free()\fR. Since the allocated buffer value is +written to \fB*pbuf\fR the \fBpbuf\fR parameter \fB\s-1MUST NOT\s0\fR be \fB\s-1NULL\s0\fR. +.PP +The function \fIEC_POINT_point2hex()\fR will allocate sufficient memory to store the +hexadecimal string. It is the caller's responsibility to free this memory with +a subsequent call to \fIOPENSSL_free()\fR. .SH "RETURN VALUES" .IX Header "RETURN VALUES" -EC_POINT_new and EC_POINT_dup return the newly allocated \s-1EC_POINT\s0 or \s-1NULL\s0 on error. +\&\fIEC_POINT_new()\fR and \fIEC_POINT_dup()\fR return the newly allocated \s-1EC_POINT\s0 or \s-1NULL\s0 +on error. .PP -The following functions return 1 on success or 0 on error: EC_POINT_copy, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates_GFp, -EC_POINT_get_Jprojective_coordinates_GFp, 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 and EC_POINT_oct2point. +The following functions return 1 on success or 0 on error: \fIEC_POINT_copy()\fR, +\&\fIEC_POINT_set_to_infinity()\fR, \fIEC_POINT_set_Jprojective_coordinates_GFp()\fR, +\&\fIEC_POINT_get_Jprojective_coordinates_GFp()\fR, +\&\fIEC_POINT_set_affine_coordinates_GFp()\fR, \fIEC_POINT_get_affine_coordinates_GFp()\fR, +\&\fIEC_POINT_set_compressed_coordinates_GFp()\fR, +\&\fIEC_POINT_set_affine_coordinates_GF2m()\fR, \fIEC_POINT_get_affine_coordinates_GF2m()\fR, +\&\fIEC_POINT_set_compressed_coordinates_GF2m()\fR and \fIEC_POINT_oct2point()\fR. .PP EC_POINT_method_of returns the \s-1EC_METHOD\s0 associated with the supplied \s-1EC_POINT.\s0 .PP -EC_POINT_point2oct returns the length of the required buffer, or 0 on error. +\&\fIEC_POINT_point2oct()\fR and \fIEC_POINT_point2buf()\fR return the length of the required +buffer or 0 on error. .PP -EC_POINT_point2bn returns the pointer to the \s-1BIGNUM\s0 supplied, or \s-1NULL\s0 on error. +\&\fIEC_POINT_point2bn()\fR returns the pointer to the \s-1BIGNUM\s0 supplied, or \s-1NULL\s0 on +error. .PP -EC_POINT_bn2point returns the pointer to the \s-1EC_POINT\s0 supplied, or \s-1NULL\s0 on error. +\&\fIEC_POINT_bn2point()\fR returns the pointer to the \s-1EC_POINT\s0 supplied, or \s-1NULL\s0 on +error. .PP -EC_POINT_point2hex returns a pointer to the hex string, or \s-1NULL\s0 on error. +\&\fIEC_POINT_point2hex()\fR returns a pointer to the hex string, or \s-1NULL\s0 on error. .PP -EC_POINT_hex2point returns the pointer to the \s-1EC_POINT\s0 supplied, or \s-1NULL\s0 on error. +\&\fIEC_POINT_hex2point()\fR returns the pointer to the \s-1EC_POINT\s0 supplied, or \s-1NULL\s0 on +error. .SH "SEE ALSO" .IX Header "SEE ALSO" -\&\fIcrypto\fR\|(3), \fIec\fR\|(3), \fIEC_GROUP_new\fR\|(3), \fIEC_GROUP_copy\fR\|(3), +\&\fIcrypto\fR\|(7), \fIEC_GROUP_new\fR\|(3), \fIEC_GROUP_copy\fR\|(3), \&\fIEC_POINT_add\fR\|(3), \fIEC_KEY_new\fR\|(3), \&\fIEC_GFp_simple_method\fR\|(3), \fId2i_ECPKParameters\fR\|(3) +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright 2013\-2018 The OpenSSL Project Authors. All Rights Reserved. +.PP +Licensed under the OpenSSL license (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>. |