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 <agl@google.com> Auto-Submit: David Benjamin <davidben@google.com> Commit-Queue: Adam Langley <agl@google.com>
diff --git a/include/openssl/ec.h b/include/openssl/ec.h index 6f1d3d5..29dc86a 100644 --- a/include/openssl/ec.h +++ b/include/openssl/ec.h
@@ -107,8 +107,8 @@ // 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); @@ -116,7 +116,7 @@ // |*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,12 +169,12 @@ // 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); @@ -182,8 +182,8 @@ // 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 @@ 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 @@ // 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 @@ // 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 @@ // 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 @@ 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);
diff --git a/include/openssl/ec_key.h b/include/openssl/ec_key.h index 1219cf1..1133a37 100644 --- a/include/openssl/ec_key.h +++ b/include/openssl/ec_key.h
@@ -130,12 +130,12 @@ // 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);