cancel
Showing results for 
Search instead for 
Did you mean: 

Knowledge Base Articles

Handling GATT attribute security permissions requirements in Bluetooth® LE – KBA233955

Chelladurai
Community Manager
Community Manager

Handling GATT attribute security permissions requirements in Bluetooth® LE – KBA233955

Version: **

According to the Bluetooth® spec (3.2.5 Version 5.2 | Vol 3, Part F), attribute permissions are a combination of access permissions, encryption permissions, authentication permissions, and authorization permissions. These ensure that the peer device cannot access (read and/or write access, as well as notification and /or indication) an attribute if the required level of security was not achieved during the pairing process.

You can set the security requirements on the GATT attribute using the GATT Settings tab of the Bluetooth® configurator as shown in Figure 1, which shows the permission settings on the Client Characteristic Configuration Descriptor (CCCD). You can set the read/write permissions and the security permissions such as Read authentication required or Write authentication required.

Chelladurai_0-1632812709245.png

Figure 1. Client Characteristic Configuration

The Read authentication required or Write authentication parameter means that either authentication or encryption is required to access (read or write) that characteristic. The Infineon Bluetooth® host stack does not differentiate between these two security permissions. However, if you want to specifically set either authentication required or encryption required or both, you can use the options in the Bluetooth® stack to differentiate these two permissions and send error responses accordingly.

  1. Choose the Read/ Write authentication required checkbox if you want authentication or encryption.
  2. After successful pairing, use the wiced_bt_ble_get_security_state() function to determine  the security level of the current connection. This function returns the type of security that was used for the connection using the flags in the
    *p_le_sec_flags enum as follows:

    enum wiced_bt_ble_sec_flags_e
    {
        BTM_SEC_LE_LINK_ENCRYPTED           = 0x01,     /* Link encrypted */
        BTM_SEC_LE_LINK_PAIRED_WITHOUT_MITM = 0x02,     /* Paired without man-in-the-middle protection */
        BTM_SEC_LE_LINK_PAIRED_WITH_MITM    = 0x04      /* Link with man-in-the-middle protection */
    };

    Multiple flags can be set at the same time by the API; for example, you can have encryption with MITM protection or encryption without MITM protection. You also get the key size of encryption using the p_le_key_size parameter.

  3. When a read or write request is received, check if that handle requires read/write authentication or encryption.

    wiced_bt_gatt_server_send_error_rsp() function and pass the appropriate status response as follows:

    • WICED_BT_GATT_INSUF_AUTHENTICATION
    • WICED_BT_GATT_INSUF_ENCRYPTION
    • WICED_BT_GATT_INSUF_KEY_SIZE

These error codes are part of the enum wiced_bt_gatt_status_e in wiced_bt_gatt.h.

1.     Sample Implementation

1.1   Read Authentication required:

Assume that you want read authentication for reading the CCCD value of the Battery Level characteristic. In the read handler, implement the code snippet similar to the following:

wiced_bt_ble_get_security_state(bd_addr, &sec_flags, &key_size);

wiced_bt_gatt_read_t *p_read_req  = p_data->attribute_request.data.read_req;                                                      

if(handle == HDLD_BAS_BATTERY_LEVEL_CLIENT_CHAR_CONFIG)
       {
            /* Requires read authentication */
            if((sec_flags & BTM_SEC_LE_LINK_PAIRED_WITH_MITM) == 0)
            {
/* Authentication not achieved, send INSUF_AUTHENTICATION error to the peer device */
 wiced_bt_gatt_server_send_error_rsp(conn_id, opcode, p_read_req->handle,
WICED_BT_GATT_INSUF_AUTHENTICATION);
            }
      }

1.2  Write Encryption required:

wiced_bt_ble_get_security_state(bd_addr, &sec_flags, &key_size);

       if(attr_handle == HDLD_BAS_BATTERY_LEVEL_CLIENT_CHAR_CONFIG)
       {
             /* Requires encryption */
             if((sec_flags & BTM_SEC_LE_LINK_ENCRYPTED) == 0)
            {
       /* Encryption not achieved, send INSUF_ENCRYPTION error to the peer device */
        wiced_bt_gatt_server_send_error_rsp(conn_id, opcode, handle, WICED_BT_GATT_INSUF_ENCRYPTION);
             }
}

0 Likes
Version history
Revision #:
1 of 1
Last update:
‎Sep 28, 2021 12:24 AM
Updated by:
 
Contributors