LE Peripheral - Test Pairing Methods
Source Code: sm_pairing_peripheral.c
Depending on the Authentication requiremens and IO Capabilities, the pairing process uses different short and long term key generation method. This example helps explore the different options incl. LE Secure Connections.
Main Application Setup
Listing here shows main application code. It initializes L2CAP, the Security Manager and configures the ATT Server with the pre-compiled ATT Database generated from $sm_pairing_peripheral.gatt$. Finally, it configures the advertisements and boots the Bluetooth stack. In this example, the Advertisement contains the Flags attribute, the device name, and a 16-bit (test) service 0x1111 The flag 0x06 indicates: LE General Discoverable Mode and BR/EDR not supported. Various examples for IO Capabilites and Authentication Requirements are given below.
static btstack_packet_callback_registration_t sm_event_callback_registration;
static btstack_packet_callback_registration_t hci_event_callback_registration;
static void sm_packet_handler (uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size);
static void hci_packet_handler(uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size);
const uint8_t adv_data[] = {
// Flags general discoverable, BR/EDR not supported
0x02, BLUETOOTH_DATA_TYPE_FLAGS, 0x06,
// Name
0x0b, BLUETOOTH_DATA_TYPE_COMPLETE_LOCAL_NAME, 'S', 'M', ' ', 'P', 'a', 'i', 'r', 'i', 'n', 'g',
// Incomplete List of 16-bit Service Class UUIDs -- 1111 - only valid for testing!
0x03, BLUETOOTH_DATA_TYPE_INCOMPLETE_LIST_OF_16_BIT_SERVICE_CLASS_UUIDS, 0x11, 0x11,
};
const uint8_t adv_data_len = sizeof(adv_data);
static void sm_peripheral_setup(void){
<a href="https://github.com/bluekitchen/btstack/blob/develop/src/l2cap.h#L477">l2cap_init</a>();
// setup SM: Display only
<a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L68">sm_init</a>();
// setup ATT server
<a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/att_server.h#L80">att_server_init</a>(profile_data, NULL, NULL);
// setup GATT Client
<a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/gatt_client.h#L359">gatt_client_init</a>();
// setup advertisements
uint16_t adv_int_min = 0x0030;
uint16_t adv_int_max = 0x0030;
uint8_t adv_type = 0;
bd_addr_t null_addr;
memset(null_addr, 0, 6);
<a href="https://github.com/bluekitchen/btstack/blob/develop/src/gap.h#L714">gap_advertisements_set_params</a>(adv_int_min, adv_int_max, adv_type, 0, null_addr, 0x07, 0x00);
<a href="https://github.com/bluekitchen/btstack/blob/develop/src/gap.h#L701">gap_advertisements_set_data</a>(adv_data_len, (uint8_t*) adv_data);
<a href="https://github.com/bluekitchen/btstack/blob/develop/src/gap.h#L721">gap_advertisements_enable</a>(1);
// register handler
hci_event_callback_registration.callback = &hci_packet_handler;
<a href="https://github.com/bluekitchen/btstack/blob/develop/src/hci.h#L1580">hci_add_event_handler</a>(&hci_event_callback_registration);
sm_event_callback_registration.callback = &sm_packet_handler;
<a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L94">sm_add_event_handler</a>(&sm_event_callback_registration);
// Configuration
// Enable mandatory authentication for GATT Client
// - if un-encrypted connections are not supported, e.g. when connecting to own device, this enforces authentication
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/gatt_client.h#L373">gatt_client_set_required_security_level</a>(LEVEL_2);
/**
* Choose ONE of the following configurations
* Bonding is disabled to allow for repeated testing. It can be enabled by or'ing
* SM_AUTHREQ_BONDING to the authentication requirements like this:
* <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L119">sm_set_authentication_requirements</a>( X | SM_AUTHREQ_BONDING)
// LE Legacy Pairing, Just Works
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L131">sm_set_secure_connections_only_mode</a>(false);
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L125">sm_set_io_capabilities</a>(IO_CAPABILITY_NO_INPUT_NO_OUTPUT);
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L119">sm_set_authentication_requirements</a>(0);
// LE Legacy Pairing, Passkey entry initiator enter, responder (us) displays
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L131">sm_set_secure_connections_only_mode</a>(false);
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L125">sm_set_io_capabilities</a>(IO_CAPABILITY_DISPLAY_ONLY);
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L119">sm_set_authentication_requirements</a>(SM_AUTHREQ_MITM_PROTECTION);
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L256">sm_use_fixed_passkey_in_display_role</a>(123456);
#ifdef ENABLE_LE_SECURE_CONNECTIONS
// LE Secure Connections, Just Works
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L125">sm_set_io_capabilities</a>(IO_CAPABILITY_NO_INPUT_NO_OUTPUT);
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L119">sm_set_authentication_requirements</a>(SM_AUTHREQ_SECURE_CONNECTION);
// LE Secure Connections, Numeric Comparison
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L125">sm_set_io_capabilities</a>(IO_CAPABILITY_DISPLAY_YES_NO);
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L119">sm_set_authentication_requirements</a>(SM_AUTHREQ_SECURE_CONNECTION|SM_AUTHREQ_MITM_PROTECTION);
// LE Secure Pairing, Passkey entry initiator enter, responder (us) displays
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L125">sm_set_io_capabilities</a>(IO_CAPABILITY_DISPLAY_ONLY);
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L119">sm_set_authentication_requirements</a>(SM_AUTHREQ_SECURE_CONNECTION|SM_AUTHREQ_MITM_PROTECTION);
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L256">sm_use_fixed_passkey_in_display_role</a>(123456);
// LE Secure Pairing, Passkey entry initiator displays, responder (us) enter
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L125">sm_set_io_capabilities</a>(IO_CAPABILITY_KEYBOARD_ONLY);
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L119">sm_set_authentication_requirements</a>(SM_AUTHREQ_SECURE_CONNECTION|SM_AUTHREQ_MITM_PROTECTION);
#endif
}
Security Manager Packet Handler
The packet handler is used to handle Security Manager events
HCI Packet Handler
static void sm_packet_handler (uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size){
UNUSED(channel);
UNUSED(size);
if (packet_type != HCI_EVENT_PACKET) return;
hci_con_handle_t con_handle;
bd_addr_t addr;
bd_addr_type_t addr_type;
uint8_t status;
switch (hci_event_packet_get_type(packet)) {
case HCI_EVENT_META_GAP:
switch (hci_event_gap_meta_get_subevent_code(packet)) {
case GAP_SUBEVENT_LE_CONNECTION_COMPLETE:
printf("Connection complete\n");
con_handle = gap_subevent_le_connection_complete_get_connection_handle(packet);
UNUSED(con_handle);
// for testing, choose one of the following actions
// manually start pairing
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L182">sm_request_pairing</a>(con_handle);
// gatt client request to authenticated characteristic in sm_pairing_central (short cut, uses hard-coded value handle)
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/gatt_client.h#L692">gatt_client_read_value_of_characteristic</a>_using_value_handle(&packet_handler, con_handle, 0x0009);
// general gatt client request to trigger mandatory authentication
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/gatt_client.h#L448">gatt_client_discover_primary_services</a>(&packet_handler, con_handle);
break;
default:
break;
}
break;
case SM_EVENT_JUST_WORKS_REQUEST:
printf("Just Works requested\n");
<a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L156">sm_just_works_confirm</a>(sm_event_just_works_request_get_handle(packet));
break;
case SM_EVENT_NUMERIC_COMPARISON_REQUEST:
printf("Confirming numeric comparison: %"PRIu32"\n", sm_event_numeric_comparison_request_get_passkey(packet));
<a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L162">sm_numeric_comparison_confirm</a>(sm_event_passkey_display_number_get_handle(packet));
break;
case SM_EVENT_PASSKEY_DISPLAY_NUMBER:
printf("Display Passkey: %"PRIu32"\n", sm_event_passkey_display_number_get_passkey(packet));
break;
case SM_EVENT_IDENTITY_CREATED:
sm_event_identity_created_get_identity_address(packet, addr);
printf("Identity created: type %u address %s\n", sm_event_identity_created_get_identity_addr_type(packet), <a href="https://github.com/bluekitchen/btstack/blob/develop/src/btstack_util.h#L271">bd_addr_to_str</a>(addr));
break;
case SM_EVENT_IDENTITY_RESOLVING_SUCCEEDED:
sm_event_identity_resolving_succeeded_get_identity_address(packet, addr);
printf("Identity resolved: type %u address %s\n", sm_event_identity_resolving_succeeded_get_identity_addr_type(packet), <a href="https://github.com/bluekitchen/btstack/blob/develop/src/btstack_util.h#L271">bd_addr_to_str</a>(addr));
break;
case SM_EVENT_IDENTITY_RESOLVING_FAILED:
sm_event_identity_created_get_address(packet, addr);
printf("Identity resolving failed\n");
break;
case SM_EVENT_PAIRING_STARTED:
printf("Pairing started\n");
break;
case SM_EVENT_PAIRING_COMPLETE:
switch (sm_event_pairing_complete_get_status(packet)){
case ERROR_CODE_SUCCESS:
printf("Pairing complete, success. CTKD active %u\n", sm_event_pairing_complete_get_ctkd_active(packet));
break;
case ERROR_CODE_CONNECTION_TIMEOUT:
printf("Pairing failed, timeout\n");
break;
case ERROR_CODE_REMOTE_USER_TERMINATED_CONNECTION:
printf("Pairing failed, disconnected\n");
break;
case ERROR_CODE_AUTHENTICATION_FAILURE:
printf("Pairing failed, authentication failure with reason = %u\n", sm_event_pairing_complete_get_reason(packet));
break;
default:
break;
}
break;
case SM_EVENT_REENCRYPTION_STARTED:
sm_event_reencryption_complete_get_address(packet, addr);
printf("Bonding information exists for addr type %u, identity addr %s -> re-encryption started\n",
sm_event_reencryption_started_get_addr_type(packet), <a href="https://github.com/bluekitchen/btstack/blob/develop/src/btstack_util.h#L271">bd_addr_to_str</a>(addr));
break;
case SM_EVENT_REENCRYPTION_COMPLETE:
switch (sm_event_reencryption_complete_get_status(packet)){
case ERROR_CODE_SUCCESS:
printf("Re-encryption complete, success\n");
break;
case ERROR_CODE_CONNECTION_TIMEOUT:
printf("Re-encryption failed, timeout\n");
break;
case ERROR_CODE_REMOTE_USER_TERMINATED_CONNECTION:
printf("Re-encryption failed, disconnected\n");
break;
case ERROR_CODE_PIN_OR_KEY_MISSING:
printf("Re-encryption failed, bonding information missing\n\n");
printf("Assuming remote lost bonding information\n");
printf("Deleting local bonding information to allow for new pairing...\n");
sm_event_reencryption_complete_get_address(packet, addr);
addr_type = sm_event_reencryption_started_get_addr_type(packet);
<a href="https://github.com/bluekitchen/btstack/blob/develop/src/gap.h#L1562">gap_delete_bonding</a>(addr_type, addr);
break;
default:
break;
}
break;
case GATT_EVENT_QUERY_COMPLETE:
status = gatt_event_query_complete_get_att_status(packet);
switch (status){
case ATT_ERROR_INSUFFICIENT_ENCRYPTION:
printf("GATT Query failed, Insufficient Encryption\n");
break;
case ATT_ERROR_INSUFFICIENT_AUTHENTICATION:
printf("GATT Query failed, Insufficient Authentication\n");
break;
case ATT_ERROR_BONDING_INFORMATION_MISSING:
printf("GATT Query failed, Bonding Information Missing\n");
break;
case ATT_ERROR_SUCCESS:
printf("GATT Query successful\n");
break;
default:
printf("GATT Query failed, status 0x%02x\n", gatt_event_query_complete_get_att_status(packet));
break;
}
break;
default:
break;
}
}
/*
*
static void hci_packet_handler (uint8_t packet_type, uint16_t channel, uint8_t *packet, uint16_t size){
UNUSED(channel);
UNUSED(size);
if (packet_type != HCI_EVENT_PACKET) return;
hci_con_handle_t con_handle;
switch (hci_event_packet_get_type(packet)) {
case HCI_EVENT_META_GAP:
switch (hci_event_gap_meta_get_subevent_code(packet)) {
case GAP_SUBEVENT_LE_CONNECTION_COMPLETE:
printf("Connection complete\n");
con_handle = gap_subevent_le_connection_complete_get_connection_handle(packet);
UNUSED(con_handle);
// for testing, choose one of the following actions
// manually start pairing
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/sm.h#L182">sm_request_pairing</a>(con_handle);
// gatt client request to authenticated characteristic in sm_pairing_central (short cut, uses hard-coded value handle)
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/gatt_client.h#L692">gatt_client_read_value_of_characteristic</a>_using_value_handle(&packet_handler, con_handle, 0x0009);
// general gatt client request to trigger mandatory authentication
// <a href="https://github.com/bluekitchen/btstack/blob/develop/src/ble/gatt_client.h#L448">gatt_client_discover_primary_services</a>(&packet_handler, con_handle);
break;
default:
break;
}
break;
default:
break;
}
}
The packet handler is used to handle new connections, can trigger Security Request