smp_api.h revision 444a8da807abaf5f9e813ce70c56a79160495fb3 
1/******************************************************************************
2 *
3 *  Copyright (C) 1999-2012 Broadcom Corporation
4 *
5 *  Licensed under the Apache License, Version 2.0 (the "License");
6 *  you may not use this file except in compliance with the License.
7 *  You may obtain a copy of the License at:
8 *
9 *  http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *  Unless required by applicable law or agreed to in writing, software
12 *  distributed under the License is distributed on an "AS IS" BASIS,
13 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *  See the License for the specific language governing permissions and
15 *  limitations under the License.
16 *
17 ******************************************************************************/
18
19/******************************************************************************
20 *
21 *  This file contains the SMP API function external definitions.
22 *
23 ******************************************************************************/
24#ifndef SMP_API_H
25#define SMP_API_H
26
27#include "bt_target.h"
28
29#define SMP_PIN_CODE_LEN_MAX    PIN_CODE_LEN
30#define SMP_PIN_CODE_LEN_MIN    6
31
32#if BLE_INCLUDED == TRUE && SMP_INCLUDED == TRUE
33/* SMP command code */
34#define SMP_OPCODE_PAIRING_REQ            0x01
35#define SMP_OPCODE_PAIRING_RSP            0x02
36#define SMP_OPCODE_CONFIRM                0x03
37#define SMP_OPCODE_RAND                   0x04
38#define SMP_OPCODE_PAIRING_FAILED         0x05
39#define SMP_OPCODE_ENCRYPT_INFO           0x06
40#define SMP_OPCODE_MASTER_ID              0x07
41#define SMP_OPCODE_IDENTITY_INFO          0x08
42#define SMP_OPCODE_ID_ADDR                0x09
43#define SMP_OPCODE_SIGN_INFO              0x0A
44#define SMP_OPCODE_SEC_REQ                0x0B
45#define SMP_OPCODE_PAIR_PUBLIC_KEY        0x0C
46#define SMP_OPCODE_PAIR_DHKEY_CHECK       0x0D
47#define SMP_OPCODE_PAIR_KEYPR_NOTIF       0x0E
48#define SMP_OPCODE_MAX                    SMP_OPCODE_PAIR_KEYPR_NOTIF
49#define SMP_OPCODE_MIN                    SMP_OPCODE_PAIRING_REQ
50#define SMP_OPCODE_PAIR_COMMITM           0x0F
51#endif
52
53/* SMP event type */
54#define SMP_IO_CAP_REQ_EVT      1       /* IO capability request event */
55#define SMP_SEC_REQUEST_EVT     2       /* SMP pairing request */
56#define SMP_PASSKEY_NOTIF_EVT   3       /* passkey notification event */
57#define SMP_PASSKEY_REQ_EVT     4       /* passkey request event */
58#define SMP_OOB_REQ_EVT         5       /* OOB request event */
59#define SMP_NC_REQ_EVT          6       /* Numeric Comparison request event */
60#define SMP_COMPLT_EVT          7       /* SMP complete event */
61#define SMP_PEER_KEYPR_NOT_EVT  8       /* Peer keypress notification received event */
62#define SMP_SC_OOB_REQ_EVT      9       /* SC OOB request event (both local and peer OOB data */
63                                        /* can be expected in response) */
64#define SMP_SC_LOC_OOB_DATA_UP_EVT  10  /* SC OOB local data set is created */
65                                        /* (as result of SMP_CrLocScOobData(...)) */
66#define SMP_BR_KEYS_REQ_EVT     12      /* SMP over BR keys request event */
67typedef UINT8   tSMP_EVT;
68
69
70/* pairing failure reason code */
71#define SMP_PASSKEY_ENTRY_FAIL      0x01
72#define SMP_OOB_FAIL                0x02
73#define SMP_PAIR_AUTH_FAIL          0x03
74#define SMP_CONFIRM_VALUE_ERR       0x04
75#define SMP_PAIR_NOT_SUPPORT        0x05
76#define SMP_ENC_KEY_SIZE            0x06
77#define SMP_INVALID_CMD             0x07
78#define SMP_PAIR_FAIL_UNKNOWN       0x08
79#define SMP_REPEATED_ATTEMPTS       0x09
80#define SMP_INVALID_PARAMETERS      0x0A
81#define SMP_DHKEY_CHK_FAIL          0x0B
82#define SMP_NUMERIC_COMPAR_FAIL     0x0C
83#define SMP_BR_PARING_IN_PROGR      0x0D
84#define SMP_XTRANS_DERIVE_NOT_ALLOW 0x0E
85#define SMP_MAX_FAIL_RSN_PER_SPEC   SMP_XTRANS_DERIVE_NOT_ALLOW
86
87/* self defined error code */
88#define SMP_PAIR_INTERNAL_ERR       (SMP_MAX_FAIL_RSN_PER_SPEC + 0x01) /* 0x0E */
89
90/* 0x0F unknown IO capability, unable to decide association model */
91#define SMP_UNKNOWN_IO_CAP          (SMP_MAX_FAIL_RSN_PER_SPEC + 0x02) /* 0x0F */
92
93#define SMP_INIT_FAIL               (SMP_MAX_FAIL_RSN_PER_SPEC + 0x03) /* 0x10 */
94#define SMP_CONFIRM_FAIL            (SMP_MAX_FAIL_RSN_PER_SPEC + 0x04) /* 0x11 */
95#define SMP_BUSY                    (SMP_MAX_FAIL_RSN_PER_SPEC + 0x05) /* 0x12 */
96#define SMP_ENC_FAIL                (SMP_MAX_FAIL_RSN_PER_SPEC + 0x06) /* 0x13 */
97#define SMP_STARTED                 (SMP_MAX_FAIL_RSN_PER_SPEC + 0x07) /* 0x14 */
98#define SMP_RSP_TIMEOUT             (SMP_MAX_FAIL_RSN_PER_SPEC + 0x08) /* 0x15 */
99#define SMP_DIV_NOT_AVAIL           (SMP_MAX_FAIL_RSN_PER_SPEC + 0x09) /* 0x16 */
100
101/* 0x17 unspecified failed reason */
102#define SMP_FAIL                    (SMP_MAX_FAIL_RSN_PER_SPEC + 0x0A) /* 0x17 */
103
104#define SMP_CONN_TOUT               (SMP_MAX_FAIL_RSN_PER_SPEC + 0x0B)
105#define SMP_SUCCESS                 0
106
107typedef UINT8 tSMP_STATUS;
108
109
110/* Device IO capability */
111#define SMP_IO_CAP_OUT      BTM_IO_CAP_OUT   /* DisplayOnly */
112#define SMP_IO_CAP_IO       BTM_IO_CAP_IO   /* DisplayYesNo */
113#define SMP_IO_CAP_IN       BTM_IO_CAP_IN   /* KeyboardOnly */
114#define SMP_IO_CAP_NONE     BTM_IO_CAP_NONE   /* NoInputNoOutput */
115#define SMP_IO_CAP_KBDISP   BTM_IO_CAP_KBDISP   /* Keyboard Display */
116#define SMP_IO_CAP_MAX      BTM_IO_CAP_MAX
117typedef UINT8  tSMP_IO_CAP;
118
119#ifndef SMP_DEFAULT_IO_CAPS
120    #define SMP_DEFAULT_IO_CAPS     SMP_IO_CAP_KBDISP
121#endif
122
123/* OOB data present or not */
124enum
125{
126    SMP_OOB_NONE,
127    SMP_OOB_PRESENT,
128    SMP_OOB_UNKNOWN
129};
130typedef UINT8  tSMP_OOB_FLAG;
131
132/* type of OOB data required from application */
133enum
134{
135    SMP_OOB_INVALID_TYPE,
136    SMP_OOB_PEER,
137    SMP_OOB_LOCAL,
138    SMP_OOB_BOTH
139};
140typedef UINT8   tSMP_OOB_DATA_TYPE;
141
142#define SMP_AUTH_NO_BOND        0x00
143#define SMP_AUTH_GEN_BOND       0x01 //todo sdh change GEN_BOND to BOND
144
145/* SMP Authentication requirement */
146#define SMP_AUTH_YN_BIT         (1 << 2)
147#define SMP_SC_SUPPORT_BIT      (1 << 3)
148#define SMP_KP_SUPPORT_BIT      (1 << 4)
149
150#define SMP_AUTH_MASK    (SMP_AUTH_GEN_BOND|SMP_AUTH_YN_BIT|SMP_SC_SUPPORT_BIT|SMP_KP_SUPPORT_BIT)
151
152#define SMP_AUTH_BOND           SMP_AUTH_GEN_BOND
153
154/* no MITM, No Bonding, encryption only */
155#define SMP_AUTH_NB_ENC_ONLY    0x00 //(SMP_AUTH_MASK | BTM_AUTH_SP_NO)
156
157/* MITM, No Bonding, Use IO Capability to determine authentication procedure */
158#define SMP_AUTH_NB_IOCAP       (SMP_AUTH_NO_BOND | SMP_AUTH_YN_BIT)
159
160/* No MITM, General Bonding, Encryption only */
161#define SMP_AUTH_GB_ENC_ONLY    (SMP_AUTH_GEN_BOND )
162
163/* MITM, General Bonding, Use IO Capability to determine authentication procedure */
164#define SMP_AUTH_GB_IOCAP       (SMP_AUTH_GEN_BOND | SMP_AUTH_YN_BIT)
165
166/* Secure Connections, no MITM, no Bonding */
167#define SMP_AUTH_SC_ENC_ONLY    (SMP_SC_SUPPORT_BIT)
168
169/* Secure Connections, no MITM, Bonding */
170#define SMP_AUTH_SC_GB          (SMP_SC_SUPPORT_BIT | SMP_AUTH_GEN_BOND)
171
172/* Secure Connections, MITM, no Bonding */
173#define SMP_AUTH_SC_MITM_NB     (SMP_SC_SUPPORT_BIT | SMP_AUTH_YN_BIT | SMP_AUTH_NO_BOND)
174
175/* Secure Connections, MITM, Bonding */
176#define SMP_AUTH_SC_MITM_GB     (SMP_SC_SUPPORT_BIT | SMP_AUTH_YN_BIT | SMP_AUTH_GEN_BOND)
177
178 /* All AuthReq RFU bits are set to 1 - NOTE: reserved bit in Bonding_Flags is not set */
179#define SMP_AUTH_ALL_RFU_SET    0xF8
180
181typedef UINT8 tSMP_AUTH_REQ;
182
183#define SMP_SEC_NONE                 0
184#define SMP_SEC_UNAUTHENTICATE      (1 << 0)
185#define SMP_SEC_AUTHENTICATED       (1 << 2)
186typedef UINT8 tSMP_SEC_LEVEL;
187
188/* Maximum Encryption Key Size range */
189#define SMP_ENCR_KEY_SIZE_MIN       7
190#define SMP_ENCR_KEY_SIZE_MAX       16
191
192/* SMP key types */
193#define SMP_SEC_KEY_TYPE_ENC                (1 << 0)    /* encryption key */
194#define SMP_SEC_KEY_TYPE_ID                 (1 << 1)    /* identity key */
195#define SMP_SEC_KEY_TYPE_CSRK               (1 << 2)    /* slave CSRK */
196#define SMP_SEC_KEY_TYPE_LK                 (1 << 3)    /* BR/EDR link key */
197typedef UINT8 tSMP_KEYS;
198
199#define SMP_BR_SEC_DEFAULT_KEY   (SMP_SEC_KEY_TYPE_ENC | SMP_SEC_KEY_TYPE_ID | \
200                                  SMP_SEC_KEY_TYPE_CSRK)
201
202/* default security key distribution value */
203#define SMP_SEC_DEFAULT_KEY      (SMP_SEC_KEY_TYPE_ENC | SMP_SEC_KEY_TYPE_ID | \
204                                  SMP_SEC_KEY_TYPE_CSRK | SMP_SEC_KEY_TYPE_LK)
205
206/* data type for BTM_SP_IO_REQ_EVT */
207typedef struct
208{
209    tSMP_IO_CAP     io_cap;         /* local IO capabilities */
210    tSMP_OOB_FLAG   oob_data;       /* OOB data present (locally) for the peer device */
211    tSMP_AUTH_REQ   auth_req;       /* Authentication required (for local device) */
212    UINT8           max_key_size;   /* max encryption key size */
213    tSMP_KEYS       init_keys;      /* initiator keys to be distributed */
214    tSMP_KEYS       resp_keys;      /* responder keys */
215} tSMP_IO_REQ;
216
217typedef struct
218{
219    tSMP_STATUS       reason;
220    tSMP_SEC_LEVEL    sec_level;
221    BOOLEAN     is_pair_cancel;
222} tSMP_CMPL;
223
224typedef struct
225{
226    BT_OCTET32  x;
227    BT_OCTET32  y;
228} tSMP_PUBLIC_KEY;
229
230/* the data associated with the info sent to the peer via OOB interface */
231typedef struct
232{
233    BOOLEAN         present;
234    BT_OCTET16      randomizer;
235    BT_OCTET16      commitment;
236
237    tBLE_BD_ADDR    addr_sent_to;
238    BT_OCTET32      private_key_used;   /* is used to calculate: */
239                    /* publ_key_used = P-256(private_key_used, curve_p256.G) - send it to the */
240                    /* other side */
241                    /* dhkey = P-256(private_key_used, publ key rcvd from the other side) */
242    tSMP_PUBLIC_KEY publ_key_used; /* P-256(private_key_used, curve_p256.G) */
243} tSMP_LOC_OOB_DATA;
244
245/* the data associated with the info received from the peer via OOB interface */
246typedef struct
247{
248    BOOLEAN         present;
249    BT_OCTET16      randomizer;
250    BT_OCTET16      commitment;
251    tBLE_BD_ADDR    addr_rcvd_from;
252} tSMP_PEER_OOB_DATA;
253
254typedef struct
255{
256    tSMP_LOC_OOB_DATA   loc_oob_data;
257    tSMP_PEER_OOB_DATA  peer_oob_data;
258} tSMP_SC_OOB_DATA;
259
260
261typedef union
262{
263    UINT32          passkey;
264    tSMP_IO_REQ     io_req;     /* IO request */
265    tSMP_CMPL       cmplt;
266    tSMP_OOB_DATA_TYPE  req_oob_type;
267    tSMP_LOC_OOB_DATA   loc_oob_data;
268}tSMP_EVT_DATA;
269
270
271/* AES Encryption output */
272typedef struct
273{
274    UINT8   status;
275    UINT8   param_len;
276    UINT16  opcode;
277    UINT8   param_buf[BT_OCTET16_LEN];
278} tSMP_ENC;
279
280/* Security Manager events - Called by the stack when Security Manager related events occur.*/
281typedef UINT8 (tSMP_CALLBACK) (tSMP_EVT event, BD_ADDR bd_addr, tSMP_EVT_DATA *p_data);
282
283/* callback function for CMAC algorithm
284*/
285typedef void (tCMAC_CMPL_CBACK)(UINT8 *p_mac, UINT16 tlen, UINT32 sign_counter);
286
287/*****************************************************************************
288**  External Function Declarations
289*****************************************************************************/
290#ifdef __cplusplus
291extern "C"
292{
293#endif
294/* API of SMP */
295
296/*******************************************************************************
297**
298** Function         SMP_Init
299**
300** Description      This function initializes the SMP unit.
301**
302** Returns          void
303**
304*******************************************************************************/
305extern void SMP_Init(void);
306
307/*******************************************************************************
308**
309** Function         SMP_SetTraceLevel
310**
311** Description      This function sets the trace level for SMP.  If called with
312**                  a value of 0xFF, it simply returns the current trace level.
313**
314** Returns          The new or current trace level
315**
316*******************************************************************************/
317extern UINT8 SMP_SetTraceLevel (UINT8 new_level);
318
319/*******************************************************************************
320**
321** Function         SMP_Register
322**
323** Description      This function register for the SMP service callback.
324**
325** Returns          void
326**
327*******************************************************************************/
328extern BOOLEAN SMP_Register (tSMP_CALLBACK *p_cback);
329
330/*******************************************************************************
331**
332** Function         SMP_Pair
333**
334** Description      This function is called to start a SMP pairing.
335**
336** Returns          SMP_STARTED if bond started, else otherwise exception.
337**
338*******************************************************************************/
339extern tSMP_STATUS SMP_Pair (BD_ADDR bd_addr);
340
341/*******************************************************************************
342**
343** Function         SMP_BR_PairWith
344**
345** Description      This function is called to start a SMP pairing over BR/EDR.
346**
347** Returns          SMP_STARTED if pairing started, otherwise reason for failure.
348**
349*******************************************************************************/
350extern tSMP_STATUS SMP_BR_PairWith (BD_ADDR bd_addr);
351
352/*******************************************************************************
353**
354** Function         SMP_PairCancel
355**
356** Description      This function is called to cancel a SMP pairing.
357**
358** Returns          TRUE - pairing cancelled
359**
360*******************************************************************************/
361extern  BOOLEAN SMP_PairCancel (BD_ADDR bd_addr);
362
363/*******************************************************************************
364**
365** Function         SMP_SecurityGrant
366**
367** Description      This function is called to grant security process.
368**
369** Parameters       bd_addr - peer device bd address.
370**                  res     - result of the operation SMP_SUCCESS if success.
371**                            Otherwise, SMP_REPEATED_ATTEMPTS is too many attempts.
372**
373** Returns          None
374**
375*******************************************************************************/
376extern void SMP_SecurityGrant(BD_ADDR bd_addr, UINT8 res);
377
378/*******************************************************************************
379**
380** Function         SMP_PasskeyReply
381**
382** Description      This function is called after Security Manager submitted
383**                  Passkey request to the application.
384**
385** Parameters:      bd_addr      - Address of the device for which PIN was requested
386**                  res          - result of the operation SMP_SUCCESS if success
387**                  passkey      - numeric value in the range of
388**                  BTM_MIN_PASSKEY_VAL(0) - BTM_MAX_PASSKEY_VAL(999999(0xF423F)).
389**
390*******************************************************************************/
391extern void SMP_PasskeyReply (BD_ADDR bd_addr, UINT8 res, UINT32 passkey);
392
393/*******************************************************************************
394**
395** Function         SMP_ConfirmReply
396**
397** Description      This function is called after Security Manager submitted
398**                  numeric comparison request to the application.
399**
400** Parameters:      bd_addr      - Address of the device with which numeric
401**                                 comparison was requested
402**                  res          - comparison result SMP_SUCCESS if success
403**
404*******************************************************************************/
405extern void SMP_ConfirmReply (BD_ADDR bd_addr, UINT8 res);
406
407/*******************************************************************************
408**
409** Function         SMP_OobDataReply
410**
411** Description      This function is called to provide the OOB data for
412**                  SMP in response to SMP_OOB_REQ_EVT
413**
414** Parameters:      bd_addr     - Address of the peer device
415**                  res         - result of the operation SMP_SUCCESS if success
416**                  p_data      - SM Randomizer  C.
417**
418*******************************************************************************/
419extern void SMP_OobDataReply(BD_ADDR bd_addr, tSMP_STATUS res, UINT8 len,
420                             UINT8 *p_data);
421
422/*******************************************************************************
423**
424** Function         SMP_SecureConnectionOobDataReply
425**
426** Description      This function is called to provide the SC OOB data for
427**                  SMP in response to SMP_SC_OOB_REQ_EVT
428**
429** Parameters:      p_data      - pointer to the data
430**
431*******************************************************************************/
432extern void SMP_SecureConnectionOobDataReply(UINT8 *p_data);
433
434/*******************************************************************************
435**
436** Function         SMP_Encrypt
437**
438** Description      This function is called to encrypt the data with the specified
439**                  key
440**
441** Parameters:      key                 - Pointer to key key[0] conatins the MSB
442**                  key_len             - key length
443**                  plain_text          - Pointer to data to be encrypted
444**                                        plain_text[0] conatins the MSB
445**                  pt_len              - plain text length
446**                  p_out               - pointer to the encrypted outputs
447**
448**  Returns         Boolean - TRUE: encryption is successful
449*******************************************************************************/
450extern BOOLEAN SMP_Encrypt (UINT8 *key, UINT8 key_len,
451                            UINT8 *plain_text, UINT8 pt_len,
452                            tSMP_ENC *p_out);
453
454/*******************************************************************************
455**
456** Function         SMP_KeypressNotification
457**
458** Description      This function is called to notify SM about Keypress Notification.
459**
460** Parameters:      bd_addr      - Address of the device to send keypress
461**                                 notification to
462**                  value        - keypress notification parameter value
463**
464*******************************************************************************/
465extern void SMP_KeypressNotification (BD_ADDR bd_addr, UINT8 value);
466
467/*******************************************************************************
468**
469** Function         SMP_CreateLocalSecureConnectionsOobData
470**
471** Description      This function is called to start creation of local SC OOB
472**                  data set (tSMP_LOC_OOB_DATA).
473**
474** Parameters:      bd_addr      - Address of the device to send OOB data block
475**                                 to.
476**
477**  Returns         Boolean - TRUE: creation of local SC OOB data set started.
478*******************************************************************************/
479extern BOOLEAN SMP_CreateLocalSecureConnectionsOobData (
480                                                                  tBLE_BD_ADDR *addr_to_send_to);
481
482#ifdef __cplusplus
483}
484#endif
485#endif /* SMP_API_H */
486