Specifies the security level of Bluetooth connections
Only available on the imp004m and imp006 (impOS 41+)
The required security level as per the Bluetooth 4.2 specification
An optional six-digit decimal value for connection authentication
This method allows you to specify the minimum connection security level the imp requires for all GAP connections made to its current bluetooth instance. This is expressed as an integer (applying the scheme used in the Bluetooth 4.2 standard) and passed into the method's securityLevel parameter.
|securityLevel||Standard Name||imp IO Capabilities|
|1||LE Security Mode 1 Level 1: No security||NoInputNoOutput|
|3||LE Security Mode 1 Level 3: Authenticated pairing with encryption||KeyboardOnly|
|4||LE Security Mode 1 Level 4: Authenticated LE Secure Connections pairing with encryption||KeyboardOnly|
Other values are illegal and will cause a Squirrel error.
Security levels 3 and 4 also require a six-digit pairing code which is passed into the pairingCode parameter. Security level 4 causes any connection which only achieves level 3 or lower will be automatically closed after pairing. Squirrel will not be notified when this happens.
The imp initiates the pairing procedure when a new connection is made, and will not answer GATT queries until pairing completes successfully. And only then will the Squirrel GAP connection callback registered using bluetooth.onconnect() be called.
Bluetooth GAP connections are authenticated by pairing code. Unfortunately, this method can leak one new bit of the code to an active adversary on each run of the protocol. Because the code is fixed at six decimal digits, only 20 failed runs are needed to recover the whole code. For this reason, you should choose your code carefully.
There are four possible levels of pairing code security:
|1||Forever||Global||None||Effectively opts out of security|
|2||Forever||Per-imp||Limited||Allows the pairing code to be etched on the product or printed on the packaging|
|3||Squirrel Bluetooth session||Squirrel Bluetooth session||Good||This is the default|
For mode 2, you generate a random pairing code and both store it in the device under test (DUT) and either relay it to the label printing or case etching station so the end-user can read it and enter it into the mobile app that is being used to activate the device, or store it in a database from which it can be retrieved by the mobile app.
For mode 3, impOS chooses a random pairing code when a bluetooth object is instantiated. This is the default behavior and provides good security, but requires the product to incorporate a means of relaying the code to the end-user, such as a display.
Mode 4 provides the best security. The imp chooses a new random pairing code after every successful connection and every time a fixed period of time has elapsed — it is not difficult to code Squirrel to do this. This period must be long enough to allow pairing to take place, but short enough to limit exposure, ie. minutes rather than seconds (too short) or hours (too long). Again, the product must incorporate a means of relaying the code to the end-user.