Mirror dsa.h's deprecation notice in dh.h.

https://raccoon-attack.com/ also applies to anyone using DH_compute_key
with a static key. Add a warning to header.

Change-Id: I937f111706bd3b4d57b076c1d0fc328809b36bb0
Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/42904
Reviewed-by: Adam Langley <agl@google.com>

include/openssl/dh.h

diff --git a/include/openssl/dh.h b/include/openssl/dh.h
index f3badcc..34e70c9 100644
--- a/include/openssl/dh.h
+++ b/include/openssl/dh.h
@@ -69,6 +69,10 @@
 
 // DH contains functions for performing Diffie-Hellman key agreement in
 // multiplicative groups.
+//
+// This module is deprecated and retained for legacy reasons only. It is not
+// considered a priority for performance or hardening work. Do not use it in
+// new code. Use X25519 or ECDH with P-256 instead.
 
 
 // Allocation and destruction.
@@ -164,6 +168,14 @@
 // writes it as a big-endian integer into |out|, which must have |DH_size|
 // bytes of space. It returns the number of bytes written, or a negative number
 // on error.
+//
+// Note the output may be shorter than |DH_size| bytes. Contrary to PKCS #3,
+// this function returns a variable-length shared key with leading zeros
+// removed. This may result in sporadic key mismatch and, if |dh| is reused,
+// side channel attacks such as https://raccoon-attack.com/.
+//
+// This is a legacy algorithm, so we do not provide a fixed-width variant. Use
+// X25519 or ECDH with P-256 instead.
 OPENSSL_EXPORT int DH_compute_key(uint8_t *out, const BIGNUM *peers_key,
                                   DH *dh);