From: Richard Levitte Date: Tue, 26 Apr 2016 11:40:53 +0000 (+0200) Subject: Documentation the changed {RSA,DSA,DH}_set0_* functionality change X-Git-Tag: OpenSSL_1_1_0-pre6~1042 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=4c5e6b2cb95a4332829af140e5edba965c9685ce;p=oweals%2Fopenssl.git Documentation the changed {RSA,DSA,DH}_set0_* functionality change Reviewed-by: Matt Caswell --- 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 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 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 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, B and B parameter values can be set by calling RSA_set0_key() and passing the new values for B, B and B 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 and B must be non-NULL +the first time this function is called on a given RSA object. The +value B 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

and B parameters can be obtained and set with RSA_get0_factors() and RSA_set0_factors(), and the B, @@ -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 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