Builder Class

class QKnxNetIpSecureWrapperProxy::Builder

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

List of all members, including inherited members

Public Functions

	Builder(const Builder &other)
	Builder()
Builder &	operator=(const Builder &other)
	~Builder()
QKnxNetIpFrame	create() const
Builder &	setEncapsulatedFrame(const QKnxByteArray &frame)
Builder &	setMessageAuthenticationCode(const QKnxByteArray &data)
Builder &	setMessageTag(quint16 tag)
Builder &	setSecureSessionId(quint16 sessionId)
Builder &	setSequenceNumber(quint48 seqNumber)
Builder &	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.

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 to ensure data integrity and freshness.

The common way to create a secure wrapper frame is:

auto auth = ... // create the full 128 bit CCM-MAC
auto frame = ... // create encrypted frame

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

See also QKnxCryptographicEngine.

Member Function Documentation

Builder::Builder(const Builder &other)

Constructs a copy of other.

Builder::Builder()

Creates a new empty secure wrapper frame builder object.

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

Assigns the specified other to this object.

Builder::~Builder()

Destroys the object and frees any allocated resources.

QKnxNetIpFrame Builder::create() const

Creates and returns a KNXnet/IP secure wrapper frame.

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

See also isValid().

Builder &Builder::setEncapsulatedFrame(const QKnxByteArray &frame)

Sets the encapsulated and already encrypted 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.

Builder &Builder::setMessageAuthenticationCode(const QKnxByteArray &data)

Sets the AES128 CCM message authentication code (MAC) of the generic KNXnet/IP secure wrapper frame to data and returns a reference to builder. The MAC has a fixed size of 16 bytes.

Builder &Builder::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.

Builder &Builder::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.

Builder &Builder::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.

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

Sets the serial number to serialNumber 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.