Frames: Secure Session (0x2E, 0xAE)

Support of XBee3 802.15.4/DigiMesh/Zigbee Secure Sessions. More...

Files
file	secure_session.h
file	xbee_secure_session.c

Data Structures
struct	xbee_header_secure_session_req_t
	Frame format for the header of Secure Session Control frame. More...
struct	xbee_frame_secure_session_resp_t
	Frame format for Secure Session Response. More...
struct	xbee_frame_xms_ss_established_t
	Frame format for Extended Modem Status: Secure Session Established. More...
struct	xbee_frame_xms_ss_ended_t
	Frame format for Extended Modem Status: Secure Session Ended. More...
struct	xbee_frame_xms_ss_auth_failed_t
	Frame format for Extended Modem Status: Secure Session Auth Failed. More...

Macros
#define	XBEE_FRAME_SECURE_SESSION_REQ   0x2E
	Secure Session Control frame type.
#define	XBEE_FRAME_SECURE_SESSION_RESP   0xAE
	Secure Session Response frame type.
#define	XBEE_FRAME_DUMP_SS_RESP
#define	XBEE_MODEM_STATUS_IS_SS(code)
	Identify whether an extended modem status code is Secure Session related. More...

Functions
int	xbee_secure_session_request (xbee_dev_t *xbee, const addr64 *dest_be, uint8_t options, uint16_t timeout_ds, const char *password)
	Send a Secure Session Request (0x2A) frame. More...
int	xbee_frame_dump_secure_session_resp (xbee_dev_t *xbee, const void FAR *payload, uint16_t length, void FAR *context)
	Dump a parsed Secure Session Response frame. More...
int	xbee_frame_dump_ext_mod_status_ss (xbee_dev_t *xbee, const void FAR *payload, uint16_t length, void FAR *context)
	Dump a parsed Extended Modem Status frame for a Secure Session code. More...

ATSA (Secure Access)
ATSA bit values for services that only work over a Secure Session.
#define	XBEE_CMD_ATSA_REMOTE_AT   (1<<1)
	Remote AT Commands.
#define	XBEE_CMD_ATSA_SERIAL_DATA   (1<<2)
	Serial Data.

XBEE_SS_REQ_OPT_xxx
Values for options field of xbee_header_secure_session_req_t.
#define	XBEE_SS_REQ_OPT_CLIENT_LOGIN   (0)
	Local device initiating SRP authentication with target server.
#define	XBEE_SS_REQ_OPT_CLIENT_LOGOUT   (1<<0)
	Local device logging out of SRP session with target server.
#define	XBEE_SS_REQ_OPT_SERVER_TERMINATION   (1<<1)
	Server terminating a specific client session (address in device_addr_be field) or all client sessions (using WPAN_IEEE_ADDR_BROADCAST). More...
#define	XBEE_SS_REQ_OPT_TIMEOUT_FIXED   (0)
	Session terminates after timeout period has elapsed from start of session.
#define	XBEE_SS_REQ_OPT_TIMEOUT_INTER_PACKET   (1<<2)
	Session terminates after timeout period has elapsed from last transmission.

XBEE_SS_REQ_TIMEOUT_xxx
Values related to timeout_be field of xbee_header_secure_session_req_t.
#define	XBEE_SS_REQ_TIMEOUT_UNITS_PER_SEC   10
	Scaler for converting timeout to seconds.
#define	XBEE_SS_REQ_TIMEOUT_MAX   (30 * 60 * XBEE_SS_REQ_TIMEOUT_UNITS_PER_SEC)
	Maximum timeout value (30 minutes).
#define	XBEE_SS_REQ_TIMEOUT_YIELDING   0x0000
	Value for a yielding session.

XBEE_SS_RESP_TYPE_xxx
Values for type field of xbee_frame_secure_session_resp_t.
#define	XBEE_SS_RESP_TYPE_LOGIN   0x00
	Login response.
#define	XBEE_SS_RESP_TYPE_LOGOUT   0x01
	Logout response.

XBEE_SS_RESP_STATUS_xxx
Values for status field of xbee_frame_secure_session_resp_t. Typical statuses range from 0x00 to 0x7F; manual SRP statuses from 0x80 to 0xFF.
#define	XBEE_SS_RESP_STATUS_SUCCESS   0x00
	Operation was successful.
#define	XBEE_SS_RESP_STATUS_INVALID_PW   0x01
	Invalid password.
#define	XBEE_SS_RESP_STATUS_BUSY   0x02
	Too many active sessions on server.
#define	XBEE_SS_RESP_STATUS_INVALID_ARG   0x03
	Session options or timeout are invalid.
#define	XBEE_SS_RESP_STATUS_NO_SESSION   0x04
	Requested session does not exist.
#define	XBEE_SS_RESP_STATUS_TIMEOUT   0x05
	Timeout waiting for response.
#define	XBEE_SS_RESP_STATUS_NO_MEMORY   0x06
	Memory allocation failed.
#define	XBEE_SS_RESP_STATUS_IN_PROGRESS   0x07
	A request to terminate a session in progress was made.
#define	XBEE_SS_RESP_STATUS_NO_PASSWORD   0x08
	No password set on server.
#define	XBEE_SS_RESP_STATUS_NO_RESPONSE   0x09
	No response from server.
#define	XBEE_SS_RESP_STATUS_BAD_FRAME   0x0A
	Malformed server response.
#define	XBEE_SS_RESP_STATUS_SRP_WRONG_WAY   0x80
	Server received a client packet or vice versa.
#define	XBEE_SS_RESP_STATUS_SRP_UNEXPECTED   0x81
	Received unexpected SRP packet.
#define	XBEE_SS_RESP_STATUS_SRP_MISORDERED   0x82
	Offset for split value (A/B) came out of order.
