API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

IBTSECURITYHANDLER

Brew Release
Brew MP 1.0.2
See Also
Description

Bluetooth Security handler interface
This interface allows applications to perform Bluetooth security related procedures.
The interface supports all the security procedures defined by Bluetooth specification V2.1 Including Secure Simple Paring (SSP). When both Bluetooth devices (local and remote) support SSP, The association model used for Pairing will be based on the IO capability of both the devices. Based on the Association model used for pairing IBTSecurityHandler interface shall deliver the appropriate events to the client during pairing procedure.
The "Numeric Comparison" association model is designed for scenarios where both devices are capable of displaying a six digit number and both are capable of having the user Enter "YES" or "NO". When "Numeric Comparison" association model is used for pairing procedure, client shall receive either AEEBTSEC_HNDLR_EV_USER_CONF_REQ event or AEEBTSEC_HNDLR_EV_PASSKEY_NOTIFICATION event. Upon receiving AEEBTSEC_HNDLR_EV_USER_CONF_REQ event,client needs to display the passkey (which is part of event structure) to user. User's input (either "Yes" or "No") needs to be sent to the driver using IBTSecurityHandler_SendUserConfirmation() API. Upon receiving AEEBTSEC_HNDLR_EV_PASSKEY_NOTIFICATION event , client needs to client needs to display the passkey (which is part of event structure) to user and ask user to enter same passkey on the remote device.
The "Just Works" association model is primarily designed for scenarios where at least one of the devices do not have a display capable of displaying a six digit number nor does it have a keyboard capable of entering six decimal digits. When the device is capable of displaying only yes/no indication, client shall receive AEEBTSEC_HNDLR_EV_USER_CONF_REQ event. Upon receiving this event client needs to invoke IBTSecurityHandler_SendUserConfirmation() API to accept/reject the pairing. If if the device does not have any display or input capability then no events are generated and paring request from remote is automatically accepted.
The "Out Of Band" (OOB) association model is primarily designed for scenarios where an OOB mechanism is used to both discover the devices as well as to exchange or transfer cryptographic numbers used in the pairing process. When OOB association model is used for pairing, client can write the remote device OOB data to the Bluetooth driver using IBTSecurityHandler_SetRemoteOOBData() API and retrieve local OOB data using IBTSecurityHandler_GetLocalOOBData() API.
The "Passkey Entry" association model is primarily designed for scenarios where one device has input capability but does not have the display capability to display six digits and the other device has output capabilities. When the "Passkey Entry" association model is used IBTSecurityHandler interface shall send "AEEBTSEC_HNDLR_EV_PASS_KEY_REQ" event. Upon receiving this event, client needs to get the passkey entered by user. During the passkey entry, each key action should be sent to remote using IBTSecurityHandler_KeyPressNotification() API. Once the user is done with the passkey entry, passkey should be sent to Bluetooth driver using IBTSecurityHandler_PasskeyReply() API.
For more information about SSP association models, please refer Bluetooth Specification 2.1.
In case the underlying Bluetooth Driver or the remote device is not SSP capable, during paring, client shall receive "AEEBTSEC_HNDLR_EV_PIN_KEY_REQ" request. Upon receiving this event, client needs to get the passkey entered by user. Once the user is done with the passkey entry,passkey should be sent to Bluetooth driver using IBTSecurityHandler_PinkeyReply() API.
This interface should be created using GetSecurityHandler() API of IBTSecurity interface.
Note that in order to configure and initiate Bluetooth security procedures, APIs from IBTSecurity interface should be used.

Usage

