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.

1 files changed, 29 insertions, 4 deletions

diff --git a/src/lib/libcrypto/man/BN_new.3 b/src/lib/libcrypto/man/BN_new.3
index 2b2166ce30..8294a4f4d1 100644
--- a/src/lib/libcrypto/man/BN_new.3
+++ b/src/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.