QMessageAuthenticationCode Class Reference

\inmodule QtCore More...

#include <qmessageauthenticationcode.h>

Collaboration diagram for QMessageAuthenticationCode:

Public Member Functions
	QMessageAuthenticationCode (QCryptographicHash::Algorithm method, QByteArrayView key={})
	QMessageAuthenticationCode (QMessageAuthenticationCode &&other) noexcept
	Move-constructs a new QMessageAuthenticationCode from other.
	~QMessageAuthenticationCode ()
	Destroys the object.
void	swap (QMessageAuthenticationCode &other) noexcept
	Swaps message authentication code other with this message authentication code.
void	reset () noexcept
	Resets message data.
void	setKey (QByteArrayView key) noexcept
	Sets secret key.
void	addData (const char *data, qsizetype length)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Adds the first length chars of data to the message.
void	addData (QByteArrayView data) noexcept
	Adds data to the message.
bool	addData (QIODevice *device)
	Reads the data from the open QIODevice device until it ends and adds it to message.
QByteArrayView	resultView () const noexcept
QByteArray	result () const
	Returns the final authentication code.

Static Public Member Functions
static QByteArray	hash (QByteArrayView message, QByteArrayView key, QCryptographicHash::Algorithm method)
	Returns the authentication code for the message message using the key key and the method method.

Detailed Description

\inmodule QtCore

The QMessageAuthenticationCode class provides a way to generate hash-based message authentication codes.

Since

5.1

\reentrant

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::Algorithm}).

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:

    QByteArray key = "key";
    QByteArray message = "The quick brown fox jumps over the lazy dog";

\dots

    QMessageAuthenticationCode code(QCryptographicHash::Sha256, key);
    code.addData(message);
    code.result().toHex(); // returns "f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8"

For simple cases like above, you can also use the static \l hash() function:

Note

The cryptographic strength of the HMAC depends upon the size of the secret key, and the security of the underlying hash function.

See also

QCryptographicHash, QCryptographicHash::Algorithm

Definition at line 16 of file qmessageauthenticationcode.h.

Constructor & Destructor Documentation

QMessageAuthenticationCode() [1/2]

QMessageAuthenticationCode::QMessageAuthenticationCode ( QCryptographicHash::Algorithm method, QByteArrayView key = {} )

explicit

Constructs an object that can be used to create a cryptographic hash from data
using method \a method and key \a key.

! [qba-to-qbav-6.6]

Note

In Qt versions prior to 6.6, this function took its arguments as QByteArray, not QByteArrayView. If you experience compile errors, it's because your code is passing objects that are implicitly convertible to QByteArray, but not QByteArrayView. Wrap the corresponding argument in {QByteArray{~~~}} to make the cast explicit. This is backwards-compatible with old Qt versions. ! [qba-to-qbav-6.6]

Definition at line 1461 of file qcryptographichash.cpp.

References QMessageAuthenticationCodePrivate::setKey().

Here is the call graph for this function:

QMessageAuthenticationCode() [2/2]

QMessageAuthenticationCode::QMessageAuthenticationCode ( QMessageAuthenticationCode && other )

inlinenoexcept

Move-constructs a new QMessageAuthenticationCode from other.

Note

The moved-from object other is placed in a partially-formed state, in which the only valid operations are destruction and assignment of a new object.

Since

6.6

Definition at line 26 of file qmessageauthenticationcode.h.

References other().

Here is the call graph for this function:

~QMessageAuthenticationCode()

QMessageAuthenticationCode::~QMessageAuthenticationCode

(

)

Destroys the object.

Definition at line 1471 of file qcryptographichash.cpp.

Member Function Documentation

addData() [1/3]

void QMessageAuthenticationCode::addData	(	const char *	data,
		qsizetype	length )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Adds the first length chars of data to the message.

Definition at line 1560 of file qcryptographichash.cpp.

