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
49typedef enum
50{
57
62typedef 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] */
652DefenderStatus_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] */
722DefenderStatus_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_ */
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 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
Default config values for the AWS IoT Device Defender Client Library.
DefenderStatus_t
Return codes from defender APIs.
Definition: defender.h:50
DefenderTopic_t
Topic values for subscription requests.
Definition: defender.h:63
@ DefenderBadParameter
Definition: defender.h:54
@ DefenderBufferTooSmall
Definition: defender.h:55
@ DefenderNoMatch
Definition: defender.h:53
@ DefenderError
Definition: defender.h:51
@ DefenderSuccess
Definition: defender.h:52
@ DefenderCborReportPublish
Definition: defender.h:68
@ DefenderInvalidTopic
Definition: defender.h:64
@ DefenderJsonReportPublish
Definition: defender.h:65
@ DefenderJsonReportAccepted
Definition: defender.h:66
@ DefenderJsonReportRejected
Definition: defender.h:67
@ DefenderCborReportRejected
Definition: defender.h:70
@ DefenderCborReportAccepted
Definition: defender.h:69