[Bluez,v3,2/3] doc: add "Bonded" flag to dbus property

Bonded flag is used to indicate the link key or ltk of the remote
device has been stored.

Reviewed-by: Sonny Sasaka <sonnysasaka@chromium.org>
Reviewed-by: Yun-Hao Chung <howardchung@chromium.org>

Signed-off-by: Zhengping Jiang <jiangzp@google.com>
---

Changes in v3:
- Move documentation update to a separate patch
- Add description to bonded and paired

 doc/device-api.txt | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

Hi Zhengping,

On Wed, May 4, 2022 at 3:04 PM Zhengping Jiang <jiangzp@google.com> wrote:
>
> Hi Bastien,
>
> To avoid confusion, I would propose to update the description to "key information".
>
>                         Indicates if the remote device is bonded. Bonded means
>                         the key information created from the pairing process
>                         has been stored.
>
> Thanks,
> Zhengping
>

Ive changed it a little bit:

https://gist.github.com/Vudentz/ca59d846b4ff840e2ee4c01f6965def6

> On Wed, May 4, 2022 at 2:47 PM Zhengping Jiang <jiangzp@google.com> wrote:
>>
>> Hi Bastien,
>>
>> Thanks for the comment. They are not the same for Classic. "Bonded" means the key information is persistent for both LE and classic.
>> For classic the stored information is "Link key" for LE it will be "LTK". But I think if a device has both classic and LE, the two types of keys can be converted.
>>
>> Thanks,
>> Zhengping
>>
>>
>> On Wed, May 4, 2022 at 2:37 PM Bastien Nocera <hadess@hadess.net> wrote:
>>>
>>> On Wed, 2022-05-04 at 14:09 -0700, Zhengping Jiang wrote:
>>> > Bonded flag is used to indicate the link key or ltk of the remote
>>> > device has been stored.
>>> >
>>> > Reviewed-by: Sonny Sasaka <sonnysasaka@chromium.org>
>>> > Reviewed-by: Yun-Hao Chung <howardchung@chromium.org>
>>> >
>>> > Signed-off-by: Zhengping Jiang <jiangzp@google.com>
>>> > ---
>>> >
>>> > Changes in v3:
>>> > - Move documentation update to a separate patch
>>> > - Add description to bonded and paired
>>> >
>>> >  doc/device-api.txt | 12 +++++++++++-
>>> >  1 file changed, 11 insertions(+), 1 deletion(-)
>>> >
>>> > diff --git a/doc/device-api.txt b/doc/device-api.txt
>>> > index 1e8590b27d58..c7e217c07526 100644
>>> > --- a/doc/device-api.txt
>>> > +++ b/doc/device-api.txt
>>> > @@ -246,7 +246,17 @@ Properties string Address [readonly]
>>> >
>>> >                 boolean Paired [readonly]
>>> >
>>> > -                       Indicates if the remote device is paired.
>>> > +                       Indicates if the remote device is paired. Pairing is
>>> > +                       the process where devices exchange the information to
>>> > +                       establish an encrypted connection.
>>> > +
>>> > +               boolean Bonded [readonly]
>>> > +
>>> > +                       Indicates if the remote device is bonded. Bonded means
>>> > +                       the link key or the ltk from the pairing process has
>>> > +                       been stored.
>>>
>>> "long-term key (LTK)"
>>>
>>> Is Paired effectively the same as Bonded for Classic devices? If so,
>>> would be great to mention.
>>>
>>> > +                       A PropertiesChanged signal indicate changes to this
>>> > +                       status.
>>> >
>>> >                 boolean Connected [readonly]
>>> >
>>>

Hi Bastien,

On Wed, May 4, 2022 at 2:37 PM Bastien Nocera <hadess@hadess.net> wrote:
>
> On Wed, 2022-05-04 at 14:09 -0700, Zhengping Jiang wrote:
> > Bonded flag is used to indicate the link key or ltk of the remote
> > device has been stored.
> >
> > Reviewed-by: Sonny Sasaka <sonnysasaka@chromium.org>
> > Reviewed-by: Yun-Hao Chung <howardchung@chromium.org>
> >
> > Signed-off-by: Zhengping Jiang <jiangzp@google.com>
> > ---
> >
> > Changes in v3:
> > - Move documentation update to a separate patch
> > - Add description to bonded and paired
> >
> >  doc/device-api.txt | 12 +++++++++++-
> >  1 file changed, 11 insertions(+), 1 deletion(-)
> >
> > diff --git a/doc/device-api.txt b/doc/device-api.txt
> > index 1e8590b27d58..c7e217c07526 100644
> > --- a/doc/device-api.txt
> > +++ b/doc/device-api.txt
> > @@ -246,7 +246,17 @@ Properties string Address [readonly]
> >
> >                 boolean Paired [readonly]
> >
> > -                       Indicates if the remote device is paired.
> > +                       Indicates if the remote device is paired. Pairing is
> > +                       the process where devices exchange the information to
> > +                       establish an encrypted connection.
> > +
> > +               boolean Bonded [readonly]
> > +
> > +                       Indicates if the remote device is bonded. Bonded means
> > +                       the link key or the ltk from the pairing process has
> > +                       been stored.
>
> "long-term key (LTK)"
>
> Is Paired effectively the same as Bonded for Classic devices? If so,
> would be great to mention.

There are some rare occasion where the link-keys cannot be
persisted/stored (e.g. debug keys), but in the other hand Bonded would
always means Paired, perhaps this is useful if you want to persist
some device information at upper layers otherwise I can't think of any
other use of Bonded over Paired.

> > +                       A PropertiesChanged signal indicate changes to this
> > +                       status.
> >
> >                 boolean Connected [readonly]
> >
>