AWS IoT Device Defender  v1.0.0
AWS IoT Device Defender Client Library
defender.h
Go to the documentation of this file.
1 /*
2  * AWS IoT Device Defender Client v1.0.0
3  * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining a copy of
6  * this software and associated documentation files (the "Software"), to deal in
7  * the Software without restriction, including without limitation the rights to
8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9  * the Software, and to permit persons to whom the Software is furnished to do so,
10  * subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in all
13  * copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21  */
22 
28 #ifndef DEFENDER_H_
29 #define DEFENDER_H_
30 
31 /* Standard includes. */
32 #include <stdint.h>
33 
34 /* DEFENDER_DO_NOT_USE_CUSTOM_CONFIG allows building the Device Defender library
35  * without a config file. If a config file is provided, DEFENDER_DO_NOT_USE_CUSTOM_CONFIG
36  * macro must not be defined.
37  */
38 #ifndef DEFENDER_DO_NOT_USE_CUSTOM_CONFIG
39  #include "defender_config.h"
40 #endif
41 
42 /* Default config values. */
44 
49 typedef enum
50 {
57 
62 typedef enum
63 {
71  DefenderMaxTopic
73 
74 /*-----------------------------------------------------------*/
75 
79 #define STRING_LITERAL_LENGTH( literal ) ( ( uint16_t ) ( sizeof( literal ) - 1U ) )
80 
81 /*-----------------------------------------------------------*/
82 
87 #define DEFENDER_THINGNAME_MAX_LENGTH 128U
88 
96 #define DEFENDER_REPORT_MIN_PERIOD_SECONDS 300
97 
98 /*-----------------------------------------------------------*/
99 
100 /*
101  * A Defender topic has the following format:
102  *
103  * <Prefix><Thing Name><Bridge><Report Format><Suffix>
104  *
105  * Where:
106  * <Prefix> = $aws/things/
107  * <Thing Name> = Name of the thing.
108  * <Bridge> = /defender/metrics/
109  * <Report Format> = json or cbor
110  * <Suffix> = /accepted or /rejected or empty
111  *
112  * Examples:
113  * $aws/things/THING_NAME/defender/metrics/json
114  * $aws/things/THING_NAME/defender/metrics/json/accepted
115  * $aws/things/THING_NAME/defender/metrics/json/rejected
116  * $aws/things/THING_NAME/defender/metrics/cbor
117  * $aws/things/THING_NAME/defender/metrics/cbor/accepted
118  * $aws/things/THING_NAME/defender/metrics/json/rejected
119  */
120 
126 #define DEFENDER_API_PREFIX "$aws/things/"
127 #define DEFENDER_API_LENGTH_PREFIX STRING_LITERAL_LENGTH( DEFENDER_API_PREFIX )
128 
129 #define DEFENDER_API_BRIDGE "/defender/metrics/"
130 #define DEFENDER_API_LENGTH_BRIDGE STRING_LITERAL_LENGTH( DEFENDER_API_BRIDGE )
131 
132 #define DEFENDER_API_JSON_FORMAT "json"
133 #define DEFENDER_API_LENGTH_JSON_FORMAT STRING_LITERAL_LENGTH( DEFENDER_API_JSON_FORMAT )
134 
135 #define DEFENDER_API_CBOR_FORMAT "cbor"
136 #define DEFENDER_API_LENGTH_CBOR_FORMAT STRING_LITERAL_LENGTH( DEFENDER_API_CBOR_FORMAT )
137 
138 #define DEFENDER_API_ACCEPTED_SUFFIX "/accepted"
139 #define DEFENDER_API_LENGTH_ACCEPTED_SUFFIX STRING_LITERAL_LENGTH( DEFENDER_API_ACCEPTED_SUFFIX )
140 
141 #define DEFENDER_API_REJECTED_SUFFIX "/rejected"
142 #define DEFENDER_API_LENGTH_REJECTED_SUFFIX STRING_LITERAL_LENGTH( DEFENDER_API_REJECTED_SUFFIX )
143 
144 #define DEFENDER_API_NULL_SUFFIX ""
145 #define DEFENDER_API_LENGTH_NULL_SUFFIX ( 0U )
146 
149 /*-----------------------------------------------------------*/
150 
156 /* Defender API topic lengths. */
157 #define DEFENDER_API_COMMON_LENGTH( thingNameLength, reportFormatLength, suffixLength ) \
158  ( DEFENDER_API_LENGTH_PREFIX + \
159  ( thingNameLength ) + \
160  DEFENDER_API_LENGTH_BRIDGE + \
161  ( reportFormatLength ) + \
162  ( suffixLength ) )
163 
171 #define DEFENDER_API_LENGTH_JSON_PUBLISH( thingNameLength ) \
172  DEFENDER_API_COMMON_LENGTH( thingNameLength, \
173  DEFENDER_API_LENGTH_JSON_FORMAT, \
174  DEFENDER_API_LENGTH_NULL_SUFFIX )
175 
181 #define DEFENDER_API_LENGTH_JSON_ACCEPTED( thingNameLength ) \
182  DEFENDER_API_COMMON_LENGTH( thingNameLength, \
183  DEFENDER_API_LENGTH_JSON_FORMAT, \
184  DEFENDER_API_LENGTH_ACCEPTED_SUFFIX )
185 
191 #define DEFENDER_API_LENGTH_JSON_REJECTED( thingNameLength ) \
192  DEFENDER_API_COMMON_LENGTH( thingNameLength, \
193  DEFENDER_API_LENGTH_JSON_FORMAT, \
194  DEFENDER_API_LENGTH_REJECTED_SUFFIX )
195 
201 #define DEFENDER_API_LENGTH_CBOR_PUBLISH( thingNameLength ) \
202  DEFENDER_API_COMMON_LENGTH( thingNameLength, \
203  DEFENDER_API_LENGTH_CBOR_FORMAT, \
204  DEFENDER_API_LENGTH_NULL_SUFFIX )
205 
211 #define DEFENDER_API_LENGTH_CBOR_ACCEPTED( thingNameLength ) \
212  DEFENDER_API_COMMON_LENGTH( thingNameLength, \
213  DEFENDER_API_LENGTH_CBOR_FORMAT, \
214  DEFENDER_API_LENGTH_ACCEPTED_SUFFIX )
215 
221 #define DEFENDER_API_LENGTH_CBOR_REJECTED( thingNameLength ) \
222  DEFENDER_API_COMMON_LENGTH( thingNameLength, \
223  DEFENDER_API_LENGTH_CBOR_FORMAT, \
224  DEFENDER_API_LENGTH_REJECTED_SUFFIX )
225 
231 #define DEFENDER_API_MAX_LENGTH( thingNameLength ) \
232  DEFENDER_API_LENGTH_CBOR_ACCEPTED( thingNameLength )
233 
234 /*-----------------------------------------------------------*/
235 
241 /* Defender API topics. */
242 #define DEFENDER_API_COMMON( thingName, reportFormat, suffix ) \
243  ( DEFENDER_API_PREFIX \
244  thingName \
245  DEFENDER_API_BRIDGE \
246  reportFormat \
247  suffix )
248 
260 #define DEFENDER_API_JSON_PUBLISH( thingName ) \
261  DEFENDER_API_COMMON( thingName, \
262  DEFENDER_API_JSON_FORMAT, \
263  DEFENDER_API_NULL_SUFFIX )
264 
274 #define DEFENDER_API_JSON_ACCEPTED( thingName ) \
275  DEFENDER_API_COMMON( thingName, \
276  DEFENDER_API_JSON_FORMAT, \
277  DEFENDER_API_ACCEPTED_SUFFIX )
278 
288 #define DEFENDER_API_JSON_REJECTED( thingName ) \
289  DEFENDER_API_COMMON( thingName, \
290  DEFENDER_API_JSON_FORMAT, \
291  DEFENDER_API_REJECTED_SUFFIX )
292 
302 #define DEFENDER_API_CBOR_PUBLISH( thingName ) \
303  DEFENDER_API_COMMON( thingName, \
304  DEFENDER_API_CBOR_FORMAT, \
305  DEFENDER_API_NULL_SUFFIX )
306 
316 #define DEFENDER_API_CBOR_ACCEPTED( thingName ) \
317  DEFENDER_API_COMMON( thingName, \
318  DEFENDER_API_CBOR_FORMAT, \
319  DEFENDER_API_ACCEPTED_SUFFIX )
320 
330 #define DEFENDER_API_CBOR_REJECTED( thingName ) \
331  DEFENDER_API_COMMON( thingName, \
332  DEFENDER_API_CBOR_FORMAT, \
333  DEFENDER_API_REJECTED_SUFFIX )
334 
335 /*-----------------------------------------------------------*/
336 
342 /* Keys used in defender report. */
343 #if ( defined( DEFENDER_USE_LONG_KEYS ) && ( DEFENDER_USE_LONG_KEYS == 1 ) )
344  #define DEFENDER_REPORT_SELECT_KEY( longKey, shortKey ) ( longKey )
345 #else
346  #define DEFENDER_REPORT_SELECT_KEY( longKey, shortKey ) ( shortKey )
347 #endif
348 
355 #define DEFENDER_REPORT_HEADER_KEY DEFENDER_REPORT_SELECT_KEY( "header", "hed" )
356 
361 #define DEFENDER_REPORT_LENGTH_HEADER_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_HEADER_KEY )
362 
367 #define DEFENDER_REPORT_METRICS_KEY DEFENDER_REPORT_SELECT_KEY( "metrics", "met" )
368 
373 #define DEFENDER_REPORT_LENGTH_METRICS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_METRICS_KEY )
374 
379 #define DEFENDER_REPORT_ID_KEY DEFENDER_REPORT_SELECT_KEY( "report_id", "rid" )
380 
385 #define DEFENDER_REPORT_LENGTH_ID_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_ID_KEY )
386 
391 #define DEFENDER_REPORT_VERSION_KEY DEFENDER_REPORT_SELECT_KEY( "version", "v" )
392 
397 #define DEFENDER_REPORT_LENGTH_VERSION_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_VERSION_KEY )
398 
403 #define DEFENDER_REPORT_TCP_CONNECTIONS_KEY DEFENDER_REPORT_SELECT_KEY( "tcp_connections", "tc" )
404 
409 #define DEFENDER_REPORT_LENGTH_TCP_CONNECTIONS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_TCP_CONNECTIONS_KEY )
410 
415 #define DEFENDER_REPORT_ESTABLISHED_CONNECTIONS_KEY DEFENDER_REPORT_SELECT_KEY( "established_connections", "ec" )
416 
421 #define DEFENDER_REPORT_LENGTH_ESTABLISHED_CONNECTIONS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_ESTABLISHED_CONNECTIONS_KEY )
422 
427 #define DEFENDER_REPORT_CONNECTIONS_KEY DEFENDER_REPORT_SELECT_KEY( "connections", "cs" )
428 
433 #define DEFENDER_REPORT_LENGTH_CONNECTIONS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_CONNECTIONS_KEY )
434 
439 #define DEFENDER_REPORT_REMOTE_ADDR_KEY DEFENDER_REPORT_SELECT_KEY( "remote_addr", "rad" )
440 
445 #define DEFENDER_REPORT_LENGTH_REMOTE_ADDR_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_REMOTE_ADDR_KEY )
446 
451 #define DEFENDER_REPORT_LOCAL_PORT_KEY DEFENDER_REPORT_SELECT_KEY( "local_port", "lp" )
452 
457 #define DEFENDER_REPORT_LENGTH_LOCAL_PORT_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LOCAL_PORT_KEY )
458 
463 #define DEFENDER_REPORT_LOCAL_INTERFACE_KEY DEFENDER_REPORT_SELECT_KEY( "local_interface", "li" )
464 
469 #define DEFENDER_REPORT_LENGTH_LOCAL_INTERFACE_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LOCAL_INTERFACE_KEY )
470 
475 #define DEFENDER_REPORT_TOTAL_KEY DEFENDER_REPORT_SELECT_KEY( "total", "t" )
476 
481 #define DEFENDER_REPORT_LENGTH_TOTAL_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_TOTAL_KEY )
482 
487 #define DEFENDER_REPORT_TCP_LISTENING_PORTS_KEY DEFENDER_REPORT_SELECT_KEY( "listening_tcp_ports", "tp" )
488 
493 #define DEFENDER_REPORT_LENGTH_TCP_LISTENING_PORTS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_TCP_LISTENING_PORTS_KEY )
494 
499 #define DEFENDER_REPORT_PORTS_KEY DEFENDER_REPORT_SELECT_KEY( "ports", "pts" )
500 
505 #define DEFENDER_REPORT_LENGTH_PORTS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_PORTS_KEY )
506 
511 #define DEFENDER_REPORT_PORT_KEY DEFENDER_REPORT_SELECT_KEY( "port", "pt" )
512 
517 #define DEFENDER_REPORT_LENGTH_PORT_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_PORT_KEY )
518 
523 #define DEFENDER_REPORT_INTERFACE_KEY DEFENDER_REPORT_SELECT_KEY( "interface", "if" )
524 
529 #define DEFENDER_REPORT_LENGTH_INTERFACE_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_INTERFACE_KEY )
530 
535 #define DEFENDER_REPORT_UDP_LISTENING_PORTS_KEY DEFENDER_REPORT_SELECT_KEY( "listening_udp_ports", "up" )
536 
541 #define DEFENDER_REPORT_LENGTH_UDP_LISTENING_PORTS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_UDP_LISTENING_PORTS_KEY )
542 
547 #define DEFENDER_REPORT_NETWORK_STATS_KEY DEFENDER_REPORT_SELECT_KEY( "network_stats", "ns" )
548 
553 #define DEFENDER_REPORT_LENGTH_NETWORK_STATS_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_NETWORK_STATS_KEY )
554 
559 #define DEFENDER_REPORT_BYTES_IN_KEY DEFENDER_REPORT_SELECT_KEY( "bytes_in", "bi" )
560 
565 #define DEFENDER_REPORT_LENGTH_BYTES_IN_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_BYTES_IN_KEY )
566 
571 #define DEFENDER_REPORT_BYTES_OUT_KEY DEFENDER_REPORT_SELECT_KEY( "bytes_out", "bo" )
572 
577 #define DEFENDER_REPORT_LENGTH_BYTES_OUT_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_BYTES_OUT_KEY )
578 
583 #define DEFENDER_REPORT_PKTS_IN_KEY DEFENDER_REPORT_SELECT_KEY( "packets_in", "pi" )
584 
589 #define DEFENDER_REPORT_LENGTH_PKTS_IN_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_PKTS_IN_KEY )
590 
595 #define DEFENDER_REPORT_PKTS_OUT_KEY DEFENDER_REPORT_SELECT_KEY( "packets_out", "po" )
596 
601 #define DEFENDER_REPORT_LENGTH_PKS_OUT_KEY STRING_LITERAL_LENGTH( DEFENDER_REPORT_LENGTH_PKS_OUT_KEY )
602 
603 /*-----------------------------------------------------------*/
604 
651 /* @[declare_defender_gettopic] */
652 DefenderStatus_t Defender_GetTopic( char * pBuffer,
653  uint16_t bufferLength,
654  const char * pThingName,
655  uint16_t thingNameLength,
656  DefenderTopic_t api,
657  uint16_t * pOutLength );
658 /* @[declare_defender_gettopic] */
659 
660 /*-----------------------------------------------------------*/
661 
721 /* @[declare_defender_matchtopic] */
722 DefenderStatus_t Defender_MatchTopic( const char * pTopic,
723  uint16_t topicLength,
724  DefenderTopic_t * pOutApi,
725  const char ** ppOutThingName,
726  uint16_t * pOutThingNameLength );
727 /* @[declare_defender_matchtopic] */
728 
729 /*-----------------------------------------------------------*/
730 
731 #endif /* DEFENDER_H_ */
DefenderError
@ DefenderError
Definition: defender.h:51
DefenderSuccess
@ DefenderSuccess
Definition: defender.h:52
DefenderJsonReportRejected
@ DefenderJsonReportRejected
Definition: defender.h:67
DefenderJsonReportPublish
@ DefenderJsonReportPublish
Definition: defender.h:65
DefenderJsonReportAccepted
@ DefenderJsonReportAccepted
Definition: defender.h:66
defender_config_defaults.h
Default config values for the AWS IoT Device Defender Client Library.
DefenderInvalidTopic
@ DefenderInvalidTopic
Definition: defender.h:64
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.
Definition: defender.c:381
DefenderStatus_t
DefenderStatus_t
Return codes from defender APIs.
Definition: defender.h:50
DefenderBufferTooSmall
@ DefenderBufferTooSmall
Definition: defender.h:55
DefenderCborReportPublish
@ DefenderCborReportPublish
Definition: defender.h:68
DefenderCborReportAccepted
@ DefenderCborReportAccepted
Definition: defender.h:69
DefenderTopic_t
DefenderTopic_t
Topic values for subscription requests.
Definition: defender.h:63
DefenderBadParameter
@ DefenderBadParameter
Definition: defender.h:54
DefenderCborReportRejected
@ DefenderCborReportRejected
Definition: defender.h:70
DefenderNoMatch
@ DefenderNoMatch
Definition: defender.h:53
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.
Definition: defender.c:462