bluetooth.setsecurity(securityLevel, pairingCode)

Description

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 default setting is level 4. A random pairing code is generated when bluetooth.open() is called. This code can be retrieved using bluetooth.getsecuritycode().

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.

Choosing Pairing Code Values

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:

Mode	Lifetime	Scope	Security Strength	Notes
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
4	Time-limited	Single connection	Strong

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.