User-facing functions and structs of AWS IoT Device Defender library. More...

#include "iot_config.h"
#include <stdint.h>
#include <stdlib.h>
#include "iot_mqtt.h"

Data Structures
struct	AwsIotDefenderCallbackInfo_t
	Callback parameters. More...

struct	AwsIotDefenderCallback_t
	User provided callback handle. More...

struct	AwsIotDefenderStartInfo_t
	Parameters of AwsIotDefender_Start function. More...

Macros
Serialization Format
Format constants: Cbor or Json. Warning JSON format is not supported for now.
#define	AWS_IOT_DEFENDER_FORMAT_CBOR 1

#define	AWS_IOT_DEFENDER_FORMAT_JSON 2

Metrics Flags
Bit flags or metrics used by AwsIotDefender_SetMetrics function. These metrics are subset of metrics supported by AWS IoT Device Defender service. For details, refer to developer document of AWS IoT Device Defender.
#define	AWS_IOT_DEFENDER_METRICS_ALL 0xffffffff

#define	AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_TOTAL 0x00000001

#define	AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_REMOTE_ADDR 0x00000004

#define	AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_CONNECTIONS ( AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_REMOTE_ADDR ) \

#define	AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED ( AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_CONNECTIONS \| AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_TOTAL ) \

Initializers
Initializers of data handles.
#define	AWS_IOT_DEFENDER_CALLBACK_INITIALIZER

#define	AWS_IOT_DEFENDER_START_INFO_INITIALIZER

Enumerations
enum	AwsIotDefenderMetricsGroup_t { AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS }
	Metrics group options for AwsIotDefender_SetMetrics() function. More...

enum	AwsIotDefenderError_t { AWS_IOT_DEFENDER_SUCCESS = 0, AWS_IOT_DEFENDER_INVALID_INPUT, AWS_IOT_DEFENDER_ALREADY_STARTED, AWS_IOT_DEFENDER_PERIOD_TOO_SHORT, AWS_IOT_DEFENDER_ERROR_NO_MEMORY, AWS_IOT_DEFENDER_INTERNAL_FAILURE }
	Return codes of defender functions. More...

enum	AwsIotDefenderEventType_t { AWS_IOT_DEFENDER_METRICS_ACCEPTED = 0, AWS_IOT_DEFENDER_METRICS_REJECTED, AWS_IOT_DEFENDER_FAILURE_MQTT, AWS_IOT_DEFENDER_FAILURE_METRICS_REPORT }
	Event codes passed into AwsIotDefenderCallbackInfo_t. More...

Functions
AwsIotDefenderError_t	AwsIotDefender_SetMetrics (AwsIotDefenderMetricsGroup_t metricsGroup, uint32_t metrics)
	Set metrics that defender agent needs to collect for a metrics group. More...

AwsIotDefenderError_t	AwsIotDefender_Start (AwsIotDefenderStartInfo_t *pStartInfo)
	Start the defender agent. More...

void	AwsIotDefender_Stop (void)
	Stop the defender agent. More...

AwsIotDefenderError_t	AwsIotDefender_SetPeriod (uint32_t periodSeconds)
	Set period in seconds. More...

uint32_t	AwsIotDefender_GetPeriod (void)
	Get period in seconds. More...

const char *	AwsIotDefender_strerror (AwsIotDefenderError_t error)
	Return a string that describes AwsIotDefenderError_t. More...

const char *	AwsIotDefender_EventType (AwsIotDefenderEventType_t eventType)
	Return a string that describes AwsIotDefenderEventType_t. More...

Detailed Description

User-facing functions and structs of AWS IoT Device Defender library.

Macro Definition Documentation

◆ AWS_IOT_DEFENDER_FORMAT_CBOR

#define AWS_IOT_DEFENDER_FORMAT_CBOR 1

CBOR format.

◆ AWS_IOT_DEFENDER_FORMAT_JSON

#define AWS_IOT_DEFENDER_FORMAT_JSON 2

JSON format (NOT supported).

◆ AWS_IOT_DEFENDER_METRICS_ALL

#define AWS_IOT_DEFENDER_METRICS_ALL 0xffffffff

