[RFC] DBus OutOfBand API update

[RFC] DBus OutOfBand API update

[Szymon Janc]

Hi,

This is an initial proposal for dbus oob api update for 5.0.
I tried to include all comments from previous discussions.

I was trying to keep dictionary keys close to what is described in "Bluetooth
Secure Simple Pairing Using NFC" whitepaper. But EIR can have other data as well
e.g. short name instead of full name, should we distinguish that to know if name
resolution should be done in band? Or is this overkill?
What about EIR flags? Is it usefull in any sense?

Adding data result in DeviceFound signal being emitted, should DeviceDisappeared
be emitted when removing oob data (if device was found via oob)?

Also, should oob interface be disabled for 2.0 (and for >2.1 with ssp
disabled) adapters?


Comments?

-- 
BR
Szymon Janc

Szymon Janc (1):
  dbusoob: Update API

 doc/oob-api.txt |   57 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 51 insertions(+), 6 deletions(-)

-- 
1.7.9.5

[RFC] dbusoob: Update API

[Szymon Janc]

---
 doc/oob-api.txt |   57 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 51 insertions(+), 6 deletions(-)

diff --git a/doc/oob-api.txt b/doc/oob-api.txt
index d838712..8b7b633 100644
--- a/doc/oob-api.txt
+++ b/doc/oob-api.txt
@@ -7,26 +7,71 @@ Service		org.bluez
 Interface	org.bluez.OutOfBand
 Object path	[variable prefix]/{hci0,hci1,...}
 
-Methods		array{byte} hash, array{byte} randomizer ReadLocalData()
+Methods		dict ReadLocalData()
 
 			This method reads local OOB data from adapter. Return
-			value is pair of arrays 16 bytes each.
+			value is a dictionary with following keys:
 
-			Note: This method will generate and return new local
-			OOB data.
+			array{byte} Hash:
+
+					16 bytes hash blob.
+
+			array{byte} Randomizer:
+
+					16 bytes randomizer blob.
+
+			Other data that can be transmitted via OOB mechanism
+			can be obtained from org.bluez.Adapter interface.
+
+			Note: This method will generate and return new hash
+			and randomizer every time it is called. Data
+			received in previous calls is invalidated and cannot be
+			used for pairing.
 
 			Possible errors: org.bluez.Error.Failed
 					 org.bluez.Error.InProgress
 
-		void AddRemoteData(string address, array{byte} hash,
-							array{byte} randomizer)
+		void AddRemoteData(string address, dict data)
 
 			This method adds new Out Of Band data for
 			specified address. If data for specified address
 			already exists it will be overwritten with new one.
 
+			All data is optional.
+
+			On success DeviceFound signal will be emitted.
+
+			possible keys:
+
+				array{byte} Hash:
+
+					16 bytes hash blob, it is used as is
+					so the size and byte order must match.
+
+				array{byte} Randomizer:
+
+					16 bytes randomizer blob, it is used as
+					is so the size and byte order must
+					match. If Randomizer is provided Hash
+					also needs to be provided.
+
+				uint32 Class:
+
+					The Bluetooth class of device of the
+					remote device.
+
+				string Name:
+
+					Remote device name.
+
+				array{string} UUIDs
+
+					List of 128-bit UUIDs that represents
+					the available local services.
+
 			Possible errors: org.bluez.Error.Failed
 					 org.bluez.Error.InvalidArguments
+					 org.bluez.Error.AlreadyPaired
 
 		void RemoveRemoteData(string address)
 
-- 
1.7.9.5

Re: [RFC] dbusoob: Update API

[Vinicius Costa Gomes]

Hi Szymon,

On 16:25 Wed 25 Jul, Szymon Janc wrote:
> ---
>  doc/oob-api.txt |   57 +++++++++++++++++++++++++++++++++++++++++++++++++------
>  1 file changed, 51 insertions(+), 6 deletions(-)
> 
> diff --git a/doc/oob-api.txt b/doc/oob-api.txt
> index d838712..8b7b633 100644
> --- a/doc/oob-api.txt
> +++ b/doc/oob-api.txt
> @@ -7,26 +7,71 @@ Service		org.bluez
>  Interface	org.bluez.OutOfBand
>  Object path	[variable prefix]/{hci0,hci1,...}
>  
> -Methods		array{byte} hash, array{byte} randomizer ReadLocalData()
> +Methods		dict ReadLocalData()
>  
>  			This method reads local OOB data from adapter. Return
> -			value is pair of arrays 16 bytes each.
> +			value is a dictionary with following keys:
>  
> -			Note: This method will generate and return new local
> -			OOB data.
> +			array{byte} Hash:
> +
> +					16 bytes hash blob.
> +
> +			array{byte} Randomizer:
> +
> +					16 bytes randomizer blob.

