Wiki Navigation

Description

The purpose of bonding is to create a relation between two Bluetooth devices based on a common link key (a bond). The link key is created and exchanged(pairing) during the bonding procedure and is expected to be stored by both Bluetooth devices, to be used for future authentication[definition from Bluetooth Core Spec].

The Bonding procedure is done through the BlueZ Adapter interface.

Development warnings/recommendations

Just one Bonding request per time is allowed.
Bonding is not allowed if there is a discovery running.
Pending remote name is canceled if a CreateBonding message is received.
The Bonding takes some seconds, therefore it is recommended set a D-Bus callback to handle the message reply for this operation.

Passkey Agent

Currently, two types of passkey agents are supported:

Device Specific: handles all passkey requests for a given remote device
Default: Handles the remaining requests(not addressed by device specific agents)

For more information check the BlueZ D-Bus API and implementation references:

utils/daemon/passkey-agent.c is a passkey agent implementation able to handle device specific and default
bluez-gnome passkey agent implementation distributed by the BlueZ community

Canceling

Canceling a Bonding procedure is a trick task. Two scenarios can happen, the BlueZ daemon can be waiting the passkey from the Passkey Agent or it can be waiting the response from the remote device. If the first scenario is detected, the a "PIN Code Negative Reply" is sent to the Host Controller. If the second scenario is detected, nothing can be done, a "NotAuthorized" error is returned.

For security reason, only the CreateBonding requestor can cancel a pending bonding operation.

Removing Bondings

When calling RemoveBonding the user must be aware that the remote device will be disconnected(if applied) due security reasons. When the operation is succeeded a BondingRemoved signal is sent.

This method will remove the link key stored in the file system(/var/lib/bluetooth/xx:xx:xx:xx:xx:xx/linkkeys) and the key stored in the Bluetooth chip(key stored using HCI_Write_Stored_Link_Key).

Listening Signals

The following python example shows how catch BondingCreated and BondingRemoved D-Bus signals:

import dbus
import dbus.glib
import gobject

def bonding_created_signal(address):
        print 'Signal: BondingCreated(%s)' % address

def bonding_removed_signal(address):
        print 'Signal: BondingRemoved(%s)' % address

bus = dbus.SystemBus();

bus.add_signal_receiver(bonding_created_signal, 'BondingCreated', 'org.bluez.Adapter', 'org.bluez', '/org/bluez/hci0')
bus.add_signal_receiver(bonding_removed_signal, 'BondingRemoved', 'org.bluez.Adapter', 'org.bluez', '/org/bluez/hci0')

main_loop = gobject.MainLoop()
main_loop.run()

Common errors

No passkey agent registered: open the syslog file and search for the following pattern: "hcid[4179]: Default passkey agent (:1.8, /org/bluez/passkey) registered"
If you don't have a passkey agent application, the following examples are available:
- bluez-passkey-gnome: gnome package
- bluez-gnome: http://www.bluez.org/download.html
- passkey-agent: under the directory utils/daemon
Authentication Rejected error: If you receive this D-Bus error message, it means that you don't have a Passkey Agent registered or the remote device rejected your request

Request Bonding examples

Python

import dbus
bus = dbus.SystemBus();
obj = bus.get_object('org.bluez', '/org/bluez/hci0')
adapter = dbus.Interface(obj, 'org.bluez.Adapter')

print adapter.CreateBonding('AA:BB:CC:DD:EE:FF')

This is a simple(blocking) example how request bonding creation. Use the D-Bus asynchronous calls setting the reply_hander and error_handler to improve this example.

dbus-send

The following command lines show how use dbus-send app to create or remove a bonding:

$dbus-send --system --type=method_call --print-reply --dest=org.bluez /org/bluez/hci0 org.bluez.Adapter.CreateBonding string:AA:BB:CC:DD:EE:FF
$dbus-send --system --type=method_call --print-reply --dest=org.bluez /org/bluez/hci0 org.bluez.Adapter.RemoveBonding string:AA:BB:CC:DD:EE:FF

Understanding the hcidump

The following dump represents the wrong passkey scenario:

< HCI Command: Authentication Requested (0x01|0x0011) plen 2 ==> Triggered by CreateBonding
    handle 41
> HCI Event: Command Status (0x0f) plen 4
    Authentication Requested (0x01|0x0011) status 0x00 ncmd 1
> HCI Event: Link Key Request (0x17) plen 6
    bdaddr 00:19:4F:DB:04:40
< HCI Command: Link Key Request Negative Reply (0x01|0x000c) plen 6 ==> hcid was not able to find a stored link key
    bdaddr 00:19:4F:DB:04:40
> HCI Event: Command Complete (0x0e) plen 10
    Link Key Request Negative Reply (0x01|0x000c) ncmd 1
    status 0x00 bdaddr 00:19:4F:DB:04:40
> HCI Event: PIN Code Request (0x16) plen 6 ==> hcid will ask for passkey(calling the passkey agent)
    bdaddr 00:19:4F:DB:04:40
   ... waiting the org.bluez.PasskeyAgent.Request reply
< HCI Command: PIN Code Request Reply (0x01|0x000d) plen 23
    bdaddr 00:19:4F:DB:04:40 len 4 pin '1234'
> HCI Event: Command Complete (0x0e) plen 10
    PIN Code Request Reply (0x01|0x000d) ncmd 1
    status 0x00 bdaddr 00:19:4F:DB:04:40
    ... waiting the remote device passkey
> HCI Event: Auth Complete (0x06) plen 3 ==> the remote device typed a wrong passkey
    status 0x05 handle 41
    Error: Authentication Failure

The following dump represents: no passkey agent available or rejection

< HCI Command: Authentication Requested (0x01|0x0011) plen 2  ==> Triggered by CreateBonding
    handle 41
> HCI Event: Command Status (0x0f) plen 4
    Authentication Requested (0x01|0x0011) status 0x00 ncmd 1
> HCI Event: Link Key Request (0x17) plen 6
    bdaddr 00:19:4F:DB:04:40
< HCI Command: Link Key Request Negative Reply (0x01|0x000c) plen 6 ==> hcid was not able to find a stored link key
    bdaddr 00:19:4F:DB:04:40
> HCI Event: Command Complete (0x0e) plen 10
    Link Key Request Negative Reply (0x01|0x000c) ncmd 1
    status 0x00 bdaddr 00:19:4F:DB:04:40
> HCI Event: PIN Code Request (0x16) plen 6 ==> hcid will ask for passkey(calling the passkey agent)
    bdaddr 00:19:4F:DB:04:40
< HCI Command: PIN Code Request Negative Reply (0x01|0x000e) plen 6 ==> no passkey agent available or the user rejected
    bdaddr 00:19:4F:DB:04:40
> HCI Event: Command Complete (0x0e) plen 10
    PIN Code Request Negative Reply (0x01|0x000e) ncmd 1
    status 0x00 bdaddr 00:19:4F:DB:04:40
> HCI Event: Auth Complete (0x06) plen 3
    status 0x06 handle 41
    Error: PIN or Key Missing

Download in other formats:

Plain Text