Flag to indicate including all metrics.

◆ AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_TOTAL

#define AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_TOTAL 0x00000001

Total count of established TCP connections.

◆ AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_REMOTE_ADDR

#define AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_REMOTE_ADDR 0x00000004

Remote address (IP:port) of established TCP connections. For example, 192.168.0.1:8000.

◆ AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_CONNECTIONS

#define AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_CONNECTIONS ( AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_REMOTE_ADDR ) \

Connections metrics including only remote address. Local port number is not supported.

◆ AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED

#define AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED ( AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_CONNECTIONS | AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_TOTAL ) \

Established connections metrics including connections metrics and total count.

◆ AWS_IOT_DEFENDER_CALLBACK_INITIALIZER

#define AWS_IOT_DEFENDER_CALLBACK_INITIALIZER

Value:

{                                         \
        .pCallbackContext = NULL,             \
        .function = NULL                      \
    }

Initializer of AwsIotDefenderCallback_t.

◆ AWS_IOT_DEFENDER_START_INFO_INITIALIZER

#define AWS_IOT_DEFENDER_START_INFO_INITIALIZER

Value:

{ .pClientIdentifier = NULL,                         \
      .clientIdentifierLength = 0,                       \
      .mqttConnection = IOT_MQTT_CONNECTION_INITIALIZER, \
      .callback = AWS_IOT_DEFENDER_CALLBACK_INITIALIZER  \
    }

Initializer of AwsIotDefenderStartInfo_t.

Function Documentation

◆ AwsIotDefender_SetMetrics()

AwsIotDefenderError_t AwsIotDefender_SetMetrics	(	AwsIotDefenderMetricsGroup_t	metricsGroup,
		uint32_t	metrics
	)

Set metrics that defender agent needs to collect for a metrics group.

If defender agent is not started, this function will provide the metrics to be collected.
If defender agent is started, this function will update the metrics and take effect in defender agent's next iteration.

Parameters

[in]	metricsGroup	Metrics group defined in AwsIotDefenderMetricsGroup_t
[in]	metrics	Bit-flags to specify what metrics to collect. If all metrics in a group is needed, simply set metrics to AWS_IOT_DEFENDER_METRICS_ALL. See Metrics flags for details.

Returns

On success, AWS_IOT_DEFENDER_SUCCESS is returned.
If metricsGroup is invalid, AWS_IOT_DEFENDER_INVALID_INPUT is returned.

Note: This function is thread safe.; AwsIotDefender_Stop will clear the metrics.

◆ AwsIotDefender_Start()

AwsIotDefenderError_t AwsIotDefender_Start ( AwsIotDefenderStartInfo_t * pStartInfo )

Start the defender agent.

Parameters

[in] pStartInfo Pointer of parameters of start function

Periodically, defender agent collects metrics and publish to specific AWS reserved MQTT topic.

Returns

On success, AWS_IOT_DEFENDER_SUCCESS is returned.
If pStartInfo is invalid, AWS_IOT_DEFENDER_INVALID_INPUT is returned.
If memory allocation fails, AWS_IOT_DEFENDER_ERROR_NO_MEMORY is returned.
If defender is already started, AWS_IOT_DEFENDER_ALREADY_STARTED is returned.

Warning: This function is not thread safe.

Note: No need to manage the memory allocated for AwsIotDefenderCallbackInfo_t. This function save the information internally.

Example:

