Interface for the AWS IoT Device Defender Client Library. More...

#include <stdint.h>
#include "defender_config.h"
#include "defender_config_defaults.h"

Macros
#define	STRING_LITERAL_LENGTH(literal) ( ( uint16_t ) ( sizeof( literal ) - 1U ) )
	Helper macro to calculate the length of a string literal.

#define	DEFENDER_THINGNAME_MAX_LENGTH 128U
	Maximum length of a thing's name as permitted by AWS IoT Core.

#define	DEFENDER_REPORT_MIN_PERIOD_SECONDS 300
	Minimum period between 2 consecutive defender reports sent by the device. More...

#define	DEFENDER_API_LENGTH_JSON_PUBLISH(thingNameLength)
	Length of the topic string for publishing a JSON report. More...

#define	DEFENDER_API_LENGTH_JSON_ACCEPTED(thingNameLength)
	Length of the topic string for getting a JSON report accepted response. More...

#define	DEFENDER_API_LENGTH_JSON_REJECTED(thingNameLength)
	Length of the topic string for getting a JSON report rejected response. More...

#define	DEFENDER_API_LENGTH_CBOR_PUBLISH(thingNameLength)
	Length of the topic string for publishing a CBOR report. More...

#define	DEFENDER_API_LENGTH_CBOR_ACCEPTED(thingNameLength)
	Length of the topic string for getting a CBOR report accepted response. More...

#define	DEFENDER_API_LENGTH_CBOR_REJECTED(thingNameLength)
	Length of the topic string for getting a CBOR report rejected response. More...

#define	DEFENDER_API_MAX_LENGTH(thingNameLength) DEFENDER_API_LENGTH_CBOR_ACCEPTED( thingNameLength )
	Maximum length of the topic string for any defender operation. More...

#define	DEFENDER_API_JSON_PUBLISH(thingName)
	Topic string for publishing a JSON report. More...

#define	DEFENDER_API_JSON_ACCEPTED(thingName)
	Topic string for getting a JSON report accepted response. More...

#define	DEFENDER_API_JSON_REJECTED(thingName)
	Topic string for getting a JSON report rejected response. More...

#define	DEFENDER_API_CBOR_PUBLISH(thingName)
	Topic string for publishing a CBOR report. More...

#define	DEFENDER_API_CBOR_ACCEPTED(thingName)
	Topic string for getting a CBOR report accepted response. More...

#define	DEFENDER_API_CBOR_REJECTED(thingName)
	Topic string for getting a CBOR report rejected response. More...

#define	DEFENDER_REPORT_HEADER_KEY DEFENDER_REPORT_SELECT_KEY( "header", "hed" )
	"header" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_HEADER_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_HEADER_KEY )
	Length of the "header" key in the defender report.

#define	DEFENDER_REPORT_METRICS_KEY DEFENDER_REPORT_SELECT_KEY( "metrics", "met" )
	"metrics" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_METRICS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_METRICS_KEY )
	Length of the "metrics" key in the defender report.

#define	DEFENDER_REPORT_ID_KEY DEFENDER_REPORT_SELECT_KEY( "report_id", "rid" )
	"report_id" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_ID_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_ID_KEY )
	Length of the "report_id" key in the defender report.

#define	DEFENDER_REPORT_VERSION_KEY DEFENDER_REPORT_SELECT_KEY( "version", "v" )
	"version" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_VERSION_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_VERSION_KEY )
	Length of the "version" key in the defender report.

#define	DEFENDER_REPORT_TCP_CONNECTIONS_KEY DEFENDER_REPORT_SELECT_KEY( "tcp_connections", "tc" )
	"tcp_connections" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_TCP_CONNECTIONS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_TCP_CONNECTIONS_KEY )
	Length of the "tcp_connections" key in the defender report.

#define	DEFENDER_REPORT_ESTABLISHED_CONNECTIONS_KEY DEFENDER_REPORT_SELECT_KEY( "established_connections", "ec" )
	"established_connections" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_ESTABLISHED_CONNECTIONS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_ESTABLISHED_CONNECTIONS_KEY )
	Length of the "established_connections" key in the defender report.

#define	DEFENDER_REPORT_CONNECTIONS_KEY DEFENDER_REPORT_SELECT_KEY( "connections", "cs" )
	"connections" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_CONNECTIONS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_CONNECTIONS_KEY )
	Length of the "connections" key in the defender report.

