AWS IoT Device Defender v1.4.0
AWS IoT Device Defender Client Library
 
Loading...
Searching...
No Matches
defender.h
Go to the documentation of this file.
1/*
2 * AWS IoT Device Defender Client v1.4.0
3 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * SPDX-License-Identifier: MIT
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy of
8 * this software and associated documentation files (the "Software"), to deal in
9 * the Software without restriction, including without limitation the rights to
10 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
11 * the Software, and to permit persons to whom the Software is furnished to do so,
12 * subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in all
15 * copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
20 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
21 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 */
24
30#ifndef DEFENDER_H_
31#define DEFENDER_H_
32
33/* Standard includes. */
34#include <stdint.h>
35
36/* *INDENT-OFF* */
37#ifdef __cplusplus
38 extern "C" {
39#endif
40/* *INDENT-ON* */
41
42/* DEFENDER_DO_NOT_USE_CUSTOM_CONFIG allows building the Device Defender library
43 * without a config file. If a config file is provided, DEFENDER_DO_NOT_USE_CUSTOM_CONFIG
44 * macro must not be defined.
45 */
46#ifndef DEFENDER_DO_NOT_USE_CUSTOM_CONFIG
47 #include "defender_config.h"
48#endif
49
50/* Default config values. */
52
57typedef enum
58{
65
70typedef enum
71{
79 DefenderMaxTopic
81
82/*-----------------------------------------------------------*/
83
87#define STRING_LITERAL_LENGTH( literal ) ( ( uint16_t ) ( sizeof( literal ) - 1U ) )
88
89/*-----------------------------------------------------------*/
90
95#define DEFENDER_THINGNAME_MAX_LENGTH 128U
96
104#define DEFENDER_REPORT_MIN_PERIOD_SECONDS 300
105
106/*-----------------------------------------------------------*/
107
108/*
109 * A Defender topic has the following format:
110 *
111 * <Prefix><Thing Name><Bridge><Report Format><Suffix>
112 *
113 * Where:
114 * <Prefix> = $aws/things/
115 * <Thing Name> = Name of the thing.
116 * <Bridge> = /defender/metrics/
117 * <Report Format> = json or cbor
118 * <Suffix> = /accepted or /rejected or empty
119 *
120 * Examples:
121 * $aws/things/THING_NAME/defender/metrics/json
122 * $aws/things/THING_NAME/defender/metrics/json/accepted
123 * $aws/things/THING_NAME/defender/metrics/json/rejected
124 * $aws/things/THING_NAME/defender/metrics/cbor
125 * $aws/things/THING_NAME/defender/metrics/cbor/accepted
126 * $aws/things/THING_NAME/defender/metrics/json/rejected
127 */
128
134#define DEFENDER_API_PREFIX "$aws/things/"
135#define DEFENDER_API_LENGTH_PREFIX STRING_LITERAL_LENGTH( DEFENDER_API_PREFIX )
136
137#define DEFENDER_API_BRIDGE "/defender/metrics/"
138#define DEFENDER_API_LENGTH_BRIDGE STRING_LITERAL_LENGTH( DEFENDER_API_BRIDGE )
139
140#define DEFENDER_API_JSON_FORMAT "json"
141#define DEFENDER_API_LENGTH_JSON_FORMAT STRING_LITERAL_LENGTH( DEFENDER_API_JSON_FORMAT )
142
143#define DEFENDER_API_CBOR_FORMAT "cbor"
144#define DEFENDER_API_LENGTH_CBOR_FORMAT STRING_LITERAL_LENGTH( DEFENDER_API_CBOR_FORMAT )
145
146#define DEFENDER_API_ACCEPTED_SUFFIX "/accepted"
147#define DEFENDER_API_LENGTH_ACCEPTED_SUFFIX STRING_LITERAL_LENGTH( DEFENDER_API_ACCEPTED_SUFFIX )
148
149#define DEFENDER_API_REJECTED_SUFFIX "/rejected"
150#define DEFENDER_API_LENGTH_REJECTED_SUFFIX STRING_LITERAL_LENGTH( DEFENDER_API_REJECTED_SUFFIX )
151
152#define DEFENDER_API_NULL_SUFFIX ""
153#define DEFENDER_API_LENGTH_NULL_SUFFIX ( 0U )
154
157/*-----------------------------------------------------------*/
158
164/* Defender API topic lengths. */
165#define DEFENDER_API_COMMON_LENGTH( thingNameLength, reportFormatLength, suffixLength ) \
166 ( DEFENDER_API_LENGTH_PREFIX + \
167 ( thingNameLength ) + \
168 DEFENDER_API_LENGTH_BRIDGE + \
169 ( reportFormatLength ) + \
170 ( suffixLength ) )
171
179#define DEFENDER_API_LENGTH_JSON_PUBLISH( thingNameLength ) \
180 DEFENDER_API_COMMON_LENGTH( thingNameLength, \
181 DEFENDER_API_LENGTH_JSON_FORMAT, \
182 DEFENDER_API_LENGTH_NULL_SUFFIX )
183
189#define DEFENDER_API_LENGTH_JSON_ACCEPTED( thingNameLength ) \
190 DEFENDER_API_COMMON_LENGTH( thingNameLength, \
191 DEFENDER_API_LENGTH_JSON_FORMAT, \
192 DEFENDER_API_LENGTH_ACCEPTED_SUFFIX )
193
199#define DEFENDER_API_LENGTH_JSON_REJECTED( thingNameLength ) \
200 DEFENDER_API_COMMON_LENGTH( thingNameLength, \
201 DEFENDER_API_LENGTH_JSON_FORMAT, \
202 DEFENDER_API_LENGTH_REJECTED_SUFFIX )
203
209#define DEFENDER_API_LENGTH_CBOR_PUBLISH( thingNameLength ) \
210 DEFENDER_API_COMMON_LENGTH( thingNameLength, \
211 DEFENDER_API_LENGTH_CBOR_FORMAT, \
212 DEFENDER_API_LENGTH_NULL_SUFFIX )
213
219#define DEFENDER_API_LENGTH_CBOR_ACCEPTED( thingNameLength ) \
220 DEFENDER_API_COMMON_LENGTH( thingNameLength, \
221 DEFENDER_API_LENGTH_CBOR_FORMAT, \
222 DEFENDER_API_LENGTH_ACCEPTED_SUFFIX )
223
229#define DEFENDER_API_LENGTH_CBOR_REJECTED( thingNameLength ) \
230 DEFENDER_API_COMMON_LENGTH( thingNameLength, \
231 DEFENDER_API_LENGTH_CBOR_FORMAT, \
232 DEFENDER_API_LENGTH_REJECTED_SUFFIX )
233
239#define DEFENDER_API_MAX_LENGTH( thingNameLength ) \
240 DEFENDER_API_LENGTH_CBOR_ACCEPTED( thingNameLength )
241
242/*-----------------------------------------------------------*/
243
249/* Defender API topics. */
250#define DEFENDER_API_COMMON( thingName, reportFormat, suffix ) \
251 ( DEFENDER_API_PREFIX \
252 thingName \
253 DEFENDER_API_BRIDGE \
254 reportFormat \
255 suffix )
256
268#define DEFENDER_API_JSON_PUBLISH( thingName ) \
269 DEFENDER_API_COMMON( thingName, \
270 DEFENDER_API_JSON_FORMAT, \
271 DEFENDER_API_NULL_SUFFIX )
272
282#define DEFENDER_API_JSON_ACCEPTED( thingName ) \
283 DEFENDER_API_COMMON( thingName, \
284 DEFENDER_API_JSON_FORMAT, \
285 DEFENDER_API_ACCEPTED_SUFFIX )
286
296#define DEFENDER_API_JSON_REJECTED( thingName ) \
297 DEFENDER_API_COMMON( thingName, \
298 DEFENDER_API_JSON_FORMAT, \
299 DEFENDER_API_REJECTED_SUFFIX )
300
310#define DEFENDER_API_CBOR_PUBLISH( thingName ) \
311 DEFENDER_API_COMMON( thingName, \
312 DEFENDER_API_CBOR_FORMAT, \
313 DEFENDER_API_NULL_SUFFIX )
314
324#define DEFENDER_API_CBOR_ACCEPTED( thingName ) \
325 DEFENDER_API_COMMON( thingName, \
326 DEFENDER_API_CBOR_FORMAT, \
327 DEFENDER_API_ACCEPTED_SUFFIX )
328
338#define DEFENDER_API_CBOR_REJECTED( thingName ) \
339 DEFENDER_API_COMMON( thingName, \
340 DEFENDER_API_CBOR_FORMAT, \
341 DEFENDER_API_REJECTED_SUFFIX )
342
343/*-----------------------------------------------------------*/
344
350/* Keys used in defender report. */
351#if ( defined( DEFENDER_USE_LONG_KEYS ) && ( DEFENDER_USE_LONG_KEYS == 1 ) )
352 #define DEFENDER_REPORT_SELECT_KEY( longKey, shortKey ) longKey
353#else
354 #define DEFENDER_REPORT_SELECT_KEY( longKey, shortKey ) shortKey
355#endif
356
363#define DEFENDER_REPORT_HEADER_KEY DEFENDER_REPORT_SELECT_KEY( "header", "hed" )
364
369#define DEFENDER_REPORT_LENGTH_HEADER_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_HEADER_KEY )
370
375#define DEFENDER_REPORT_METRICS_KEY DEFENDER_REPORT_SELECT_KEY( "metrics", "met" )
376
381#define DEFENDER_REPORT_LENGTH_METRICS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_METRICS_KEY )
382
387#define DEFENDER_REPORT_ID_KEY DEFENDER_REPORT_SELECT_KEY( "report_id", "rid" )
388
393#define DEFENDER_REPORT_LENGTH_ID_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_ID_KEY )
394
399#define DEFENDER_REPORT_VERSION_KEY DEFENDER_REPORT_SELECT_KEY( "version", "v" )
400
405#define DEFENDER_REPORT_LENGTH_VERSION_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_VERSION_KEY )
406
411#define DEFENDER_REPORT_TCP_CONNECTIONS_KEY DEFENDER_REPORT_SELECT_KEY( "tcp_connections", "tc" )
412
417#define DEFENDER_REPORT_LENGTH_TCP_CONNECTIONS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_TCP_CONNECTIONS_KEY )
418
423#define DEFENDER_REPORT_ESTABLISHED_CONNECTIONS_KEY DEFENDER_REPORT_SELECT_KEY( "established_connections", "ec" )
424
429#define DEFENDER_REPORT_LENGTH_ESTABLISHED_CONNECTIONS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_ESTABLISHED_CONNECTIONS_KEY )
430
435#define DEFENDER_REPORT_CONNECTIONS_KEY DEFENDER_REPORT_SELECT_KEY( "connections", "cs" )
436
441#define DEFENDER_REPORT_LENGTH_CONNECTIONS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_CONNECTIONS_KEY )
442
447#define DEFENDER_REPORT_REMOTE_ADDR_KEY DEFENDER_REPORT_SELECT_KEY( "remote_addr", "rad" )
448
453#define DEFENDER_REPORT_LENGTH_REMOTE_ADDR_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_REMOTE_ADDR_KEY )
454
459#define DEFENDER_REPORT_LOCAL_PORT_KEY DEFENDER_REPORT_SELECT_KEY( "local_port", "lp" )
460
465#define DEFENDER_REPORT_LENGTH_LOCAL_PORT_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LOCAL_PORT_KEY )
466
471#define DEFENDER_REPORT_LOCAL_INTERFACE_KEY DEFENDER_REPORT_SELECT_KEY( "local_interface", "li" )
472
477#define DEFENDER_REPORT_LENGTH_LOCAL_INTERFACE_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LOCAL_INTERFACE_KEY )
478
483#define DEFENDER_REPORT_TOTAL_KEY DEFENDER_REPORT_SELECT_KEY( "total", "t" )
484
489#define DEFENDER_REPORT_LENGTH_TOTAL_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_TOTAL_KEY )
490
495#define DEFENDER_REPORT_TCP_LISTENING_PORTS_KEY DEFENDER_REPORT_SELECT_KEY( "listening_tcp_ports", "tp" )
496
501#define DEFENDER_REPORT_LENGTH_TCP_LISTENING_PORTS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_TCP_LISTENING_PORTS_KEY )
502
507#define DEFENDER_REPORT_PORTS_KEY DEFENDER_REPORT_SELECT_KEY( "ports", "pts" )
508
513#define DEFENDER_REPORT_LENGTH_PORTS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_PORTS_KEY )
514
519#define DEFENDER_REPORT_PORT_KEY DEFENDER_REPORT_SELECT_KEY( "port", "pt" )
520
525#define DEFENDER_REPORT_LENGTH_PORT_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_PORT_KEY )
526
531#define DEFENDER_REPORT_INTERFACE_KEY DEFENDER_REPORT_SELECT_KEY( "interface", "if" )
532
537#define DEFENDER_REPORT_LENGTH_INTERFACE_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_INTERFACE_KEY )
538
543#define DEFENDER_REPORT_UDP_LISTENING_PORTS_KEY DEFENDER_REPORT_SELECT_KEY( "listening_udp_ports", "up" )
544
549#define DEFENDER_REPORT_LENGTH_UDP_LISTENING_PORTS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_UDP_LISTENING_PORTS_KEY )
550
555#define DEFENDER_REPORT_NETWORK_STATS_KEY DEFENDER_REPORT_SELECT_KEY( "network_stats", "ns" )
556
561#define DEFENDER_REPORT_LENGTH_NETWORK_STATS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_NETWORK_STATS_KEY )
562
567#define DEFENDER_REPORT_BYTES_IN_KEY DEFENDER_REPORT_SELECT_KEY( "bytes_in", "bi" )
568
573#define DEFENDER_REPORT_LENGTH_BYTES_IN_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_BYTES_IN_KEY )
574
579#define DEFENDER_REPORT_BYTES_OUT_KEY DEFENDER_REPORT_SELECT_KEY( "bytes_out", "bo" )
580
585#define DEFENDER_REPORT_LENGTH_BYTES_OUT_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_BYTES_OUT_KEY )
586
591#define DEFENDER_REPORT_PKTS_IN_KEY DEFENDER_REPORT_SELECT_KEY( "packets_in", "pi" )
592
597#define DEFENDER_REPORT_LENGTH_PKTS_IN_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_PKTS_IN_KEY )
598
603#define DEFENDER_REPORT_PKTS_OUT_KEY DEFENDER_REPORT_SELECT_KEY( "packets_out", "po" )
604
609#define DEFENDER_REPORT_LENGTH_PKS_OUT_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LENGTH_PKS_OUT_KEY )
610
615#define DEFENDER_REPORT_CUSTOM_METRICS_KEY DEFENDER_REPORT_SELECT_KEY( "custom_metrics", "cmet" )
616
621#define DEFENDER_REPORT_LENGTH_CUSTOM_METRICS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LENGTH_CUSTOM_METRICS_KEY )
622
627#define DEFENDER_REPORT_NUMBER_KEY "number"
628
633#define DEFENDER_REPORT_LENGTH_NUMBER_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LENGTH_NUMBER_KEY )
634
639#define DEFENDER_REPORT_NUMBER_LIST_KEY "number_list"
640
645#define DEFENDER_REPORT_LENGTH_NUMBER_LIST_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LENGTH_NUMBER_LIST_KEY )
646
651#define DEFENDER_REPORT_STRING_LIST_KEY "string_list"
652
657#define DEFENDER_REPORT_LENGTH_STRING_LIST_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LENGTH_STRING_LIST_KEY )
658
663#define DEFENDER_REPORT_IP_LIST_KEY "ip_list"
664
669#define DEFENDER_REPORT_LENGTH_IP_LIST_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LENGTH_IP_LIST_KEY )
670
671/*-----------------------------------------------------------*/
672
719/* @[declare_defender_gettopic] */
720DefenderStatus_t Defender_GetTopic( char * pBuffer,
721 uint16_t bufferLength,
722 const char * pThingName,
723 uint16_t thingNameLength,
724 DefenderTopic_t api,
725 uint16_t * pOutLength );
726/* @[declare_defender_gettopic] */
727
728/*-----------------------------------------------------------*/
729
789/* @[declare_defender_matchtopic] */
790DefenderStatus_t Defender_MatchTopic( const char * pTopic,
791 uint16_t topicLength,
792 DefenderTopic_t * pOutApi,
793 const char ** ppOutThingName,
794 uint16_t * pOutThingNameLength );
795/* @[declare_defender_matchtopic] */
796
797/*-----------------------------------------------------------*/
798
799/* *INDENT-OFF* */
800#ifdef __cplusplus
801 }
802#endif
803/* *INDENT-ON* */
804
805#endif /* DEFENDER_H_ */
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.
Definition: defender.c:384
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.
Definition: defender.c:465
Default config values for the AWS IoT Device Defender Client Library.
DefenderStatus_t
Return codes from defender APIs.
Definition: defender.h:58
DefenderTopic_t
Topic values for subscription requests.
Definition: defender.h:71
@ DefenderBadParameter
Definition: defender.h:62
@ DefenderBufferTooSmall
Definition: defender.h:63
@ DefenderNoMatch
Definition: defender.h:61
@ DefenderError
Definition: defender.h:59
@ DefenderSuccess
Definition: defender.h:60
@ DefenderCborReportPublish
Definition: defender.h:76
@ DefenderInvalidTopic
Definition: defender.h:72
@ DefenderJsonReportPublish
Definition: defender.h:73
@ DefenderJsonReportAccepted
Definition: defender.h:74
@ DefenderJsonReportRejected
Definition: defender.h:75
@ DefenderCborReportRejected
Definition: defender.h:78
@ DefenderCborReportAccepted
Definition: defender.h:77