// assume valid IotMqttConnection_t is created and available.
const IotMqttConnection_t _mqttConnection;
// use AWS thing name as client identifier
const char * pClientIdentifier = "AwsThingName";
void logDefenderCallback( void * param1, AwsIotDefenderCallbackInfo_t * const pCallbackInfo )
{
    if ( pCallbackInfo->eventType == AWS_IOT_DEFENDER_METRICS_ACCEPTED )
    {
        // log info: metrics report accepted by defender service is a happy case
    }
    else
    {
        // log error: pCallbackInfo->eventType
    }
    if ( pCallbackInfo->pPayload != NULL )
    {
        // log info: pCallbackInfo->pPayload with length pCallbackInfo->payloadLength
    }
    if ( pCallbackInfo->pMetricsReport != NULL )
    {
        // log info: pCallbackInfo->pMetricsReport with length pCallbackInfo->metricsReportLength
    }
}
void startDefender()
{
    // define a simple callback function which simply logs
    const AwsIotDefenderCallback_t callback = { .function = logDefenderCallback, .pCallbackContext = NULL };
    // define parameters of AwsIotDefender_Start function
    // Note: This example assumes MQTT connection is already established and metrics library is initialized.
    const AwsIotDefenderStartInfo_t startInfo =
    {
        .pClientIdentifier = pClientIdentifier,
        .clientIdentifierLength = strlen( pClientIdentifier ),
        .mqttConnection = _mqttConnection,
        .callback = callback
    };
    // specify two TCP connections metrics: total count and local port
    AwsIotDefenderError_t error = AwsIotDefender_SetMetrics(AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS,
                                                            AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_TOTAL |
                                                            AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_REMOTE_ADDR );
    if ( error == AWS_IOT_DEFENDER_SUCCESS )
    {
        // set metrics report period to 10 minutes (600 seconds)
        error = AwsIotDefender_SetPeriod( 600 );
    }
    if (error == AWS_IOT_DEFENDER_SUCCESS)
    {
        // start the defender
        error = AwsIotDefender_Start( &startInfo );
    }
    if ( error != AWS_IOT_DEFENDER_SUCCESS )
    {
        const char * pError = AwsIotDefender_strerror( error );
        // log error: pError
    }
}
void stopDefender()
{
    //stop the defender
    AwsIotDefender_Stop();
}

◆ AwsIotDefender_Stop()

void AwsIotDefender_Stop ( void )

Stop the defender agent.

It waits for the current metrics-publishing iteration to finish before freeing the resource allocated. It also clears the metrics set previously so that user is expected to SetMetrics again before restarting defender agent.

Warning: This function must be called after successfully calling AwsIotDefender_Start.; This function is not thread safe.

◆ AwsIotDefender_SetPeriod()

AwsIotDefenderError_t AwsIotDefender_SetPeriod ( uint32_t periodSeconds )

Set period in seconds.

Parameters

[in] periodSeconds Period is specified in seconds. Minimum is 300 (5 minutes)

Returns

On success, AWS_IOT_DEFENDER_SUCCESS is returned.
If defender is not started yet, AWS_IOT_DEFENDER_NOT_STARTED is returned.

Warning: This function is not thread safe.

Note: If this function is called when defender agent is started, the period is re-calculated and updated in next iteration.

◆ AwsIotDefender_GetPeriod()

uint32_t AwsIotDefender_GetPeriod ( void )

Get period in seconds.

Returns: Current period in seconds

◆ AwsIotDefender_strerror()

const char* AwsIotDefender_strerror ( AwsIotDefenderError_t error )

Return a string that describes AwsIotDefenderError_t.

Returns: A string that describes given AwsIotDefenderError_t

◆ AwsIotDefender_EventType()

const char* AwsIotDefender_EventType ( AwsIotDefenderEventType_t eventType )

Return a string that describes AwsIotDefenderEventType_t.

Returns: A string that describes given AwsIotDefenderEventType_t

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ AWS_IOT_DEFENDER_FORMAT_CBOR

◆ AWS_IOT_DEFENDER_FORMAT_JSON

◆ AWS_IOT_DEFENDER_METRICS_ALL

◆ AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_TOTAL

◆ AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_REMOTE_ADDR

◆ AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED_CONNECTIONS

◆ AWS_IOT_DEFENDER_METRICS_TCP_CONNECTIONS_ESTABLISHED

◆ AWS_IOT_DEFENDER_CALLBACK_INITIALIZER

◆ AWS_IOT_DEFENDER_START_INFO_INITIALIZER

Function Documentation

◆ AwsIotDefender_SetMetrics()

◆ AwsIotDefender_Start()

◆ AwsIotDefender_Stop()

◆ AwsIotDefender_SetPeriod()

◆ AwsIotDefender_GetPeriod()

◆ AwsIotDefender_strerror()

◆ AwsIotDefender_EventType()