Clean up EC_METHOD and EC_GROUP definitions

Remove obvious comments, wrap long lines and general KNF cleanup. Format
and rephrase the more important comments.

Discussed with jsing

1 files changed, 111 insertions, 102 deletions

diff --git a/lib/libcrypto/ec/ec_lcl.h b/lib/libcrypto/ec/ec_lcl.h
index 3a4f6ad791f..e8bac0ac0e8 100644
--- a/lib/libcrypto/ec/ec_lcl.h
+++ b/lib/libcrypto/ec/ec_lcl.h
@@ -1,4 +1,4 @@
-/* $OpenBSD: ec_lcl.h,v 1.22 2022/11/23 02:13:24 jsing Exp $ */
+/* $OpenBSD: ec_lcl.h,v 1.23 2022/11/24 16:29:09 tb Exp $ */
 /*
  * Originally written by Bodo Moeller for the OpenSSL project.
  */
@@ -89,101 +89,102 @@ __BEGIN_HIDDEN_DECLS
 /* Use default functions for poin2oct, oct2point and compressed coordinates */
 #define EC_FLAGS_DEFAULT_OCT	0x1
 
-/* Structure details are not part of the exported interface,
- * so all this may change in future versions. */
-
 struct ec_method_st {
-	/* Various method flags */
+
+	/*
+	 * Methods and members exposed directly by the public API.
+	 */
+
 	int flags;
-	/* used by EC_METHOD_get_field_type: */
-	int field_type; /* a NID */
 
-	/* used by EC_GROUP_new, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_copy: */
+	int field_type;
+
 	int (*group_init)(EC_GROUP *);
 	void (*group_finish)(EC_GROUP *);
 	void (*group_clear_finish)(EC_GROUP *);
 	int (*group_copy)(EC_GROUP *, const EC_GROUP *);
 
-	/* used by EC_GROUP_{get,set}_curve */
-	int (*group_set_curve)(EC_GROUP *, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *);
-	int (*group_get_curve)(const EC_GROUP *, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *);
+	int (*group_set_curve)(EC_GROUP *, const BIGNUM *p, const BIGNUM *a,
+	    const BIGNUM *b, BN_CTX *);
+	int (*group_get_curve)(const EC_GROUP *, BIGNUM *p, BIGNUM *a,
+	    BIGNUM *b, BN_CTX *);
 
-	/* used by EC_GROUP_get_degree: */
 	int (*group_get_degree)(const EC_GROUP *);
-	/* used by EC_GROUP_order_bits: */
 	int (*group_order_bits)(const EC_GROUP *);
-	/* used by EC_GROUP_check: */
 	int (*group_check_discriminant)(const EC_GROUP *, BN_CTX *);
 
-	/* used by EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy: */
 	int (*point_init)(EC_POINT *);
 	void (*point_finish)(EC_POINT *);
 	void (*point_clear_finish)(EC_POINT *);
 	int (*point_copy)(EC_POINT *, const EC_POINT *);
 
-	/*
-	 * used by EC_POINT_set_to_infinity,
-	 * EC_POINT_set_Jprojective_coordinates,
-	 * EC_POINT_get_Jprojective_coordinates,
-	 * EC_POINT_set_affine_coordinates,
-	 * EC_POINT_get_affine_coordinates,
-	 * EC_POINT_set_compressed_coordinates:
-	 */
 	int (*point_set_to_infinity)(const EC_GROUP *, EC_POINT *);
 	int (*point_set_Jprojective_coordinates)(const EC_GROUP *, EC_POINT *,
-		const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *);
-	int (*point_get_Jprojective_coordinates)(const EC_GROUP *, const EC_POINT *,
-		BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *);
+	    const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *);
+	int (*point_get_Jprojective_coordinates)(const EC_GROUP *,
+	    const EC_POINT *, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *);
 	int (*point_set_affine_coordinates)(const EC_GROUP *, EC_POINT *,
-		const BIGNUM *x, const BIGNUM *y, BN_CTX *);
+	    const BIGNUM *x, const BIGNUM *y, BN_CTX *);
 	int (*point_get_affine_coordinates)(const EC_GROUP *, const EC_POINT *,
-		BIGNUM *x, BIGNUM *y, BN_CTX *);
+	    BIGNUM *x, BIGNUM *y, BN_CTX *);
 	int (*point_set_compressed_coordinates)(const EC_GROUP *, EC_POINT *,
-		const BIGNUM *x, int y_bit, BN_CTX *);
+	    const BIGNUM *x, int y_bit, BN_CTX *);
 
