Home | History | Annotate | Download | only in include
      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) /* 0x0F */
     89 
     90 /* Unknown IO capability, unable to decide association model */
     91 #define SMP_UNKNOWN_IO_CAP          (SMP_MAX_FAIL_RSN_PER_SPEC + 0x02) /* 0x10 */
     92 
     93 #define SMP_INIT_FAIL               (SMP_MAX_FAIL_RSN_PER_SPEC + 0x03) /* 0x11 */
     94 #define SMP_CONFIRM_FAIL            (SMP_MAX_FAIL_RSN_PER_SPEC + 0x04) /* 0x12 */
     95 #define SMP_BUSY                    (SMP_MAX_FAIL_RSN_PER_SPEC + 0x05) /* 0x13 */
     96 #define SMP_ENC_FAIL                (SMP_MAX_FAIL_RSN_PER_SPEC + 0x06) /* 0x14 */
     97 #define SMP_STARTED                 (SMP_MAX_FAIL_RSN_PER_SPEC + 0x07) /* 0x15 */
     98 #define SMP_RSP_TIMEOUT             (SMP_MAX_FAIL_RSN_PER_SPEC + 0x08) /* 0x16 */
     99 #define SMP_DIV_NOT_AVAIL           (SMP_MAX_FAIL_RSN_PER_SPEC + 0x09) /* 0x17 */
    100 
    101 /* Unspecified failure reason */
    102 #define SMP_FAIL                    (SMP_MAX_FAIL_RSN_PER_SPEC + 0x0A) /* 0x18 */
    103 
    104 #define SMP_CONN_TOUT               (SMP_MAX_FAIL_RSN_PER_SPEC + 0x0B) /* 0x19 */
    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 #define SMP_SC_KEY_STARTED      0   /* passkey entry started */
    207 #define SMP_SC_KEY_ENTERED      1   /* passkey digit entered */
    208 #define SMP_SC_KEY_ERASED       2   /* passkey digit erased */
    209 #define SMP_SC_KEY_CLEARED      3   /* passkey cleared */
    210 #define SMP_SC_KEY_COMPLT       4   /* passkey entry completed */
    211 #define SMP_SC_KEY_OUT_OF_RANGE 5   /* out of range */
    212 typedef UINT8 tSMP_SC_KEY_TYPE;
    213 
    214 /* data type for BTM_SP_IO_REQ_EVT */
    215 typedef struct
    216 {
    217     tSMP_IO_CAP     io_cap;         /* local IO capabilities */
    218     tSMP_OOB_FLAG   oob_data;       /* OOB data present (locally) for the peer device */
    219     tSMP_AUTH_REQ   auth_req;       /* Authentication required (for local device) */
    220     UINT8           max_key_size;   /* max encryption key size */
    221     tSMP_KEYS       init_keys;      /* initiator keys to be distributed */
    222     tSMP_KEYS       resp_keys;      /* responder keys */
    223 } tSMP_IO_REQ;
    224 
    225 typedef struct
    226 {
    227     tSMP_STATUS reason;
    228     tSMP_SEC_LEVEL sec_level;
    229     BOOLEAN is_pair_cancel;
    230     BOOLEAN smp_over_br;
    231 } tSMP_CMPL;
    232 
    233 typedef struct
    234 {
    235     BT_OCTET32  x;
    236     BT_OCTET32  y;
    237 } tSMP_PUBLIC_KEY;
    238 
    239 /* the data associated with the info sent to the peer via OOB interface */
    240 typedef struct
    241 {
    242     BOOLEAN         present;
    243     BT_OCTET16      randomizer;
    244     BT_OCTET16      commitment;
    245 
    246     tBLE_BD_ADDR    addr_sent_to;
    247     BT_OCTET32      private_key_used;   /* is used to calculate: */
    248                     /* publ_key_used = P-256(private_key_used, curve_p256.G) - send it to the */
    249                     /* other side */
    250                     /* dhkey = P-256(private_key_used, publ key rcvd from the other side) */
    251     tSMP_PUBLIC_KEY publ_key_used; /* P-256(private_key_used, curve_p256.G) */
    252 } tSMP_LOC_OOB_DATA;
    253 
    254 /* the data associated with the info received from the peer via OOB interface */
    255 typedef struct
    256 {
    257     BOOLEAN         present;
    258     BT_OCTET16      randomizer;
    259     BT_OCTET16      commitment;
    260     tBLE_BD_ADDR    addr_rcvd_from;
    261 } tSMP_PEER_OOB_DATA;
    262 
    263 typedef struct
    264 {
    265     tSMP_LOC_OOB_DATA   loc_oob_data;
    266     tSMP_PEER_OOB_DATA  peer_oob_data;
    267 } tSMP_SC_OOB_DATA;
    268 
    269 
    270 typedef union
    271 {
    272     UINT32          passkey;
    273     tSMP_IO_REQ     io_req;     /* IO request */
    274     tSMP_CMPL       cmplt;
    275     tSMP_OOB_DATA_TYPE  req_oob_type;
    276     tSMP_LOC_OOB_DATA   loc_oob_data;
    277 }tSMP_EVT_DATA;
    278 
    279 
    280 /* AES Encryption output */
    281 typedef struct
    282 {
    283     UINT8   status;
    284     UINT8   param_len;
    285     UINT16  opcode;
    286     UINT8   param_buf[BT_OCTET16_LEN];
    287 } tSMP_ENC;
    288 
    289 /* Security Manager events - Called by the stack when Security Manager related events occur.*/
    290 typedef UINT8 (tSMP_CALLBACK) (tSMP_EVT event, BD_ADDR bd_addr, tSMP_EVT_DATA *p_data);
    291 
    292 /* callback function for CMAC algorithm
    293 */
    294 typedef void (tCMAC_CMPL_CBACK)(UINT8 *p_mac, UINT16 tlen, UINT32 sign_counter);
    295 
    296 /*****************************************************************************
    297 **  External Function Declarations
    298 *****************************************************************************/
    299 #ifdef __cplusplus
    300 extern "C"
    301 {
    302 #endif
    303 /* API of SMP */
    304 
    305 /*******************************************************************************
    306 **
    307 ** Function         SMP_Init
    308 **
    309 ** Description      This function initializes the SMP unit.
    310 **
    311 ** Returns          void
    312 **
    313 *******************************************************************************/
    314 extern void SMP_Init(void);
    315 
    316 /*******************************************************************************
    317 **
    318 ** Function         SMP_SetTraceLevel
    319 **
    320 ** Description      This function sets the trace level for SMP.  If called with
    321 **                  a value of 0xFF, it simply returns the current trace level.
    322 **
    323 ** Returns          The new or current trace level
    324 **
    325 *******************************************************************************/
    326 extern UINT8 SMP_SetTraceLevel (UINT8 new_level);
    327 
    328 /*******************************************************************************
    329 **
    330 ** Function         SMP_Register
    331 **
    332 ** Description      This function register for the SMP service callback.
    333 **
    334 ** Returns          void
    335 **
    336 *******************************************************************************/
    337 extern BOOLEAN SMP_Register (tSMP_CALLBACK *p_cback);
    338 
    339 /*******************************************************************************
    340 **
    341 ** Function         SMP_Pair
    342 **
    343 ** Description      This function is called to start a SMP pairing.
    344 **
    345 ** Returns          SMP_STARTED if bond started, else otherwise exception.
    346 **
    347 *******************************************************************************/
    348 extern tSMP_STATUS SMP_Pair (BD_ADDR bd_addr);
    349 
    350 /*******************************************************************************
    351 **
    352 ** Function         SMP_BR_PairWith
    353 **
    354 ** Description      This function is called to start a SMP pairing over BR/EDR.
    355 **
    356 ** Returns          SMP_STARTED if pairing started, otherwise reason for failure.
    357 **
    358 *******************************************************************************/
    359 extern tSMP_STATUS SMP_BR_PairWith (BD_ADDR bd_addr);
    360 
    361 /*******************************************************************************
    362 **
    363 ** Function         SMP_PairCancel
    364 **
    365 ** Description      This function is called to cancel a SMP pairing.
    366 **
    367 ** Returns          TRUE - pairing cancelled
    368 **
    369 *******************************************************************************/
    370 extern  BOOLEAN SMP_PairCancel (BD_ADDR bd_addr);
    371 
    372 /*******************************************************************************
    373 **
    374 ** Function         SMP_SecurityGrant
    375 **
    376 ** Description      This function is called to grant security process.
    377 **
    378 ** Parameters       bd_addr - peer device bd address.
    379 **                  res     - result of the operation SMP_SUCCESS if success.
    380 **                            Otherwise, SMP_REPEATED_ATTEMPTS is too many attempts.
    381 **
    382 ** Returns          None
    383 **
    384 *******************************************************************************/
    385 extern void SMP_SecurityGrant(BD_ADDR bd_addr, UINT8 res);
    386 
    387 /*******************************************************************************
    388 **
    389 ** Function         SMP_PasskeyReply
    390 **
    391 ** Description      This function is called after Security Manager submitted
    392 **                  Passkey request to the application.
    393 **
    394 ** Parameters:      bd_addr      - Address of the device for which PIN was requested
    395 **                  res          - result of the operation SMP_SUCCESS if success
    396 **                  passkey      - numeric value in the range of
    397 **                  BTM_MIN_PASSKEY_VAL(0) - BTM_MAX_PASSKEY_VAL(999999(0xF423F)).
    398 **
    399 *******************************************************************************/
    400 extern void SMP_PasskeyReply (BD_ADDR bd_addr, UINT8 res, UINT32 passkey);
    401 
    402 /*******************************************************************************
    403 **
    404 ** Function         SMP_ConfirmReply
    405 **
    406 ** Description      This function is called after Security Manager submitted
    407 **                  numeric comparison request to the application.
    408 **
    409 ** Parameters:      bd_addr      - Address of the device with which numeric
    410 **                                 comparison was requested
    411 **                  res          - comparison result SMP_SUCCESS if success
    412 **
    413 *******************************************************************************/
    414 extern void SMP_ConfirmReply (BD_ADDR bd_addr, UINT8 res);
    415 
    416 /*******************************************************************************
    417 **
    418 ** Function         SMP_OobDataReply
    419 **
    420 ** Description      This function is called to provide the OOB data for
    421 **                  SMP in response to SMP_OOB_REQ_EVT
    422 **
    423 ** Parameters:      bd_addr     - Address of the peer device
    424 **                  res         - result of the operation SMP_SUCCESS if success
    425 **                  p_data      - SM Randomizer  C.
    426 **
    427 *******************************************************************************/
    428 extern void SMP_OobDataReply(BD_ADDR bd_addr, tSMP_STATUS res, UINT8 len,
    429                              UINT8 *p_data);
    430 
    431 /*******************************************************************************
    432 **
    433 ** Function         SMP_SecureConnectionOobDataReply
    434 **
    435 ** Description      This function is called to provide the SC OOB data for
    436 **                  SMP in response to SMP_SC_OOB_REQ_EVT
    437 **
    438 ** Parameters:      p_data      - pointer to the data
    439 **
    440 *******************************************************************************/
    441 extern void SMP_SecureConnectionOobDataReply(UINT8 *p_data);
    442 
    443 /*******************************************************************************
    444 **
    445 ** Function         SMP_Encrypt
    446 **
    447 ** Description      This function is called to encrypt the data with the specified
    448 **                  key
    449 **
    450 ** Parameters:      key                 - Pointer to key key[0] conatins the MSB
    451 **                  key_len             - key length
    452 **                  plain_text          - Pointer to data to be encrypted
    453 **                                        plain_text[0] conatins the MSB
    454 **                  pt_len              - plain text length
    455 **                  p_out               - pointer to the encrypted outputs
    456 **
    457 **  Returns         Boolean - TRUE: encryption is successful
    458 *******************************************************************************/
    459 extern BOOLEAN SMP_Encrypt (UINT8 *key, UINT8 key_len,
    460                             UINT8 *plain_text, UINT8 pt_len,
    461                             tSMP_ENC *p_out);
    462 
    463 /*******************************************************************************
    464 **
    465 ** Function         SMP_KeypressNotification
    466 **
    467 ** Description      This function is called to notify SM about Keypress Notification.
    468 **
    469 ** Parameters:      bd_addr      - Address of the device to send keypress
    470 **                                 notification to
    471 **                  value        - keypress notification parameter value
    472 **
    473 *******************************************************************************/
    474 extern void SMP_KeypressNotification (BD_ADDR bd_addr, UINT8 value);
    475 
    476 /*******************************************************************************
    477 **
    478 ** Function         SMP_CreateLocalSecureConnectionsOobData
    479 **
    480 ** Description      This function is called to start creation of local SC OOB
    481 **                  data set (tSMP_LOC_OOB_DATA).
    482 **
    483 ** Parameters:      bd_addr      - Address of the device to send OOB data block
    484 **                                 to.
    485 **
    486 **  Returns         Boolean - TRUE: creation of local SC OOB data set started.
    487 *******************************************************************************/
    488 extern BOOLEAN SMP_CreateLocalSecureConnectionsOobData (
    489                                                                   tBLE_BD_ADDR *addr_to_send_to);
    490 
    491 #ifdef __cplusplus
    492 }
    493 #endif
    494 #endif /* SMP_API_H */
    495