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

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

3 files changed, 35 insertions, 6 deletions

diff --git a/doc/crypto/DH_get0_pqg.pod b/doc/crypto/DH_get0_pqg.pod
index bcbecf37a6..068096b168 100644
--- a/doc/crypto/DH_get0_pqg.pod
+++ b/doc/crypto/DH_get0_pqg.pod
@@ -47,7 +47,9 @@ be. The values point to the internal representation of the public key and
 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 @@ length parameter associated with this DH object. If the length is non-zero then
 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.
diff --git a/doc/crypto/DSA_get0_pqg.pod b/doc/crypto/DSA_get0_pqg.pod
index 1c835f0128..50f95b94d3 100644
--- a/doc/crypto/DSA_get0_pqg.pod
+++ b/doc/crypto/DSA_get0_pqg.pod
@@ -44,7 +44,9 @@ be. The values point to the internal representation of the public key and
 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 @@ within the DSA object.
 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.
diff --git a/doc/crypto/RSA_get0_key.pod b/doc/crypto/RSA_get0_key.pod
index 5caf9dd72e..0a45cae585 100644
--- a/doc/crypto/RSA_get0_key.pod
+++ b/doc/crypto/RSA_get0_key.pod
@@ -43,10 +43,13 @@ by the caller.
 
 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 object.
 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