Move discussion on BN_div's sign to the headers

This is part of the public API and should be documented as such.

Bug: 358687140
Change-Id: I1d736f39c5cff18f7c8e3ff8207a4b60ee96cd18
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/70169
Commit-Queue: David Benjamin <davidben@google.com>
Reviewed-by: Bob Beck <bbe@google.com>

crypto/fipsmodule/bn/div.c

diff --git a/crypto/fipsmodule/bn/div.c b/crypto/fipsmodule/bn/div.c
index ba6b69e..23e1b63 100644
--- a/crypto/fipsmodule/bn/div.c
+++ b/crypto/fipsmodule/bn/div.c
@@ -175,18 +175,6 @@
 #endif
 }
 
-// BN_div computes "quotient := numerator / divisor", rounding towards zero,
-// and sets up |rem| such that "quotient * divisor + rem = numerator" holds.
-//
-// Thus:
-//
-//     quotient->neg == numerator->neg ^ divisor->neg
-//        (unless the result is zero)
-//     rem->neg == numerator->neg
-//        (unless the remainder is zero)
-//
-// If |quotient| or |rem| is NULL, the respective value is not returned.
-//
 // This was specifically designed to contain fewer branches that may leak
 // sensitive information; see "New Branch Prediction Vulnerabilities in OpenSSL
 // and Necessary Software Countermeasures" by Onur Acıçmez, Shay Gueron, and

include/openssl/bn.h

diff --git a/include/openssl/bn.h b/include/openssl/bn.h
index fb6e962..a5bfcd7 100644
--- a/include/openssl/bn.h
+++ b/include/openssl/bn.h
@@ -424,9 +424,14 @@
 
 // BN_div divides |numerator| by |divisor| and places the result in |quotient|
 // and the remainder in |rem|. Either of |quotient| or |rem| may be NULL, in
-// which case the respective value is not returned. The result is rounded
-// towards zero; thus if |numerator| is negative, the remainder will be zero or
-// negative. It returns one on success or zero on error.
+// which case the respective value is not returned. It returns one on success or
+// zero on error. It is an error condition if |divisor| is zero.
+//
+// The outputs will be such that |quotient| * |divisor| + |rem| = |numerator|,
+// with the quotient rounded towards zero. Thus, if |numerator| is negative,
+// |rem| will be zero or negative. If |divisor| is negative, the sign of
+// |quotient| will be flipped to compensate but otherwise rounding will be as if
+// |divisor| were its absolute value.
 OPENSSL_EXPORT int BN_div(BIGNUM *quotient, BIGNUM *rem,
                           const BIGNUM *numerator, const BIGNUM *divisor,
                           BN_CTX *ctx);