I would add a TK field (with 16 bytes) for Low Energy bonding.

> +
> +			Other data that can be transmitted via OOB mechanism
> +			can be obtained from org.bluez.Adapter interface.
> +
> +			Note: This method will generate and return new hash
> +			and randomizer every time it is called. Data
> +			received in previous calls is invalidated and cannot be
> +			used for pairing.
>  
>  			Possible errors: org.bluez.Error.Failed
>  					 org.bluez.Error.InProgress
>  
> -		void AddRemoteData(string address, array{byte} hash,
> -							array{byte} randomizer)
> +		void AddRemoteData(string address, dict data)

I am thinking if only the address is enough for the Low Energy case, i.e.
should we have an address type here?

>  
>  			This method adds new Out Of Band data for
>  			specified address. If data for specified address
>  			already exists it will be overwritten with new one.
>  
> +			All data is optional.
> +
> +			On success DeviceFound signal will be emitted.
> +
> +			possible keys:
> +
> +				array{byte} Hash:
> +
> +					16 bytes hash blob, it is used as is
> +					so the size and byte order must match.
> +
> +				array{byte} Randomizer:
> +
> +					16 bytes randomizer blob, it is used as
> +					is so the size and byte order must
> +					match. If Randomizer is provided Hash
> +					also needs to be provided.

Same here.

Apart these minor comments, the API looks good.

> +
> +				uint32 Class:
> +
> +					The Bluetooth class of device of the
> +					remote device.
> +
> +				string Name:
> +
> +					Remote device name.
> +
> +				array{string} UUIDs
> +
> +					List of 128-bit UUIDs that represents
> +					the available local services.
> +
>  			Possible errors: org.bluez.Error.Failed
>  					 org.bluez.Error.InvalidArguments
> +					 org.bluez.Error.AlreadyPaired
>  
>  		void RemoveRemoteData(string address)
>  
> -- 
> 1.7.9.5
> 
> --
> 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


Cheers,
-- 
Vinicius

Re: Re: [RFC] dbusoob: Update API

[Szymon Janc]

On Wednesday 25 of July 2012 21:22:01 Vinicius Costa Gomes wrote:
> Hi Szymon,

Hi Vinicius,

> 
> On 16:25 Wed 25 Jul, Szymon Janc wrote:
> > ---
> >  doc/oob-api.txt |   57 +++++++++++++++++++++++++++++++++++++++++++++++++------
> >  1 file changed, 51 insertions(+), 6 deletions(-)
> > 
> > diff --git a/doc/oob-api.txt b/doc/oob-api.txt
> > index d838712..8b7b633 100644
> > --- a/doc/oob-api.txt
> > +++ b/doc/oob-api.txt
> > @@ -7,26 +7,71 @@ Service		org.bluez
> >  Interface	org.bluez.OutOfBand
> >  Object path	[variable prefix]/{hci0,hci1,...}
> >  
> > -Methods		array{byte} hash, array{byte} randomizer ReadLocalData()
> > +Methods		dict ReadLocalData()
> >  
> >  			This method reads local OOB data from adapter. Return
> > -			value is pair of arrays 16 bytes each.
> > +			value is a dictionary with following keys:
> >  
> > -			Note: This method will generate and return new local
> > -			OOB data.
> > +			array{byte} Hash:
> > +
> > +					16 bytes hash blob.
> > +
> > +			array{byte} Randomizer:
> > +
> > +					16 bytes randomizer blob.
> 
> I would add a TK field (with 16 bytes) for Low Energy bonding.

I must admit that I totally ignored LE case :) I'll add TK to dictionary,
yet I'm not very familiar with LE, is TK a random number returned by 'LE Rand'
command ? It doesn't seem to have same semantic as 'Read Local OOB Data' command.
Hints?