Usage example:



   ===== To create an IBTSecurityHandler object, create IBTSecurity interface
         IBTSecurity_GetSecurityHandler (piBTSecurity, 
                                      &(ppiBTSecurityHndlr));
  
   ===== To register signal
   // first create the signals;
   // for example, use ISignalCBFactory_CreateSignal()
   // then register the signals:
   IBTSecurityHandler_OnEventNotify (ppiBTSecurityHndlr, piSignal);

   
   ===== To set remote OOB Data with Bluetooth driver
   IBTSecurityHandler_SetRemoteOOBData (piBTSecurityHndlr,
                                        &remoteOOB      // Remote OOB data buffer
                                        remoteOOBLen ); // size of data in bytes 
                        
   ===== To send a request to get the local OOB data,  
   IBTSecurityHandler_GetLocalOOBData (piBTSecurityHndlr);

                              
   ===== To retrieve and handle events when Event signal is triggered:
   while( IBTSecurityHandler_GetEvent (piBTSecurityHndlr, &eventData) 
        != AEE_ENOMORE )
   {
      switch( eventData.event )
      {
       case AEEBTSEC_HNDLR_EV_PASS_KEY_REQ:
         // Request to enter Passkey for the authentication procedure 
         //  eventData.bdAddr will have the BDaddress of remote device

         // Notify user to enter Passkey
         // While user entering the passkey, send the key press notification
         // by calling
         IBTSecurityHandler_KeyPressNotification
                     (piBTSecurityHndlr, 
                    &bdAddr,  // BD Address
                    AEEBTSEC_PASSKEY_DIGIT_ENTERED); // key press type. 

         // once user is done with entering passkey
         IBTSecurityHandler_PassKeyReply (piBTSecurityHndlr, 
                                         &bdAddr, 
                                         passkey,
                                         TRUE);

         // To send a negative reply to passkey request  
         IBTSecurityHandler_PassKeyReply (piBTSecurityHndlr, 
                                          &bdAddr, 
                                           0,
                                           FALSE);
       break;
                                    
       case AEEBTSEC_HNDLR_EV_PIN_KEY_REQ:
         // Notify user to enter Passkey.
         // once the user completes entering Pin key, call
         // IBTSecurityHandler_PinKeyReply (piBTSecurityHndlr, 
                                            &bdAddr, 
                                            pPasskey,      // Passkey
                                            nPinkeyLen ) // Length of passkey
                                
         // To send a negative reply to Pinkey request
          IBTSecurityHandler_PinKeyReply (piBTSecurityHndlr, 
                                          &bdAddr, 
                                          NULL, 
                                          0) ;   // zero len to reject
      
         break;
      
       case AEEBTSEC_HNDLR_EV_USER_CONF_REQ:
         // eventData.bdAddr will have the BDaddress of remote device
         // Retrieve the passkey from driver to display to the user
         // eventData.passKey has the passkey.
         // Display the passkey to user. Get the user confirmation (Yes/No)
         // send the user confirmation to remote
         IBTSecurityHandler_SendUserConfirmation(piBTSecurityHndlr,
                                                  &bdAddr, // Remote BDAddr
                                                   TRUE) ;  // passkeys on both
                                                            // sides match.
         break;

         case AEEBTSEC_HNDLR_EV_PASSKEY_NOTIFICATION:
         // eventData.bdAddr will have the BDaddress of remote device
         // Retrieve the passkey from driver to display to the user
         // eventData.passKey has the passkey.
         // Display the passkey to user. Ask the user to enter the 
         // same passkey on the remote device
         // send the user confirmation to remote
         IBTSecurityHandler_SendUserConfirmation(piBTSecurityHndlr,
                                             &bdAddr, // Remote BDAddr
                    TRUE) ;  // passkeys on both
                                                           // sides match.
       case AEEBTSEC_HNDLR_EV_AUTHORIZE_BOND;
         // Request to authorize bond request. 
         // eventData.bdAddr has the BD Address of remote device
         // Authorize/Reject the bond  request by calling 
         IBTSecurityHandler_Authorizebond(piBTSecurityHndlr, 
                                          &bdAddr,
                                          AEEBT_SEC_HIGH, // Security level for bonding
                                          TRUE); //TRUE: Authorize
         break;
       
       case AEEBTSEC_HNDLR_EV_AUTHORIZE_REBOND;
         // Request to authorize a re-bond request. 
         // eventData.bdAddr has the BD Address of remote device
         // Authorize/Reject the rebond  request by calling 
         IBTSecurityHandler_AuthorizeRebond(piBTSecurityHndlr, 
                                            &bdAddr,
                                            AEEBT_SEC_HIGH, // Security level for rebonding
                                            TRUE); //TRUE: Authorize
         break;
       
       case AEEBTSEC_HNDLR_EV_REMOTE_BOND_DONE;
         // Bond operation initiated by Remote device is complete
         // eventData.bdAddr has the BD Address of remote device
         // eventData.cResult has the result of the operation.
         break;
             
       case AEEBTSEC_HNDLR_EV_SVC_CONN_REQ:
         // service level Connection request. eventData.bdAddress has the BD address of
         // remote. Retrieve the connection request info by calling
         IBTSecurityHandler_RetrieveSvcConnReqInfo (piBTSecurityHndlr,
                                                   &bdAddr, 
                                                  &serviceID); 
         // To authorize the service level connection 
         IBTSecurityHandler_AuthorizeSvcConnection (piBTSecurityHndlr,
                                                    &bdAddr, // remote BDAddr
                                                    pSvcID,  // Service identifier
                                                    TRUE);   // TRUE :Authorize
         break;
       
       case AEEBTSEC_HNDLR_EV_GET_LOCAL_OOB_DONE:
         // Local OOB data is ready to be retrieved. To retrieve the OOB data
         IBTSecurityHandler_RetrieveLocalOOBData (piBTSecurityHndlr,
                                         pLocalOOB,  // Buffer to fill in with OOB data
                                         len,        // Length of the buffer
                                         lenRequired);// Actual length of the OOB data
       break; 

      case AEEBTSEC_HNDLR_EV_KEY_PRESS_NOTIFICATION:
          // A key has been pressed in remote device display. Event will arrive during
            // Pairing using Passkey key entry association model
            // eventData.keyPress will have the details of the remote key press type. 
            // Based on the key press type, update the display. 
         break;
   
       case AEEBTSEC_HNDLR_EV_EVENT_Q_OVERFLOW:
         // Missed some events.
         break;
      }
   }
ISignalCtl_Enable (piSignalCtl); // re-enable signal

===== When done with IBTSecurityHndlr object:
IBTSecurityHandler_Release (piBTSecurityHndlr);