Add threading documentation to DH and DSA

The RSA, etc., APIs have some discussion on threading expectations. We
should have the same text on DH and DSA.

While I'm here, const-correct DSA_SIG in some legacy DSA APIs.

Change-Id: I6ad43c9347c320dc0b1c8e73850fa07c41e028ea
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/67247
Reviewed-by: Theo Buehler <theorbuehler@gmail.com>
Auto-Submit: David Benjamin <davidben@google.com>
Reviewed-by: Bob Beck <bbe@google.com>
Commit-Queue: Bob Beck <bbe@google.com>

2 files changed, 27 insertions, 4 deletions

diff --git a/include/openssl/dh.h b/include/openssl/dh.h
index a3094d8..6373bbb 100644
--- a/include/openssl/dh.h
+++ b/include/openssl/dh.h
@@ -75,6 +75,12 @@ extern "C" {
 
 
 // Allocation and destruction.
+//
+// A |DH| object represents a Diffie-Hellman key or group parameters. A given
+// object may be used concurrently on multiple threads by non-mutating
+// functions, provided no other thread is concurrently calling a mutating
+// function. Unless otherwise documented, functions which take a |const| pointer
+// are non-mutating and functions which take a non-|const| pointer are mutating.
 
 // DH_new returns a new, empty DH object or NULL on error.
 OPENSSL_EXPORT DH *DH_new(void);
@@ -83,7 +89,8 @@ OPENSSL_EXPORT DH *DH_new(void);
 // count drops to zero.
 OPENSSL_EXPORT void DH_free(DH *dh);
 
-// DH_up_ref increments the reference count of |dh| and returns one.
+// DH_up_ref increments the reference count of |dh| and returns one. It does not
+// mutate |dh| for thread-safety purposes and may be used concurrently.
 OPENSSL_EXPORT int DH_up_ref(DH *dh);
 
 
@@ -214,6 +221,9 @@ OPENSSL_EXPORT int DH_generate_key(DH *dh);
 // Callers that expect a fixed-width secret should use this function over
 // |DH_compute_key|. Callers that use either function should migrate to a modern
 // primitive such as X25519 or ECDH with P-256 instead.
+//
+// This function does not mutate |dh| for thread-safety purposes and may be used
+// concurrently.
 OPENSSL_EXPORT int DH_compute_key_padded(uint8_t *out, const BIGNUM *peers_key,
                                          DH *dh);
 
@@ -225,6 +235,9 @@ OPENSSL_EXPORT int DH_compute_key_padded(uint8_t *out, const BIGNUM *peers_key,
 //
 // NOTE: this follows the usual BoringSSL return-value convention, but that's
 // different from |DH_compute_key| and |DH_compute_key_padded|.
+//
+// This function does not mutate |dh| for thread-safety purposes and may be used
+// concurrently.
 OPENSSL_EXPORT int DH_compute_key_hashed(DH *dh, uint8_t *out, size_t *out_len,
                                          size_t max_out_len,
                                          const BIGNUM *peers_key,
@@ -327,6 +340,9 @@ OPENSSL_EXPORT int i2d_DHparams(const DH *in, unsigned char **outp);
 // Callers that expect a fixed-width secret should use |DH_compute_key_padded|
 // instead. Callers that use either function should migrate to a modern
 // primitive such as X25519 or ECDH with P-256 instead.
+//
+// This function does not mutate |dh| for thread-safety purposes and may be used
+// concurrently.
 OPENSSL_EXPORT int DH_compute_key(uint8_t *out, const BIGNUM *peers_key,
                                   DH *dh);
 
diff --git a/include/openssl/dsa.h b/include/openssl/dsa.h
index 4075001..f46a8fc 100644
--- a/include/openssl/dsa.h
+++ b/include/openssl/dsa.h
@@ -78,6 +78,12 @@ extern "C" {
 
 
 // Allocation and destruction.
+//
+// A |DSA| object represents a DSA key or group parameters. A given object may
+// be used concurrently on multiple threads by non-mutating functions, provided
+// no other thread is concurrently calling a mutating function. Unless otherwise
+// documented, functions which take a |const| pointer are non-mutating and
+// functions which take a non-|const| pointer are mutating.
 
 // DSA_new returns a new, empty DSA object or NULL on error.
 OPENSSL_EXPORT DSA *DSA_new(void);
@@ -86,7 +92,8 @@ OPENSSL_EXPORT DSA *DSA_new(void);
 // reference count drops to zero.
 OPENSSL_EXPORT void DSA_free(DSA *dsa);
 
-// DSA_up_ref increments the reference count of |dsa| and returns one.
+// DSA_up_ref increments the reference count of |dsa| and returns one. It does
+// not mutate |dsa| for thread-safety purposes and may be used concurrently.
 OPENSSL_EXPORT int DSA_up_ref(DSA *dsa);
 
 
@@ -216,7 +223,7 @@ OPENSSL_EXPORT DSA_SIG *DSA_do_sign(const uint8_t *digest, size_t digest_len,
 //
 // TODO(fork): deprecate.
 OPENSSL_EXPORT int DSA_do_verify(const uint8_t *digest, size_t digest_len,
-                                 DSA_SIG *sig, const DSA *dsa);
+                                 const DSA_SIG *sig, const DSA *dsa);
 
 // DSA_do_check_signature sets |*out_valid| to zero. Then it verifies that |sig|
 // is a valid signature, by the public key in |dsa| of the hash in |digest|
@@ -225,7 +232,7 @@ OPENSSL_EXPORT int DSA_do_verify(const uint8_t *digest, size_t digest_len,
 // It returns one if it was able to verify the signature as valid or invalid,
 // and zero on error.
 OPENSSL_EXPORT int DSA_do_check_signature(int *out_valid, const uint8_t *digest,
-                                          size_t digest_len, DSA_SIG *sig,
+                                          size_t digest_len, const DSA_SIG *sig,
                                           const DSA *dsa);