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