Amazon FreeRTOS
User Guide

Amazon FreeRTOS AWS IoT Device Defender Library

Overview

AWS IoT Device Defender is an AWS IoT service that enables you to monitor connected devices to detect abnormal behavior and to mitigate security risks. With AWS IoT Device Defender, you can enforce consistent IoT configurations across your AWS IoT device fleet and respond quickly when devices are compromised.

Amazon FreeRTOS provides a library that allows your Amazon FreeRTOS-based devices to work with AWS IoT Device Defender. You can download Amazon FreeRTOS with the Device Defender library from the Amazon FreeRTOS Console by adding the Device Defender library to your software configuration. You can also clone the Amazon FreeRTOS GitHub repository, which includes all Amazon FreeRTOS libraries.

Note

The Amazon FreeRTOS AWS IoT Device Defender library only supports a subset of the device-side AWS IoT Device Defender metrics related to connection metrics. For more information, see Usage Restrictions.

Dependencies and Requirements

The Device Defender library has the following dependencies:

Troubleshooting

Amazon FreeRTOS Device Defender Error Codes

The Device Defender library returns error codes as positive values. For more information about each error code, see AwsIotDefenderError_t in the Device Defender C SDK API Reference.

Amazon FreeRTOS Device Defender Events

The Device Defender library includes the AwsIotDefenderCallback_t callback function, which returns positive, enumerated values known as "events" that indicate success or failure. For more information about event types, see AwsIotDefenderEventType_t in the Device Defender C SDK API Reference.

Debugging Amazon FreeRTOS Device Defender

To enable the debugging for the Device Defender library, set the log level for Device Defender to debug mode in the global configuration file:

#define AWS_IOT_LOG_LEVEL_DEFENDER IOT_LOG_DEBUG

For more information, see the Global Configuration File Reference.

Developer Support

The Device Defender library includes the AwsIotDefender_strerror helper function, which returns a string that describes the error that you provide to the function:

const char * AwsIotDefender_strerror( AwsIotDefenderError_t error );

Usage Restrictions

Although the AWS IoT Device Defender service supports both JSON and CBOR formats for data serialization, the Amazon FreeRTOS Device Defender library currently only supports CBOR, which is controlled by the configuration option AWS_IOT_DEFENDER_FORMAT.

Additionally, the Amazon FreeRTOS AWS IoT Device Defender library only supports a subset of device-side AWS IoT Device Defender metrics:

Long Name Short Name Parent Element Description
remote_addr rad connections Lists the remote address of a TCP connection.
total t established_connections Lists the number of established TCP connections.

For example:

"tcp_connections": { "established_connections": { "connections": [ { "remote_addr": "192.168.0.1:8000" }, { "remote_addr": "192.168.0.2:8000" } ], "total": 2 } }

This JSON document is for example purposes only, as Amazon FreeRTOS Device Defender library does not support JSON-formatted metrics.

Initialization

The macro AWS_IOT_SECURE_SOCKETS_METRICS_ENABLED must be defined to enable the secure sockets metrics. Leaving this macro undefined could result in unpredictable behavior.

Amazon FreeRTOS Device Defender API

For a full API reference, see the Device Defender C SDK API Reference.

Example Usage

For a full example of the Device Defender library in use, see AWS IoT Device Defender Demo.