QKnxCryptographicEngine Class

auto dummyMac = QKnxByteArray(16, 000); // dummy to get a valid header

// Session Response Frame

quint16 secureSessionIdentifier = 0x0001;
auto responseBuilder = QKnxNetIpSessionResponseProxy::builder();

// create an intermediate frame to fetch a valid frame header
auto netIpFrame = responseBuilder
    .setSecureSessionId(secureSessionIdentifier)
    .setPublicKey(serverPublicKey)
    .setMessageAuthenticationCode(dummyMac)
    .create();

auto deviceAuthenticationHash =
    QKnxCryptographicEngine::deviceAuthenticationCodeHash({ "trustme" });
auto XOR_X_Y = QKnxCryptographicEngine::XOR(clientPublicKey.bytes(), serverPublicKey.bytes());

auto mac = QKnxCryptographicEngine::computeMessageAuthenticationCode(deviceAuthenticationHash,
    netIpFrame.header(), secureSessionIdentifier, XOR_X_Y);

// create the final frame including the computed MAC
netIpFrame = responseBuilder.
    .setMessageAuthenticationCode(mac)
    .create();


// Session Authenticate Frame

auto authenticateBuilder = QKnxNetIpSessionAuthenticateProxy::builder()'

// create an intermediate frame to fetch a valid frame header
netIpFrame = authenticateBuilder
    .setUserId(QKnxNetIp::SecureUserId::Management)
    .setMessageAuthenticationCode(dummyMac)
    .create();

auto passwordHash = QKnxCryptographicEngine::userPasswordHash({ "secret" });

mac = QKnxCryptographicEngine::computeMessageAuthenticationCode(passwordHash,
    netIpFrame.header(), userId, XOR_X_Y);

// create the final frame including the computed MAC
netIpFrame = responseBuilder.
    .setMessageAuthenticationCode(mac)
    .create();


// Timer Notify Frame

