[RFC] D-Bus API for out of band association model

[RFC] D-Bus API for out of band association model

[Andrzej Kaczmarek]

Hi,

On behalf of ST-Ericsson SA, below is our proposal of API for out of band
association model. To give you a bit more overview how this will be integrated
into BlueZ:

.RequestRemoteOobData should be called from hcid_dbus_request_io_cap to
check if any data was exchange/retrieved from remote device. Returned data
will be stored (if any) and used to reply with proper IO capabilities as well
as to to return retrieved data. This will involve some changes in flow from
io_capa_request onwards.

Please let me know if you have any comments. Implementation will follow.

BR,
Andrzej


---
 doc/adapter-api.txt |   14 ++++++++++++++
 doc/agent-api.txt   |   14 ++++++++++++++
 2 files changed, 28 insertions(+), 0 deletions(-)

diff --git a/doc/adapter-api.txt b/doc/adapter-api.txt
index 6098c76..0dd628e 100644
--- a/doc/adapter-api.txt
+++ b/doc/adapter-api.txt
@@ -5,6 +5,7 @@ Copyright (C) 2004-2010  Marcel Holtmann <marcel@holtmann.org>
 Copyright (C) 2005-2006  Johan Hedberg <johan.hedberg@nokia.com>
 Copyright (C) 2005-2006  Claudio Takahasi <claudio.takahasi@indt.org.br>
 Copyright (C) 2006-2007  Luiz von Dentz <luiz.dentz@indt.org.br>
+Copyright (C) 2010       ST-Ericsson SA <andrzej.kaczmarek@tieto.com>
 
 
 Adapter hierarchy
@@ -173,6 +174,19 @@ Methods		dict GetProperties()
 
 			Possible errors: org.bluez.Error.DoesNotExist
 
+		struct{
+			array{byte}, array{byte}
+		} GetLocalOobData()
+
+			Retrieves current C and R values used for out-of-band
+			bonding association model.
+
+			The return value is struct containing two arrays of
+			bytes, C and R values retrieved from local device.
+
+			Possible errors: org.bluez.Error.InProgress
+					 org.bluez.Error.Failed
+
 Signals		PropertyChanged(string name, variant value)
 
 			This signal indicates a changed value of the given
diff --git a/doc/agent-api.txt b/doc/agent-api.txt
index d8d35c0..323ccf1 100644
--- a/doc/agent-api.txt
+++ b/doc/agent-api.txt
@@ -3,6 +3,7 @@ BlueZ D-Bus Agent API description
 
 Copyright (C) 2004-2010  Marcel Holtmann <marcel@holtmann.org>
 Copyright (C) 2005-2006  Johan Hedberg <johan.hedberg@nokia.com>
+Copyright (C) 2010       ST-Ericsson SA <andrzej.kaczmarek@tieto.com>
 
 
 Agent hierarchy
@@ -68,6 +69,19 @@ Methods		void Release()
 			Possible errors: org.bluez.Error.Rejected
 			                 org.bluez.Error.Canceled
 
+		struct{
+			array{byte}, array{byte}
+		} RequestRemoteOobData(object device)
+
+			This method gets called when the service daemon
+			needs out-of-band data for an authentication.
+
+			The return value should be struct containing two
+			arrays of bytes, C and R values retrieved from
+			remote device.
+
+			Possible errors: org.bluez.Error.NoData
+
 		void Authorize(object device, string uuid)
 
 			This method gets called when the service daemon
-- 
1.7.0.4

Re: [RFC] D-Bus API for out of band association model

[Johan Hedberg]

Hi Andrzej,

On Wed, Sep 15, 2010, Andrzej Kaczmarek wrote:
> On behalf of ST-Ericsson SA, below is our proposal of API for out of band
> association model. To give you a bit more overview how this will be integrated
> into BlueZ:
> 
> .RequestRemoteOobData should be called from hcid_dbus_request_io_cap to
> check if any data was exchange/retrieved from remote device. Returned data
> will be stored (if any) and used to reply with proper IO capabilities as well
> as to to return retrieved data. This will involve some changes in flow from
> io_capa_request onwards.
> 
> Please let me know if you have any comments. Implementation will follow.

I'd prefer to do this completely internally in bluetoothd through a
plugin. Do you see any reasons why not to do it that way? We still need
some UI to call CreatePairedDevice but a plugin that knows about local
platform specific OOB mechanisms (e.g. NFC) could provide the core
daemon with enough info to set the IO capabilities correctly and provide
the necessary OOB values.

Johan

Re: [RFC] D-Bus API for out of band association model

[Claudio Takahasi]

