Mistake on this page?
Report an issue in GitHub or email us
smp_api.h
Go to the documentation of this file.
1 /*************************************************************************************************/
2 /*!
3  * \file
4  *
5  * \brief SMP subsystem API.
6  *
7  * Copyright (c) 2010-2019 Arm Ltd. All Rights Reserved.
8  *
9  * Copyright (c) 2019-2020 Packetcraft, Inc.
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 /*************************************************************************************************/
24 #ifndef SMP_API_H
25 #define SMP_API_H
26 
27 #include "wsf_os.h"
28 #include "smp_defs.h"
29 #include "dm_api.h"
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
35 /*! \addtogroup STACK_SMP_API
36  * \{ */
37 
38 /**************************************************************************************************
39  Macros
40 **************************************************************************************************/
41 
42 /** \name SMP Events
43  * Events recognized and handled by the SMP state machine.
44  */
45 /**@{*/
46 /*! \brief Event handler messages for SMP state machines */
47 enum
48 {
49  SMP_MSG_API_PAIR_REQ = 1, /*!< \brief API pairing request */
50  SMP_MSG_API_PAIR_RSP, /*!< \brief API pairing response */
51  SMP_MSG_API_CANCEL_REQ, /*!< \brief API cancel request */
52  SMP_MSG_API_AUTH_RSP, /*!< \brief API pin response */
53  SMP_MSG_API_SECURITY_REQ, /*!< \brief API security request */
54  SMP_MSG_CMD_PKT, /*!< \brief SMP command packet received */
55  SMP_MSG_CMD_PAIRING_FAILED, /*!< \brief SMP pairing failed packet received */
56  SMP_MSG_DM_ENCRYPT_CMPL, /*!< \brief Link encrypted */
57  SMP_MSG_DM_ENCRYPT_FAILED, /*!< \brief Link encryption failed */
58  SMP_MSG_DM_CONN_CLOSE, /*!< \brief Connection closed */
59  SMP_MSG_WSF_AES_CMPL, /*!< \brief AES calculation complete */
60  SMP_MSG_INT_SEND_NEXT_KEY, /*!< \brief Send next key to be distributed */
61  SMP_MSG_INT_MAX_ATTEMPTS, /*!< \brief Maximum pairing attempts reached */
62  SMP_MSG_INT_PAIRING_CMPL, /*!< \brief Pairing complete */
63  SMP_MSG_INT_RSP_TIMEOUT, /*!< \brief Pairing protocol response timeout */
64  SMP_MSG_INT_WI_TIMEOUT, /*!< \brief Pairing protocol wait interval timeout */
65  SMP_MSG_INT_LESC, /*!< \brief Pair with Secure Connections */
66  SMP_MSG_INT_LEGACY, /*!< \brief Pair with Legacy Security */
67  SMP_MSG_INT_JW_NC, /*!< \brief LESC Just-Works/Numeric Comparison pairing */
68  SMP_MSG_INT_PASSKEY, /*!< \brief LESC Passkey pairing */
69  SMP_MSG_INT_OOB, /*!< \brief LESC Out-of-Band Pairing */
70  SMP_MSG_API_USER_CONFIRM, /*!< \brief User confirms valid numeric comparison */
71  SMP_MSG_API_USER_KEYPRESS, /*!< \brief User keypress in passkey pairing */
72  SMP_MSG_API_KEYPRESS_CMPL, /*!< \brief User keypress complete in passkey pairing */
73  SMP_MSG_WSF_ECC_CMPL, /*!< \brief WSF ECC operation complete */
74  SMP_MSG_INT_PK_NEXT, /*!< \brief Continue to next passkey bit */
75  SMP_MSG_INT_PK_CMPL, /*!< \brief Passkey operation complete */
76  SMP_MSG_WSF_CMAC_CMPL, /*!< \brief WSF CMAC operation complete */
77  SMP_MSG_DH_CHECK_FAILURE, /*!< \brief DHKey check failure */
78  SMP_MSG_EARLY_CNF, /*!< \brief An early Confirm from the initiator in passkey pairing */
79  SMP_MSG_INT_CLEANUP, /*!< \brief Cleanup control information and return to IDLE state */
80  SMP_NUM_MSGS /*!< \brief Number of SMP message types. */
81 };
82 /**@}*/
83 
84 /**@{*/
85 /*! \brief Additional SMP messages */
86 enum
87 {
88  SMP_DB_SERVICE_IND = SMP_NUM_MSGS /*!< \brief SMP DB Service timer indication */
89 };
90 /**@}*/
91 
92 /**************************************************************************************************
93  Data Types
94 **************************************************************************************************/
95 
96 /*! \brief Configurable parameters */
97 typedef struct
98 {
99  uint32_t attemptTimeout; /*!< \brief 'Repeated attempts' timeout in msec */
100  uint8_t ioCap; /*!< \brief I/O Capability */
101  uint8_t minKeyLen; /*!< \brief Minimum encryption key length */
102  uint8_t maxKeyLen; /*!< \brief Maximum encryption key length */
103  uint8_t maxAttempts; /*!< \brief Attempts to trigger 'repeated attempts' timeout */
104  uint8_t auth; /*!< \brief Device authentication requirements */
105  uint32_t maxAttemptTimeout; /*!< \brief Maximum 'Repeated attempts' timeout in msec */
106  uint32_t attemptDecTimeout; /*!< \brief Time msec before attemptExp decreases */
107  uint16_t attemptExp; /*!< \brief Exponent to raise attemptTimeout on maxAttempts */
108 } smpCfg_t;
109 
110 /*! \brief Data type for SMP_MSG_API_PAIR_REQ and SMP_MSG_API_PAIR_RSP */
111 typedef struct
112 {
113  wsfMsgHdr_t hdr; /*!< \brief Message header */
114  uint8_t oob; /*!< \brief Out-of-band data present flag */
115  uint8_t auth; /*!< \brief authentication flags */
116  uint8_t iKeyDist; /*!< \brief Initiator key distribution flags */
117  uint8_t rKeyDist; /*!< \brief Responder key distribution flags */
118 } smpDmPair_t;
119 
120 /*! \brief Data type for SMP_MSG_API_AUTH_RSP */
121 typedef struct
122 {
123  wsfMsgHdr_t hdr; /*!< \brief Message header */
124  uint8_t authData[SMP_OOB_LEN]; /*!< \brief Authentication data to display */
125  uint8_t authDataLen; /*!< \brief Length of authentication data */
127 
128 /*! \brief Data type for SMP_MSG_API_USER_KEYPRESS */
129 typedef struct
130 {
131  wsfMsgHdr_t hdr; /*!< \brief Message header */
132  uint8_t keypress; /*!< \brief Keypress */
134 
135 /*! \brief Data type for SMP_MSG_API_SECURITY_REQ */
136 typedef struct
137 {
138  wsfMsgHdr_t hdr; /*!< \brief Message header */
139  uint8_t auth; /*!< \brief Authentication flags */
141 
142 /*! \brief Union SMP DM message data types */
143 typedef union
144 {
145  wsfMsgHdr_t hdr; /*!< \brief Message header */
146  smpDmPair_t pair; /*!< \brief Pairing request/response message */
147  smpDmAuthRsp_t authRsp; /*!< \brief Authentication message */
148  smpDmSecurityReq_t securityReq; /*!< \brief Security Request message */
149  smpDmKeypress_t keypress; /*!< \brief Keypress message */
150 } smpDmMsg_t;
151 
152 /*! \} */ /* STACK_SMP_API */
153 
154 /**************************************************************************************************
155  Global Variables;
156 **************************************************************************************************/
157 
158 /*! \addtogroup STACK_INIT
159  * \{ */
160 
161 /** \name SMP Configuration Structure
162  * Pointer to structure containing initialization details of the SMP Subsystem. To be configured
163  * by Application.
164  */
165 /**@{*/
166 /*! \brief Configuration pointer */
167 extern smpCfg_t *pSmpCfg;
168 /**@}*/
169 
170 /*! \} */ /* STACK_INIT */
171 
172 /**************************************************************************************************
173  Function Declarations
174 **************************************************************************************************/
175 
176 /*! \addtogroup STACK_SMP_API
177  * \{ */
178 
179 /** \name SMP Initialization Functions
180  * Legacy and Secure Connections initialization for Initiator and Responder roles.
181  */
182 /**@{*/
183 
184 /*************************************************************************************************/
185 /*!
186  * \brief Initialize SMP initiator role.
187  *
188  * \return None.
189  */
190 /*************************************************************************************************/
191 void SmpiInit(void);
192 
193 /*************************************************************************************************/
194 /*!
195  * \brief Initialize SMP responder role.
196  *
197  * \return None.
198  */
199 /*************************************************************************************************/
200 void SmprInit(void);
201 
202 /*************************************************************************************************/
203 /*!
204  * \brief Initialize SMP initiator role utilizing BTLE Secure Connections.
205  *
206  * \return None.
207  */
208 /*************************************************************************************************/
209 void SmpiScInit(void);
210 
211 /*************************************************************************************************/
212 /*!
213  * \brief Initialize SMP responder role utilizing BTLE Secure Connections.
214  *
215  * \return None.
216  */
217 /*************************************************************************************************/
218 void SmprScInit(void);
219 
220 /*************************************************************************************************/
221 /*!
222  * \brief Use this SMP init function when SMP is not supported.
223  *
224  * \return None.
225  */
226 /*************************************************************************************************/
227 void SmpNonInit(void);
228 
229 /**@}*/
230 
231 /** \name SMP DM Interface Functions
232  * Functions that allow the DM to send messages to SMP.
233  */
234 /**@{*/
235 
236 /*************************************************************************************************/
237 /*!
238  * \brief This function is called by DM to send a message to SMP.
239  *
240  * \param pMsg Pointer to message structure.
241  *
242  * \return None.
243  */
244 /*************************************************************************************************/
245 void SmpDmMsgSend(smpDmMsg_t *pMsg);
246 
247 /*************************************************************************************************/
248 /*!
249  * \brief This function is called by DM to notify SMP of encrypted link status.
250  *
251  * \param pMsg Pointer to HCI message structure.
252  *
253  * \return None.
254  */
255 /*************************************************************************************************/
256 void SmpDmEncryptInd(wsfMsgHdr_t *pMsg);
257 
258 /*************************************************************************************************/
259 /*!
260  * \brief Check if LE Secure Connections is enabled on the connection.
261  *
262  * \param connId Connection identifier.
263  *
264  * \return TRUE is Secure Connections is enabled, else FALSE
265  */
266 /*************************************************************************************************/
267 bool_t SmpDmLescEnabled(dmConnId_t connId);
268 
269 /*************************************************************************************************/
270 /*!
271  * \brief Return the STK for the given connection.
272  *
273  * \param connId Connection identifier.
274  * \param pSecLevel Returns the security level of pairing when STK was created.
275  *
276  * \return Pointer to STK or NULL if not available.
277  */
278 /*************************************************************************************************/
279 uint8_t *SmpDmGetStk(dmConnId_t connId, uint8_t *pSecLevel);
280 
281 /*************************************************************************************************/
282 /*!
283  * \brief Format a cancel message with consideration for the attempts counter
284  *
285  * \param connId Connection Id.
286  * \param pHdr Pointer to header of message to fill.
287  * \param status Status to include.
288  *
289  * \return none.
290  */
291 /*************************************************************************************************/
292 void SmpScGetCancelMsgWithReattempt(dmConnId_t connId, wsfMsgHdr_t *pHdr, uint8_t status);
293 
294 /*************************************************************************************************/
295 /*!
296  * \brief Initialize the SMP Database.
297  *
298  * \return None.
299  */
300 /*************************************************************************************************/
301 void SmpDbInit(void);
302 
303 /*************************************************************************************************/
304 /*!
305  * \brief Called to force the DhKey to zero for qualification test purposes.
306  *
307  * \param enable TRUE - Force DhKey to zero. FALSE - Use calculated key
308  *
309  * \return None.
310  */
311 /*************************************************************************************************/
312 void SmpScEnableZeroDhKey(bool_t enable);
313 
314 /**@}*/
315 
316 /*! \} */ /* STACK_SMP_API */
317 
318 #ifdef __cplusplus
319 };
320 #endif
321 
322 #endif /* SMP_API_H */
void SmpDmMsgSend(smpDmMsg_t *pMsg)
This function is called by DM to send a message to SMP.
uint8_t * SmpDmGetStk(dmConnId_t connId, uint8_t *pSecLevel)
Return the STK for the given connection.
API cancel request.
Definition: smp_api.h:51
Pair with Secure Connections.
Definition: smp_api.h:65
An early Confirm from the initiator in passkey pairing.
Definition: smp_api.h:78
smpDmKeypress_t keypress
Keypress message.
Definition: smp_api.h:149
uint8_t dmConnId_t
Connection identifier.
Definition: dm_api.h:588
smpDmSecurityReq_t securityReq
Security Request message.
Definition: smp_api.h:148
uint8_t keypress
Keypress.
Definition: smp_api.h:132
Number of SMP message types.
Definition: smp_api.h:80
wsfMsgHdr_t hdr
Message header.
Definition: smp_api.h:131
SMP command packet received.
Definition: smp_api.h:54
Maximum pairing attempts reached.
Definition: smp_api.h:61
Link encrypted.
Definition: smp_api.h:56
Data type for SMP_MSG_API_AUTH_RSP.
Definition: smp_api.h:121
uint8_t minKeyLen
Minimum encryption key length.
Definition: smp_api.h:101
void SmprScInit(void)
Initialize SMP responder role utilizing BTLE Secure Connections.
smpDmPair_t pair
Pairing request/response message.
Definition: smp_api.h:146
wsfMsgHdr_t hdr
Message header.
Definition: smp_api.h:138
uint32_t maxAttemptTimeout
Maximum &#39;Repeated attempts&#39; timeout in msec.
Definition: smp_api.h:105
void SmpScEnableZeroDhKey(bool_t enable)
Called to force the DhKey to zero for qualification test purposes.
wsfMsgHdr_t hdr
Message header.
Definition: smp_api.h:145
API security request.
Definition: smp_api.h:53
bool_t SmpDmLescEnabled(dmConnId_t connId)
Check if LE Secure Connections is enabled on the connection.
Pair with Legacy Security.
Definition: smp_api.h:66
void SmpiScInit(void)
Initialize SMP initiator role utilizing BTLE Secure Connections.
WSF CMAC operation complete.
Definition: smp_api.h:76
Data type for SMP_MSG_API_USER_KEYPRESS.
Definition: smp_api.h:129
API pairing request.
Definition: smp_api.h:49
User keypress in passkey pairing.
Definition: smp_api.h:71
SMP DB Service timer indication.
Definition: smp_api.h:88
uint8_t ioCap
I/O Capability.
Definition: smp_api.h:100
wsfMsgHdr_t hdr
Message header.
Definition: smp_api.h:113
API pairing response.
Definition: smp_api.h:50
Data type for SMP_MSG_API_PAIR_REQ and SMP_MSG_API_PAIR_RSP.
Definition: smp_api.h:111
LESC Out-of-Band Pairing.
Definition: smp_api.h:69
uint8_t maxAttempts
Attempts to trigger &#39;repeated attempts&#39; timeout.
Definition: smp_api.h:103
uint8_t auth
authentication flags
Definition: smp_api.h:115
Send next key to be distributed.
Definition: smp_api.h:60
Link encryption failed.
Definition: smp_api.h:57
uint16_t attemptExp
Exponent to raise attemptTimeout on maxAttempts.
Definition: smp_api.h:107
smpDmAuthRsp_t authRsp
Authentication message.
Definition: smp_api.h:147
LESC Just-Works/Numeric Comparison pairing.
Definition: smp_api.h:67
SMP pairing failed packet received.
Definition: smp_api.h:55
User confirms valid numeric comparison.
Definition: smp_api.h:70
Data type for SMP_MSG_API_SECURITY_REQ.
Definition: smp_api.h:136
Connection closed.
Definition: smp_api.h:58
uint32_t attemptDecTimeout
Time msec before attemptExp decreases.
Definition: smp_api.h:106
API pin response.
Definition: smp_api.h:52
uint8_t maxKeyLen
Maximum encryption key length.
Definition: smp_api.h:102
uint32_t attemptTimeout
&#39;Repeated attempts&#39; timeout in msec
Definition: smp_api.h:99
Security manager constants and definitions from the Bluetooth specification.
WSF ECC operation complete.
Definition: smp_api.h:73
LESC Passkey pairing.
Definition: smp_api.h:68
void SmpNonInit(void)
Use this SMP init function when SMP is not supported.
void SmpDmEncryptInd(wsfMsgHdr_t *pMsg)
This function is called by DM to notify SMP of encrypted link status.
uint8_t oob
Out-of-band data present flag.
Definition: smp_api.h:114
Device Manager subsystem API.
wsfMsgHdr_t hdr
Message header.
Definition: smp_api.h:123
Passkey operation complete.
Definition: smp_api.h:75
uint8_t auth
Authentication flags.
Definition: smp_api.h:139
DHKey check failure.
Definition: smp_api.h:77
AES calculation complete.
Definition: smp_api.h:59
void SmprInit(void)
Initialize SMP responder role.
void SmpDbInit(void)
Initialize the SMP Database.
User keypress complete in passkey pairing.
Definition: smp_api.h:72
#define SMP_OOB_LEN
OOB Data length in bytes.
Definition: smp_defs.h:52
uint8_t rKeyDist
Responder key distribution flags.
Definition: smp_api.h:117
Configurable parameters.
Definition: smp_api.h:97
Cleanup control information and return to IDLE state.
Definition: smp_api.h:79
Union SMP DM message data types.
Definition: smp_api.h:143
void SmpScGetCancelMsgWithReattempt(dmConnId_t connId, wsfMsgHdr_t *pHdr, uint8_t status)
Format a cancel message with consideration for the attempts counter.
uint8_t authDataLen
Length of authentication data.
Definition: smp_api.h:125
Software foundation OS API.
void SmpiInit(void)
Initialize SMP initiator role.
Common message structure passed to event handler.
Definition: wsf_os.h:106
smpCfg_t * pSmpCfg
Configuration pointer.
Pairing complete.
Definition: smp_api.h:62
Continue to next passkey bit.
Definition: smp_api.h:74
Pairing protocol response timeout.
Definition: smp_api.h:63
Pairing protocol wait interval timeout.
Definition: smp_api.h:64
uint8_t iKeyDist
Initiator key distribution flags.
Definition: smp_api.h:116
uint8_t auth
Device authentication requirements.
Definition: smp_api.h:104
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.