#define	DEFENDER_REPORT_REMOTE_ADDR_KEY DEFENDER_REPORT_SELECT_KEY( "remote_addr", "rad" )
	"remote_addr" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_REMOTE_ADDR_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_REMOTE_ADDR_KEY )
	Length of the "remote_addr" key in the defender report.

#define	DEFENDER_REPORT_LOCAL_PORT_KEY DEFENDER_REPORT_SELECT_KEY( "local_port", "lp" )
	"local_port" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_LOCAL_PORT_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LOCAL_PORT_KEY )
	Length of the "local_port" key in the defender report.

#define	DEFENDER_REPORT_LOCAL_INTERFACE_KEY DEFENDER_REPORT_SELECT_KEY( "local_interface", "li" )
	"local_interface" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_LOCAL_INTERFACE_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LOCAL_INTERFACE_KEY )
	Length of the "local_interface" key in the defender report.

#define	DEFENDER_REPORT_TOTAL_KEY DEFENDER_REPORT_SELECT_KEY( "total", "t" )
	"total" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_TOTAL_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_TOTAL_KEY )
	Length of the "total" key in the defender report.

#define	DEFENDER_REPORT_TCP_LISTENING_PORTS_KEY DEFENDER_REPORT_SELECT_KEY( "listening_tcp_ports", "tp" )
	"listening_tcp_ports" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_TCP_LISTENING_PORTS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_TCP_LISTENING_PORTS_KEY )
	Length of the "listening_tcp_ports" key in the defender report.

#define	DEFENDER_REPORT_PORTS_KEY DEFENDER_REPORT_SELECT_KEY( "ports", "pts" )
	"ports" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_PORTS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_PORTS_KEY )
	Length of the "ports" key in the defender report.

#define	DEFENDER_REPORT_PORT_KEY DEFENDER_REPORT_SELECT_KEY( "port", "pt" )
	"port" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_PORT_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_PORT_KEY )
	Length of the "port" key in the defender report.

#define	DEFENDER_REPORT_INTERFACE_KEY DEFENDER_REPORT_SELECT_KEY( "interface", "if" )
	"interface" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_INTERFACE_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_INTERFACE_KEY )
	Length of the "interface" key in the defender report.

#define	DEFENDER_REPORT_UDP_LISTENING_PORTS_KEY DEFENDER_REPORT_SELECT_KEY( "listening_udp_ports", "up" )
	"listening_udp_ports" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_UDP_LISTENING_PORTS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_UDP_LISTENING_PORTS_KEY )
	Length of the "listening_udp_ports" key in the defender report.

#define	DEFENDER_REPORT_NETWORK_STATS_KEY DEFENDER_REPORT_SELECT_KEY( "network_stats", "ns" )
	"network_stats" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_NETWORK_STATS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_NETWORK_STATS_KEY )
	Length of the "network_stats" key in the defender report.

#define	DEFENDER_REPORT_BYTES_IN_KEY DEFENDER_REPORT_SELECT_KEY( "bytes_in", "bi" )
	"bytes_in" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_BYTES_IN_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_BYTES_IN_KEY )
	Length of the "bytes_in" key in the defender report.

#define	DEFENDER_REPORT_BYTES_OUT_KEY DEFENDER_REPORT_SELECT_KEY( "bytes_out", "bo" )
	"bytes_out" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_BYTES_OUT_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_BYTES_OUT_KEY )
	Length of the "bytes_out" key in the defender report.

#define	DEFENDER_REPORT_PKTS_IN_KEY DEFENDER_REPORT_SELECT_KEY( "packets_in", "pi" )
	"packets_in" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_PKTS_IN_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_PKTS_IN_KEY )
	Length of the "packets_in" key in the defender report.

#define	DEFENDER_REPORT_PKTS_OUT_KEY DEFENDER_REPORT_SELECT_KEY( "packets_out", "po" )
	"packets_out" key in the defender report.

#define	DEFENDER_REPORT_LENGTH_PKS_OUT_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LENGTH_PKS_OUT_KEY )
	Length of the "packets_out" key in the defender report.

Enumerations
enum	DefenderStatus_t { DefenderError = 0 , DefenderSuccess , DefenderNoMatch , DefenderBadParameter , DefenderBufferTooSmall }
	Return codes from defender APIs. More...

