stack/include/smp_api.h

   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 */
  67 typedef 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
 107 typedef 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
 117 typedef 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 */
 124 enum
 125 {
 126     SMP_OOB_NONE,
 127     SMP_OOB_PRESENT,
 128     SMP_OOB_UNKNOWN
 129 };
 130 typedef UINT8  tSMP_OOB_FLAG;
 131
 132 /* type of OOB data required from application */
 133 enum
 134 {
 135     SMP_OOB_INVALID_TYPE,
 136     SMP_OOB_PEER,
 137     SMP_OOB_LOCAL,
 138     SMP_OOB_BOTH
 139 };
 140 typedef 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
 181 typedef 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)
 186 typedef 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 */
 197 typedef 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 */
 207 typedef 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
 217 typedef struct
 218 {
 219     tSMP_STATUS       reason;
 220     tSMP_SEC_LEVEL    sec_level;
 221     BOOLEAN     is_pair_cancel;
 222 } tSMP_CMPL;
 223
 224 typedef 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 */
 231 typedef 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 */
 246 typedef 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
 254 typedef 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
 261 typedef 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 */
 272 typedef 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.*/
 281 typedef UINT8 (tSMP_CALLBACK) (tSMP_EVT event, BD_ADDR bd_addr, tSMP_EVT_DATA *p_data);
 282
 283 /* callback function for CMAC algorithm
 284 */
 285 typedef void (tCMAC_CMPL_CBACK)(UINT8 *p_mac, UINT16 tlen, UINT32 sign_counter);
 286
 287 /*****************************************************************************
 288 **  External Function Declarations
 289 *****************************************************************************/
 290 #ifdef __cplusplus
 291 extern "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 *******************************************************************************/
 305 extern 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 *******************************************************************************/
 317 extern 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 *******************************************************************************/
 328 extern 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 *******************************************************************************/
 339 extern 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 *******************************************************************************/
 350 extern 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 *******************************************************************************/
 361 extern  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 *******************************************************************************/
 376 extern 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 *******************************************************************************/
 391 extern 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 *******************************************************************************/
 405 extern 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 *******************************************************************************/
 419 extern 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 *******************************************************************************/
 432 extern 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 *******************************************************************************/
 450 extern 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 *******************************************************************************/
 465 extern 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 *******************************************************************************/
 479 extern BOOLEAN SMP_CreateLocalSecureConnectionsOobData (
 480                                                                   tBLE_BD_ADDR *addr_to_send_to);
 481
 482 #ifdef __cplusplus
 483 }
 484 #endif
 485 #endif /* SMP_API_H */