-	/* used by EC_POINT_point2oct, EC_POINT_oct2point: */
-	size_t (*point2oct)(const EC_GROUP *, const EC_POINT *, point_conversion_form_t form,
-		unsigned char *buf, size_t len, BN_CTX *);
-	int (*oct2point)(const EC_GROUP *, EC_POINT *,
-		const unsigned char *buf, size_t len, BN_CTX *);
+	size_t (*point2oct)(const EC_GROUP *, const EC_POINT *,
+	    point_conversion_form_t form, unsigned char *buf, size_t len,
+	    BN_CTX *);
+	int (*oct2point)(const EC_GROUP *, EC_POINT *, const unsigned char *buf,
+	    size_t len, BN_CTX *);
 
-	/* used by EC_POINT_add, EC_POINT_dbl, ECP_POINT_invert: */
-	int (*add)(const EC_GROUP *, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *);
+	int (*add)(const EC_GROUP *, EC_POINT *r, const EC_POINT *a,
+	    const EC_POINT *b, BN_CTX *);
 	int (*dbl)(const EC_GROUP *, EC_POINT *r, const EC_POINT *a, BN_CTX *);
 	int (*invert)(const EC_GROUP *, EC_POINT *, BN_CTX *);
 
-	/* used by EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp: */
 	int (*is_at_infinity)(const EC_GROUP *, const EC_POINT *);
 	int (*is_on_curve)(const EC_GROUP *, const EC_POINT *, BN_CTX *);
-	int (*point_cmp)(const EC_GROUP *, const EC_POINT *a, const EC_POINT *b, BN_CTX *);
+	int (*point_cmp)(const EC_GROUP *, const EC_POINT *a, const EC_POINT *b,
+	    BN_CTX *);
 
-	/* used by EC_POINT_make_affine, EC_POINTs_make_affine: */
 	int (*make_affine)(const EC_GROUP *, EC_POINT *, BN_CTX *);
-	int (*points_make_affine)(const EC_GROUP *, size_t num, EC_POINT *[], BN_CTX *);
-
-	/* used by EC_POINTs_mul, EC_POINT_mul, EC_POINT_precompute_mult, EC_POINT_have_precompute_mult */
-	int (*mul_generator_ct)(const EC_GROUP *, EC_POINT *r, const BIGNUM *scalar, BN_CTX *);
-	int (*mul_single_ct)(const EC_GROUP *group, EC_POINT *r, const BIGNUM *scalar,
-		const EC_POINT *point, BN_CTX *);
-	int (*mul_double_nonct)(const EC_GROUP *group, EC_POINT *r, const BIGNUM *g_scalar,
-		const BIGNUM *p_scalar, const EC_POINT *point, BN_CTX *);
+	int (*points_make_affine)(const EC_GROUP *, size_t num, EC_POINT *[],
+	    BN_CTX *);
+
+	int (*mul_generator_ct)(const EC_GROUP *, EC_POINT *r,
+	    const BIGNUM *scalar, BN_CTX *);
+	int (*mul_single_ct)(const EC_GROUP *group, EC_POINT *r,
+	    const BIGNUM *scalar, const EC_POINT *point, BN_CTX *);
+	int (*mul_double_nonct)(const EC_GROUP *group, EC_POINT *r,
+	    const BIGNUM *g_scalar, const BIGNUM *p_scalar,
+	    const EC_POINT *point, BN_CTX *);
 	int (*precompute_mult)(EC_GROUP *group, BN_CTX *);
 	int (*have_precompute_mult)(const EC_GROUP *group);
 
+	/*
+	 * Internal methods.
+	 */
 
-	/* internal functions */
-
-	/* 'field_mul', 'field_sqr', and 'field_div' can be used by 'add' and 'dbl' so that
-	 * the same implementations of point operations can be used with different
-	 * optimized implementations of expensive field operations: */
-	int (*field_mul)(const EC_GROUP *, BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *);
-	int (*field_sqr)(const EC_GROUP *, BIGNUM *r, const BIGNUM *a, BN_CTX *);
-	int (*field_div)(const EC_GROUP *, BIGNUM *r, const BIGNUM *a, const BIGNUM *b, BN_CTX *);
+	/*
+	 * These can be used by 'add' and 'dbl' so that the same implementations
+	 * of point operations can be used with different optimized versions of
+	 * expensive field operations.
+	 */
+	int (*field_mul)(const EC_GROUP *, BIGNUM *r, const BIGNUM *a,
+	    const BIGNUM *b, BN_CTX *);
+	int (*field_sqr)(const EC_GROUP *, BIGNUM *r, const BIGNUM *a,
+	    BN_CTX *);
+	int (*field_div)(const EC_GROUP *, BIGNUM *r, const BIGNUM *a,
+	    const BIGNUM *b, BN_CTX *);
+
+	/* Encode to and decode from other forms (e.g. Montgomery). */
+	int (*field_encode)(const EC_GROUP *, BIGNUM *r, const BIGNUM *a,
+	    BN_CTX *);
+	int (*field_decode)(const EC_GROUP *, BIGNUM *r, const BIGNUM *a,
+	    BN_CTX *);
 
