1 /**************************************************************************/
2 /*                                                                        */
3 /*       Copyright (c) Microsoft Corporation. All rights reserved.        */
4 /*                                                                        */
5 /*       This software is licensed under the Microsoft Software License   */
6 /*       Terms for Microsoft Azure RTOS. Full text of the license can be  */
7 /*       found in the LICENSE file at https://aka.ms/AzureRTOS_EULA       */
8 /*       and in the root directory of this software.                      */
9 /*                                                                        */
10 /**************************************************************************/
11 
12 #ifndef NX_AZURE_IOT_SECURITY_MODULE_H
13 #define NX_AZURE_IOT_SECURITY_MODULE_H
14 
15 #include <asc_config.h>
16 
17 #ifdef __ASC_CONFIG_EXCLUDE_PORT__H__
18 #error Platform includes error
19 #endif
20 
21 #ifdef __cplusplus
22 extern   "C" {
23 #endif
24 
25 #include "nx_api.h"
26 #include "nx_azure_iot.h"
27 
28 /* Ensure enable ip packet filter is defined. */
29 #ifndef NX_ENABLE_IP_PACKET_FILTER
30 #error "Azure IoT Security Module requires NX_ENABLE_IP_PACKET_FILTER to be defined, enable NX_ENABLE_IP_PACKET_FILTER in `nx_user.h`."
31 #endif /* NX_ENABLE_IP_PACKET_FILTER */
32 
33 #include "asc_security_core/core.h"
34 #include "asc_security_core/version.h"
35 #include "asc_security_core/utils/itime.h"
36 #include "asc_security_core/utils/notifier.h"
37 #include "asc_security_core/utils/ievent_loop.h"
38 
39 /* Define AZ IoT ASC event flags. These events are processed by the Cloud thread.  */
40 #define AZ_IOT_SECURITY_MODULE_SEND_EVENT   ((ULONG)0x00000001)       /* Security send event. */
41 
42 /**
43  * @brief Azure IoT Security Module state enum
44  *
45  * @details State diagram:
46  *
47  *       +--------------+           +--------------+               +--------------+                +------+-------+
48  *       |              |           |              +--------+      |              +--------+       |              |
49  *       |              |           |              |        |(2)   |              |        |(4)    |              |
50  *       |     NOT      |    (1)    |    PENDING   <--------+      |    ACTIVE    <--------+       |  SUSPENDED   |
51  *       | INITIALIZED  +----------->              |               |              |                |              |
52  *       |              |           |              +--------------->              <----------------|              |
53  *       |              |           |              |      (3)      |              |       (7)      |              |
54  *       +--------------+           +-+----+-------+               +------+-------+                +------+-------+
55  *                                    |    ^                              |                               ^
56  *                                    |    |        (5)                   |                               |
57  *                                    |    +------------------------------+                  (6)          |
58  *                                    +-------------------------------------------------------------------+
59  *
60  * (1) After registering to cloud thread.
61  * (2) Collect event and waiting for established connection.
62  * (3) Connection established.
63  * (4) Collect and send security messages.
64  * (5) No connections.
65  * (6) Pending time interval exceeded.
66  * (7) Connection has been established.
67  *
68  */
69 typedef enum security_module_state
70 {
71     /* Security Module initial state. */
72     SECURITY_MODULE_STATE_NOT_INITIALIZED = 0,
73 
74     /* Security Module collects security events, but skips sending to IoT Hub. */
75     SECURITY_MODULE_STATE_PENDING = 1,
76 
77     /* Security Module is collecting security messages and sending them to IoT Hub. */
78     SECURITY_MODULE_STATE_ACTIVE = 2,
79 
80     /* Security Module is idle, waiting for a healthy IoT Hub connection. */
81     SECURITY_MODULE_STATE_SUSPENDED = 3
82 } security_module_state_t;
83 
84 /**
85  * @struct NX_AZURE_IOT_SECURITY_MODULE
86  *
87  * @details Azure Security Center for IoT security module provides a comprehensive security solution for Azure RTOS devices.
88  *
89  * Azure Security Center for IoT security module with Azure RTOS support offers the following features:
90  *  - Detection of malicious network activities: Every device inbound and outbound network activity is
91  *    monitored (supported protocols: TCP, UDP, ICMP on IPv4 and IPv6). Azure Security Center for IoT inspects each of
92  *    these network activities against the Microsoft Threat Intelligence feed. The feed gets updated in real-time with
93  *    millions of unique threat indicators collected worldwide.
94  *  - Device behavior baselining based on custom alerts: Allows for clustering of devices into security groups and
95  *    defining the expected behavior of each group. As IoT devices are typically designed to operate in well-defined
96  *    and limited scenarios, it is easy to create a baseline that defines their expected behavior using a set of
97  *    parameters. Any deviation from the baseline, triggers an alert.
98  *  - Improve the security hygiene of the device: By leveraging the recommended infrastructure Azure Security Center
99  *    for IoT provides, gain knowledge and insights about issues in your environment that impact and damage the
100  *    security posture of your devices. Poor IoT device security posture can allow potential attacks to succeed if left
101  *    unchanged, as security is always measured by the weakest link within any organization.
102  */
103 typedef struct NX_AZURE_IOT_SECURITY_MODULE_STRUCT
104 {
105     security_module_state_t state;
106     notifier_t message_ready;
107     unsigned long state_timestamp;
108     event_loop_timer_handler h_state_machine;
109 
110     NX_AZURE_IOT *nx_azure_iot_ptr;
111 
112     NX_CLOUD_MODULE nx_azure_iot_security_module_cloud;
113 } NX_AZURE_IOT_SECURITY_MODULE;
114 
115 /**
116  * @brief Enable Azure IoT Security Module
117  *
118  * @details This routine enables the Azure IoT Security Module subsystem. An internal state machine
119  *          manage security events collection and sends them to Azure IoT Hub. Only one NX_AZURE_IOT_SECURITY_MODULE
120  *          instance exists and needed to manage data collection.
121  *
122  * @param[in] nx_azure_iot_ptr    A pointer to a #NX_AZURE_IOT
123  *
124  * @return A `UINT` with the result of the API.
125  *   @retval #NX_AZURE_IOT_SUCCESS               Successfully enabled Azure IoT Security Module.
126  *   @retval #NX_AZURE_IOT_FAILURE               Fail to enable Azure IoT Security Module due to internal error.
127  *   @retval #NX_AZURE_IOT_INVALID_PARAMETER     Security module requires valid #NX_AZURE_IOT instance.
128  */
129 UINT nx_azure_iot_security_module_enable(NX_AZURE_IOT *nx_azure_iot_ptr);
130 
131 
132 /**
133  * @brief Disable Azure IoT Security Module
134  *
135  * @details This routine disables the Azure IoT Security Module subsystem.
136  *
137  * @param[in] nx_azure_iot_ptr    A pointer to a #NX_AZURE_IOT, if NULL the singleton instance will be disabled.
138  *
139  * @return A `UINT` with the result of the API.
140  *   @retval #NX_AZURE_IOT_SUCCESS               Successful if Azure IoT Security Module has been disabled successfully.
141  *   @retval #NX_AZURE_IOT_INVALID_PARAMETER     Azure IoT Hub instance differ than the singleton composite instance.
142  *   @retval #NX_AZURE_IOT_FAILURE               Fail to disable Azure IoT Security Module due to internal error.
143  */
144 UINT nx_azure_iot_security_module_disable(NX_AZURE_IOT *nx_azure_iot_ptr);
145 
146 
147 #ifdef __cplusplus
148 }
149 #endif
150 
151 #endif /* NX_AZURE_IOT_SECURITY_MODULE_H */