Documentation the changed {RSA,DSA,DH}_set0_* functionality change

Reviewed-by: Matt Caswell <matt@openssl.org>

doc/crypto/DH_get0_pqg.pod

diff --git a/doc/crypto/DH_get0_pqg.pod b/doc/crypto/DH_get0_pqg.pod
index bcbecf3..068096b 100644
--- a/doc/crypto/DH_get0_pqg.pod
+++ b/doc/crypto/DH_get0_pqg.pod
@@ -47,7 +47,9 @@
 private key values. This memory should not be freed directly.
 
 The public and private key values can be set using DH_set0_key(). The public
-key must always be non-NULL. The private key may be NULL. As for DH_set0_pqg()
+key must be non-NULL the first time this function is called on a given DH
+object. The private key may be NULL.  On subsequent calls, either may be NULL,
+which means the corresponding DH field is left untouched. As for DH_set0_pqg()
 this function transfers the memory management of the key values to the DH
 object, and therefore they should not be freed directly after this function has
 been called.
@@ -68,6 +70,13 @@
 it is used, otherwise it is ignored. The B<length> parameter indicates the
 length of the secret exponent (private key) in bits.
 
+=head1 NOTES
+
+Values retrieved with DH_get0_key() are owned by the DH object used
+in the call and may therefore I<not> be passed to DH_set0_key().  If
+needed, duplicate the received value using BN_dup() and pass the
+duplicate.  The same applies to DH_get0_pqg() and DH_set0_pqg().
+
 =head1 RETURN VALUES
 
 DH_set0_pqg() and DH_set0_key() return 1 on success or 0 on failure.

doc/crypto/DSA_get0_pqg.pod

diff --git a/doc/crypto/DSA_get0_pqg.pod b/doc/crypto/DSA_get0_pqg.pod
index 1c835f0..50f95b9 100644
--- a/doc/crypto/DSA_get0_pqg.pod
+++ b/doc/crypto/DSA_get0_pqg.pod
@@ -44,7 +44,9 @@
 private key values. This memory should not be freed directly.
 
 The public and private key values can be set using DSA_set0_key(). The public
-key must always be non-NULL. The private key may be NULL. As for DSA_set0_pqg()
+key must be non-NULL the first time this function is called on a given DSA
+object. The private key may be NULL.  On subsequent calls, either may be NULL,
+which means the corresponding DSA field is left untouched. As for DSA_set0_pqg()
 this function transfers the memory management of the key values to the DSA
 object, and therefore they should not be freed directly after this function has
 been called.
@@ -60,6 +62,13 @@
 DSA_get0_engine() returns a handle to the ENGINE that has been set for this DSA
 object, or NULL if no such ENGINE has been set.
 
+=head1 NOTES
+
+Values retrieved with DSA_get0_key() are owned by the DSA object used
+in the call and may therefore I<not> be passed to DSA_set0_key().  If
+needed, duplicate the received value using BN_dup() and pass the
+duplicate.  The same applies to DSA_get0_pqg() and DSA_set0_pqg().
+
 =head1 RETURN VALUES
 
 DSA_set0_pqg() and DSA_set0_key() return 1 on success or 0 on failure.

doc/crypto/RSA_get0_key.pod

diff --git a/doc/crypto/RSA_get0_key.pod b/doc/crypto/RSA_get0_key.pod
index 5caf9dd..0a45cae 100644
--- a/doc/crypto/RSA_get0_key.pod
+++ b/doc/crypto/RSA_get0_key.pod
@@ -43,10 +43,13 @@
 
 The B<n>, B<e> and B<d> parameter values can be set by calling
 RSA_set0_key() and passing the new values for B<n>, B<e> and B<d> as
-parameters to the function. Calling this function transfers the memory
-management of the values to the RSA object, and therefore the values
-that have been passed in should not be freed by the caller after this
-function has been called.
+parameters to the function.  The values B<n> and B<e> must be non-NULL
+the first time this function is called on a given RSA object. The
+value B<d> may be NULL. On subsequent calls any of these values may be
+NULL which means the corresponding RSA field is left untouched.
+Calling this function transfers the memory management of the values to
+the RSA object, and therefore the values that have been passed in
+should not be freed by the caller after this function has been called.
 
 In a similar fashion, the B<p> and B<q> parameters can be obtained and
 set with RSA_get0_factors() and RSA_set0_factors(), and the B<dmp1>,
@@ -65,6 +68,14 @@
 RSA_get0_engine() returns a handle to the ENGINE that has been set for
 this RSA object, or NULL if no such ENGINE has been set.
 
+=head1 NOTES
+
+Values retrieved with RSA_get0_key() are owned by the RSA object used
+in the call and may therefore I<not> be passed to RSA_set0_key().  If
+needed, duplicate the received value using BN_dup() and pass the
+duplicate.  The same applies to RSA_get0_factors() and RSA_set0_factors()
+as well as RSA_get0_crt_params() and RSA_set0_crt_params().
+
 =head1 RETURN VALUES
 
 RSA_set0_key(), RSA_set0_factors and RSA_set0_crt_params() return 1 on