quint48 timerValue = 211938428830917;
auto serialNumber = QKnxByteArray::fromHex("00fa12345678");
quint16 messageTag = quint16(QRandomGenerator::global()->generate();

auto timerNotifyBuilder = QKnxNetIpTimerNotifyProxy::builder();

// create an intermediate frame to fetch a valid frame header
netIpFrame = timerNotifyBuilder
    .setTimerValue(timerValue)
    .setSerialNumber(serialNumber)
    .setMessageTag(messageTag)
    .setMessageAuthenticationCode(dummyMac)
    .create();

QKnxByteArray dummyPayload;
quint16 dummySession = 0x0000;
auto backboneKey = QKnxByteArray::fromHex("000102030405060708090a0b0c0d0e0f");

mac = QKnxCryptographicEngine::computeMessageAuthenticationCode(backboneKey,
    netIpFrame.header(), dummySession, dummyPayload, timerValue, serialNumber, messageTag);

// create the final frame including the computed MAC
netIpFrame = responseBuilder.
    .setMessageAuthenticationCode(mac)
    .create();

Member Function Documentation

[static] QKnxByteArray QKnxCryptographicEngine::XOR(const QKnxByteArray &left, const QKnxByteArray &right, bool adjust = true)

Performs a byte-wise XOR operation on the arguments left and right. If the arguments are not equal in size, the function uses only the shorter array for the operation. If adjust is set to true, the arrays are made equal by padding them with 0x00 bytes.

[static] QKnxByteArray QKnxCryptographicEngine::computeMessageAuthenticationCode(const QKnxByteArray &key, const QKnxNetIpFrameHeader &header, quint16 id, const QKnxByteArray &data, quint48 sequenceNumber = 0, const QKnxByteArray &serialNumber = {}, quint16 messageTag = 0)

Computes a message authentication code (MAC) using the given key, header, and id for the given data. Returns an array of bytes that represent the computed MAC or an empty byte array in case of an error.

For an example of using this function, see Calculating Message Authentication Codes.

[static] QKnxByteArray QKnxCryptographicEngine::decodeAndDecryptPassword(const QKnxByteArray &passwordHash, const QKnxByteArray &createdHash, const QByteArray &password)

Decodes and decrypts a password password that was stored in an ETS keyring (*.knxkeys) file with the given password hash passwordHash and created hash createdHash.

Returns an array of bytes that represent the decrypted password or an empty byte array in case of an error.

[static] QKnxByteArray QKnxCryptographicEngine::decodeAndDecryptToolKey(const QKnxByteArray &passwordHash, const QKnxByteArray &createdHash, const QByteArray &toolKey)

Decodes and decrypts a tool key toolKey that was stored in an ETS keyring (*.knxkeys) file with the given password hash passwordHash and created hash createdHash.

Returns an array of bytes that represent the decrypted tool key or an empty byte array in case of an error.

[static] QKnxByteArray QKnxCryptographicEngine::decrypt(const QKnxByteArray &key, const QKnxByteArray &iv, const QKnxByteArray &data)

Decrypts the given data with key and the initial vector iv. Returns an array of bytes that represents the decrypted data.

[static] QKnxByteArray QKnxCryptographicEngine::decryptMessageAuthenticationCode(const QKnxByteArray &key, const QKnxByteArray &mac, quint48 sequenceNumber = 0, const QKnxByteArray &serialNumber = {}, quint16 messageTag = 0)

Decrypts the given message authentication code (MAC) mac with the given key key, sequence number sequenceNumber, serial number serialNumber, and message tag messageTag. Returns an array of bytes that represent the decrypted MAC or an empty byte array in case of an error.

[static] QKnxByteArray QKnxCryptographicEngine::decryptSecureWrapperPayload(const QKnxByteArray &key, const QKnxByteArray &frame, quint48 sequenceNumber, const QKnxByteArray &serialNumber, quint16 messageTag)

Decrypts the given KNXnet/IP frame frame with the given key key, sequence number sequenceNumber, serial number serialNumber, and message tag messageTag. Returns an array of bytes that represent the decrypted frame or an empty byte array in case of an error.

[static] QKnxByteArray QKnxCryptographicEngine::deviceAuthenticationCodeHash(const QByteArray &password)

Returns the device authentication code hash derived from the user chosen password password.

[static] QKnxByteArray QKnxCryptographicEngine::encrypt(const QKnxByteArray &key, const QKnxByteArray &iv, const QKnxByteArray &data)

Encrypts the given data with key and the initial vector iv. Returns an array of bytes that represents the encrypted data.

[static] QKnxByteArray QKnxCryptographicEngine::encryptMessageAuthenticationCode(const QKnxByteArray &key, const QKnxByteArray &mac, quint48 sequenceNumber = 0, const QKnxByteArray &serialNumber = {}, quint16 messageTag = 0)

Encrypts the given message authentication code (MAC) mac with the given key key, sequence number sequenceNumber, serial number serialNumber, and message tag messageTag. Returns an array of bytes that represent the encrypted MAC or an empty byte array in case of an error.

[static] QKnxByteArray QKnxCryptographicEngine::encryptSecureWrapperPayload(const QKnxByteArray &key, const QKnxNetIpFrame &frame, quint48 sequenceNumber, const QKnxByteArray &serialNumber, quint16 messageTag)

Encrypts the given KNXnet/IP frame frame with the given key key, sequence number sequenceNumber, serial number serialNumber, and message tag messageTag. Returns an array of bytes that represent the encrypted frame or an empty byte array in case of an error or invalid KNXnet/IP frame frame.

[static] QKnxByteArray QKnxCryptographicEngine::hashSha256(const QByteArray &data)

Returns the hash of data using the Sha256 algorithm.

[static] QKnxByteArray QKnxCryptographicEngine::keyringPasswordHash(const QByteArray &password)

Returns the keyring password hash derived from the user chosen password password.

[static] QKnxByteArray QKnxCryptographicEngine::sessionKey(const QKnxSecureKey &privateKey, const QKnxSecureKey &peerPublicKey)

Returns the session key calculated from the given private key privateKey and the peer's public key peerPublicKey if OpenSSL is available and no error occurs; otherwise returns a default-constructed value which can be empty.

[static] QKnxByteArray QKnxCryptographicEngine::sessionKey(const QKnxByteArray &privateKey, const QKnxByteArray &peerPublicKey)

This function overloads sessionKey().

[static] QKnxByteArray QKnxCryptographicEngine::sessionKey(const QKnxByteArray &sharedSecret)

Returns the session key computed from the given secret sharedSecret.

[static] long QKnxCryptographicEngine::sslLibraryVersionNumber()

Returns the OpenSSL version number of the OpenSSL library if OpenSSL is available and used to provide cryptographic support; or 0 in any other case.

[static] bool QKnxCryptographicEngine::supportsCryptography()

Determines if cryptography support is available. Returns true on success; false otherwise.

[static] QKnxByteArray QKnxCryptographicEngine::userPasswordHash(const QByteArray &password)

Returns the password hash derived from the user chosen password password.