More clearly suggest passing NULL for EC and EC_KEY APIs

We didn't note they could be NULL in some APIs. Also almost all of EC
ignores BN_CTX anyway, so we can just say it's ignored. For the handful
of functions that don't ignore it, I think we can probably just say it
hint that you can pass in NULL and, if you think you have something
useful to do with BN_CTX, you probably know what it's used for.

(But also we should just remove the EC code's dependency on BN_CTX.
BN_CTX is really only useful when you call lots and lots of BIGNUM-using
operations in a row, and neither of the remaining such operations fall
under that umbrella.)

Bug: 42290433
Change-Id: I2766b310ca1d28a67e45354111cc2d90fa45f113
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/79988
Reviewed-by: Adam Langley <[email protected]>
Auto-Submit: David Benjamin <[email protected]>
Commit-Queue: Adam Langley <[email protected]>

Author: davidben

include/openssl/ec.h

@@ -107,16 +107,16 @@ OPENSSL_EXPORT const BIGNUM *EC_GROUP_get0_order(const EC_GROUP *group);
 // EC_GROUP_order_bits returns the number of bits of the order of |group|.
 OPENSSL_EXPORT int EC_GROUP_order_bits(const EC_GROUP *group);
 
-// EC_GROUP_get_cofactor sets |*cofactor| to the cofactor of |group| using
-// |ctx|, if it's not NULL. It returns one on success and zero otherwise.
+// EC_GROUP_get_cofactor sets |*cofactor| to the cofactor of |group|. It returns
+// one on success and zero otherwise. |ctx| is ignored and may be NULL.
 OPENSSL_EXPORT int EC_GROUP_get_cofactor(const EC_GROUP *group,
                                          BIGNUM *cofactor, BN_CTX *ctx);
 
 // EC_GROUP_get_curve_GFp gets various parameters about a group. It sets
 // |*out_p| to the order of the coordinate field and |*out_a| and |*out_b| to
 // the parameters of the curve when expressed as y² = x³ + ax + b. Any of the
 // output parameters can be NULL. It returns one on success and zero on
-// error.
+// error. |ctx| is ignored and may be NULL.
 OPENSSL_EXPORT int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *out_p,
                                           BIGNUM *out_a, BIGNUM *out_b,
                                           BN_CTX *ctx);
@@ -169,21 +169,21 @@ OPENSSL_EXPORT int EC_POINT_is_at_infinity(const EC_GROUP *group,
 
 // EC_POINT_is_on_curve returns one if |point| is an element of |group| and
 // and zero otherwise or when an error occurs. This is different from OpenSSL,
-// which returns -1 on error. If |ctx| is non-NULL, it may be used.
+// which returns -1 on error. |ctx| is ignored and may be NULL.
 OPENSSL_EXPORT int EC_POINT_is_on_curve(const EC_GROUP *group,
                                         const EC_POINT *point, BN_CTX *ctx);
 
 // EC_POINT_cmp returns zero if |a| is equal to |b|, greater than zero if
-// not equal and -1 on error. If |ctx| is not NULL, it may be used.
+// not equal and -1 on error. |ctx| is ignored and may be NULL.
 OPENSSL_EXPORT int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a,
                                 const EC_POINT *b, BN_CTX *ctx);
 
 
 // Point conversion.
 
 // EC_POINT_get_affine_coordinates_GFp sets |x| and |y| to the affine value of
-// |point| using |ctx|, if it's not NULL. It returns one on success and zero
-// otherwise.
+// |point|. It returns one on success and zero otherwise. |ctx| is ignored and
+// may be NULL.
 //
 // Either |x| or |y| may be NULL to skip computing that coordinate. This is
 // slightly faster in the common case where only the x-coordinate is needed.
@@ -200,9 +200,8 @@ OPENSSL_EXPORT int EC_POINT_get_affine_coordinates(const EC_GROUP *group,
                                                    BN_CTX *ctx);
 
 // EC_POINT_set_affine_coordinates_GFp sets the value of |point| to be
-// (|x|, |y|). The |ctx| argument may be used if not NULL. It returns one
-// on success or zero on error. It's considered an error if the point is not on
-// the curve.
+// (|x|, |y|). |ctx| is ignored and may be NULL. It returns one on success or
+// zero on error. It's considered an error if the point is not on the curve.
 //
 // Note that the corresponding function in OpenSSL versions prior to 1.0.2s does
 // not check if the point is on the curve. This is a security-critical check, so