enum	DefenderTopic_t { DefenderInvalidTopic = -1 , DefenderJsonReportPublish , DefenderJsonReportAccepted , DefenderJsonReportRejected , DefenderCborReportPublish , DefenderCborReportAccepted , DefenderCborReportRejected , DefenderMaxTopic }
	Topic values for subscription requests. More...

Functions
DefenderStatus_t	Defender_GetTopic (char pBuffer, uint16_t bufferLength, const char pThingName, uint16_t thingNameLength, DefenderTopic_t api, uint16_t *pOutLength)
	Populate the topic string for a Device Defender operation. More...

DefenderStatus_t	Defender_MatchTopic (const char pTopic, uint16_t topicLength, DefenderTopic_t pOutApi, const char *ppOutThingName, uint16_t pOutThingNameLength)
	Check if the given topic is one of the Device Defender topics. More...

Detailed Description

Interface for the AWS IoT Device Defender Client Library.

Macro Definition Documentation

◆ DEFENDER_API_LENGTH_JSON_PUBLISH

#define DEFENDER_API_LENGTH_JSON_PUBLISH ( thingNameLength )

Value:

    DEFENDER_API_COMMON_LENGTH( thingNameLength,                 \
                                DEFENDER_API_LENGTH_JSON_FORMAT, \
                                DEFENDER_API_LENGTH_NULL_SUFFIX )

Length of the topic string for publishing a JSON report.

Parameters

[in] thingNameLength Length of the thing name as registered with AWS IoT Core.

◆ DEFENDER_API_LENGTH_JSON_ACCEPTED

#define DEFENDER_API_LENGTH_JSON_ACCEPTED ( thingNameLength )

Value:

    DEFENDER_API_COMMON_LENGTH( thingNameLength,                 \
                                DEFENDER_API_LENGTH_JSON_FORMAT, \
                                DEFENDER_API_LENGTH_ACCEPTED_SUFFIX )

Length of the topic string for getting a JSON report accepted response.

Parameters

[in] thingNameLength Length of the thing name as registered with AWS IoT Core.

◆ DEFENDER_API_LENGTH_JSON_REJECTED

#define DEFENDER_API_LENGTH_JSON_REJECTED ( thingNameLength )

Value:

    DEFENDER_API_COMMON_LENGTH( thingNameLength,                 \
                                DEFENDER_API_LENGTH_JSON_FORMAT, \
                                DEFENDER_API_LENGTH_REJECTED_SUFFIX )

Length of the topic string for getting a JSON report rejected response.

Parameters

[in] thingNameLength Length of the thing name as registered with AWS IoT Core.

◆ DEFENDER_API_LENGTH_CBOR_PUBLISH

#define DEFENDER_API_LENGTH_CBOR_PUBLISH ( thingNameLength )

Value:

    DEFENDER_API_COMMON_LENGTH( thingNameLength,                 \
                                DEFENDER_API_LENGTH_CBOR_FORMAT, \
                                DEFENDER_API_LENGTH_NULL_SUFFIX )

Length of the topic string for publishing a CBOR report.

Parameters

[in] thingNameLength Length of the thing name as registered with AWS IoT Core.

◆ DEFENDER_API_LENGTH_CBOR_ACCEPTED

#define DEFENDER_API_LENGTH_CBOR_ACCEPTED ( thingNameLength )

Value:

    DEFENDER_API_COMMON_LENGTH( thingNameLength,                 \
                                DEFENDER_API_LENGTH_CBOR_FORMAT, \
                                DEFENDER_API_LENGTH_ACCEPTED_SUFFIX )

Length of the topic string for getting a CBOR report accepted response.

Parameters

[in] thingNameLength Length of the thing name. as registered with AWS IoT Core.

◆ DEFENDER_API_LENGTH_CBOR_REJECTED

#define DEFENDER_API_LENGTH_CBOR_REJECTED ( thingNameLength )

Value:

    DEFENDER_API_COMMON_LENGTH( thingNameLength,                 \
                                DEFENDER_API_LENGTH_CBOR_FORMAT, \
                                DEFENDER_API_LENGTH_REJECTED_SUFFIX )

Length of the topic string for getting a CBOR report rejected response.

Parameters

[in] thingNameLength Length of the thing name as registered with AWS IoT Core.

◆ DEFENDER_API_MAX_LENGTH