#define	XBEE_SS_RESP_STATUS_SRP_BAD_FRAME   0x83
	Unrecognized or invalid SRP frame type.
#define	XBEE_SS_RESP_STATUS_SRP_BAD_PROTOCOL   0x84
	Authentication protocol version is not supported.
#define	XBEE_SS_RESP_STATUS_UNDEFINED   0xFF
	Undefined error occurred.

XBEE_SS_END_REASON_xxx
Values for status_code field of an Extended Modem Status (0x98) frame, when reporting Secure Session status changes.
#define	XBEE_SS_END_REASON_REMOTE_TERM   0x00
	Terminated by remote node.
#define	XBEE_SS_END_REASON_TIMED_OUT   0x01
	Timed out.
#define	XBEE_SS_END_REASON_BAD_ENCRYPT_CTR   0x02
	Received invalid encryption counter.
#define	XBEE_SS_END_REASON_ENCRYPT_CTR_OVERFLOW   0x03
	Encryption counter overflow: maximum number of transmissions for a single session reached. More...
#define	XBEE_SS_END_REASON_REMOTE_NO_MEMORY   0x04
	Remote node out of memory.

Detailed Description

Support of XBee3 802.15.4/DigiMesh/Zigbee Secure Sessions.

Macro Definition Documentation

#define XBEE_FRAME_DUMP_SS_RESP

Value:

{ XBEE_FRAME_SECURE_SESSION_RESP, 0, \
      xbee_frame_dump_secure_session_resp, NULL }

#define XBEE_MODEM_STATUS_IS_SS

(

code

)

Value:

(code >= XBEE_MODEM_STATUS_SS_ESTABLISHED \
     && code <= XBEE_MODEM_STATUS_SS_AUTH_FAILED)

Identify whether an extended modem status code is Secure Session related.

#define XBEE_SS_END_REASON_ENCRYPT_CTR_OVERFLOW   0x03

Encryption counter overflow: maximum number of transmissions for a single session reached.

#define XBEE_SS_REQ_OPT_SERVER_TERMINATION   (1<<1)

Server terminating a specific client session (address in device_addr_be field) or all client sessions (using WPAN_IEEE_ADDR_BROADCAST).

Function Documentation

int xbee_frame_dump_ext_mod_status_ss	(	xbee_dev_t *	xbee,
		const void FAR *	payload,
		uint16_t	length,
		void FAR *	context
	)

Dump a parsed Extended Modem Status frame for a Secure Session code.

View the documentation of xbee_frame_handler_fn() for this function's parameters and return value.

Return values

-EINVAL	Error in parameters passed to function.
-EBADMSG	This isn't an Extended Modem Status frame.
-ENOENT	This isn't a Secure Session extended modem status.
0	Status message printed to stdout.

See also

xbee_frame_handler_fn()

References addr64_format(), ADDR64_STRING_LENGTH, be16toh, EBADMSG, EINVAL, ENOENT, FAR, XBEE_FRAME_EXT_MODEM_STATUS, XBEE_MODEM_STATUS_SS_AUTH_FAILED, XBEE_MODEM_STATUS_SS_ENDED, XBEE_MODEM_STATUS_SS_ESTABLISHED, and XBEE_UNUSED_PARAMETER.

int xbee_frame_dump_secure_session_resp	(	xbee_dev_t *	xbee,
		const void FAR *	payload,
		uint16_t	length,
		void FAR *	context
	)

Dump a parsed Secure Session Response frame.

View the documentation of xbee_frame_handler_fn() for this function's parameters and return value.

See also

XBEE_FRAME_DUMP_SS_RESP, xbee_frame_handler_fn()

Return values

-EINVAL	Error in parameters passed to function.
-EBADMSG	This isn't a Secure Session Response frame.
-ENOENT	This isn't a Secure Session extended modem status.
0	Status message printed to stdout.

References addr64_format(), ADDR64_STRING_LENGTH, EBADMSG, EINVAL, FAR, XBEE_FRAME_SECURE_SESSION_RESP, and XBEE_UNUSED_PARAMETER.

int xbee_secure_session_request	(	xbee_dev_t *	xbee,
		const addr64 *	dest_be,
		uint8_t	options,
		uint16_t	timeout_ds,
		const char *	password
	)

Send a Secure Session Request (0x2A) frame.

Parameters

[in]	xbee	Device to send the frame on.
[in]	dest_be	Target node for request, or WPAN_IEEE_ADDR_BROADCAST to logout of all nodes.
[in]	options	Combination of XBEE_SS_REQ_OPT_xxx macros. XBEE_SS_REQ_OPT_CLIENT_LOGIN XBEE_SS_REQ_OPT_CLIENT_LOGOUT XBEE_SS_REQ_OPT_SERVER_TERMINATION XBEE_SS_REQ_OPT_TIMEOUT_FIXED XBEE_SS_REQ_OPT_TIMEOUT_INTER_PACKET
[in]	timeout_ds	Timeout in deciseconds (0.1s) or XBEE_SS_REQ_TIMEOUT_YIELDING to close the idlest session when session list is full.
[in]	password	Password to use for XBEE_SS_REQ_OPT_CLIENT_LOGIN or NULL for XBEE_SS_REQ_OPT_CLIENT_LOGOUT.

Return values

0	Frame sent.
-EINVAL	Invalid parameter.
-EBUSY	Transmit serial buffer is full, or XBee is not accepting serial data (deasserting /CTS signal).

References EINVAL, xbee_header_secure_session_req_t::frame_type, htobe16, xbee_header_secure_session_req_t::options, xbee_header_secure_session_req_t::remote_addr_be, xbee_header_secure_session_req_t::timeout_be, XBEE_FRAME_SECURE_SESSION_REQ, and xbee_frame_write().