SecureBuilder Class

class QKnxNetIpSecureWrapperProxy::SecureBuilder

The QKnxNetIpSecureWrapperProxy::SecureBuilder class provides the means to create a KNXnet/IP secure wrapper frame. More...

List of all members, including inherited members

Public Functions

	SecureBuilder(const SecureBuilder &other)
	SecureBuilder()
SecureBuilder &	operator=(const SecureBuilder &other)
	~SecureBuilder()
QKnxNetIpFrame	create(const QKnxByteArray &sessionKey) const
SecureBuilder &	setEncapsulatedFrame(const QKnxNetIpFrame &frame)
SecureBuilder &	setMessageTag(quint16 tag)
SecureBuilder &	setSecureSessionId(quint16 sessionId)
SecureBuilder &	setSequenceNumber(quint48 seqNumber)
SecureBuilder &	setSerialNumber(const QKnxByteArray &serialNumber)

Detailed Description

This class is part of the Qt KNX module and currently available as a Technology Preview, and therefore the API and functionality provided by the class may be subject to change at any time without prior notice.

The advantage of using this builder over the default one is that it can take away the burden to do the encryption of the encapsulated frame and the calculation the message authentication code (MAC).

Note: To use this class OpenSSL must be supported on your target system.

This frame will be sent during secure KNXnet/IP communication and includes a fully encrypted KNXnet/IP frame as well as information needed to decrypt the encapsulated frame and for ensuring data integrity and freshness.

The common way to create a secure wrapper frame is:

QKnxNetIpFrame frame = QKnxNetIpFrame::fromBytes(...); // create frame

auto netIpFrame = QKnxNetIpSecureWrapperProxy::secureBuilder()
    .setSequenceNumber(15021976)
    .setSerialNumber(QKnxByteArray::fromHex("0123456789AB"))
    .setEncapsulatedFrame(frame)
    .create(sessionKey);

See also QKnxCryptographicEngine.

Member Function Documentation

SecureBuilder::SecureBuilder(const SecureBuilder &other)

Constructs a copy of other.

SecureBuilder::SecureBuilder()

Creates a new empty secure wrapper frame builder object.

SecureBuilder &SecureBuilder::operator=(const SecureBuilder &other)

Assigns the specified other to this object.

SecureBuilder::~SecureBuilder()

Destroys the object and frees any allocated resources.

QKnxNetIpFrame SecureBuilder::create(const QKnxByteArray &sessionKey) const

Creates and returns a KNXnet/IP secure wrapper frame. During creation the encapsulated frame gets encrypted and the corresponding MAC computed. The given session key sessionKey takes part of the encryption process. Both values, the encrypted frame and the MAC are appended to the KNXnet/IP secure wrapper frame.

Note: The returned frame may be invalid depending on the values used during setup.

See also isValid().

SecureBuilder &SecureBuilder::setEncapsulatedFrame(const QKnxNetIpFrame &frame)

Sets the encapsulated KNXnet/IP frame to frame and returns a reference to the builder.

Note: A secure wrapper frame cannot be encapsulated in another secure wrapper frame and will result in creating an invalid frame.

SecureBuilder &SecureBuilder::setMessageTag(quint16 tag)

Sets the message tag of the generic KNXnet/IP secure wrapper frame to tag and returns a reference to the builder. By default value is set to 0x0000.

This field contains an arbitrary value to differentiate two KNXnet/IP secure wrapper multicast frames sent by one KNXnet/IP device within the same millisecond (thus the same timer value).

Note: For unicast connections this field is ignored and must be set to 0x0000.

SecureBuilder &SecureBuilder::setSecureSessionId(quint16 sessionId)

Sets the secure session ID to sessionId and returns a reference to the builder. By default value is set to 0x0000.

For multicast connections the fixed identifier 0x0000 must be used. For unicast connections the ID was established during a previous successful secure session setup procedure.

SecureBuilder &SecureBuilder::setSequenceNumber(quint48 seqNumber)

Sets the sequence number to seqNumber and returns a reference to the builder.

For unicast connections it is a monotonically increasing sequence number assigned by the sender; incremented by the sender after each frame sent. For multicast connections this is the device's current multicast timer value in millisecond resolution.

Note: The size of a sequence number is limited to 48 bits, so the maximum number can be 281474976710655. Passing a larger value will result in creating an invalid frame.

SecureBuilder &SecureBuilder::setSerialNumber(const QKnxByteArray &serialNumber)

Sets the serial number to serialNumber of the device sending the frame and returns a reference to the builder.

Note: The serial number must contain exactly 6 bytes.

© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.