Extend docs for EC_POINT conversion functions

Add more explicit documentation about the relation between
EC_POINT_point2oct(), EC_POINT_point2hex(), EC_POINT_point2bn() and
their reverse.

In particular highlight that EC_POINT_point2oct() and
EC_POINT_oct2point() conform to, respectively, Sec. 2.3.3 and Sec. 2.3.4
of the SECG SEC 1 standard (which is the normative reference for the
already mentioned RFC 5480), highlighting with a note how this affect
the encoding/decoding of the point at infinity (which in contrast with
any other valid generic point of a curve is assigned an exceptional
fixed octet string encoding, i.e., 0x00).

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/10329)

diff --git a/doc/man3/EC_POINT_new.pod b/doc/man3/EC_POINT_new.pod
index 42eaddd460c42da0b4b1407ad827300908a82404..f941446fd5c99a89959294dcd3ab7500d2fbb2ee 100644 (file)
--- a/doc/man3/EC_POINT_new.pod
+++ b/doc/man3/EC_POINT_new.pod
@@ -171,6 +171,26 @@ 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, BIGNUM and hexadecimal respectively.
 
+The function EC_POINT_point2oct() encodes the given curve point B<p> as an
+octet string into the buffer B<buf> of size B<len>, using the specified
+conversion form B<form>.
+The encoding conforms with Sec. 2.3.3 of the SECG SEC 1 ("Elliptic Curve
+Cryptography") standard.
+Similarly the function EC_POINT_oct2point() decodes a curve point into B<p> from
+the octet string contained in the given buffer B<buf> of size B<len>, conforming
+to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic Curve Cryptography") standard.
+
+The functions EC_POINT_point2hex() and EC_POINT_point2bn() convert a point B<p>,
+respectively, to the hexadecimal or BIGNUM representation of the same
+encoding of the function EC_POINT_point2oct().
+Vice versa, similarly to the function EC_POINT_oct2point(), the functions
+EC_POINT_hex2point() and EC_POINT_point2bn() decode the hexadecimal or
+BIGNUM representation into the EC_POINT B<p>.
+
+Notice that, according to the standard, the octet string encoding of the point
+at infinity for a given curve is fixed to a single octet of value zero and that,
+vice versa, a single octet of size zero is decoded as the point at infinity.
+
 The function EC_POINT_point2oct() 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 NULL buffer will not perform the conversion but