* Document DH_up_ref(3), DSA_up_ref(3), and RSA_up_ref(3).

* Correct documentation of DH_new(3), DH_free(3), DSA_new(3), DSA_free(3),
RSA_new(3), and RSA_free(3) with respect to reference counting.
* Stop referencing engine(3).

3 files changed, 73 insertions, 16 deletions

diff --git a/lib/libcrypto/man/DH_new.3 b/lib/libcrypto/man/DH_new.3
index bd3b3105611..3208e767013 100644
--- a/lib/libcrypto/man/DH_new.3
+++ b/lib/libcrypto/man/DH_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: DH_new.3,v 1.7 2018/03/27 17:35:50 schwarze Exp $
+.\"	$OpenBSD: DH_new.3,v 1.8 2018/04/18 01:11:45 schwarze Exp $
 .\"	OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
 .\" This file was written by Ulf Moeller <ulf@openssl.org>.
@@ -48,17 +48,22 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 27 2018 $
+.Dd $Mdocdate: April 18 2018 $
 .Dt DH_NEW 3
 .Os
 .Sh NAME
 .Nm DH_new ,
+.Nm DH_up_ref ,
 .Nm DH_free
 .Nd allocate and free DH objects
 .Sh SYNOPSIS
 .In openssl/dh.h
 .Ft DH*
 .Fn DH_new void
+.Ft int
+.Fo DH_up_ref
+.Fa "DH *dh"
+.Fc
 .Ft void
 .Fo DH_free
 .Fa "DH *dh"
@@ -69,10 +74,19 @@ The DH functions implement the Diffie-Hellman key agreement protocol.
 .Fn DH_new
 allocates and initializes a
 .Vt DH
-structure.
+structure, setting the reference count to 1.
+It is equivalent to
+.Xr DH_new_method 3
+with a
+.Dv NULL
+argument.
+.Pp
+.Fn DH_up_ref
+increments the reference count by 1.
 .Pp
 .Fn DH_free
-frees the
+decrements the reference count by 1.
+If it reaches 0, it frees the
 .Vt DH
 structure and its components.
 The values are erased before the memory is returned to the system.
@@ -89,6 +103,9 @@ returns
 and sets an error code that can be obtained by
 .Xr ERR_get_error 3 .
 Otherwise it returns a pointer to the newly allocated structure.
+.Pp
+.Fn DH_up_ref
+returns 1 for success or 0 for failure.
 .Sh SEE ALSO
 .Xr BN_new 3 ,
 .Xr d2i_DHparams 3 ,
@@ -108,3 +125,7 @@ and
 .Fn DH_free
 first appeared in SSLeay 0.5.1 and have been available since
 .Ox 2.4 .
+.Pp
+.Fn DH_up_ref
+first appeared in OpenSSL 0.9.7 and has been available since
+.Ox 3.2 .
diff --git a/lib/libcrypto/man/DSA_new.3 b/lib/libcrypto/man/DSA_new.3
index 90e9ab6812b..357b113b0ad 100644
--- a/lib/libcrypto/man/DSA_new.3
+++ b/lib/libcrypto/man/DSA_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: DSA_new.3,v 1.9 2018/03/27 17:35:50 schwarze Exp $
+.\"	$OpenBSD: DSA_new.3,v 1.10 2018/04/18 01:11:45 schwarze Exp $
 .\"	OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
 .\" This file was written by Ulf Moeller <ulf@openssl.org>.
@@ -48,17 +48,22 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 27 2018 $
+.Dd $Mdocdate: April 18 2018 $
 .Dt DSA_NEW 3
 .Os
 .Sh NAME
 .Nm DSA_new ,
+.Nm DSA_up_ref ,
 .Nm DSA_free
 .Nd allocate and free DSA objects
 .Sh SYNOPSIS
 .In openssl/dsa.h
 .Ft DSA*
 .Fn DSA_new void
+.Ft int
+.Fo DSA_up_ref
+.Fa "DSA *dsa"
+.Fc
 .Ft void
 .Fo DSA_free
 .Fa "DSA *dsa"
@@ -69,12 +74,19 @@ The DSA functions implement the Digital Signature Algorithm.
 .Fn DSA_new
 allocates and initializes a
 .Vt DSA
-structure.
+structure, setting the reference count to 1.
 It is equivalent to calling
