Document BN_set_flags(3) and BN_get_flags(3).

jsing@ confirmed that these macros are public and worth documenting.

6 files changed, 159 insertions, 13 deletions

diff --git a/lib/libcrypto/man/BN_add.3 b/lib/libcrypto/man/BN_add.3
index 77afec7de30..a275dbfe950 100644
--- a/lib/libcrypto/man/BN_add.3
+++ b/lib/libcrypto/man/BN_add.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: BN_add.3,v 1.6 2017/01/07 05:06:22 schwarze Exp $
+.\"	$OpenBSD: BN_add.3,v 1.7 2017/01/30 01:29:31 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: January 7 2017 $
+.Dd $Mdocdate: January 30 2017 $
 .Dt BN_ADD 3
 .Os
 .Sh NAME
@@ -384,8 +384,8 @@ The error codes can be obtained by
 .Xr BN_CTX_new 3 ,
 .Xr BN_new 3 ,
 .Xr BN_set_bit 3 ,
-.Xr BN_set_negative 3 ,
-.Xr ERR_get_error 3
+.Xr BN_set_flags 3 ,
+.Xr BN_set_negative 3
 .Sh HISTORY
 .Fn BN_add ,
 .Fn BN_sub ,
diff --git a/lib/libcrypto/man/BN_copy.3 b/lib/libcrypto/man/BN_copy.3
index 34653be7e3b..398cf1f8ecb 100644
--- a/lib/libcrypto/man/BN_copy.3
+++ b/lib/libcrypto/man/BN_copy.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: BN_copy.3,v 1.5 2017/01/07 05:06:22 schwarze Exp $
+.\"	$OpenBSD: BN_copy.3,v 1.6 2017/01/30 01:29:31 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: January 7 2017 $
+.Dd $Mdocdate: January 30 2017 $
 .Dt BN_COPY 3
 .Os
 .Sh NAME
@@ -151,7 +151,7 @@ The error codes can be obtained by
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
 .Xr BN_new 3 ,
-.Xr ERR_get_error 3
+.Xr BN_set_flags 3
 .Sh HISTORY
 .Fn BN_copy
 and
diff --git a/lib/libcrypto/man/BN_mod_inverse.3 b/lib/libcrypto/man/BN_mod_inverse.3
index 6817fc2a3f3..f407fa71e8a 100644
--- a/lib/libcrypto/man/BN_mod_inverse.3
+++ b/lib/libcrypto/man/BN_mod_inverse.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: BN_mod_inverse.3,v 1.5 2016/12/10 21:13:25 schwarze Exp $
+.\"	$OpenBSD: BN_mod_inverse.3,v 1.6 2017/01/30 01:29:31 schwarze Exp $
 .\"	OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
 .\" This file was written by Ulf Moeller <ulf@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 10 2016 $
+.Dd $Mdocdate: January 30 2017 $
 .Dt BN_MOD_INVERSE 3
 .Os
 .Sh NAME
@@ -103,7 +103,7 @@ The error codes can be obtained by
 .Sh SEE ALSO
 .Xr BN_add 3 ,
 .Xr BN_new 3 ,
-.Xr ERR_get_error 3
+.Xr BN_set_flags 3
 .Sh HISTORY
 .Fn BN_mod_inverse
 is available in all versions of SSLeay and OpenSSL.
diff --git a/lib/libcrypto/man/BN_new.3 b/lib/libcrypto/man/BN_new.3
index 8294a4f4d13..ce3734938d9 100644
--- a/lib/libcrypto/man/BN_new.3
+++ b/lib/libcrypto/man/BN_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: BN_new.3,v 1.7 2017/01/29 23:41:49 schwarze Exp $
+.\"	$OpenBSD: BN_new.3,v 1.8 2017/01/30 01:29:31 schwarze Exp $
 .\"	OpenSSL doc/man3/BN_new.pod 2457c19d Mar 6 08:43:36 2004 +0000
 .\"	OpenSSL doc/man7/bn.pod 05ea606a May 20 20:52:46 2016 -0400
 .\"
@@ -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: January 29 2017 $
+.Dd $Mdocdate: January 30 2017 $
 .Dt BN_NEW 3
 .Os
 .Sh NAME
@@ -155,6 +155,7 @@ and sets an error code that can be obtained by
 .Xr BN_num_bytes 3 ,
 .Xr BN_rand 3 ,
 .Xr BN_set_bit 3 ,
