From 21eeef83f642d8c34f7ab3bbcd3171c267cff09f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kai=20K=C3=B6hne?= <kai.koehne@qt.io>
Date: Mon, 27 Nov 2023 15:48:36 +0100
Subject: [PATCH] Doc: Improve documentation for QMessageAuthenticationCode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Mention 'HMAC' as something people will search for
* Change description to actually reflect code snippet
  (where the key is passed to the constructor)
* At least mention that the security of the HMAC depends
  also on the length of the key, as the code snippet
  uses an artificial/short key. Not sure whether we
  should further expand on this, or link to some other source?

Pick-to: 6.5 6.6
Fixes: QTBUG-119499
Change-Id: I2768d9a9d553957e1a778c798d82a73468bee16f
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
---
 src/corelib/tools/qcryptographichash.cpp | 27 +++++++++++++++++-------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/src/corelib/tools/qcryptographichash.cpp b/src/corelib/tools/qcryptographichash.cpp
index 8e2abc2307a..01dca14d220 100644
--- a/src/corelib/tools/qcryptographichash.cpp
+++ b/src/corelib/tools/qcryptographichash.cpp
@@ -1417,21 +1417,32 @@ void QMessageAuthenticationCodePrivate::initMessageHash() noexcept
     \ingroup tools
     \reentrant
 
-    QMessageAuthenticationCode supports all cryptographic hashes which are supported by
-    QCryptographicHash.
+    Use the QMessageAuthenticationCode class to generate hash-based message
+    authentication codes (HMACs). The class supports all cryptographic
+    hash algorithms from \l QCryptographicHash (see also
+    \l{QCryptographicHash::Algorithms}).
+
+    To generate a message authentication code, pass a suitable hash
+    algorithm and secret key to the constructor. Then process the message
+    data by calling \l addData() one or more times. After the full
+    message has been processed, get the final authentication code
+    via the \l result() function:
 
-    To generate message authentication code, pass hash algorithm QCryptographicHash::Algorithm
-    to constructor, then set key and message by setKey() and addData() functions. Result
-    can be acquired by result() function.
     \snippet qmessageauthenticationcode/main.cpp 0
     \dots
     \snippet qmessageauthenticationcode/main.cpp 1
 
-    Alternatively, this effect can be achieved by providing message,
-    key and method to hash() method.
+    For simple cases like above, you can also use the static
+    \l hash() function:
+
     \snippet qmessageauthenticationcode/main.cpp 2
 
-    \sa QCryptographicHash
+
+    \note The cryptographic strength of the HMAC depends upon the
+    size of the secret key, and the security of the
+    underlying hash function.
+
+    \sa QCryptographicHash, QCryptographicHash::Algorithms
 */
 
 /*!