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, 38 insertions, 21 deletions

diff --git a/src/lib/libcrypto/man/BN_set_flags.3 b/src/lib/libcrypto/man/BN_set_flags.3
index a998037534..9b1647cd31 100644
--- a/src/lib/libcrypto/man/BN_set_flags.3
+++ b/src/lib/libcrypto/man/BN_set_flags.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: BN_set_flags.3,v 1.2 2018/03/21 09:03:49 schwarze Exp $
+.\"     $OpenBSD: BN_set_flags.3,v 1.3 2018/04/29 15:58:21 schwarze Exp $
 .\"
 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: March 21 2018 $
+.Dd $Mdocdate: April 29 2018 $
 .Dt BN_SET_FLAGS 3
 .Os
 .Sh NAME
@@ -47,6 +47,8 @@ together:
 .It Dv BN_FLG_CONSTTIME
 If this flag is set on the divident
 .Fa a
+or the divisor
+.Fa d
 in
 .Xr BN_div 3 ,
 on the exponent
@@ -59,27 +61,14 @@ or the modulus
 .Fa n
 in
 .Xr BN_mod_inverse 3 ,
-these functions prefer algorithms with an execution time independent
+these functions select algorithms with an execution time independent
 of the respective numbers, to avoid exposing sensitive information
-to timing attacks.
+to timing side-channel attacks.
 .Pp
-If this flag is set on the exponent
-.Fa p
-in
-.Xr BN_exp 3
-or if the modulus
-.Fa m
-is even for
-.Xr BN_mod_exp 3 ,
-an error occurs.
-.Pp
-Various functions automatically set this flag on sensitive data.
-For example, the default implementations of
-.Xr DH_generate_key 3 ,
-.Xr DSA_generate_key 3 ,
-and
-.Xr RSA_generate_key_ex 3
-set it on the generated private key.
+This flag is off by default for
+.Vt BIGNUM
+objects created with
+.Xr BN_new 3 .
 .It Dv BN_FLG_MALLOCED
 If this flag is set,
 .Xr BN_free 3
@@ -148,3 +137,31 @@ first appeared in SSLeay 0.9.1 and have been available since
 No public interface exists to clear a flag once it is set.
 So think twice before using
 .Fn BN_set_flags .
+.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,
+.Xr BN_mod_exp 3
+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.