Skip to main content

bluetooth.setsecurity(securityLevel, pairingCode)

Specifies the security level of Bluetooth connections

Availability

Device
Only available on the imp004m and imp006 (impOS 42)

Parameters

Name Type Description
securityLevel Integer The required security level as per the Bluetooth 4.2 specification
pairingCode Integer An optional six-digit decimal value for connection authentication

Returns

Nothing

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.