-.Fn DSA_new_method NULL .
+.Xr DSA_new_method 3
+with a
+.Dv NULL
+argument.
+.Pp
+.Fn DSA_up_ref
+increments the reference count by 1.
 .Pp
 .Fn DSA_free
-frees the
+decrements the reference count by 1.
+If it reaches 0, it frees the
 .Vt DSA
 structure and its components.
 The values are erased before the memory is returned to the system.
@@ -91,6 +103,9 @@ returns
 and sets an error code that can be obtained by
 .Xr ERR_get_error 3 .
 Otherwise it returns a pointer to the newly allocated structure.
+.Pp
+.Fn DSA_up_ref
+returns 1 for success or 0 for failure.
 .Sh SEE ALSO
 .Xr BN_new 3 ,
 .Xr d2i_DSAPublicKey 3 ,
@@ -107,7 +122,6 @@ Otherwise it returns a pointer to the newly allocated structure.
 .Xr DSA_SIG_new 3 ,
 .Xr DSA_sign 3 ,
 .Xr DSA_size 3 ,
-.Xr engine 3 ,
 .Xr ERR_get_error 3 ,
 .Xr EVP_PKEY_set1_DSA 3 ,
 .Xr RSA_new 3
@@ -120,3 +134,7 @@ and
 .Fn DSA_free
 first appeared in SSLeay 0.6.0 and have been available since
 .Ox 2.4 .
+.Pp
+.Fn DSA_up_ref
+first appeared in OpenSSL 0.9.7 and has been available since
+.Ox 3.2 .
diff --git a/lib/libcrypto/man/RSA_new.3 b/lib/libcrypto/man/RSA_new.3
index d995ce12343..0b6bcf97407 100644
--- a/lib/libcrypto/man/RSA_new.3
+++ b/lib/libcrypto/man/RSA_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: RSA_new.3,v 1.9 2018/04/03 21:20:49 tb Exp $
+.\"	$OpenBSD: RSA_new.3,v 1.10 2018/04/18 01:11:45 schwarze Exp $
 .\"	OpenSSL doc/man3/RSA_new.pod 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"	OpenSSL doc/crypto/rsa.pod 35d2e327 Jun 3 16:19:49 2016 -0400
 .\"
@@ -49,17 +49,22 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: April 3 2018 $
+.Dd $Mdocdate: April 18 2018 $
 .Dt RSA_NEW 3
 .Os
 .Sh NAME
 .Nm RSA_new ,
+.Nm RSA_up_ref ,
 .Nm RSA_free
 .Nd allocate and free RSA objects
 .Sh SYNOPSIS
 .In openssl/rsa.h
 .Ft RSA *
 .Fn RSA_new void
+.Ft int
+.Fo RSA_up_ref
+.Fa "RSA *rsa"
+.Fc
 .Ft void
 .Fo RSA_free
 .Fa "RSA *rsa"
@@ -71,12 +76,19 @@ as defined in PKCS #1 v2.0 (RFC 2437).
 .Fn RSA_new
 allocates and initializes an
 .Vt RSA
-structure.
+structure, setting the reference count to 1.
 It is equivalent to calling
-.Fn RSA_new_method NULL .
+.Xr RSA_new_method 3
+with a
+.Dv NULL
+argument.
+.Pp
+.Fn RSA_up_ref
+increments the reference count by 1.
 .Pp
 .Fn RSA_free
-frees the
+decrements the reference count by 1.
+If it reaches 0, it frees the
 .Vt RSA
 structure and its components.
 The key is erased before the memory is returned to the system.
@@ -149,12 +161,14 @@ returns
 and sets an error code that can be obtained by
 .Xr ERR_get_error 3 .
 Otherwise it returns a pointer to the newly allocated structure.
+.Pp
+.Fn RSA_up_ref
+returns 1 for success or 0 for failure.
 .Sh SEE ALSO
 .Xr BN_new 3 ,
 .Xr d2i_RSAPublicKey 3 ,
 .Xr DH_new 3 ,
 .Xr DSA_new 3 ,
-.Xr engine 3 ,
 .Xr ERR_get_error 3 ,
 .Xr EVP_PKEY_set1_RSA 3 ,
 .Xr RSA_blinding_on 3 ,
@@ -181,3 +195,7 @@ and
 .Fn RSA_free
 appeared in SSLeay 0.4 or earlier and have been available since
 .Ox 2.4 .
+.Pp
+.Fn RSA_up_ref
+first appeared in OpenSSL 0.9.7 and has been available since
+.Ox 3.2 .