Seriously warn against calling BN_init(3), BN_MONT_CTX_init(3),

and BN_RECP_CTX_init(3).  They are not only deprecated but so
dangerous that they are almost unusable.  I found these scary
traps while reading the code in order to document BN_set_flags(3).
While here, delete ERR_get_error(3) from SEE ALSO.

3 files changed, 75 insertions, 12 deletions

diff --git a/lib/libcrypto/man/BN_mod_mul_montgomery.3 b/lib/libcrypto/man/BN_mod_mul_montgomery.3
index 8b06cb62175..87f09e3cb67 100644
--- a/lib/libcrypto/man/BN_mod_mul_montgomery.3
+++ b/lib/libcrypto/man/BN_mod_mul_montgomery.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: BN_mod_mul_montgomery.3,v 1.5 2016/12/10 21:13:25 schwarze Exp $
+.\"	$OpenBSD: BN_mod_mul_montgomery.3,v 1.6 2017/01/29 23:41:49 schwarze Exp $
 .\"	OpenSSL 6859cf74 Sep 25 13:33:28 2002 +0000
 .\"
 .\" 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 29 2017 $
 .Dt BN_MOD_MUL_MONTGOMERY 3
 .Os
 .Sh NAME
@@ -119,9 +119,12 @@ operations are to be performed using the same modulus.
 allocates and initializes a
 .Vt BN_MONT_CTX
 structure.
+.Pp
 .Fn BN_MONT_CTX_init
 initializes an existing uninitialized
 .Vt BN_MONT_CTX .
+It is deprecated and dangerous, see
+.Sx CAVEATS .
 .Pp
 .Fn BN_MONT_CTX_set
 sets up the
@@ -213,8 +216,7 @@ The error codes can be obtained by
 .Sh SEE ALSO
 .Xr BN_add 3 ,
 .Xr BN_CTX_new 3 ,
-.Xr BN_new 3 ,
-.Xr ERR_get_error 3
+.Xr BN_new 3
 .Sh HISTORY
 .Fn BN_MONT_CTX_new ,
 .Fn BN_MONT_CTX_free ,
@@ -229,3 +231,20 @@ are available in all versions of SSLeay and OpenSSL.
 and
 .Fn BN_MONT_CTX_copy
 were added in SSLeay 0.9.1b.
+.Sh CAVEATS
+.Fn BN_MONT_CTX_init
+must not be called on a context that was used previously, or
+memory used by the embedded
+.Vt BIGNUM
+structures is leaked immediately.
+Besides, it must not be called on a context created with
+.Fn BN_MONT_CTX_new ,
+or the context itself will likely be leaked later.
+It can only be used on a static
+.Vt BN_MONT_CTX
+structure, on one located on the stack, or on one
+.Xr malloc 3 Ap ed
+manually, but all these options are discouraged because they
+will no longer work once
+.Vt BN_MONT_CTX
+will be made opaque.
diff --git a/lib/libcrypto/man/BN_mod_mul_reciprocal.3 b/lib/libcrypto/man/BN_mod_mul_reciprocal.3
index 74783b2f55e..a24917bef93 100644
--- a/lib/libcrypto/man/BN_mod_mul_reciprocal.3
+++ b/lib/libcrypto/man/BN_mod_mul_reciprocal.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: BN_mod_mul_reciprocal.3,v 1.5 2016/12/10 21:13:25 schwarze Exp $
+.\"	$OpenBSD: BN_mod_mul_reciprocal.3,v 1.6 2017/01/29 23:41:49 schwarze Exp $
 .\"	OpenSSL 6859cf74 Sep 25 13:33:28 2002 +0000
 .\"
 .\" 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 29 2017 $
 .Dt BN_MOD_MUL_RECIPROCAL 3
 .Os
 .Sh NAME
@@ -115,9 +115,12 @@ used for temporary variables.
 allocates and initializes a
 .Vt BN_RECP_CTX
 structure.
+.Pp
 .Fn BN_RECP_CTX_init
 initializes an existing uninitialized
 .Vt BN_RECP_CTX .
+It is deprecated and dangerous, see
+.Sx CAVEATS .
 .Pp
 .Fn BN_RECP_CTX_free
 frees the components of the
@@ -185,8 +188,7 @@ The error codes can be obtained by
 .Sh SEE ALSO
 .Xr BN_add 3 ,
 .Xr BN_CTX_new 3 ,
-.Xr BN_new 3 ,
-.Xr ERR_get_error 3
+.Xr BN_new 3
 .Sh HISTORY
 .Vt BN_RECP_CTX
 was added in SSLeay 0.9.0.
@@ -195,3 +197,20 @@ Before that, a function
 was used instead, and the
 .Fn BN_mod_mul_reciprocal
 arguments were different.
+.Sh CAVEATS
+.Fn BN_RECP_CTX_init
+must not be called on a context that was used previously, or
+memory used by the embedded
+.Vt BIGNUM
+structures is leaked immediately.
+Besides, it must not be called on a context created with
+.Fn BN_RECP_CTX_new ,
+or the context itself will likely be leaked later.
+It can only be used on a static
+.Vt BN_RECP_CTX
+structure, on one located on the stack, or on one
+.Xr malloc 3 Ap ed
+manually, but all these options are discouraged because they
+will no longer work once
+.Vt BN_RECP_CTX
+will be made opaque.
diff --git a/lib/libcrypto/man/BN_new.3 b/lib/libcrypto/man/BN_new.3
index 2b2166ce30b..8294a4f4d13 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.6 2016/12/22 19:33:57 jmc Exp $
+.\"	$OpenBSD: BN_new.3,v 1.7 2017/01/29 23:41:49 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: December 22 2016 $
+.Dd $Mdocdate: January 29 2017 $
 .Dt BN_NEW 3
 .Os
 .Sh NAME
@@ -102,9 +102,12 @@ or accessed directly.
 allocates and initializes a
 .Vt BIGNUM
 structure.
+.Pp
 .Fn BN_init
 initializes an existing uninitialized
 .Vt BIGNUM .
+It is deprecated and dangerous, see
+.Sx CAVEATS .
 .Pp
 .Fn BN_clear
 is used to destroy sensitive data such as keys when they are no longer
@@ -154,8 +157,7 @@ and sets an error code that can be obtained by
 .Xr BN_set_bit 3 ,
 .Xr BN_set_negative 3 ,
 .Xr BN_swap 3 ,
-.Xr BN_zero 3 ,
-.Xr ERR_get_error 3
+.Xr BN_zero 3
 .Sh HISTORY
 .Fn BN_new ,
 .Fn BN_clear ,
@@ -165,3 +167,26 @@ and
 are available in all versions of SSLeay and OpenSSL.
 .Fn BN_init
 was added in SSLeay 0.9.1b.
+.Sh CAVEATS
+.Fn BN_init
+must not be called on a
+.Vt BIGNUM
+that was used and contains an actual number, or the memory
+used for storing the number is leaked immediately.
+Besides, it must not be called on a number allocated with
+.Fn BN_new ,
+or the
+.Vt BIGNUM
+structure itself will likely be leaked later on.
+It can only be used on static
+.Vt BIGNUM
+structures, on
+.Vt BIGNUM
+structures on the stack, or on
+.Vt BIGNUM
+structures
+.Xr malloc 3 Ap ed
+manually, but all of these options are discouraged because they
+will no longer work once the
+.Vt BIGNUM
+data type will be made opaque.