On Wed, Sep 15, 2010 at 5:10 AM, Johan Hedberg <johan.hedberg@gmail.com> wrote:
> Hi Andrzej,
>
> On Wed, Sep 15, 2010, Andrzej Kaczmarek wrote:
>> On behalf of ST-Ericsson SA, below is our proposal of API for out of band
>> association model. To give you a bit more overview how this will be integrated
>> into BlueZ:
>>
>> .RequestRemoteOobData should be called from hcid_dbus_request_io_cap to
>> check if any data was exchange/retrieved from remote device. Returned data
>> will be stored (if any) and used to reply with proper IO capabilities as well
>> as to to return retrieved data. This will involve some changes in flow from
>> io_capa_request onwards.
>>
>> Please let me know if you have any comments. Implementation will follow.
>
> I'd prefer to do this completely internally in bluetoothd through a
> plugin. Do you see any reasons why not to do it that way? We still need
> some UI to call CreatePairedDevice but a plugin that knows about local
> platform specific OOB mechanisms (e.g. NFC) could provide the core
> daemon with enough info to set the IO capabilities correctly and provide
> the necessary OOB values.
>
> Johan
> --

Hi Andrzej,

I did some testing with OOB last year.
See my branch git://git.infradead.org/users/cktakahasi/bluez.git
oob-displayyesno

About the API changes. MAYBE, Hash and Randomizer could be only
adapter properties.
For the remote Hash and Randomizer still not clear to me what is the
best way to allow external apps to set those values, but in my opinion
BlueZ should not know the OOB mechanism, only the capability is
enough.

Regards,
Claudio

Re: [RFC] D-Bus API for out of band association model

[jaikumar Ganesh]

Hi,

On Wed, Sep 15, 2010 at 6:30 AM, Claudio Takahasi
<claudio.takahasi@openbossa.org> wrote:
> On Wed, Sep 15, 2010 at 5:10 AM, Johan Hedberg <johan.hedberg@gmail.com> wrote:
>> Hi Andrzej,
>>
>> On Wed, Sep 15, 2010, Andrzej Kaczmarek wrote:
>>> On behalf of ST-Ericsson SA, below is our proposal of API for out of band
>>> association model. To give you a bit more overview how this will be integrated
>>> into BlueZ:
>>>
>>> .RequestRemoteOobData should be called from hcid_dbus_request_io_cap to
>>> check if any data was exchange/retrieved from remote device. Returned data
>>> will be stored (if any) and used to reply with proper IO capabilities as well
>>> as to to return retrieved data. This will involve some changes in flow from
>>> io_capa_request onwards.
>>>
>>> Please let me know if you have any comments. Implementation will follow.
>>
>> I'd prefer to do this completely internally in bluetoothd through a
>> plugin. Do you see any reasons why not to do it that way? We still need
>> some UI to call CreatePairedDevice but a plugin that knows about local
>> platform specific OOB mechanisms (e.g. NFC) could provide the core
>> daemon with enough info to set the IO capabilities correctly and provide
>> the necessary OOB values.
>>
>> Johan
>> --
>
> Hi Andrzej,
>
> I did some testing with OOB last year.
> See my branch git://git.infradead.org/users/cktakahasi/bluez.git
> oob-displayyesno
>
> About the API changes. MAYBE, Hash and Randomizer could be only
> adapter properties.
> For the remote Hash and Randomizer still not clear to me what is the
> best way to allow external apps to set those values, but in my opinion
> BlueZ should not know the OOB mechanism, only the capability is
> enough.


[Resending, because the mail to linux-bluetooth bounced. Sorry if some
folks got it twice]

We started to work on this API too last week. Not complete yet to post
to the mailing list.
The approach we took was this:

 a) Since OOB authentication is just another means of authentication
compared to Passkey, Pin entry,
      we added an agent API (similar to the lines of other
authentication mechanisms) that will ask for the Out Of Band data.
b) We added an API to the adapter to get the local Out of Band Data
c) Currently, RegisterAgent is called to register with the
capabilities. Since OOB is part of the capabilities data structure, we
added OOB to agent structure which already has the capabilities.
d) We added an API variant of createPairedDevice which will be used
for OutOfBand Pairing. When the device agent is created, the OOB field
    in agent is updated.
e) When a capability request comes from the remote side the agent OOB
field is checked. It will be set if the pairing is initiated locally
through d).
    For incoming pairing requests if the Agent has OOB field set but
there is no device specific agent, we need to make an Agent API call
asking if
    there is OOB data for this remote device.

We left it to the users of the API - regarding the OOB channel to use.
It can be NFC or any other trusted channel.

Comments ?

Regards,
Jaikumar
>
> Regards,
> Claudio
> --
> To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>

Re: [RFC] D-Bus API for out of band association model

[Johan Hedberg]

Hi Jaikumar,

