Skip to content

Pairing Agents in BlueZ stack

Introduction

This technical note describes the pairing process between two Bluetooth devices explaining the role of Agent objects in BlueZ stack.

Bluetoothd

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 is /etc/bluetooth/main.conf.

D-Bus API

bluetoothd exposes D-Bus API to allow external processes to act as Agents and manage pairing mechanisms. BlueZ Agent objects APIs provide methods for:

  1. Creation and registration of an Agent
  2. Setting the Agent capability, that is the kind of pairing mechanism
  3. Setting a previously registered Agent as default
  4. 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:

  1. DisplayOnly or DisplayYesNo : authentication by PIN/passkey code
  2. KeyboardOnly or KeyboardDisplay : yes/no choice to the pairing attempt
  3. NoInputNoOutput : no user confirmation

Available BlueZ Agents

There are several BlueZ agents, we will briefly present three of them:

  • built-in Agent in bluetoothctl
  • simple-agent
  • bt-agent

Bluetoothctl

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

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 with:

$ ./simple-agent -c NoInputNoOutput

bt-agent tool

bt-agent is a tool part of the bluez-tools suite. We can set the capability of bt-agent with:

$ bt-agent --capability=NoInputNoOutput