References QCryptographicHashPrivate::addData(), and QMessageAuthenticationCodePrivate::messageHash.

Here is the call graph for this function:

addData() [2/3]

void QMessageAuthenticationCode::addData ( QByteArrayView data )

noexcept

Adds data to the message.

{qba-to-qbav-6.6}

See also

resultView(), result()

Definition at line 1572 of file qcryptographichash.cpp.

References d.

addData() [3/3]

bool QMessageAuthenticationCode::addData

(

QIODevice *

device

)

Reads the data from the open QIODevice device until it ends and adds it to message.

Returns true if reading was successful.

Note

device must be already opened.

Definition at line 1583 of file qcryptographichash.cpp.

References QCryptographicHashPrivate::addData(), device, and QMessageAuthenticationCodePrivate::messageHash.

Here is the call graph for this function:

hash()

QByteArray QMessageAuthenticationCode::hash ( QByteArrayView message, QByteArrayView key, QCryptographicHash::Algorithm method )

static

Returns the authentication code for the message message using the key key and the method method.

{qba-to-qbav-6.6}

Definition at line 1639 of file qcryptographichash.cpp.

References method.

Referenced by main().

Here is the caller graph for this function:

reset()

void QMessageAuthenticationCode::reset ( )

noexcept

Resets message data.

Calling this function doesn't affect the key.

Definition at line 1512 of file qcryptographichash.cpp.

References QMessageAuthenticationCodePrivate::initMessageHash(), QMessageAuthenticationCodePrivate::messageHash, and QCryptographicHashPrivate::reset().

Here is the call graph for this function:

result()

QByteArray QMessageAuthenticationCode::result

(

)

const

Returns the final authentication code.

See also

resultView(), QByteArray::toHex()

Definition at line 1609 of file qcryptographichash.cpp.

References resultView(), and QByteArrayView::toByteArray().

Here is the call graph for this function:

resultView()

QByteArrayView QMessageAuthenticationCode::resultView ( ) const

noexcept

Since

6.6

Returns the final hash value.

Note that the returned view remains valid only as long as the QMessageAuthenticationCode object is not modified by other means.

See also

result()

Definition at line 1598 of file qcryptographichash.cpp.

References QMessageAuthenticationCodePrivate::finalize(), QMessageAuthenticationCodePrivate::messageHash, and QCryptographicHashPrivate::resultView().

Referenced by result().

Here is the call graph for this function:

Here is the caller graph for this function:

setKey()

void QMessageAuthenticationCode::setKey ( QByteArrayView key )

noexcept

Sets secret key.

Calling this function automatically resets the object state.

For optimal performance, call this function only to change the active key, not to set an initial key, as in

QMessageAuthenticationCode mac(method);
mac.setKey(key); // does extra work
use(mac);

Prefer to pass initial keys as the constructor argument:

QMessageAuthenticationCode mac(method, key); // OK, optimal
use(mac);

You can use std::optional to delay construction of a QMessageAuthenticationCode until you know the key:

std::optional<QMessageAuthenticationCode> mac;
~~~
key = ~~~;
mac.emplace(method, key);
use(*mac);

{qba-to-qbav-6.6}

Definition at line 1550 of file qcryptographichash.cpp.

References d.

swap()

void QMessageAuthenticationCode::swap ( QMessageAuthenticationCode & other )

inlinenoexcept

Swaps message authentication code other with this message authentication code.

This operation is very fast and never fails.

Since

6.6

Definition at line 31 of file qmessageauthenticationcode.h.

References d, other(), and qt_ptr_swap().

Here is the call graph for this function:

---

The documentation for this class was generated from the following files:

• qtbase/src/corelib/tools/qmessageauthenticationcode.h (a6bf36d409f5a5ba7cae7438142c37d786042429)
• qtbase/src/corelib/tools/qcryptographichash.cpp (96740ea3fed8a7837dc282135661723858fff198)