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, 23 insertions, 4 deletions

diff --git a/src/lib/libcrypto/man/BN_mod_mul_reciprocal.3 b/src/lib/libcrypto/man/BN_mod_mul_reciprocal.3
index 74783b2f55..a24917bef9 100644
--- a/src/lib/libcrypto/man/BN_mod_mul_reciprocal.3
+++ b/src/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.