> 
> > +
> > +			Other data that can be transmitted via OOB mechanism
> > +			can be obtained from org.bluez.Adapter interface.
> > +
> > +			Note: This method will generate and return new hash
> > +			and randomizer every time it is called. Data
> > +			received in previous calls is invalidated and cannot be
> > +			used for pairing.
> >  
> >  			Possible errors: org.bluez.Error.Failed
> >  					 org.bluez.Error.InProgress
> >  
> > -		void AddRemoteData(string address, array{byte} hash,
> > -							array{byte} randomizer)
> > +		void AddRemoteData(string address, dict data)
> 
> I am thinking if only the address is enough for the Low Energy case, i.e.
> should we have an address type here?

In spec there are 'Flags' and 'Security Manager OOB Flags' EIR data types,
is that needed/useful for LE case? Maybe pass them as blobs to bluez so that
dbusoob user doesn't need to parse those bit fields to set address type?

-- 
BR
Szymon Janc

Re: Re: [RFC] dbusoob: Update API

[Vinicius Costa Gomes]

On 11:24 Thu 26 Jul, Szymon Janc wrote:
> On Wednesday 25 of July 2012 21:22:01 Vinicius Costa Gomes wrote:
> > Hi Szymon,
> 
> Hi Vinicius,
> 
> > 
> > On 16:25 Wed 25 Jul, Szymon Janc wrote:
> > > ---
> > >  doc/oob-api.txt |   57 +++++++++++++++++++++++++++++++++++++++++++++++++------
> > >  1 file changed, 51 insertions(+), 6 deletions(-)
> > > 
> > > diff --git a/doc/oob-api.txt b/doc/oob-api.txt
> > > index d838712..8b7b633 100644
> > > --- a/doc/oob-api.txt
> > > +++ b/doc/oob-api.txt
> > > @@ -7,26 +7,71 @@ Service		org.bluez
> > >  Interface	org.bluez.OutOfBand
> > >  Object path	[variable prefix]/{hci0,hci1,...}
> > >  
> > > -Methods		array{byte} hash, array{byte} randomizer ReadLocalData()
> > > +Methods		dict ReadLocalData()
> > >  
> > >  			This method reads local OOB data from adapter. Return
> > > -			value is pair of arrays 16 bytes each.
> > > +			value is a dictionary with following keys:
> > >  
> > > -			Note: This method will generate and return new local
> > > -			OOB data.
> > > +			array{byte} Hash:
> > > +
> > > +					16 bytes hash blob.
> > > +
> > > +			array{byte} Randomizer:
> > > +
> > > +					16 bytes randomizer blob.
> > 
> > I would add a TK field (with 16 bytes) for Low Energy bonding.
> 
> I must admit that I totally ignored LE case :) I'll add TK to dictionary,
> yet I'm not very familiar with LE, is TK a random number returned by 'LE Rand'
> command ? It doesn't seem to have same semantic as 'Read Local OOB Data' command.
> Hints?

The generation of the TK number is actually up to the host, it may want
to use 'LE Rand' (which generates only 8 bytes) or it may want to use
something else, which should be our case. More about TK in the page 1969
of the spec (section 2.3.5.4).

You are right that the semantics of 'LE Rand' are different from 'Read Local
OOB'. That is because the security protocol of LE is implemented in the
host side.

What I mean is that it would be up to BlueZ to guarantee that each time
ReadLocalData() is called a different TK is generated.

> 
> > 
> > > +
> > > +			Other data that can be transmitted via OOB mechanism
> > > +			can be obtained from org.bluez.Adapter interface.
> > > +
> > > +			Note: This method will generate and return new hash
> > > +			and randomizer every time it is called. Data
> > > +			received in previous calls is invalidated and cannot be
> > > +			used for pairing.
> > >  
> > >  			Possible errors: org.bluez.Error.Failed
> > >  					 org.bluez.Error.InProgress
> > >  
> > > -		void AddRemoteData(string address, array{byte} hash,
> > > -							array{byte} randomizer)
> > > +		void AddRemoteData(string address, dict data)
> > 
> > I am thinking if only the address is enough for the Low Energy case, i.e.
> > should we have an address type here?
> 
> In spec there are 'Flags' and 'Security Manager OOB Flags' EIR data types,
> is that needed/useful for LE case? Maybe pass them as blobs to bluez so that
> dbusoob user doesn't need to parse those bit fields to set address type?

Yeah, that should be enough. BlueZ already has access to all the EIR/AD
data.

> 
> -- 
> BR
> Szymon Janc
> 


Cheers,
-- 
Vinicius