diff options
author | Kai Köhne <kai.koehne@qt.io> | 2023-11-27 15:48:36 +0100 |
---|---|---|
committer | Kai Köhne <kai.koehne@qt.io> | 2023-12-04 15:19:38 +0100 |
commit | 21eeef83f642d8c34f7ab3bbcd3171c267cff09f (patch) | |
tree | ae908bc7936954d94773a6e7879525e20e9aafb1 | |
parent | 0f985e16ba741695182020f2c6a952f31e44c722 (diff) |
Doc: Improve documentation for QMessageAuthenticationCode
* 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>
-rw-r--r-- | src/corelib/tools/qcryptographichash.cpp | 27 |
1 files changed, 19 insertions, 8 deletions
diff --git a/src/corelib/tools/qcryptographichash.cpp b/src/corelib/tools/qcryptographichash.cpp index 8e2abc2307..01dca14d22 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 */ /*! |