In view of the recent BN_FLG_CONSTTIME vulnerabilities in OpenSSL,

carefully document constant time vs. non-constant time operation
of BN_div(3), BN_mod_exp(3), and BN_mod_inverse(3).

Until the work that is required on the ill-designed BN_exp(3) and
BN_gcd(3) interfaces can be undertaken, also document the imperfections
in their behaviour, for now.  Finally, mention BN_mod_exp(3) behaviour
for even moduli.

Delete the vague statement about some functions automatically
setting BN_FLG_CONSTTIME.  It created a false sense of security.
Do not rely on it: not all relevant functions do that.

Topic brought up by beck@, significant feedback and OK jsing@.

1 files changed, 49 insertions, 2 deletions

diff --git a/src/lib/libcrypto/man/BN_add.3 b/src/lib/libcrypto/man/BN_add.3
index 6001a9a4bd..8a11d7c080 100644
--- a/src/lib/libcrypto/man/BN_add.3
+++ b/src/lib/libcrypto/man/BN_add.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: BN_add.3,v 1.12 2018/03/27 17:35:50 schwarze Exp $
+.\"     $OpenBSD: BN_add.3,v 1.13 2018/04/29 15:58:21 schwarze Exp $
 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
 .\" This file was written by Ulf Moeller <ulf@openssl.org>
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 27 2018 $
+.Dd $Mdocdate: April 29 2018 $
 .Dt BN_ADD 3
 .Os
 .Sh NAME
@@ -66,6 +66,13 @@
 .Nm BN_mod_sqr ,
 .Nm BN_exp ,
 .Nm BN_mod_exp ,
+.\" The following are public, but intentionally undocumented for now:
+.\" .Nm BN_mod_exp_mont_consttime ,
+.\" .Nm BN_mod_exp_mont ,
+.\" .Nm BN_mod_exp_mont_word ,
+.\" .Nm BN_mod_exp_recp ,
+.\" .Nm BN_mod_exp_simple ,
+.\" Maybe they should be deleted from <openssl/bn.h>.
 .Nm BN_gcd
 .Nd arithmetic operations on BIGNUMs
 .Sh SYNOPSIS
@@ -245,6 +252,13 @@ and places the result in
 and the remainder in
 .Fa rem
 .Pq Li dv=a/d , rem=a%d .
+If the flag
+.Dv BN_FLG_CONSTTIME
+is set on
+.Fa a
+or
+.Fa d ,
+it operates in constant time.
 Either of
 .Fa dv
 and
@@ -343,6 +357,11 @@ to the
 power modulo
 .Fa m
 .Pq Li r=(a^p)%m .
+If the flag
+.Dv BN_FLG_CONSTTIME
+is set on
+.Fa p ,
+it operates in constant time.
 This function uses less time and space than
 .Fn BN_exp .
 .Pp
@@ -417,3 +436,31 @@ and
 .Fn BN_mod_sqr
 first appeared in OpenSSL 0.9.7 and have been available since
 .Ox 3.2 .
+.Sh BUGS
+Even if the
+.Dv BN_FLG_CONSTTIME
+flag is set on
+.Fa a
+or
+.Fa b ,
+.Fn BN_gcd
+neither fails nor operates in constant time, potentially allowing
+timing side-channel attacks.
+.Pp
+Even if the
+.Dv BN_FLG_CONSTTIME
+flag is set on
+.Fa p ,
+if the modulus
+.Fa m
+is even,
+.Fn BN_mod_exp
+does not operate in constant time, potentially allowing
+timing side-channel attacks.
+.Pp
+If
+.Dv BN_FLG_CONSTTIME
+is set on
+.Fa p ,
+.Fn BN_exp
+fails instead of operating in constant time.