#define DEFENDER_API_MAX_LENGTH ( thingNameLength ) DEFENDER_API_LENGTH_CBOR_ACCEPTED( thingNameLength )

Maximum length of the topic string for any defender operation.

Parameters

[in] thingNameLength Length of the thing name as registered with AWS IoT Core.

◆ DEFENDER_API_JSON_PUBLISH

#define DEFENDER_API_JSON_PUBLISH ( thingName )

Value:

    DEFENDER_API_COMMON( thingName,                \
                         DEFENDER_API_JSON_FORMAT, \
                         DEFENDER_API_NULL_SUFFIX )

Topic string for publishing a JSON report.

This macro should be used when the thing name is known at the compile time. If the thing name is not known at compile time, the Defender_GetTopic API should be used instead.

Parameters

thingName The thing name as registered with AWS IoT Core.

◆ DEFENDER_API_JSON_ACCEPTED

#define DEFENDER_API_JSON_ACCEPTED ( thingName )

Value:

    DEFENDER_API_COMMON( thingName,                \
                         DEFENDER_API_JSON_FORMAT, \
                         DEFENDER_API_ACCEPTED_SUFFIX )

Topic string for getting a JSON report accepted response.

This macro should be used when the thing name is known at the compile time. If the thing name is not known at compile time, the Defender_GetTopic API should be used instead.

Parameters

thingName The thing name as registered with AWS IoT Core.

◆ DEFENDER_API_JSON_REJECTED

#define DEFENDER_API_JSON_REJECTED ( thingName )

Value:

    DEFENDER_API_COMMON( thingName,                \
                         DEFENDER_API_JSON_FORMAT, \
                         DEFENDER_API_REJECTED_SUFFIX )

Topic string for getting a JSON report rejected response.

This macro should be used when the thing name is known at the compile time. If the thing name is not known at compile time, the Defender_GetTopic API should be used instead.

Parameters

thingName The thing name as registered with AWS IoT Core.

◆ DEFENDER_API_CBOR_PUBLISH

#define DEFENDER_API_CBOR_PUBLISH ( thingName )

Value:

    DEFENDER_API_COMMON( thingName,                \
                         DEFENDER_API_CBOR_FORMAT, \
                         DEFENDER_API_NULL_SUFFIX )

Topic string for publishing a CBOR report.

This macro should be used when the thing name is known at the compile time. If the thing name is not known at compile time, the Defender_GetTopic API should be used instead.

Parameters

thingName The thing name as registered with AWS IoT Core.

◆ DEFENDER_API_CBOR_ACCEPTED

#define DEFENDER_API_CBOR_ACCEPTED ( thingName )

Value:

    DEFENDER_API_COMMON( thingName,                \
                         DEFENDER_API_CBOR_FORMAT, \
                         DEFENDER_API_ACCEPTED_SUFFIX )

Topic string for getting a CBOR report accepted response.

This macro should be used when the thing name is known at the compile time. If the thing name is not known at compile time, the Defender_GetTopic API should be used instead.

Parameters

thingName The thing name as registered with AWS IoT Core.

◆ DEFENDER_API_CBOR_REJECTED

#define DEFENDER_API_CBOR_REJECTED ( thingName )

Value:

    DEFENDER_API_COMMON( thingName,                \
                         DEFENDER_API_CBOR_FORMAT, \
                         DEFENDER_API_REJECTED_SUFFIX )

Topic string for getting a CBOR report rejected response.

This macro should be used when the thing name is known at the compile time. If the thing name is not known at compile time, the Defender_GetTopic API should be used instead.

Parameters

thingName The thing name as registered with AWS IoT Core.

Function Documentation

◆ Defender_GetTopic()

DefenderStatus_t Defender_GetTopic	(	char *	pBuffer,
		uint16_t	bufferLength,
		const char *	pThingName,
		uint16_t	thingNameLength,
		DefenderTopic_t	api,
		uint16_t *	pOutLength
	)

Populate the topic string for a Device Defender operation.

Parameters

[in]	pBuffer	The buffer to write the topic string into.
[in]	bufferLength	The length of the buffer.
[in]	pThingName	The device's thingName as registered with AWS IoT.
[in]	thingNameLength	The length of the thing name.
[in]	api	The desired Device Defender API.
[out]	pOutLength	The length of the topic string written to the buffer.

