Cordio Stack and Cordio Profiles  r2p3-02rel0
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_TIMEOUT, /*!< \brief Pairing protocol timeout */
59  SMP_MSG_INT_LESC, /*!< \brief Pair with Secure Connections */
60  SMP_MSG_INT_LEGACY, /*!< \brief Pair with Legacy Security */
61  SMP_MSG_INT_JW_NC, /*!< \brief LESC Just-Works/Numeric Comparison pairing */
62  SMP_MSG_INT_PASSKEY, /*!< \brief LESC Passkey pairing */
63  SMP_MSG_INT_OOB, /*!< \brief LESC Out-of-Band Pairing */
64  SMP_MSG_API_USER_CONFIRM, /*!< \brief User confirms valid numeric comparison */
65  SMP_MSG_API_USER_KEYPRESS, /*!< \brief User keypress in passkey pairing */
66  SMP_MSG_API_KEYPRESS_CMPL, /*!< \brief User keypress complete in passkey pairing */
67  SMP_MSG_WSF_ECC_CMPL, /*!< \brief WSF ECC operation complete */
68  SMP_MSG_INT_PK_NEXT, /*!< \brief Continue to next passkey bit */
69  SMP_MSG_INT_PK_CMPL, /*!< \brief Passkey operation complete */
70  SMP_MSG_WSF_CMAC_CMPL, /*!< \brief WSF CMAC operation complete */
71  SMP_MSG_DH_CHECK_FAILURE, /*!< \brief WSF CMAC operation complete */
72  SMP_MSG_EARLY_CNF, /*!< \brief An early Confirm from the initiator in passkey pairing */
73  SMP_NUM_MSGS /*!< \brief Number of SMP message types. */
74 };
75 /**@}*/
76 
77 /**************************************************************************************************
78  Data Types
79 **************************************************************************************************/
80 
81 /*! \brief Configurable parameters */
82 typedef struct
83 {
84  uint16_t attemptTimeout; /*!< \brief 'Repeated attempts' timeout in msec */
85  uint8_t ioCap; /*!< \brief I/O Capability */
86  uint8_t minKeyLen; /*!< \brief Minimum encryption key length */
87  uint8_t maxKeyLen; /*!< \brief Maximum encryption key length */
88  uint8_t maxAttempts; /*!< \brief Attempts to trigger 'repeated attempts' timeout */
89  uint8_t auth; /*!< \brief Device authentication requirements */
90 } smpCfg_t;
91 
92 /*! \brief Data type for SMP_MSG_API_PAIR_REQ and SMP_MSG_API_PAIR_RSP */
93 typedef struct
94 {
95  wsfMsgHdr_t hdr; /*!< \brief Message header */
96  uint8_t oob; /*!< \brief Out-of-band data present flag */
97  uint8_t auth; /*!< \brief authentication flags */
98  uint8_t iKeyDist; /*!< \brief Initiator key distribution flags */
99  uint8_t rKeyDist; /*!< \brief Responder key distribution flags */
100 } smpDmPair_t;
101 
102 /*! \brief Data type for SMP_MSG_API_AUTH_RSP */
103 typedef struct
104 {
105  wsfMsgHdr_t hdr; /*!< \brief Message header */
106  uint8_t authData[SMP_OOB_LEN]; /*!< \brief Authentication data to display */
107  uint8_t authDataLen; /*!< \brief Length of authentication data */
109 
110 /*! \brief Data type for SMP_MSG_API_USER_KEYPRESS */
111 typedef struct
112 {
113  wsfMsgHdr_t hdr; /*!< \brief Message header */
114  uint8_t keypress; /*!< \brief Keypress */
116 
117 /*! \brief Data type for SMP_MSG_API_SECURITY_REQ */
118 typedef struct
119 {
120  wsfMsgHdr_t hdr; /*!< \brief Message header */
121  uint8_t auth; /*!< \brief Authentication flags */
123 
124 /*! \brief Union SMP DM message data types */
125 typedef union
126 {
127  wsfMsgHdr_t hdr; /*!< \brief Message header */
128  smpDmPair_t pair; /*!< \brief Pairing request/response message */
129  smpDmAuthRsp_t authRsp; /*!< \brief Authentication message */
130  smpDmSecurityReq_t securityReq; /*!< \brief Security Request message */
131  smpDmKeypress_t keypress; /*!< \brief Keypress message */
132 } smpDmMsg_t;
133 
134 /*! \} */ /* STACK_SMP_API */
135 
136 /**************************************************************************************************
137  Global Variables;
138 **************************************************************************************************/
139 
140 /*! \addtogroup STACK_INIT
141  * \{ */
142 
143 /** \name SMP Configuration Structure
144  * Pointer to structure containing initialization details of the SMP Subsystem. To be configured
145  * by Application.
146  */
147 /**@{*/
148 /*! \brief Configuration pointer */
149 extern smpCfg_t *pSmpCfg;
150 /**@}*/
151 
152 /*! \} */ /* STACK_INIT */
153 
154 /**************************************************************************************************
155  Function Declarations
156 **************************************************************************************************/
157 
158 /*! \addtogroup STACK_SMP_API
159  * \{ */
160 
161 /** \name SMP Initialization Functions
162  * Legacy and Secure Connections initialization for Initiator and Responder roles.
163  */
164 /**@{*/
165 
166 /*************************************************************************************************/
167 /*!
168  * \brief Initialize SMP initiator role.
169  *
170  * \return None.
171  */
172 /*************************************************************************************************/
173 void SmpiInit(void);
174 
175 /*************************************************************************************************/
176 /*!
177  * \brief Initialize SMP responder role.
178  *
179  * \return None.
180  */
181 /*************************************************************************************************/
182 void SmprInit(void);
183 
184 /*************************************************************************************************/
185 /*!
186  * \brief Initialize SMP initiator role utilizing BTLE Secure Connections.
187  *
188  * \return None.
189  */
190 /*************************************************************************************************/
191 void SmpiScInit(void);
192 
193 /*************************************************************************************************/
194 /*!
195  * \brief Initialize SMP responder role utilizing BTLE Secure Connections.
196  *
197  * \return None.
198  */
199 /*************************************************************************************************/
200 void SmprScInit(void);
201 
202 /*************************************************************************************************/
203 /*!
204  * \brief Use this SMP init function when SMP is not supported.
205  *
206  * \return None.
207  */
208 /*************************************************************************************************/
209 void SmpNonInit(void);
210 
211 /**@}*/
212 
213 /** \name SMP DM Interface Functions
214  * Functions that allow the DM to send messages to SMP.
215  */
216 /**@{*/
217 
218 /*************************************************************************************************/
219 /*!
220  * \brief This function is called by DM to send a message to SMP.
221  *
222  * \param pMsg Pointer to message structure.
223  *
224  * \return None.
225  */
226 /*************************************************************************************************/
227 void SmpDmMsgSend(smpDmMsg_t *pMsg);
228 
229 /*************************************************************************************************/
230 /*!
231  * \brief This function is called by DM to notify SMP of encrypted link status.
232  *
233  * \param pMsg Pointer to HCI message structure.
234  *
235  * \return None.
236  */
237 /*************************************************************************************************/
238 void SmpDmEncryptInd(wsfMsgHdr_t *pMsg);
239 
240 /*************************************************************************************************/
241 /*!
242  * \brief Return the STK for the given connection.
243  *
244  * \param connId Connection identifier.
245  * \param pSecLevel Returns the security level of pairing when STK was created.
246  *
247  * \return Pointer to STK or NULL if not available.
248  */
249 /*************************************************************************************************/
250 uint8_t *SmpDmGetStk(dmConnId_t connId, uint8_t *pSecLevel);
251 
252 /**@}*/
253 
254 /*! \} */ /* STACK_SMP_API */
255 
256 #ifdef __cplusplus
257 };
258 #endif
259 
260 #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.
Link encryption failed.
Definition: smp_api.h:52
uint8_t dmConnId_t
Connection identifier.
Definition: dm_api.h:501
uint8_t oob
Out-of-band data present flag.
Definition: smp_api.h:96
smpDmKeypress_t keypress
Keypress message.
Definition: smp_api.h:131
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:89
Continue to next passkey bit.
Definition: smp_api.h:68
Data type for SMP_MSG_API_AUTH_RSP.
Definition: smp_api.h:103
LESC Just-Works/Numeric Comparison pairing.
Definition: smp_api.h:61
void SmprScInit(void)
Initialize SMP responder role utilizing BTLE Secure Connections.
smpDmPair_t pair
Pairing request/response message.
Definition: smp_api.h:128
LESC Out-of-Band Pairing.
Definition: smp_api.h:63
wsfMsgHdr_t hdr
Message header.
Definition: smp_api.h:95
User keypress in passkey pairing.
Definition: smp_api.h:65
An early Confirm from the initiator in passkey pairing.
Definition: smp_api.h:72
API cancel request.
Definition: smp_api.h:46
smpDmSecurityReq_t securityReq
Security Request message.
Definition: smp_api.h:130
LESC Passkey pairing.
Definition: smp_api.h:62
User confirms valid numeric comparison.
Definition: smp_api.h:64
wsfMsgHdr_t hdr
Message header.
Definition: smp_api.h:120
void SmpiScInit(void)
Initialize SMP initiator role utilizing BTLE Secure Connections.
uint8_t minKeyLen
Minimum encryption key length.
Definition: smp_api.h:86
Data type for SMP_MSG_API_USER_KEYPRESS.
Definition: smp_api.h:111
AES calculation complete.
Definition: smp_api.h:54
wsfMsgHdr_t hdr
Message header.
Definition: smp_api.h:127
uint8_t ioCap
I/O Capability.
Definition: smp_api.h:85
uint8_t maxAttempts
Attempts to trigger &#39;repeated attempts&#39; timeout.
Definition: smp_api.h:88
WSF CMAC operation complete.
Definition: smp_api.h:70
Data type for SMP_MSG_API_PAIR_REQ and SMP_MSG_API_PAIR_RSP.
Definition: smp_api.h:93
Maximum pairing attempts reached.
Definition: smp_api.h:56
WSF ECC operation complete.
Definition: smp_api.h:67
wsfMsgHdr_t hdr
Message header.
Definition: smp_api.h:105
Passkey operation complete.
Definition: smp_api.h:69
Data type for SMP_MSG_API_SECURITY_REQ.
Definition: smp_api.h:118
wsfMsgHdr_t hdr
Message header.
Definition: smp_api.h:113
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
uint16_t attemptTimeout
&#39;Repeated attempts&#39; timeout in msec
Definition: smp_api.h:84
uint8_t rKeyDist
Responder key distribution flags.
Definition: smp_api.h:99
Security manager constants and definitions from the Bluetooth specification.
User keypress complete in passkey pairing.
Definition: smp_api.h:66
uint8_t maxKeyLen
Maximum encryption key length.
Definition: smp_api.h:87
Connection closed.
Definition: smp_api.h:53
void SmpNonInit(void)
Use this SMP init function when SMP is not supported.
Pairing protocol timeout.
Definition: smp_api.h:58
void SmpDmEncryptInd(wsfMsgHdr_t *pMsg)
This function is called by DM to notify SMP of encrypted link status.
uint8_t authDataLen
Length of authentication data.
Definition: smp_api.h:107
Device Manager subsystem API.
uint8_t keypress
Keypress.
Definition: smp_api.h:114
SMP pairing failed packet received.
Definition: smp_api.h:50
unsigned short uint16_t
Unsigned 16-bit value.
Definition: wsf_types.h:67
uint8_t auth
Authentication flags.
Definition: smp_api.h:121
smpDmAuthRsp_t authRsp
Authentication message.
Definition: smp_api.h:129
void SmprInit(void)
Initialize SMP responder role.
#define SMP_OOB_LEN
OOB Data length in bytes.
Definition: smp_defs.h:47
Pair with Legacy Security.
Definition: smp_api.h:60
Configurable parameters.
Definition: smp_api.h:82
Union SMP DM message data types.
Definition: smp_api.h:125
uint8_t iKeyDist
Initiator key distribution flags.
Definition: smp_api.h:98
WSF CMAC operation complete.
Definition: smp_api.h:71
Software foundation OS API.
void SmpiInit(void)
Initialize SMP initiator role.
Common message structure passed to event handler.
Definition: wsf_os.h:97
smpCfg_t * pSmpCfg
Configuration pointer.
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:73
Pair with Secure Connections.
Definition: smp_api.h:59
Pairing complete.
Definition: smp_api.h:57
unsigned char uint8_t
Unsigned 8-bit value.
Definition: wsf_types.h:63
uint8_t auth
authentication flags
Definition: smp_api.h:97