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:

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:

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

At a glance

Topic: BlueZ pairing agents · Interface: D-Bus API · Platform: Linux / Android with BlueZ stack

This article explains how BlueZ uses Agent objects to handle Bluetooth pairing and connection authorization. Learn how to register agents, set pairing capabilities, and use built-in agents like bluetoothctl, simple-agent, and bt-agent.

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

Frequently Asked Questions¶

What is a BlueZ pairing agent?¶

A BlueZ pairing agent is an external process that registers with the bluetoothd daemon via the D-Bus API to handle Bluetooth pairing and connection authorization. Agents declare an IO capability (such as NoInputNoOutput or KeyboardDisplay) that tells BlueZ which authentication methods the device supports, and implement callbacks to accept or reject pairing and connection requests.

How do I register a custom pairing agent in BlueZ?¶

Custom pairing agents are registered by calling the RegisterAgent method on BlueZ's org.bluez.AgentManager1 D-Bus interface, passing the agent's object path and its IO capability string. Once registered, call RequestDefaultAgent to make it the default. BlueZ will then invoke your agent's D-Bus methods (such as RequestConfirmation or AuthorizeService) whenever a pairing or authorization event occurs.

What are the available IO capabilities for BlueZ agents?¶

BlueZ agents support five IO capability strings: DisplayOnly (can show a passkey but not accept input), DisplayYesNo (can show a passkey and confirm yes/no), KeyboardOnly (can accept keyboard input but not display), KeyboardDisplay (can both display a passkey and accept input — the default for simple-agent), and NoInputNoOutput (no user interaction possible, falls back to Just Works pairing).

What is the difference between bluetoothctl and simple-agent?¶

bluetoothctl is an interactive command-line client for bluetoothd that includes a built-in agent, but the agent is unregistered as soon as bluetoothctl exits, making it unsuitable for long-running or automated scenarios. simple-agent is a standalone Python script from the BlueZ test suite that registers an agent with a configurable capability and keeps it running as a daemon, making it more suitable for headless embedded environments.

How does BlueZ handle incoming connection authorization?¶

When a remote device attempts to connect to a service, bluetoothd calls the AuthorizeService method on the registered default agent, passing the device address and the service UUID. The agent can allow or deny the connection by returning normally or raising an org.bluez.Error.Rejected D-Bus error. If no agent is registered, BlueZ applies its default built-in authorization policy.