ble_sec.h
Go to the documentation of this file.
1 /**
2  ****************************************************************************************
3  *
4  * @file ble_sec.h
5  *
6  * @brief BLE SEC API
7  *
8  ****************************************************************************************
9  * @attention
10  #####Copyright (c) 2019 GOODIX
11  All rights reserved.
12 
13  Redistribution and use in source and binary forms, with or without
14  modification, are permitted provided that the following conditions are met:
15  * Redistributions of source code must retain the above copyright
16  notice, this list of conditions and the following disclaimer.
17  * Redistributions in binary form must reproduce the above copyright
18  notice, this list of conditions and the following disclaimer in the
19  documentation and/or other materials provided with the distribution.
20  * Neither the name of GOODIX nor the names of its contributors may be used
21  to endorse or promote products derived from this software without
22  specific prior written permission.
23 
24  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  POSSIBILITY OF SUCH DAMAGE.
35  *****************************************************************************************
36  */
37 
38 /**
39  * @addtogroup BLE
40  * @{
41  */
42 
43  /**
44  @addtogroup BLE_SEC Security Manager(SM)
45  @{
46  @brief Definitions and prototypes for the BLE_SEC interface.
47  */
48 
49 #ifndef __BLE_SEC_H__
50 #define __BLE_SEC_H__
51 
52 #include "ble_error.h"
53 #include <stdbool.h>
54 
55 /**@addtogroup BLE_SM_DEFINES Defines
56  * @{
57  */
58 /**@defgroup BLE_SEC_AUTH_FLAG SEC Auth Flag
59 * @{
60 */
61 #define BLE_SEC_AUTH_NONE 0 /**< No auth requirement. */
62 #define BLE_SEC_AUTH_BOND (1 << 0) /**< Bond flag. */
63 #define BLE_SEC_AUTH_MITM (1 << 2) /**< MITM flag. */
64 #define BLE_SEC_AUTH_SEC_CON (1 << 3) /**< Security connection flag. */
65 #define BLE_SEC_AUTH_KEY_PRESS_NOTIFY (1 << 4) /**< Key press notify flag. */
66 #define BLE_SEC_AUTH_ALL (AUTH_BOND | AUTH_MITM | AUTH_SEC_CON | AUTH_KEY_PRESS_NOTIFY) /**< All authentication flags are on. */
67 /**@} */
68 
69 /**@defgroup BLE_SEC_KEY_DIST_FLAG SEC Key Distribution Flag
70 * @{
71 */
72 #define BLE_SEC_KDIST_NONE 0 /**< No key needs to be distributed. */
73 #define BLE_SEC_KDIST_ENCKEY (1 << 0) /**< Distribute encryption and master identification info. */
74 #define BLE_SEC_KDIST_IDKEY (1 << 1) /**< Distribute identity and address info. */
75 #define BLE_SEC_KDIST_SIGNKEY (1 << 2) /**< Distribute signing info. */
76 #define BLE_SEC_KDIST_ALL (BLE_SEC_KDIST_ENCKEY | BLE_SEC_KDIST_IDKEY | BLE_SEC_KDIST_SIGNKEY) /**< Distribute all info. */
77 
78 /**@} */
79 /**@} */
80 
81 /**@addtogroup BLE_SEC_ENUMERATIONS Enumerations
82  * @{ */
83 /**@brief SEC IO Capability. */
84 typedef enum
85 {
86  BLE_SEC_IO_DISPLAY_ONLY = 0x00, /**< Display only. */
87  BLE_SEC_IO_DISPLAY_YES_NO = 0x01, /**< Display and input yes or no. */
88  BLE_SEC_IO_KEYBOARD_ONLY = 0x02, /**< Keyboard only. */
89  BLE_SEC_IO_NO_INPUT_NO_OUTPUT = 0x03, /**< No input and no output. */
90  BLE_SEC_IO_KEYBOARD_DISPLAY = 0x04 /**< Keyboard and display. */
92 
93 /**@brief SEC Encryption Request Type.
94  *@note These types indicate some operations need to interact with app during pair process.
95  */
96 typedef enum
97 {
98  BLE_SEC_PAIR_REQ, /**< Pair request. Apps need to decide whether to accept this request. */
99  BLE_SEC_TK_REQ, /**< TK request. Apps need to set the TK value. */
100  BLE_SEC_OOB_REQ, /**< OOB request. Apps need to set the OOB value. */
101  BLE_SEC_NC_REQ /**< Number comparison request. Apps need to check if it is the same number displayed in Master and Slave. */
103 
104 /**@brief SEC Key Press Notify. */
105 typedef enum
106 {
107  BLE_SEC_KEY_PRESS_STARTED = 0x00, /**< Passkey entry started. */
108  BLE_SEC_KEY_PRESS_ENTERED = 0x01, /**< Passkey digit entered. */
109  BLE_SEC_KEY_PRESS_ERASED = 0x02, /**< Passkey digit erased. */
110  BLE_SEC_KEY_PRESS_CLEARED = 0x03, /**< Passkey cleared. */
111  BLE_SEC_KEY_PRESS_COMPLETED = 0x04 /**< Passkey entry completed. */
113 
114 /**@brief SEC mode and level. */
115 typedef enum
116 {
117  BLE_SEC_MODE1_LEVEL1 = 0x00, /**< No security is needed. */
118  BLE_SEC_MODE1_LEVEL2 = 0x01, /**< Encrypted link is required. Unnecessary: MITM and SC. */
119  BLE_SEC_MODE1_LEVEL3 = 0x02, /**< Encrypted link is required. Necessary: MITM; unnecessary: SC. */
120  BLE_SEC_MODE1_LEVEL4 = 0x03, /**< Encrypted link is required. Necessary: MITM and SC. */
121  BLE_SEC_MODE2_LEVEL1 = 0x04, /**< Data signing is required. Unnecessary: MITM and SC. */
122  BLE_SEC_MODE2_LEVEL2 = 0x05, /**< Data signing is required. Necessary: MITM; unnecessary: SC. */
124 
125 /**@brief SEC TK type. */
126 typedef enum
127 {
128  BLE_SEC_TK_OOB = 0x00, /**<TK got from OOB (out of band) method. */
129  BLE_SEC_TK_DISPLAY, /**<TK generated and shall be displayed by local device. */
130  BLE_SEC_TK_KEY_ENTRY /**<TK shall be entered by user using device keyboard. */
132 
133 /**@brief Key missing reason. */
134 typedef enum
135 {
136  BLE_SEC_BOND_INFO_LOAD_FAILED = 0x00, /**<Bond information load failed. */
137  BLE_SEC_LTK_VALID_MASK_ERR, /**<LTK valid mask flag is false. */
138  BLE_SEC_EDIV_RAND_VALUE_ERR /**<Ediv and rand value not match. */
140 /** @} */
141 
142 /**@addtogroup BLE_SEC_STRUCTURES Structures
143  * @{ */
144 /**@brief SEC Parameter. */
145 typedef struct
146 {
147  ble_sec_mode_level_t level; /**< Set the minimum security level of the device, see @ref ble_sec_mode_level_t. */
148  ble_sec_io_cap_t io_cap; /**< Set the IO capability, see @ref ble_sec_io_cap_t. */
149  bool oob; /**< Indicate whether OOB is supported. */
150  uint8_t auth; /**< Set the auth, see @ref BLE_SEC_AUTH_FLAG. */
151  uint8_t key_size; /**< Indicate the supported maximum LTK size (range: 7-16). */
152  uint8_t ikey_dist; /**< Set the initial key distribution, see @ref BLE_SEC_KEY_DIST_FLAG. */
153  uint8_t rkey_dist; /**< Set the response key distribution, see @ref BLE_SEC_KEY_DIST_FLAG. */
155 
156 /**@brief TK value. */
157 typedef struct
158 {
159  uint8_t key[16]; /**< TK value. */
160 } ble_sec_tk_t;
161 
162 /**@brief SEC OOB value. */
163 typedef struct
164 {
165  uint8_t conf[16]; /**< Confirm value. */
166  uint8_t rand[16]; /**< Random value. */
167 } ble_sec_oob_t;
168 
169 /**@brief SEC Confirm encryption data. */
170 typedef union
171 {
172  ble_sec_tk_t tk; /**< TK value, see @ref ble_sec_tk_t. */
173  ble_sec_oob_t oob; /**< OOB value, see @ref ble_sec_oob_t. */
175 
176 /**@brief SEC Confirm encryption. */
177 typedef struct
178 {
179  ble_sec_enc_req_type_t req_type; /**< Request type, see @ref ble_sec_enc_req_type_t. */
180  bool accept; /**< Indicate whether to accept the request. */
181  ble_sec_cfm_enc_data_t data; /**< SEC Confirm encryption data, see @ref ble_sec_cfm_enc_data_t. */
183 
184 /**@brief SEC number comparison value. */
185 typedef struct
186 {
187  uint8_t value[4]; /**< Number comparison value (000000~999999). */
188 } ble_sec_nc_t;
189 
190 /**@brief SEC encryption request data. */
191 typedef union
192 {
193  ble_sec_tk_type_t tk_type; /**<TK type, see @ref ble_sec_tk_type_t. */
194  ble_sec_oob_t oob_data; /**<OOB data, see @ref ble_sec_oob_t. */
195  ble_sec_nc_t nc_data; /**<Number comparison data, see @ref ble_sec_nc_t. */
197 
198  /**@brief Link Encrypte Request event for @ref BLE_SEC_EVT_LINK_ENC_REQUEST. */
199 typedef struct
200 {
201  ble_sec_enc_req_type_t req_type; /**< Indicate the request type, @ref ble_sec_enc_req_type_t. */
202  ble_sec_enc_req_data_t data; /**< SEC encryption request data, @ref ble_sec_enc_req_data_t. */
204 
205  /**@brief Link Encrypted event for @ref BLE_SEC_EVT_LINK_ENCRYPTED. */
206 typedef struct
207 {
208  uint8_t auth; /**< Auth type. */
210 
211 /**@brief Key Press Notify event for @ref BLE_SEC_EVT_KEY_PRESS_NTF. */
212 typedef struct
213 {
214  ble_sec_keypress_notify_t notify_type; /**< key Press Notify type. */
216 
217 /**@brief Key Missing event for @ref BLE_SEC_EVT_KEY_MISSING. */
218 typedef struct
219 {
220  ble_sec_key_missing_reason_t reason; /**< Keymissing reason. */
222 
223 /**@brief BLE Security event structure. */
224 typedef struct
225 {
226  uint8_t index; /**< Index of connection. */
227  union
228  {
229  ble_sec_evt_enc_req_t enc_req; /**< Link Encrypte Request event. */
230  ble_sec_evt_enc_ind_t enc_ind; /**< Link Encrypted event. */
231  ble_sec_evt_keypress_notify_t keypress_ntf; /**< Key Press Notify event. */
232  ble_sec_evt_key_missing_t key_missing; /**< Key Missing event. */
233  } params; /**< The parameters of sec events. */
234 } ble_sec_evt_t; /**< Event Parameters. */
235 
236 /** @} */
237 
238 /** @addtogroup BLE_SEC_FUNCTIONS Functions
239  * @{ */
240 /**
241  ****************************************************************************************
242  * @brief Set security parameter.
243  *
244 * @param[in] p_sec_param: Pointer to the security parameter structure, @ref ble_sec_param_t.
245  *
246  * @retval ::SDK_SUCCESS: The security parameter is successfully set to the BLE stack.
247  * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
248  * @retval ::SDK_ERR_INVALID_PARAM: Invalid parameter supplied.
249  ****************************************************************************************
250  */
251 uint16_t ble_sec_params_set(ble_sec_param_t *p_sec_param);
252 
253 /**
254  ****************************************************************************************
255  * @brief Start security encryption, this interface is used by both slave and master
256  *
257  * @note If the local device role is master, it will check that if the peer device is bonded firstly. If the peer device is bonded,
258  * the stack will encrypt the link directly, otherwise the stack will send a pair request to the peer device.
259  *
260  * @note If the local device role is slave, the stack will send a security request to the peer device.
261  *
262  * @param[in] conn_idx: ACL connection index, the first ACL connection index is 0, and increased one by one.
263  *
264  * @retval ::SDK_SUCCESS: The security encryption is successfully set to the BLE stack.
265  * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
266  ****************************************************************************************
267  */
268 uint16_t ble_sec_enc_start(uint8_t conn_idx);
269 
270 /**
271  ****************************************************************************************
272  * @brief Send the encrypt confirm information
273  *
274  * @param[in] conn_idx: ACL connection index, the first ACL connection index is 0, and increased one by one.
275  * @param[in] p_cfm_enc: Pointer to the confirm encryption structure, see @ref ble_sec_cfm_enc_t.
276  *
277  * @retval ::SDK_SUCCESS: The confirm encryption is successfully set to the BLE stack.
278  * @retval ::SDK_ERR_POINTER_NULL: Invalid pointer supplied.
279  * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
280  * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
281  ****************************************************************************************
282  */
283 uint16_t ble_sec_enc_cfm(uint8_t conn_idx, const ble_sec_cfm_enc_t *p_cfm_enc);
284 
285 /**
286  ****************************************************************************************
287  * @brief Send key press notify
288  *
289  * @param[in] conn_idx: ACL connection index. The first ACL connection index is 0, and the index will be increased one by one.
290  * @param[in] notify_type: Key press notify type, see @ref ble_sec_keypress_notify_t.
291  *
292  * @retval ::SDK_SUCCESS: The key press notify type is successfully set to the BLE stack.
293  * @retval ::SDK_ERR_INVALID_CONN_IDX: Invalid connection index supplied.
294  * @retval ::SDK_ERR_NO_RESOURCES: Not enough resources.
295  ****************************************************************************************
296  */
297 uint16_t ble_sec_keypress_notify_send(uint8_t conn_idx, uint8_t notify_type);
298 /** @} */
299 
300 #endif
301 
302 /** @} */
303 /** @} */
ble_sec_enc_req_data_t::nc_data
ble_sec_nc_t nc_data
Definition: ble_sec.h:195
BLE_SEC_KEY_PRESS_COMPLETED
@ BLE_SEC_KEY_PRESS_COMPLETED
Definition: ble_sec.h:111
BLE_SEC_BOND_INFO_LOAD_FAILED
@ BLE_SEC_BOND_INFO_LOAD_FAILED
Definition: ble_sec.h:136
ble_sec_cfm_enc_data_t::oob
ble_sec_oob_t oob
Definition: ble_sec.h:173
ble_sec_nc_t
SEC number comparison value.
Definition: ble_sec.h:186
BLE_SEC_KEY_PRESS_CLEARED
@ BLE_SEC_KEY_PRESS_CLEARED
Definition: ble_sec.h:110
BLE_SEC_MODE2_LEVEL1
@ BLE_SEC_MODE2_LEVEL1
Definition: ble_sec.h:121
BLE_SEC_OOB_REQ
@ BLE_SEC_OOB_REQ
Definition: ble_sec.h:100
BLE_SEC_KEY_PRESS_STARTED
@ BLE_SEC_KEY_PRESS_STARTED
Definition: ble_sec.h:107
ble_sec_evt_keypress_notify_t
Key Press Notify event for BLE_SEC_EVT_KEY_PRESS_NTF.
Definition: ble_sec.h:213
ble_sec_evt_enc_req_t::req_type
ble_sec_enc_req_type_t req_type
Definition: ble_sec.h:201
BLE_SEC_TK_OOB
@ BLE_SEC_TK_OOB
Definition: ble_sec.h:128
ble_sec_cfm_enc_data_t::tk
ble_sec_tk_t tk
Definition: ble_sec.h:172
ble_sec_tk_t
TK value.
Definition: ble_sec.h:158
BLE_SEC_TK_KEY_ENTRY
@ BLE_SEC_TK_KEY_ENTRY
Definition: ble_sec.h:130
ble_sec_param_t::io_cap
ble_sec_io_cap_t io_cap
Definition: ble_sec.h:148
ble_sec_param_t::rkey_dist
uint8_t rkey_dist
Definition: ble_sec.h:153
ble_sec_evt_keypress_notify_t::notify_type
ble_sec_keypress_notify_t notify_type
Definition: ble_sec.h:214
ble_sec_param_t::oob
bool oob
Definition: ble_sec.h:149
ble_sec_evt_key_missing_t
Key Missing event for BLE_SEC_EVT_KEY_MISSING.
Definition: ble_sec.h:219
ble_sec_keypress_notify_send
uint16_t ble_sec_keypress_notify_send(uint8_t conn_idx, uint8_t notify_type)
Send key press notify.
ble_sec_cfm_enc_t
SEC Confirm encryption.
Definition: ble_sec.h:178
BLE_SEC_KEY_PRESS_ENTERED
@ BLE_SEC_KEY_PRESS_ENTERED
Definition: ble_sec.h:108
BLE_SEC_TK_DISPLAY
@ BLE_SEC_TK_DISPLAY
Definition: ble_sec.h:129
ble_sec_evt_enc_ind_t::auth
uint8_t auth
Definition: ble_sec.h:208
ble_sec_evt_enc_ind_t
Link Encrypted event for BLE_SEC_EVT_LINK_ENCRYPTED.
Definition: ble_sec.h:207
ble_sec_evt_key_missing_t::reason
ble_sec_key_missing_reason_t reason
Definition: ble_sec.h:220
ble_sec_evt_enc_req_t
Link Encrypte Request event for BLE_SEC_EVT_LINK_ENC_REQUEST.
Definition: ble_sec.h:200
ble_sec_enc_req_data_t::tk_type
ble_sec_tk_type_t tk_type
Definition: ble_sec.h:193
BLE_SEC_MODE1_LEVEL1
@ BLE_SEC_MODE1_LEVEL1
Definition: ble_sec.h:117
ble_sec_cfm_enc_t::data
ble_sec_cfm_enc_data_t data
Definition: ble_sec.h:181
ble_sec_enc_req_data_t
SEC encryption request data.
Definition: ble_sec.h:192
ble_error.h
File that contains error codes.
BLE_SEC_MODE1_LEVEL2
@ BLE_SEC_MODE1_LEVEL2
Definition: ble_sec.h:118
BLE_SEC_KEY_PRESS_ERASED
@ BLE_SEC_KEY_PRESS_ERASED
Definition: ble_sec.h:109
ble_sec_evt_t::enc_req
ble_sec_evt_enc_req_t enc_req
Definition: ble_sec.h:229
ble_sec_enc_cfm
uint16_t ble_sec_enc_cfm(uint8_t conn_idx, const ble_sec_cfm_enc_t *p_cfm_enc)
Send the encrypt confirm information.
ble_sec_cfm_enc_t::accept
bool accept
Definition: ble_sec.h:180
BLE_SEC_IO_DISPLAY_ONLY
@ BLE_SEC_IO_DISPLAY_ONLY
Definition: ble_sec.h:86
ble_sec_param_t::key_size
uint8_t key_size
Definition: ble_sec.h:151
BLE_SEC_MODE1_LEVEL3
@ BLE_SEC_MODE1_LEVEL3
Definition: ble_sec.h:119
ble_sec_mode_level_t
ble_sec_mode_level_t
SEC mode and level.
Definition: ble_sec.h:116
ble_sec_evt_enc_req_t::data
ble_sec_enc_req_data_t data
Definition: ble_sec.h:202
ble_sec_cfm_enc_t::req_type
ble_sec_enc_req_type_t req_type
Definition: ble_sec.h:179
ble_sec_tk_type_t
ble_sec_tk_type_t
SEC TK type.
Definition: ble_sec.h:127
BLE_SEC_TK_REQ
@ BLE_SEC_TK_REQ
Definition: ble_sec.h:99
BLE_SEC_IO_NO_INPUT_NO_OUTPUT
@ BLE_SEC_IO_NO_INPUT_NO_OUTPUT
Definition: ble_sec.h:89
ble_sec_keypress_notify_t
ble_sec_keypress_notify_t
SEC Key Press Notify.
Definition: ble_sec.h:106
BLE_SEC_NC_REQ
@ BLE_SEC_NC_REQ
Definition: ble_sec.h:101
ble_sec_enc_start
uint16_t ble_sec_enc_start(uint8_t conn_idx)
Start security encryption, this interface is used by both slave and master.
ble_sec_enc_req_data_t::oob_data
ble_sec_oob_t oob_data
Definition: ble_sec.h:194
ble_sec_key_missing_reason_t
ble_sec_key_missing_reason_t
Key missing reason.
Definition: ble_sec.h:135
BLE_SEC_IO_KEYBOARD_DISPLAY
@ BLE_SEC_IO_KEYBOARD_DISPLAY
Definition: ble_sec.h:90
BLE_SEC_LTK_VALID_MASK_ERR
@ BLE_SEC_LTK_VALID_MASK_ERR
Definition: ble_sec.h:137
ble_sec_cfm_enc_data_t
SEC Confirm encryption data.
Definition: ble_sec.h:171
BLE_SEC_MODE2_LEVEL2
@ BLE_SEC_MODE2_LEVEL2
Definition: ble_sec.h:122
BLE_SEC_IO_KEYBOARD_ONLY
@ BLE_SEC_IO_KEYBOARD_ONLY
Definition: ble_sec.h:88
ble_sec_evt_t::enc_ind
ble_sec_evt_enc_ind_t enc_ind
Definition: ble_sec.h:230
BLE_SEC_PAIR_REQ
@ BLE_SEC_PAIR_REQ
Definition: ble_sec.h:98
BLE_SEC_IO_DISPLAY_YES_NO
@ BLE_SEC_IO_DISPLAY_YES_NO
Definition: ble_sec.h:87
ble_sec_io_cap_t
ble_sec_io_cap_t
SEC IO Capability.
Definition: ble_sec.h:85
ble_sec_evt_t::index
uint8_t index
Definition: ble_sec.h:226
BLE_SEC_EDIV_RAND_VALUE_ERR
@ BLE_SEC_EDIV_RAND_VALUE_ERR
Definition: ble_sec.h:138
ble_sec_param_t
SEC Parameter.
Definition: ble_sec.h:146
ble_sec_evt_t::keypress_ntf
ble_sec_evt_keypress_notify_t keypress_ntf
Definition: ble_sec.h:231
ble_sec_param_t::ikey_dist
uint8_t ikey_dist
Definition: ble_sec.h:152
ble_sec_params_set
uint16_t ble_sec_params_set(ble_sec_param_t *p_sec_param)
Set security parameter.
BLE_SEC_MODE1_LEVEL4
@ BLE_SEC_MODE1_LEVEL4
Definition: ble_sec.h:120
ble_sec_param_t::auth
uint8_t auth
Definition: ble_sec.h:150
ble_sec_evt_t
BLE Security event structure.
Definition: ble_sec.h:225
ble_sec_enc_req_type_t
ble_sec_enc_req_type_t
SEC Encryption Request Type.
Definition: ble_sec.h:97
ble_sec_evt_t::key_missing
ble_sec_evt_key_missing_t key_missing
Definition: ble_sec.h:232
ble_sec_param_t::level
ble_sec_mode_level_t level
Definition: ble_sec.h:147
ble_sec_oob_t
SEC OOB value.
Definition: ble_sec.h:164