How PSSP communication works

Connections, authentication, encrypted sessions and data delivery

An end device and a server application each establish a PSSP session with the broker. The broker authenticates both participants, enforces their permissions and delivers opaque application data to authorized receivers. Your application defines the payload format and what successful processing means.

1. Establish a connection

Connect to the broker's TCP listener, normally port 6688. When TLS is enabled, complete the TLS 1.3 handshake first and verify that the trusted certificate matches the broker hostname. Send HELLO and wait for HELLO_ACK, which describes the connection identifier, protocol limits and encryption requirements.

Check the negotiated limits before sending data. TCP is a byte stream: a read may contain only part of a record or several records together. Buffer incoming bytes and decode complete records instead of treating each socket read as one message.

2. Establish encryption and authenticate

TLS and PSSP AES-256-GCM are independent settings. Configure both participants to match the broker. The default AES-only setup verifies a pinned broker X25519 public key; the pin must come from a trusted administrator or provisioning process.

AES enabled, TLS disabled

Verify the broker's advertised X25519 public key against your configured pin.
Generate an ephemeral X25519 key pair and fresh salt, then send KEY_REQUEST with the public material.
Derive the session's AES key using X25519 and HKDF-SHA-256. The symmetric key is not transmitted.
Send encrypted AUTH with your Client ID, Username and Password.
Wait for AUTH_OK before performing application operations. Treat AUTH_ERROR as a failed session.

TLS and AES both enabled

After the TLS handshake and protocol negotiation, authenticate inside TLS. Then request the PSSP encryption key. The broker returns a fresh session key and nonce prefixes inside the protected TLS connection. Subsequent PSSP records use AES-GCM.

Keys and sequence state belong to one connection. A reconnect requires a new session; do not reuse previous encrypted records, nonces or UDP association state.

3. Prepare the receiver

After authentication, the receiving application registers its administrator-approved subscription and waits for acceptance. This tells the broker that it is ready to receive authorized data. Keep a stable Worker ID for the same logical receiver if it needs to resume after reconnection.

Replay selection	Behavior
Latest	Receive newly published data after subscribing.
Earliest available	Read data still retained by the broker, then receive new data.
Resume after ACK	Continue after the acknowledged position for the same receiver identity, subject to retention and resume limits.

The broker controls delivery permissions. A client cannot acquire additional access by choosing a different Worker ID.

4. Send and receive application data

Encode the payload in the format agreed by the device and server, then publish using the identity's assigned settings. For reliable delivery, include the publisher session identifier and increasing publisher sequence required by the protocol. The broker uses that pair to recognize repeated submissions.

The sender publishes a payload over TCP using QoS 1.
The broker accepts it into its bounded buffer and returns PUBACK.
An authorized receiver receives MESSAGE and validates its payload.
The receiver completes its required durable handoff and returns MSGACK.

These acknowledgements represent different stages. Broker acceptance does not prove completed server processing. If your device needs confirmation of an application outcome, define a response in your application format and send it back through an authorized PSSP session.

Use application message identifiers and idempotent processing where a repeated delivery could otherwise cause a duplicate effect. The broker's deduplication and in-memory buffering do not replace your application's persistent state.

5. Select the appropriate delivery behavior

Option	Characteristics	Application responsibility
TCP QoS 1	Acknowledged publication and receipt; replay while data remains retained	Handle retries, duplicates, processing failures and expired data
UDP QoS 0	Best effort; no delivery acknowledgement or replay guarantee	Use only when losing an individual message is acceptable

UDP uses port 6688 by default and requires an association established through a live authenticated TCP session. With PSSP AES enabled, UDP records are encrypted and protected by a replay window. A dropped TCP session invalidates its UDP association.

6. Handle connection loss and recovery

Detect the failed session and stop using its encryption and association state.
Reconnect with bounded retry delays, renegotiate security and authenticate again.
Restore reception using the same logical receiver identity and the appropriate replay selection.
Process repeated deliveries idempotently and acknowledge after the required handoff.
If the broker reports GAP, recover missing data through your application's storage or recovery mechanism.

Broker buffering is limited by size, count and age. Restarting the broker loses buffered application data. Its persistent administrative database is not an application-data archive. Design recovery around your own durability requirements.

7. Validate a device-to-server integration

Begin with a small payload and confirm authentication, sender acknowledgement, receiver delivery and decoded content separately. Then test the reverse direction, a temporary disconnection, a server restart, repeated data, rejected credentials and rejected operations. Measure throughput with realistic payload sizes only after the basic flow works.

The desktop client provides Settings for connecting and transferring test data, Events for inspecting received content, and Monitor for protocol diagnostics. Use the broker portal to review identities, active connections and logs. Protect passwords and private keys when collecting diagnostic information.