+.Xr BN_set_flags 3 ,
 .Xr BN_set_negative 3 ,
 .Xr BN_swap 3 ,
 .Xr BN_zero 3
diff --git a/lib/libcrypto/man/BN_set_flags.3 b/lib/libcrypto/man/BN_set_flags.3
new file mode 100644
index 00000000000..27649fd074b
--- /dev/null
+++ b/lib/libcrypto/man/BN_set_flags.3
@@ -0,0 +1,144 @@
+.\"	$OpenBSD: BN_set_flags.3,v 1.1 2017/01/30 01:29:31 schwarze Exp $
+.\"
+.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: January 30 2017 $
+.Dt BN_SET_FLAGS 3
+.Os
+.Sh NAME
+.Nm BN_set_flags ,
+.Nm BN_get_flags
+.Nd enable and inspect flags on BIGNUM objects
+.Sh SYNOPSIS
+.In openssl/bn.h
+.Ft void
+.Fo BN_set_flags
+.Fa "BIGNUM *b"
+.Fa "int flags"
+.Fc
+.Ft int
+.Fo BN_get_flags
+.Fa "const BIGNUM *b"
+.Fa "int flags"
+.Fc
+.Sh DESCRIPTION
+.Fn BN_set_flags
+enables the given
+.Fa flags
+on
+.Fa b .
+The
+.Fa flags
+argument can contain zero or more of the following constants OR'ed
+together:
+.Bl -tag -width Ds
+.It Dv BN_FLG_CONSTTIME
+If this flag is set on the divident
+.Fa a
+in
+.Xr BN_div 3 ,
+on the exponent
+.Fa p
+in
+.Xr BN_mod_exp 3 ,
+or on the divisor
+.Fa a
+or the modulus
+.Fa n
+in
+.Xr BN_mod_inverse 3 ,
+these functions prefer algorithms with an execution time independent
+of the respective numbers, to avoid exposing sensitive information
+to timing 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.
+.It Dv BN_FLG_MALLOCED
+If this flag is set,
+.Xr BN_free 3
+and
+.Xr BN_clear_free 3
+will not only clear and free the components of
+.Fa b ,
+but also
+.Fa b
+itself.
+This flag is set internally by
+.Xr BN_new 3 .
+Setting it manually on an existing
+.Vt BIGNUM
+object is usually a bad idea and can cause calls to
+.Xr free 3
+with bogus arguments.
+.It Dv BN_FLG_STATIC_DATA
+If this flag is set,
+.Xr BN_clear_free 3
+will neither clear nor free the memory used for storing the number.
+Consequently, setting it manually on an existing
+.Vt BIGNUM
+object is usually a terrible idea that can cause both disclosure
+of secret data and memory leaks.
+This flag is automatically set on the constant
+.Vt BIGNUM
+objects returned by
+.Xr BN_value_one 3
+and by the functions documented in
+.Xr BN_get0_nist_prime_521 3 .
+.El
+.Pp
+.Fn BN_get_flags
+interpretes
+.Fa flags
+as a bitmask and returns those of the given flags that are set in
+.Fa b ,
+OR'ed together, or 0 if none of the given
+.Fa flags
+is set.
+The
+.Fa flags
+argument has the same syntax as for
+.Fn BN_set_flags .
+.Pp
+These functions are currently implemented as macros, but they are
+likely to become real functions in the future when the
+.Vt BIGNUM
+data type will be made opaque.
+.Sh RETURN VALUES
+.Fn BN_get_flags
+returns zero or more of the above constants, OR'ed together.
+.Sh SEE ALSO
+.Xr BN_mod_exp 3 ,
+.Xr BN_mod_inverse 3 ,
+.Xr BN_new 3 ,
+.Xr BN_with_flags 3
+.Sh CAVEATS
+No public interface exists to clear a flag once it is set.
+So think twice before using
+.Fn BN_set_flags .
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 46e8ba57391..d991508cff9 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.112 2017/01/07 00:45:04 schwarze Exp $
+# $OpenBSD: Makefile,v 1.113 2017/01/30 01:29:31 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -55,6 +55,7 @@ MAN=	\
 	BN_num_bytes.3 \
 	BN_rand.3 \
 	BN_set_bit.3 \
+	BN_set_flags.3 \
 	BN_set_negative.3 \
 	BN_swap.3 \
 	BN_zero.3 \