Secure Session Control - 0x2E

Response frame: 0xAE - Secure Session Response

Description

This frame type is used to control a secure session between a client and a server. If the remote node has a password set and you set the frame to login, this will establish a secure session that will allow secured messages to be passed between the server and client.

This frame is also used for clients to log out of an existing secure session.

Secure Sessions are end-to-end connections. If a login attempt is addressed to a broadcast address, the attempt will fail with an invalid value—status 0xA—error.

Format

The following table provides the contents of the frame. For details on frame structure, see API frame format.

Offset Size Frame Field Description
0 8-bit Start Delimiter Indicates the start of an API frame.
1 16-bit Length Number of bytes between the length and checksum.
3 8-bit Frame type

Secure Session Control - 0x2E

4 64-bit 64-bit destination address

Set to the 64-bit IEEE address of the destination device.

Set to a broadcast address (0x000000000000FFFF) to affect all active incoming sessions.

12 8-bit Secure Session options

Bit field of options that alter the session behavior:

  • Bit 0: Client-side control:
    • [0x00] = Login - Log in to a server as a client. 
      • If this bit is clear, the local device will act as a client and initiate SRP authentication with the target server.

    • [0x01] = Logout - Log out of an existing session as a client.
      • If this bit is set, the local device will attempt to end an existing client-side session with the target server.

      • When set, all other options, the timeout field, and password will be ignored.

  • Bit 1: Server-side control:
    • [0x02] =  Terminate Session - If this bit is set, the server will end active incoming session(s).
      • The address field can be set to a specific node or the broadcast address can be used to end all incoming sessions.
      • Use Extended Modem Status - 0x98 frames to manage multiple incoming sessions.
  • Bit 2: Timeout type:
    • [0x00] = Fixed timeout - The session terminates after the timeout period has elapsed.
    • [0x04] = Inter-packet timeout - The timeout is refreshed every time a secure transmission occurs between client and server.

Note Option values may be combined. Set all unused bits to 0.

13 16-bit

Timeout

Timeout value for the secure session in units of ⅒th second. Accepts up to 0x4650 (30 minutes).

A session with a timeout of 0x0000 is considered a yielding session. Yielding sessions will never time out, but if a server receives a request to start a session when it has the maximum incoming sessions, the oldest yielding session will be ended by the server to make room for the new session. Sessions with non-zero timeouts will never be ended in this way.

15-n variable Password

The password set on the remote node—up to 64 ASCII characters. Will be ignored if this frame is a logout or server termination frame.

EOF 8-bit Checksum 0xFF minus the 8-bit sum of bytes from offset 3 to this byte—between length and checksum.

Examples

Each example is written without escapes (AP = 1) and all bytes are represented in hex format. For brevity, the start delimiter, length, and checksum fields have been excluded.

Secure Session Client - Login with fixed timeout

A change is needed to be made on a device that is secured against unauthorized configuration changes. A gateway that is authorized to make the change logs into the remote node for 5 minutes as a client using the following frame:

The corresponding Secure Session Response - 0xAE will indicate whether the login attempt succeeded.

7E 00 14 2E 00 13 A2 00 12 34 56 78 00 0B B8 50 41 53 53 57 4F 52 44 D2
Frame type 64-bit dest Session options Timeout Password
0x2E 0x0013A200
12345678
0x00 0x02B8 0x50415353574F5244D2
Request
Login
Fixed
5 minutes "PASSWORD"

Secure Session Client - Login for streaming data

A large stream of data needs to be sent to a gateway that is secured against receiving unauthorized data. Because the data stream, and the gateway's ability to process the data is unknown, a Secure Session using a 60 second inter-packet timeout is established. The sending device logs into the gateway as a client using the following frame:

The corresponding Secure Session Response - 0xAE will indicate whether the login attempt succeeded.

7E 00 13 2E 00 00 00 00 00 00 00 00 04 02 58 52 6F 73 33 62 75 64 D1
Frame type 64-bit dest Session options Timeout Password
0x2E 0x00000000
00000000
0x04 0x0258 0x526F7333627564
Request Zigbee coordinator Login
Inter-packet
 60 seconds "Ros3bud"