Pairing Agents in BlueZ stack¶
Edited by Marta Todeschini
This technical note describes the pairing process between two Bluetooth devices explaining the role of Agent objects in BlueZ stack.
Pairing is the process for establishing a bond between two Bluetooth devices, exchanging a shared secret that allows to establish subsequent connections flawlessly.
bluetoothd is the BlueZ daemon which implements the Bluetooth stack.
BlueZ requires the registration of Agent objects to handle pairing and incoming connection authorization between devices. Bluez allows the registration of multiple Agents, and one of them can be selected as default.
The configuration file for
bluetoothd exposes D-Bus API to allow external processes to act as Agents and manage pairing mechanisms. BlueZ Agent objects APIs provide methods for:
- Creation and registration of an Agent
- Setting the Agent capability, that is the kind of pairing mechanism
- Setting a previously registered Agent as default
- Accepting or rejecting connection requests, based on the policy of the Agent that is used
In particular, Agent's capability indicates how the authentication of two devices during the pairing process must be confirmed. Due to the nature and variety of Bluetooth devices, the value for capability can be:
DisplayYesNo: authentication by PIN/passkey code
KeyboardDisplay: yes/no choice to the pairing attempt
NoInputNoOutput: no user confirmation
Available BlueZ Agents¶
There are several BlueZ agents, we will briefly present three of them:
- built-in Agent in
Bluetoothctl is a client tool to interact with
bluetoothd from the command line. It can be used also to create Agent objects with a specific capability interactively or using command line options.
1) Using interactive commands¶
$ bluetoothctl Agent registered [bluetooth]# agent off Agent unregistered [bluetooth]# agent NoInputNoOutput Agent registered [bluetooth]# default-agent Default agent request successful
2) Using Bluetoothctl options¶
$ bluetoothctl --agent=NoInputNoOutput Agent registered [bluetooth]# default-agent Default agent request successful
The drawback of using Bluetoothctl is that closing the tool unregisters the Agent. The solution is to run Agents that can daemonized; the next sections provide two possible alternatives.
simple-agent is a Python script which is part of the tests in the BlueZ source code.
simple-agent creates and register a new Agent either with the capability passed as
--capability command line option or with the default
KeyboardDisplay capability if no associated option is passed.
We can set the capability of
$ ./simple-agent -c NoInputNoOutput
$ bt-agent --capability=NoInputNoOutput