On Wed, Sep 15, 2010, jaikumar Ganesh wrote:
> We started to work on this API too last week. Not complete yet to post
> to the mailing list.
> The approach we took was this:
> 
>  a) Since OOB authentication is just another means of authentication
> compared to Passkey, Pin entry,
>       we added an agent API (similar to the lines of other
> authentication mechanisms) that will ask for the Out Of Band data.
> b) We added an API to the adapter to get the local Out of Band Data
> c) Currently, RegisterAgent is called to register with the
> capabilities. Since OOB is part of the capabilities data structure, we
> added OOB to agent structure which already has the capabilities.
> d) We added an API variant of createPairedDevice which will be used
> for OutOfBand Pairing. When the device agent is created, the OOB field
>     in agent is updated.
> e) When a capability request comes from the remote side the agent OOB
> field is checked. It will be set if the pairing is initiated locally
> through d).
>     For incoming pairing requests if the Agent has OOB field set but
> there is no device specific agent, we need to make an Agent API call
> asking if
>     there is OOB data for this remote device.
> 
> We left it to the users of the API - regarding the OOB channel to use.
> It can be NFC or any other trusted channel.
> 
> Comments ?

I'm still not convinced that the Agent is the right place for this. The
agent is typically representing the UI whereas in most cases (like NFC)
the OOB data will be coming from below bluetoothd in the software stack
and not from above it (which is where the agent resides). Also, the
presence of OOB data isn't really agent specific. It's something that
can come and go during the lifetime of an agent.

My idea has been to add a a plugin interface through which a hardware
specific plugin could notify the core daemon about the existence of OOB
data. bluetoothd would then take care of setting the right flag when it
gets a IO capability request. This doesn't of course rule out the
possibility of having part of the work done in another process since the
plugin could simply export a service over D-Bus or talk to another D-Bus
service.

Johan

Re: [RFC] D-Bus API for out of band association model

[jaikumar Ganesh]

Hi Johan:

On Wed, Sep 15, 2010 at 11:53 AM, Johan Hedberg <johan.hedberg@gmail.com> wrote:
> Hi Jaikumar,
>
> On Wed, Sep 15, 2010, jaikumar Ganesh wrote:
>> We started to work on this API too last week. Not complete yet to post
>> to the mailing list.
>> The approach we took was this:
>>
>>  a) Since OOB authentication is just another means of authentication
>> compared to Passkey, Pin entry,
>>       we added an agent API (similar to the lines of other
>> authentication mechanisms) that will ask for the Out Of Band data.
>> b) We added an API to the adapter to get the local Out of Band Data
>> c) Currently, RegisterAgent is called to register with the
>> capabilities. Since OOB is part of the capabilities data structure, we
>> added OOB to agent structure which already has the capabilities.
>> d) We added an API variant of createPairedDevice which will be used
>> for OutOfBand Pairing. When the device agent is created, the OOB field
>>     in agent is updated.
>> e) When a capability request comes from the remote side the agent OOB
>> field is checked. It will be set if the pairing is initiated locally
>> through d).
>>     For incoming pairing requests if the Agent has OOB field set but
>> there is no device specific agent, we need to make an Agent API call
>> asking if
>>     there is OOB data for this remote device.
>>
>> We left it to the users of the API - regarding the OOB channel to use.
>> It can be NFC or any other trusted channel.
>>
>> Comments ?
>
> I'm still not convinced that the Agent is the right place for this. The
> agent is typically representing the UI whereas in most cases (like NFC)
> the OOB data will be coming from below bluetoothd in the software stack
> and not from above it (which is where the agent resides). Also, the
> presence of OOB data isn't really agent specific. It's something that
> can come and go during the lifetime of an agent.

Consider a case where there is a third party app residing on the device.
This wants to initiate pairing and has OOB data. (here OOB data comes
from above bluetoothd)

When the remote request OOB data comes, bluetoothd asks the app for
the OOB data.

Depending on the implementation either the app can show a UI to the user
asking permission to pair when the OOB data Agent API is called. This is again
similar to what we have for the passkey mechanism.

This need of the UI and the fact that OOB data can come from above
bluetoothd (similar to pin entry)
is what made us go with the agent approach.

The device agent is removed when the device is unpaired. So next time
when pairing
happens depending upon the API used we can again have OOB pairing or
non OOB pairing.

Yes OOB data can come and go during the life of an agent. Hence we put
this burden on the users
of bluetoothd to supply bluetoothd if the OOB data. We not storing any
OOB data of the remote device
in bluetoothd


> My idea has been to add a a plugin interface through which a hardware
> specific plugin could notify the core daemon about the existence of OOB
> data. bluetoothd would then take care of setting the right flag when it
> gets a IO capability request. This doesn't of course rule out the
> possibility of having part of the work done in another process since the
> plugin could simply export a service over D-Bus or talk to another D-Bus
> service.

If I understand correctly, hardware specific plugin works well for
things like NFC.

What about cases where the trusted channel is say something like an
app running on
both the computer and the device. That channel is trusted using some
other authentication mechanism
The apps communicate to exchange OOB data.

