summaryrefslogtreecommitdiff
path: root/secure/lib/libcrypto/man/EC_POINT_new.3
diff options
context:
space:
mode:
Diffstat (limited to 'secure/lib/libcrypto/man/EC_POINT_new.3')
-rw-r--r--secure/lib/libcrypto/man/EC_POINT_new.3225
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>.