Skip to content

TBD corrections 3 #460

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Apr 12, 2018
Merged

TBD corrections 3 #460

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c9b6c59
TBD corrections 3
jen3andruska Mar 19, 2018
d7f437c
TBD corrections 4
jen3andruska Mar 19, 2018
5c66f55
Update commas in Gap.md
Apr 12, 2018
0a55fcb
Update SecurityManager.md
Apr 12, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/reference/api/connectivity/bluetooth/Gap.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

The Generic Access Profile is the layer of the stack that handles connectivity tasks. This includes link establishment and termination, advertising and scanning.

Devices with data to publish can use GAP to advertise. They can include the data in the advertisement itself or inside the scan response or leave a peer device to query it after the connection has been established.
Devices with data to publish can use GAP to advertise. They can include the data in the advertisement itself, inside the scan response, or leave a peer device to query it after the connection has been established.

The other side of the process is the act of scanning, which listens for advertisements, allows you to query the advertisers for more data through a scan request or to connect in order to query the peer device for the data we want.
The other side of the process is the act of scanning, which listens for advertisements, allows you to query the advertisers for more data through a scan request, or connect in order to query the peer device for the data you want.

Advertising, scanning and connection all have parameters that let you find a compromise between desired power consumption levels and latency and efficiency of these processes.
Advertising, scanning and connection all have parameters that let you find a compromise between desired power consumption levels, latency, and efficiency of these processes.

### GAP class reference

Expand Down
8 changes: 4 additions & 4 deletions docs/reference/api/connectivity/bluetooth/SecurityManager.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
## SecurityManager

SecurityManager deals with authentication and encryption for the Bluetooth Low Energy link. The process of pairing and optionally bonding provides this. The SecurityManager achieves bonding by saving the pairing information and reusing it on subsequent reconnections in order to save time by not having to perform pairing again.
SecurityManager deals with authentication and encryption for the Bluetooth Low Energy link. The pairing and optionally bonding processes provide this. The SecurityManager achieves bonding by saving the pairing information and reusing it on subsequent reconnections. This saves time because the pairing does not have to be performed again.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pairing always happens. Bonding may happen. Bonding means: saving pairing information for later use so that you don't have to pair again. There is no extra communication between the devices. One device may just decide to "bond" with the other which means nothing else than just save the result of the pairing process which otherwise would have to be redone on subsequent reconnections.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok this is what I thought - they are different processes but related. This makes sense, thanks!


The process of pairing may produce a set of keys to be used during current or later connections. The SecurityManager and include the Long Term Encryption Key (LTK), the Identity Resolving Key (IRK) and the Connection Signature Resolving Key (CSRK) handle these. The SecurityManager uses the LTK to encrypt subsequent connections without having to pair again. The Link Controller uses IRK to identify peers who use random resolvable addresses. The application uses CSRK to sign and authenticate signed data.
The pairing process may produce a set of keys to be used during current or later connections. The SecurityManager includes the Long Term Encryption Key (LTK), the Identity Resolving Key (IRK) and the Connection Signature Resolving Key (CSRK). The SecurityManager uses the LTK to encrypt subsequent connections without having to pair again. The Link Controller uses IRK to identify peers who use random resolvable addresses. The application uses CSRK to sign and authenticate signed data.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first two sentences were originally:
"The process of pairing may produce a set of keys to be used during current or later connections. These are handled by the SecurityManager and include the Long Term Encryption Key (LTK), the Identity Resolving Key (IRK) and the Connection Signature Resolving Key (CSRK)."
Something must've gotten lost in copy edits.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok I see, yes something must have gotten lost - this makes much more sense.


The pairing process may provide man-in-the-middle protection (MITM). The SecurityManager achieves this through various means, including out of band communication, depending on the capabilities of the local and peer device.
The pairing process can provide man-in-the-middle protection (MITM). The SecurityManager achieves this through various means, including out of band communication, depending on the capabilities of the local and peer device.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MITM protection may/can be provided by the SM if it's possible to do so. That's not always the case, some combinations of devices simply don't have the required capabilities

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok I see, so it really is 'may' then. This makes sense.


The SecurityManager stores the keys, permanently if possible, to speed security requests on subsequent connections.

Expand All @@ -16,6 +16,6 @@ Security requests may come explicitly from the user application or implicitly fr

### SecurityManager example

The SecurityManager example demonstrates both a central and a peripheral connecting and performing basic pairing and setting up link security.
The SecurityManager example demonstrates both a central and a peripheral connecting, performing basic pairing, and setting up link security.

[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-SM/)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-ble-SM/file/fcb1e0b995a9/source/main.cpp)