For example, you can use the browser to device messaging mechanism
(Cloud to device messaging using Chrome).

>
> Johan
>

Re: [RFC] D-Bus API for out of band association model

[Andrzej Kaczmarek]

  Hi,

On 15.09.2010 20:53, Johan Hedberg wrote:
> I'm still not convinced that the Agent is the right place for this. The
> agent is typically representing the UI whereas in most cases (like NFC)
> the OOB data will be coming from below bluetoothd in the software stack
> and not from above it (which is where the agent resides).
In case of NFC I guess data will be coming from some application or 
perhaps a daemon which can understand data coming from lower layers, 
which I guess will rather process raw data. So these data will come from 
the same level as bluetoothd resides or above. This is something that 
agent can communicate freely with. Also from our point of view OOB data 
is used in the same way as i.e. passkey and this is what agent provides. 
We don't care how it will receive such data.
> Also, the
> presence of OOB data isn't really agent specific. It's something that
> can come and go during the lifetime of an agent
That's not a problem, agent should make use of interfaces published by 
applications which can provide secure channel. NFC application is one of 
examples.
Also Jakiumar gave quite good example where NFC application receives 
some data which is identified as BT OOB data so it initiates pairing 
with device specific agent which will provide these data.
> My idea has been to add a a plugin interface through which a hardware
> specific plugin could notify the core daemon about the existence of OOB
> data. bluetoothd would then take care of setting the right flag when it
> gets a IO capability request.
Do I understand correctly that also plugin or daemon should manage 
received data? Won't it make bluetoothd store unnecessary data, i.e. for 
devices we won't use anyway?
Also what in case we want to use several different secure channels? 
Multiple plugins? In case of agent, we make single call and no need to 
worry where the data come from. Agent is platform dependent anyway so 
platform vendor can put required logic there.
> This doesn't of course rule out the
> possibility of having part of the work done in another process since the
> plugin could simply export a service over D-Bus or talk to another D-Bus
> service.
I agree, such plugin can communicate with some other daemon/application 
to get data. So do agent. And in case of agent we're consistent that all 
bonding related data (pin, passkey, OOB...) are handled in one place 
which is an agent application.

BR,
Andrzej

Re: [RFC] D-Bus API for out of band association model

[Johan Hedberg]

Hi Andrzej,

It would be nice if you could use some empty lines in your replies. It
was quite hard to distinguish the quoted text from your own.

On Thu, Sep 16, 2010, Andrzej Kaczmarek wrote:
> In case of NFC I guess data will be coming from some application or
> perhaps a daemon which can understand data coming from lower layers,
> which I guess will rather process raw data. So these data will come
> from the same level as bluetoothd resides or above.

Agreed. It might also come from below if the plugin talks to some kernel
driver handling the OOB communication.

> This is something that agent can communicate freely with. Also from
> our point of view OOB data is used in the same way as i.e. passkey and
> this is what agent provides. We don't care how it will receive such
> data.

The same goes for the plugin approach. If we wanted to care about the
actual OOB mechanism the would be no need to abstract this and make it
pluggable.

> Also Jakiumar gave quite good example where NFC application receives
> some data which is identified as BT OOB data so it initiates pairing
> with device specific agent which will provide these data.

Agreed. I do see now that a D-Bus based approach might make more sense
in the end. On the other hand, we could still abstract this inside the
daemon for plugins, and then there'd simply be a special (default)
plugin that'd expose this over D-Bus.

> Do I understand correctly that also plugin or daemon should manage
> received data? Won't it make bluetoothd store unnecessary data, i.e.
> for devices we won't use anyway?

This would be completely implementation specific. It could be within the
daemon or delegated to some external component. The only certain thing
would be an interface for the core daemon to get the OOB data when it
gets an IO capability request.

> Also what in case we want to use several different secure channels?
> Multiple plugins?

Yes, that would be possible.

> In case of agent, we make single call and no need to worry where the
> data come from. Agent is platform dependent anyway so platform vendor
> can put required logic there.

Right, but at the same time it would also require you to multiplex all
potential available OOB methods through a single agent. So in that sense
the agent approach is more restrictive (with plugins we could at least
allow multiple of them).

One thing I'm quite concerned about is that I wouldn't want to add an
extra rountrip to an external process for every single IO capability
request that we get. This extra work should only be done if we know that
there's a non-zero probability for the existence of OOB data.

We could either have the agent tell bluetoothd about the OOB capability
somehow, or we could define some new sort of external "OOB data
provider" D-Bus object. The benefit of using a new object separate from
the agent is that we could allow multiple of them whereas there can only
be one agent right now. And only if there'd be one or more of these new
types of objects registered would bluetoothd make the extra roundtrip
when it gets an IO capability request.

Johan