sm.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015-2016, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!*****************************************************************************
 *  @file     sm.h
 *  @brief    This file contains the interface to the SM.
 */

#ifndef SM_H
#define SM_H

#ifdef __cplusplus
extern "C"
{
#endif

/*-------------------------------------------------------------------
 * INCLUDES
 */
#include "bcomdef.h"
#include "osal.h"

#include "hci.h"
  
/*-------------------------------------------------------------------
 * MACROS
 */

/*-------------------------------------------------------------------
 * CONSTANTS
 */
#define DISPLAY_ONLY              0x00  
#define DISPLAY_YES_NO            0x01  
#define KEYBOARD_ONLY             0x02  
#define NO_INPUT_NO_OUTPUT        0x03  
#define KEYBOARD_DISPLAY          0x04  

#define SM_AUTH_MITM_MASK(a)    (((a) & 0x04) >> 2)

#define SM_PASSKEY_TYPE_INPUT   0x01    
#define SM_PASSKEY_TYPE_DISPLAY 0x02    

#define SM_AUTH_REQ_NO_BONDING    0x00  
#define SM_AUTH_REQ_BONDING       0x01  

#define PASSKEY_LEN     6   

#define SM_AUTH_STATE_AUTHENTICATED       0x04  
#define SM_AUTH_STATE_BONDING             0x01  
#define SM_AUTH_STATE_SECURECONNECTION    0x08  
   
#define SM_ECC_KEY_LEN 32  // ECC Key length in bytes
   
/* SM private/public key regeneration policy */
#define SM_ECC_KEYS_NOT_AVAILABLE     0xFF  // Initial state of recycled keys before they exist.
#define SM_ECC_KEYS_REGNENERATE_NEVER 0xFF  // Never regenerate the keys.
#define SM_ECC_KEYS_REGENERATE_ALWAYS 0x00  // Always regenerate the keys.
   
#define SM_ECC_KEYS_EVENT 0x00 // ECC Keys
#define SM_DH_KEY_EVENT   0x01 // Diffie-Hellman key
 // end of GAPBondMgr_Constants

/*-------------------------------------------------------------------
 * General TYPEDEFS
 */

typedef struct
{
  osal_event_hdr_t  hdr;      
  uint8 newKey[KEYLEN];       
} smNewRandKeyEvent_t;

typedef struct
{
  osal_event_hdr_t hdr;
  uint8 opcode;
} smEventHdr_t;

typedef struct
{
  osal_event_hdr_t hdr;             
  uint8 opcode;                     
  uint8 privateKey[SM_ECC_KEY_LEN]; 
  uint8 publicKeyX[SM_ECC_KEY_LEN]; 
  uint8 publicKeyY[SM_ECC_KEY_LEN]; 
} smEccKeysEvt_t;

typedef struct
{
  osal_event_hdr_t hdr;        
  uint8 opcode;                
  uint8 dhKey[SM_ECC_KEY_LEN]; 
} smDhKeyEvt_t;

typedef struct
{
  unsigned int sEncKey:1;    
  unsigned int sIdKey:1;     
  unsigned int sSign:1;      
  unsigned int sLinkKey:1;   
  unsigned int sReserved:4;  
  unsigned int mEncKey:1;    
  unsigned int mIdKey:1;     
  unsigned int mSign:1;      
  unsigned int mLinkKey:1;   
  unsigned int mReserved:4;  
} keyDist_t;

typedef struct
{
  uint8 isUsed;               
  uint8 sK[SM_ECC_KEY_LEN];   
  uint8 pK_x[SM_ECC_KEY_LEN]; 
  uint8 pK_y[SM_ECC_KEY_LEN]; 
} smEccKeys_t;

typedef struct
{
  uint8 ioCaps;                 
  uint8 oobAvailable;           
  uint8 oob[KEYLEN];            
  uint8 oobConfirm[KEYLEN];     
  uint8 localOobAvailable;      
  uint8 localOob[KEYLEN];       
  uint8 isSCOnlyMode;           
  smEccKeys_t eccKeys;          
  uint8 authReq;                
  keyDist_t keyDist;            
  uint8 maxEncKeySize;          
} smLinkSecurityReq_t;

typedef struct
{
  uint8 ltk[KEYLEN];              
  uint16 div;                     
  uint8 rand[B_RANDOM_NUM_SIZE];  
  uint8 keySize;                  
} smSecurityInfo_t;

typedef struct
{
  uint8 irk[KEYLEN];          
  uint8 addrType;             
  uint8 bd_addr[B_ADDR_LEN];  
} smIdentityInfo_t;

typedef struct
{
  uint8  srk[KEYLEN]; 
  uint32 signCounter; 
} smSigningInfo_t;

typedef struct
{
  unsigned int bonding:2;    
  unsigned int mitm:1;       
  unsigned int sc:1;         
  unsigned int kp:1;         
  unsigned int reserved:3;   
} authReq_t;

typedef void (*smCB_t)
(
uint8 *secretKey,  
uint8 *publicKeyX, 
uint8 *publicKeyY  
);

/*-------------------------------------------------------------------
 * GLOBAL VARIABLES
 */

/*-------------------------------------------------------------------
 * FUNCTIONS - APPLICATION API - Functions the application may call
 */

extern void SM_RegisterTask( uint8 taskID );

extern bStatus_t SM_GetEccKeys( void );

/*********************************************************************
 * @brief   Request a Diffie-Hellman key from the ECC engine. Key is returned 
 *          through the callback registered in SM_RegisterCb, in the first 
 *          parameter.
 *
 * @param   secretKey - the local private key
 * @param   publicKey1 - the remote public key, X-Coordinate.
 * @param   publicKey2 - the remote public key, Y-Coordinate.
 *
 * @return SUCCESS if processing, FAILURE if SM is pairing, or 
 *         HCI_ERROR_CODE_MEM_CAP_EXCEEDED if out of heap memory.
 */
extern bStatus_t SM_GetDHKey( uint8 *secretKey, uint8 *publicKeyX, 
                              uint8 *publicKeyY );

/*********************************************************************
 * @brief   Generate a confirm value for OOB data.
 *
 * @param   publicKey - the local public key X-coordinate
 * @param   oob       - the random string to be sent to the remote device via 
 *                      oob
 * @param   pOut      - pointer to the generated confirm value.  The calling
 *                      application must copy this data into its own buffer.
 *
 * @return  SUCCESS, INVALIDPARAMETER or bleMemAllocError
 */
extern bStatus_t SM_GetScConfirmOob( uint8 *publicKey, uint8 *oob, uint8 *pOut );

/*-------------------------------------------------------------------
 * FUNCTIONS - MASTER API - Only use these in a master device
 */

extern bStatus_t SM_InitiatorInit( void );

extern bStatus_t SM_StartPairing(  uint8 initiator,
                                   uint8 taskID,
                                   uint16 connectionHandle,
                                   smLinkSecurityReq_t *pSecReqs );

extern bStatus_t SM_StartEncryption( uint16 connHandle, uint8 *pLTK,
                                     uint16 div, uint8 *pRandNum, 
                                     uint8 keyLen );


/*-------------------------------------------------------------------
 * FUNCTIONS - SLAVE API - Only use these in a slave device
 */

extern bStatus_t SM_ResponderInit( void );

/*-------------------------------------------------------------------
 * FUNCTIONS - GENERAL API - both master and slave
 */

extern bStatus_t SM_NewRandKey( uint8 taskID );

#if !defined (BLE_V42_FEATURES) || !(BLE_V42_FEATURES & PRIVACY_1_2_CFG)

extern bStatus_t SM_CalcRandomAddr( uint8 *pIRK, uint8 *pNewAddr );

extern bStatus_t SM_ResolveRandomAddrs( uint8 *pIRK, uint8 *pAddr );
#endif // ! BLE_V42_FEATURES | ! PRIVACY_1_2_CFG

extern bStatus_t SM_Encrypt( uint8 *pKey, uint8 *pPlainText, uint8 *pResult );

extern bStatus_t SM_GenerateAuthenSig( uint8 *pData, uint16 len, 
                                       uint8 *pAuthenSig );

extern bStatus_t SM_VerifyAuthenSig( uint16 connHandle,
                                     uint8 authentication,
                                     uint8 *pData,
                                     uint16 len,
                                     uint8 *pAuthenSig );

extern bStatus_t SM_PasskeyUpdate( uint8 *pPasskey, uint16 connectionHandle );


extern void SM_SetECCRegenerationCount(uint8 count);

/*-------------------------------------------------------------------
 * TASK API - These functions must only be called by OSAL.
 */

  extern void SM_Init( uint8 task_id );

  extern uint16 SM_ProcessEvent( uint8 task_id, uint16 events );

  extern void SM_p256KeyCB( hciEvt_BLEReadP256PublicKeyComplete_t *pK, 
                            uint8 *privateKey );

  extern void SM_dhKeyCB( hciEvt_BLEGenDHKeyComplete_t *pDhKey );

/*-------------------------------------------------------------------
-------------------------------------------------------------------*/

#ifdef __cplusplus
}
#endif

#endif /* SM_H */