Returns: DefenderSuccess if the topic string is written to the buffer; DefenderBadParameter if invalid parameters are passed; DefenderBufferTooSmall if the buffer cannot hold the full topic string.

Example

// The following example shows how to use the Defender_GetTopic API to
// generate a topic string for getting a JSON report accepted response.
 
#define TOPIC_BUFFER_LENGTH      ( 256U )
 
// Every device should have a unique thing name registered with AWS IoT Core.
// This example assumes that the device has a unique serial number which is
// registered as the thing name with AWS IoT Core.
const char * pThingName = GetDeviceSerialNumber();
uint16_t thingNameLength = ( uint16_t )strlen( pThingname );
char topicBuffer[ TOPIC_BUFFER_LENGTH ] = { 0 };
uint16_t topicLength = 0;
DefenderStatus_t status = DefenderSuccess;
 
status = Defender_GetTopic( &( topicBuffer[ 0 ] ),
                            TOPIC_BUFFER_LENGTH,
                            pThingName,
                            thingNameLength,
                            DefenderJsonReportAccepted,
                            &( topicLength ) );
 
if( status == DefenderSuccess )
{
     // The buffer topicBuffer contains the topic string of length
     // topicLength for getting a JSON report accepted response. Subscribe
     // to this topic using an MQTT client of your choice.
}

◆ Defender_MatchTopic()

DefenderStatus_t Defender_MatchTopic	(	const char *	pTopic,
		uint16_t	topicLength,
		DefenderTopic_t *	pOutApi,
		const char **	ppOutThingName,
		uint16_t *	pOutThingNameLength
	)

Check if the given topic is one of the Device Defender topics.

The function outputs which API the topic is for. It also optionally outputs the starting location and length of the thing name in the given topic.

Parameters

[in]	pTopic	The topic string to check.
[in]	topicLength	The length of the topic string.
[out]	pOutApi	The defender topic API value.
[out]	ppOutThingName	Optional parameter to output the beginning of the thing name in the topic string. Pass NULL if not needed.
[out]	pOutThingNameLength	Optional parameter to output the length of the thing name in the topic string. Pass NULL if not needed.

Returns: DefenderSuccess if the topic is one of the defender topics; DefenderBadParameter if invalid parameters are passed; DefenderNoMatch if the topic is NOT one of the defender topics (parameter pOutApi gets DefenderInvalidTopic).

Example

// The following example shows how to use the Defender_MatchTopic API to
// check if an incoming MQTT publish message is a Device Defender message.
 
DefenderTopic_t api;
DefenderStatus_t status = DefenderSuccess;
 
// pTopic and topicLength are the topic string and length of the topic on
// which the publish message is received. These are usually provided by the
// MQTT client used. We pass the last two argument as NULL as we are not
// interested in the thing name in the topic string.
status = Defender_MatchTopic( pTopic,
                              topicLength,
                              &( api ),
                              NULL,
                              NULL );
 
if( status == DefenderSuccess )
{
     if( api == DefenderJsonReportAccepted )
     {
         // The published JSON report was accepted by the AWS IoT Device
         // Defender service. You can parse the response using your choice
         // of JSON parser and ensure that the report Id is same as was sent
         // in the defender report.
     }
     else if( api == DefenderJsonReportRejected )
     {
         // The published JSON report was rejected by the AWS IoT Device
         // Defender service.
     }
     else
     {
         // Unexpected response.
     }
}

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ DEFENDER_API_LENGTH_JSON_PUBLISH

◆ DEFENDER_API_LENGTH_JSON_ACCEPTED

◆ DEFENDER_API_LENGTH_JSON_REJECTED

◆ DEFENDER_API_LENGTH_CBOR_PUBLISH

◆ DEFENDER_API_LENGTH_CBOR_ACCEPTED

◆ DEFENDER_API_LENGTH_CBOR_REJECTED

◆ DEFENDER_API_MAX_LENGTH

◆ DEFENDER_API_JSON_PUBLISH

◆ DEFENDER_API_JSON_ACCEPTED

◆ DEFENDER_API_JSON_REJECTED

◆ DEFENDER_API_CBOR_PUBLISH

◆ DEFENDER_API_CBOR_ACCEPTED

◆ DEFENDER_API_CBOR_REJECTED

Function Documentation

◆ Defender_GetTopic()

◆ Defender_MatchTopic()