From 609d4fc18811e24ddced7c997c9f7967125719a7 Mon Sep 17 00:00:00 2001
From: tb <tb@openbsd.org>
Date: Wed, 28 Jun 2023 18:07:07 +0000
Subject: [PATCH] Adjust EC_GROUP_get_basis_type() documentation

After the GF2m removal, this function always returns 0, so adjust the
documentation and remove EC_GROUP_get_{trinomial,pentanomial}_basis()
that were left behind. Also add a tiny grammar tweak in the HISTORY
section.
---
 lib/libcrypto/man/EC_GROUP_copy.3 | 72 ++++---------------------------
 1 file changed, 8 insertions(+), 64 deletions(-)

diff --git a/lib/libcrypto/man/EC_GROUP_copy.3 b/lib/libcrypto/man/EC_GROUP_copy.3
index 6aa56959600..c83ee3d5b18 100644
--- a/lib/libcrypto/man/EC_GROUP_copy.3
+++ b/lib/libcrypto/man/EC_GROUP_copy.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EC_GROUP_copy.3,v 1.13 2022/07/02 17:09:09 jsing Exp $
+.\" $OpenBSD: EC_GROUP_copy.3,v 1.14 2023/06/28 18:07:07 tb Exp $
 .\" full merge up to: OpenSSL d900a015 Oct 8 14:40:42 2015 +0200
 .\" selective merge up to: OpenSSL 24c23e1f Aug 22 10:51:25 2019 +0530
 .\"
@@ -51,7 +51,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 2 2022 $
+.Dd $Mdocdate: June 28 2023 $
 .Dt EC_GROUP_COPY 3
 .Os
 .Sh NAME
@@ -76,9 +76,7 @@
 .Nm EC_GROUP_check ,
 .Nm EC_GROUP_check_discriminant ,
 .Nm EC_GROUP_cmp ,
-.Nm EC_GROUP_get_basis_type ,
-.Nm EC_GROUP_get_trinomial_basis ,
-.Nm EC_GROUP_get_pentanomial_basis
+.Nm EC_GROUP_get_basis_type
 .Nd manipulate EC_GROUP objects
 .Sh SYNOPSIS
 .In openssl/ec.h
@@ -188,18 +186,6 @@
 .Fo EC_GROUP_get_basis_type
 .Fa "const EC_GROUP *"
 .Fc
-.Ft int
-.Fo EC_GROUP_get_trinomial_basis
-.Fa "const EC_GROUP *"
-.Fa "unsigned int *k"
-.Fc
-.Ft int
-.Fo EC_GROUP_get_pentanomial_basis
-.Fa "const EC_GROUP *"
-.Fa "unsigned int *k1"
-.Fa "unsigned int *k2"
-.Fa "unsigned int *k3"
-.Fc
 .Sh DESCRIPTION
 These functions operate on
 .Vt EC_GROUP
@@ -398,48 +384,15 @@ and
 .Fa b
 to determine whether they represent the same curve or not.
 .Pp
-The functions
-.Fn EC_GROUP_get_basis_type ,
-.Fn EC_GROUP_get_trinomial_basis ,
-and
-.Fn EC_GROUP_get_pentanomial_basis
-should only be called for curves defined over an F2^m field.
-Addition and multiplication operations within an F2^m field are
-performed using an irreducible polynomial function f(x).
-This function is either a trinomial of the form:
-.Pp
-.Dl f(x) = x^m + x^k + 1 with m > k >= 1
-.Pp
-or a pentanomial of the form:
-.Pp
-.Dl f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1
-.Pp
-The function
 .Fn EC_GROUP_get_basis_type
-returns a NID identifying whether a trinomial or pentanomial is in
-use for the field.
-The function
-.Fn EC_GROUP_get_trinomial_basis
-must only be called where f(x) is of the trinomial form, and returns
-the value of
-.Fa k .
-Similarly, the function
-.Fn EC_GROUP_get_pentanomial_basis
-must only be called where f(x) is of the pentanomial form, and
-returns the values of
-.Fa k1 ,
-.Fa k2 ,
-and
-.Fa k3 .
+always returns 0 and is only provided for compatibility.
 .Sh RETURN VALUES
 The following functions return 1 on success or 0 on error:
 .Fn EC_GROUP_copy ,
 .Fn EC_GROUP_set_generator ,
 .Fn EC_GROUP_check ,
-.Fn EC_GROUP_check_discriminant ,
-.Fn EC_GROUP_get_trinomial_basis ,
 and
-.Fn EC_GROUP_get_pentanomial_basis .
+.Fn EC_GROUP_check_discriminant .
 .Pp
 .Fn EC_GROUP_dup
 returns a pointer to the duplicated curve or
@@ -516,14 +469,7 @@ returns 0 if the curves are equal, 1 if they are not equal,
 or -1 on error.
 .Pp
 .Fn EC_GROUP_get_basis_type
-returns the values
-.Dv NID_X9_62_tpBasis
-or
-.Dv NID_X9_62_ppBasis
-as defined in
-.In openssl/objects.h
-for a trinomial or pentanomial, respectively.
-Alternatively in the event of an error a 0 is returned.
+always returns 0.
 .Sh SEE ALSO
 .Xr d2i_ECPKParameters 3 ,
 .Xr EC_GFp_simple_method 3 ,
@@ -556,11 +502,9 @@ first appeared in OpenSSL 0.9.7 and have been available since
 .Fn EC_GROUP_check ,
 .Fn EC_GROUP_check_discriminant ,
 .Fn EC_GROUP_cmp ,
-.Fn EC_GROUP_get_basis_type ,
-.Fn EC_GROUP_get_trinomial_basis ,
 and
-.Fn EC_GROUP_get_pentanomial_basis
-first appeared in OpenSSL 0.9.8 and has been available since
+.Fn EC_GROUP_get_basis_type
+first appeared in OpenSSL 0.9.8 and have been available since
 .Ox 4.5 .
 .Pp
 .Fn EC_GROUP_order_bits
-- 
2.20.1