-	int (*field_encode)(const EC_GROUP *, BIGNUM *r, const BIGNUM *a, BN_CTX *); /* e.g. to Montgomery */
-	int (*field_decode)(const EC_GROUP *, BIGNUM *r, const BIGNUM *a, BN_CTX *); /* e.g. from Montgomery */
 	int (*field_set_to_one)(const EC_GROUP *, BIGNUM *r, BN_CTX *);
-	int (*blind_coordinates)(const EC_GROUP *group, EC_POINT *p, BN_CTX *ctx);
+	int (*blind_coordinates)(const EC_GROUP *group, EC_POINT *p,
+	    BN_CTX *ctx);
 } /* EC_METHOD */;
 
 typedef struct ec_extra_data_st {
@@ -195,57 +196,65 @@ typedef struct ec_extra_data_st {
 } EC_EXTRA_DATA; /* used in EC_GROUP */
 
 struct ec_group_st {
+	/*
+	 * Methods and members exposed via the public API.
+	 */
+
 	const EC_METHOD *meth;
 
-	EC_POINT *generator; /* optional */
-	BIGNUM order, cofactor;
+	EC_POINT *generator;	/* Optional */
+	BIGNUM order;
+	BIGNUM cofactor;
 
-	int curve_name;/* optional NID for named curve */
-	int asn1_flag; /* flag to control the asn1 encoding */
+	int curve_name;		/* Optional NID for named curve. */
+
+	/* ASN.1 encoding controls. */
+	int asn1_flag;
 	point_conversion_form_t asn1_form;
 
-	unsigned char *seed; /* optional seed for parameters (appears in ASN1) */
+	/* Optional seed for parameters (appears in ASN.1). */
+	unsigned char *seed;
 	size_t seed_len;
 
-	EC_EXTRA_DATA *extra_data; /* linked list */
-
-	/* The following members are handled by the method functions,
-	 * even if they appear generic */
-
-	BIGNUM field;	/*
-			 * Field specification.
-			 * For curves over GF(p), this is the modulus;
-			 * for curves over GF(2^m), this is the
-			 * irreducible polynomial defining the field.
-			 */
-
-	int poly[6];	/*
-			 * Field specification for curves over GF(2^m).
-			 * The irreducible f(t) is then of the form:
-			 *     t^poly[0] + t^poly[1] + ... + t^poly[k]
-			 * where m = poly[0] > poly[1] > ... > poly[k] = 0.
-			 * The array is terminated with poly[k+1]=-1.
-			 * All elliptic curve irreducibles have at most 5
-			 * non-zero terms.
-			 */
-
-	BIGNUM a, b;	/*
-			 * Curve coefficients.
-			 * (Here the assumption is that BIGNUMs can be used
-			 * or abused for all kinds of fields, not just GF(p).)
-			 * For characteristic  > 3,  the curve is defined
-			 * by a Weierstrass equation of the form
-			 *     y^2 = x^3 + a*x + b.
-			 * For characteristic  2,  the curve is defined by
-			 * an equation of the form
-			 *     y^2 + x*y = x^3 + a*x^2 + b.
-			 */
-
-	int a_is_minus3; /* enable optimized point arithmetics for special case */
-
-	void *field_data1; /* method-specific (e.g., Montgomery structure) */
-	void *field_data2; /* method-specific */
-	int (*field_mod_func)(BIGNUM *, const BIGNUM *, const BIGNUM *,	BN_CTX *); /* method-specific */
+	/*
+	 * Internal methods and members. Handled by the method functions, even
+	 * if they appear to be generic.
+	 */
+
+	EC_EXTRA_DATA *extra_data;
+
+	/*
+	 * Field specification. For GF(p) this is the modulus; for GF(2^m),
+	 * this is the irreducible polynomial defining the field.
+	 */
+	BIGNUM field;
+
+	/*
+	 * Field specification for GF(2^m). The irreducible polynomial  is
+	 *	f(t) = t^poly[0] + t^poly[1] + ... + t^poly[k],
+	 * where
+	 *	m = poly[0] > poly[1] > ... > poly[k] = 0,
+	 * and the array is terminated with poly[k+1] = -1. All elliptic curve
+	 * irreducibles have at most 5 non-zero terms.
+	 */
+	int poly[6];
+
+	/*
+	 * Curve coefficients. In characteristic > 3, the curve is defined by a
+	 * Weierstrass equation of the form
+	 *	y^2 = x^3 + a*x + b.
+	 * For characteristic 2, the curve is defined by an equation of the form
+	 *	y^2 + x*y = x^3 + a*x^2 + b.
+	 */
+	BIGNUM a, b;
+
+	/* Enables optimized point arithmetics for special case. */
+	int a_is_minus3;
+
+	void *field_data1;
+	void *field_data2;
+	int (*field_mod_func)(BIGNUM *, const BIGNUM *, const BIGNUM *,
+	    BN_CTX *);
 } /* EC_GROUP */;
 
 struct ec_key_st {