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
	\memberswap{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.
static QByteArrayView	hashInto (QSpan< char > buffer, QByteArrayView message, QByteArrayView key, QCryptographicHash::Algorithm method) noexcept
static QByteArrayView	hashInto (QSpan< uchar > buffer, QByteArrayView message, QByteArrayView key, QCryptographicHash::Algorithm method) noexcept
static QByteArrayView	hashInto (QSpan< std::byte > buffer, QByteArrayView message, QByteArrayView key, QCryptographicHash::Algorithm method) noexcept
	Returns the authentication code for the message (message or, for the QSpan overloads, the concatenation of messageParts) using the key key and the method method.
static QByteArrayView	hashInto (QSpan< char > buffer, QSpan< const QByteArrayView > messageParts, QByteArrayView key, QCryptographicHash::Algorithm method) noexcept
static QByteArrayView	hashInto (QSpan< uchar > buffer, QSpan< const QByteArrayView > messageParts, QByteArrayView key, QCryptographicHash::Algorithm method) noexcept
static QByteArrayView	hashInto (QSpan< std::byte > buffer, QSpan< const QByteArrayView > message, QByteArrayView key, QCryptographicHash::Algorithm method) noexcept

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:

    QMessageAuthenticationCode::hash(message, key, QCryptographicHash::Sha256).toHex();

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 1441 of file qcryptographichash.cpp.

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.

~QMessageAuthenticationCode()

QMessageAuthenticationCode::~QMessageAuthenticationCode

(

)

Destroys the object.

Definition at line 1451 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 1537 of file qcryptographichash.cpp.

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 1549 of file qcryptographichash.cpp.

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 1560 of file qcryptographichash.cpp.

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}

See also

hashInto()

Definition at line 1618 of file qcryptographichash.cpp.

hashInto() [1/6]

static QByteArrayView QMessageAuthenticationCode::hashInto ( QSpan< char > buffer, QByteArrayView message, QByteArrayView key, QCryptographicHash::Algorithm method )

inlinestaticnoexcept

Definition at line 59 of file qmessageauthenticationcode.h.

hashInto() [2/6]

static QByteArrayView QMessageAuthenticationCode::hashInto ( QSpan< char > buffer, QSpan< const QByteArrayView > messageParts, QByteArrayView key, QCryptographicHash::Algorithm method )

inlinestaticnoexcept

Since

6.8

Definition at line 71 of file qmessageauthenticationcode.h.

hashInto() [3/6]

static QByteArrayView QMessageAuthenticationCode::hashInto ( QSpan< std::byte > buffer, QByteArrayView message, QByteArrayView key, QCryptographicHash::Algorithm method )

inlinestaticnoexcept

Returns the authentication code for the message (message or, for the QSpan overloads, the concatenation of messageParts) using the key key and the method method.

The return value will be a sub-span of buffer, unless buffer is of insufficient size, in which case a null QByteArrayView is returned.

See also

hash()

Definition at line 67 of file qmessageauthenticationcode.h.

hashInto() [4/6]

QByteArrayView QMessageAuthenticationCode::hashInto ( QSpan< std::byte > buffer, QSpan< const QByteArrayView > message, QByteArrayView key, QCryptographicHash::Algorithm method )

staticnoexcept

Definition at line 1645 of file qcryptographichash.cpp.

hashInto() [5/6]

static QByteArrayView QMessageAuthenticationCode::hashInto ( QSpan< uchar > buffer, QByteArrayView message, QByteArrayView key, QCryptographicHash::Algorithm method )

inlinestaticnoexcept

Definition at line 63 of file qmessageauthenticationcode.h.

hashInto() [6/6]

static QByteArrayView QMessageAuthenticationCode::hashInto ( QSpan< uchar > buffer, QSpan< const QByteArrayView > messageParts, QByteArrayView key, QCryptographicHash::Algorithm method )

inlinestaticnoexcept

Definition at line 75 of file qmessageauthenticationcode.h.

reset()

void QMessageAuthenticationCode::reset ( )

noexcept

Resets message data.

Calling this function doesn't affect the key.

Definition at line 1489 of file qcryptographichash.cpp.

result()

QByteArray QMessageAuthenticationCode::result

(

)

const

Returns the final authentication code.

See also

resultView(), QByteArray::toHex()

Definition at line 1586 of file qcryptographichash.cpp.

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 1575 of file qcryptographichash.cpp.

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 1527 of file qcryptographichash.cpp.

swap()

void QMessageAuthenticationCode::swap ( QMessageAuthenticationCode & other )

inlinenoexcept

\memberswap{message authentication code}

Since

6.6

Definition at line 31 of file qmessageauthenticationcode.h.

---

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

• qtbase/src/corelib/tools/qmessageauthenticationcode.h (2b6a77cd1509322c5a6f71d5fdbdae68b806080d)
• qtbase/src/corelib/tools/qcryptographichash.cpp (b83e825fab16f83f86149ead78efb6ec3d2fa16d)