@@ -226,7 +225,7 @@ OPENSSL_EXPORT int EC_POINT_set_affine_coordinates(const EC_GROUP *group,
 // EC_POINT_point2oct serialises |point| into the X9.62 form given by |form|
 // into, at most, |max_out| bytes at |buf|. It returns the number of bytes
 // written or zero on error if |buf| is non-NULL, else the number of bytes
-// needed. The |ctx| argument may be used if not NULL.
+// needed. |ctx| is ignored and may be NULL.
 OPENSSL_EXPORT size_t EC_POINT_point2oct(const EC_GROUP *group,
                                          const EC_POINT *point,
                                          point_conversion_form_t form,
@@ -236,30 +235,31 @@ OPENSSL_EXPORT size_t EC_POINT_point2oct(const EC_GROUP *group,
 // EC_POINT_point2buf serialises |point| into the X9.62 form given by |form| to
 // a newly-allocated buffer and sets |*out_buf| to point to it. It returns the
 // length of the result on success or zero on error. The caller must release
-// |*out_buf| with |OPENSSL_free| when done.
+// |*out_buf| with |OPENSSL_free| when done. |ctx| is ignored and may be NULL.
 OPENSSL_EXPORT size_t EC_POINT_point2buf(const EC_GROUP *group,
                                          const EC_POINT *point,
                                          point_conversion_form_t form,
                                          uint8_t **out_buf, BN_CTX *ctx);
 
 // EC_POINT_point2cbb behaves like |EC_POINT_point2oct| but appends the
-// serialised point to |cbb|. It returns one on success and zero on error.
+// serialised point to |cbb|. It returns one on success and zero on error. |ctx|
+// is ignored and may be NULL.
 OPENSSL_EXPORT int EC_POINT_point2cbb(CBB *out, const EC_GROUP *group,
                                       const EC_POINT *point,
                                       point_conversion_form_t form,
                                       BN_CTX *ctx);
 
 // EC_POINT_oct2point sets |point| from |len| bytes of X9.62 format
-// serialisation in |buf|. It returns one on success and zero on error. The
-// |ctx| argument may be used if not NULL. It's considered an error if |buf|
-// does not represent a point on the curve.
+// serialisation in |buf|. It returns one on success and zero on error. |ctx|
+// may be NULL. It's considered an error if |buf| does not represent a point on
+// the curve.
 OPENSSL_EXPORT int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *point,
                                       const uint8_t *buf, size_t len,
                                       BN_CTX *ctx);
 
 // EC_POINT_set_compressed_coordinates_GFp sets |point| to equal the point with
 // the given |x| coordinate and the y coordinate specified by |y_bit| (see
-// X9.62). It returns one on success and zero otherwise.
+// X9.62). It returns one on success and zero otherwise. |ctx| may be NULL.
 OPENSSL_EXPORT int EC_POINT_set_compressed_coordinates_GFp(
     const EC_GROUP *group, EC_POINT *point, const BIGNUM *x, int y_bit,
     BN_CTX *ctx);
@@ -268,23 +268,23 @@ OPENSSL_EXPORT int EC_POINT_set_compressed_coordinates_GFp(
 // Group operations.
 
 // EC_POINT_add sets |r| equal to |a| plus |b|. It returns one on success and
-// zero otherwise. If |ctx| is not NULL, it may be used.
+// zero otherwise. |ctx| is ignored and may be NULL.
 OPENSSL_EXPORT int EC_POINT_add(const EC_GROUP *group, EC_POINT *r,
                                 const EC_POINT *a, const EC_POINT *b,
                                 BN_CTX *ctx);
 
 // EC_POINT_dbl sets |r| equal to |a| plus |a|. It returns one on success and
-// zero otherwise. If |ctx| is not NULL, it may be used.
+// zero otherwise. |ctx| is ignored and may be NULL.
 OPENSSL_EXPORT int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r,
                                 const EC_POINT *a, BN_CTX *ctx);
 
 // EC_POINT_invert sets |a| equal to minus |a|. It returns one on success and
-// zero otherwise. If |ctx| is not NULL, it may be used.
+// zero otherwise. |ctx| is ignored and may be NULL.
 OPENSSL_EXPORT int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a,
                                    BN_CTX *ctx);
 
 // EC_POINT_mul sets r = generator*n + q*m. It returns one on success and zero
-// otherwise. If |ctx| is not NULL, it may be used.
+// otherwise. |ctx| may be NULL.
 OPENSSL_EXPORT int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r,
                                 const BIGNUM *n, const EC_POINT *q,
                                 const BIGNUM *m, BN_CTX *ctx);
@@ -368,8 +368,8 @@ OPENSSL_EXPORT int EC_GROUP_set_generator(EC_GROUP *group,
                                           const BIGNUM *cofactor);
 
 // EC_GROUP_get_order sets |*order| to the order of |group|, if it's not
-// NULL. It returns one on success and zero otherwise. |ctx| is ignored. Use
-// |EC_GROUP_get0_order| instead.
+// NULL. It returns one on success and zero otherwise. |ctx| is ignored and may
+// be NULL. Use |EC_GROUP_get0_order| instead.
 OPENSSL_EXPORT int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order,
                                       BN_CTX *ctx);
 

include/openssl/ec_key.h

@@ -130,12 +130,12 @@ OPENSSL_EXPORT int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key,
 // EC_KEY_oct2key decodes |len| bytes from |in| as an EC public key in X9.62
 // form. |key| must already have a group configured. On success, it sets the
 // public key in |key| to the result and returns one. Otherwise, it returns
-// zero.
+// zero. |ctx| may be NULL.
 OPENSSL_EXPORT int EC_KEY_oct2key(EC_KEY *key, const uint8_t *in, size_t len,
                                   BN_CTX *ctx);
 
 // EC_KEY_key2buf behaves like |EC_POINT_point2buf|, except it encodes the
-// public key in |key|.
+// public key in |key|. |ctx| is ignored and may be NULL.
 OPENSSL_EXPORT size_t EC_KEY_key2buf(const EC_KEY *key,
                                      point_conversion_form_t form,
                                      uint8_t **out_buf, BN_CTX *ctx);