Secure +Simple Pairing (SSP)

Introduction
Overview
Symbian support for SSP
Implementing SSP notifiers
Using the Out of Band API
Using the dedicated bonding API

Introduction

Secure +Simple Pairing, introduced into Bluetooth v2.1, simplifies the user experience +when pairing Bluetooth devices.

This document describes the Symbian +platform implementation of SSP. It describes the tasks that must be performed +by UI creators to implement SSP and it describes how application developers +can use Symbian APIs to pair with Bluetooth enabled devices using SSP.

Scope

This document is intended for Symbian partners and developers +implementing SSP on Symbian platform. It assumes that you are familiar with +Bluetooth and with developing on Symbian platform.

Purpose of SSP

SSP was introduced to simplify the user experience +when pairing Bluetooth devices. Specifically:

there is no need for +the user to think of a number
the authentication process +may differ for different devices and different services
all data transfer is +encrypted

Overview

The pairing model

Pre-SSP pairing is achieved by the user(s) +entering a personal identification number (PIN) on one or both devices. Devices +with no keypads, such as headsets, have their PINs (typically "0000" or "1234") +hard-wired. This is now referred to as Legacy Paring.

Under SSP, devices +specify their authorisation requirements. The user may have to:

press a button in response +to a simple yes or no query
compare two automatically +generated numbers and select 'yes' if they match or 'no' if they do not
enter a number on one +or both devices
do nothing

Once the devices have paired the user may be asked to authorise bonding. +Bonded devices can subsequently pair with no user interaction.

Key concepts

Authentication: Verification that a remote device is what it claims to be. Authentication +may be unnecessary for some pairings (see Just Works), may require user intervention +(see Man in the Middle) or may be performed through another channel (see Out +of Band).
Authorisation: In legacy pairing a remote device can be authorised after pairing such +that it subsequently connects automatically without user intervention. Authorisation +is on a per-service basis. See bonding.
Encryption: Transmission of data between devices after SSP is always encrypted. +Under legacy pairing data transmission is not always encrypted.
Man In The Middle (MITM) protection: Authentication explicitly provided by the user before pairing can take +place. Under SSP, devices and services have hard-wired authentication requirements +as follows: MITM required, MITM not required (see Just Works) and MITM desired +(subject to the user interface capabilities of the devices)
Just Works: For some pairings there is little risk of a security breach so SSP +provides a mechanism for devices to pair with no explicit user authentication.
Passkey: In the context of a Symbian device, which always has both a display +and a keypad, passkey authentication is used when pairing with a remote device +which has a keypad but no display. The Symbian device displays a number which +the user must enter using the keypad on the remote device
Out Of Band (OOB): Out of Band authentication is performed using a non-Bluetooth communication +channel. The data required to open an MITM protected Bluetooth connection +with a remote device is transmitted by other means.
Bonding: Two devices may bond after athentication such that they can reconnect +without user intervention. Bonding is achieved on a Symbian device by storing +a link key. Symbian devices attempt to bond by default. The user or the remote +device may specify that the devices do not bond.
Link key: When a connection is authenticated a link key is created. The link +key indicates the strength of authentication (legacy, authenticated or unauthenticated). +The link key may be stored by the Symbian device and used to bond (the default +behaviour) or discarded when the connection ends. The link key is not displayed +to the user.

Symbian support +for SSP

Components

Most +of the changes are internal and transparent to system creators and developers. +However, some new APIs added to the Bluetooth User Library allow application +developers to use SSP features, and Licensees must implement some SSP specific +notifiers.

The diagram below shows the interfaces and interface classes +required to implement SSP.

Dedicated +Bonding

Dedicated bonding is performed by the Bluetooth Pairing +Server. Applications can use the RBluetoothDedicatedBondingInitiator API +to request bonding with a specified Bluetooth device.

Out of Band Data

Out of Band pairing data can be passed to +the Bluetooth Pairing Server. The server can use the supplied data to pair +with the specified device. Applications can also use the RBluetoothOobData API +to retrieve OOB data for the local device to be passed to remote devices.

Numeric Comparison Notifier

The Bluetooth sub-system requires +a Numeric Comparison Notifier to be provided by the UI. The notifier must +handle TBTNumericComparisonParams and return a boolean +value which indicates the user's decision.

Passkey Entry Notifier

The Bluetooth sub-system requires +a Passkey Entry Notifier to be provided by the UI. The notifier must handle TBTPasskeyDisplayParams and TBTPasskeyDisplayUpdateParams.

Data +Types

SSP specific data is stored and manipulated using the following +types (significant functions and fields shown only). These types are used +in various device and service related APIs. They are defined in bt_sock.h and btdevice.h.

#include <bt_sock.h>

+enum TBluetoothMitmProtection + { + EMitmNotRequired = 0x0, // No Man-in-the-Middle authentication is not required. + EMitmDesired = 0x1, // Man-in-the-Middle authentication should be used where possible. + EMitmRequired = 0x2 // Man-in-the-Middle authentication is required. + }; +

TBTAccessRequirements

+class TBTAccessRequirements + { +public: + ... + IMPORT_C void SetAuthentication( TBluetoothMitmProtection aPreference ); + IMPORT_C TBluetoothMitmProtection MitmProtection() const; + ... + + +private: + enum TBTServiceSecuritySettings + { + EAuthenticate = 0x01, + EAuthorise = 0x02, + EEncrypt = 0x04, + EDenied = 0x08, + EMitm = 0x30, // 2 bit field for MITM + }; + + enum TBTAccessRequirementsMitmProtection + { + EAccessRequirementsMitmUndefined = 0x00, + EAccessRequirementsMitmNotRequired = 0x10, + EAccessRequirementsMitmDesired = 0x20, + EAccessRequirementsMitmRequired = 0x30 + }; + };

TBTServiceSecurity

+class TBTServiceSecurity + { +public: + ... + IMPORT_C void SetAuthentication( TBluetoothMitmProtection aPreference ); + IMPORT_C TBool AuthenticationRequired() const; + IMPORT_C TBluetoothMitmProtection MitmProtection() const; + ... + +private: + TBTAccessRequirements iSecurityRequirements; // Whether the service requires authentication, authorisation, encryption or min passkey len. + }; + +typedef TPckgBuf<TBTServiceSecurity> TBTServiceSecurityPckg; // Package definition for securty settings +

#include <btdevice.h>

TBTDeviceSecurity

+class TBTDeviceSecurity + { +public: + + // Enumeration to provide select MITM protection required. + + enum TMitmRequired + { + EMitmUnspecified, // No specific MITM protection requirements + EMitmRequired // Require the link is MITM protected + }; + +public: + + ... + IMPORT_C void SetNoAuthenticate(TBool aDecision); + IMPORT_C void SetMitmRequirements(TMitmRequired aDecision); + ... + IMPORT_C TBool NoAuthenticate() const; + IMPORT_C TMitmRequired MitmRequirements() const; + ... + +public: + // Enumeration to assist in parsing of security settings. + enum TBTDeviceSecuritySettings + { + ENoAuthenticate = 0x01, // Don't authenticate the link @deprecated + ENoAuthorise = 0x02, // Don't authorise the connection + EEncrypt = 0x04, // Encrypt the link + EBanned = 0x08, // Don't connect to the device + EMitmProtectionRequired = 0x10, // Require the link is MITM protected + }; + }; +

Implementing +SSP notifiers

Introdution

The +Bluetooth sub-system has no user interface. It uses the Symbian notifier +framework for user interaction when pairing. The UI system must provide +a notifier, in plug-in form, for each user interaction required by SSP. The +notifier must receive data in a specified format from the Bluetooth sub-system, +display appropriate controls in a dialog on the screen, respond to the user's +input and send data back to the Bluetooth sub-system in a specified format.

This +document assumes that you already have Bluetooth notifiers in your system. +It describes the key aspects of adding notifiers for SSP. The structures, +types and constants described below are defined in BTExtNotifiers.h. +You can add notifiers to an existing plug-in or create a new plug-in.

Notifiers +are typically implemented as sleeping dialogs. A sleeping dialog has its resources +allocated when its application (in this case the Uikon Server) is started. +A sleeping dialog can therefore be displayed (roused) safely under low memory +conditions.

Notes:

This document does not +describe how to implement an ECOM plug-in or a sleeping dialog.
Customisation Kit Licensees +can find an example notifier implementation here: sf/mw/classicui/commonuisupport/uikon/examples/notifier1/

Numeric +Comparison Notifier

A numeric comparison notifier is required +for SSP Man in the Middle (MITM) authentication when the remote device is +capable of displaying a number to the the user and accepting a yes or no response +from the user. The notifier must display an automatically generated number +and invite the user to confirm (yes or no) that the number is the same as +the number displayed on the remote device. The notifier must return the user's +response.

The Bluetooth Security Manager uses the following code to +ask the notifier framework to display the Numeric Comparison Notifier

+ +// defined in header file(s) + +TBTDevAddr iDevAddr ; +RNotifier iNotifier ; +TUint32 iNumericValue ; +TBool iInternallyInitiated ; +TBTNumericComparisonParamsPckg iNumericComparisonParamsPckg ; +TPckgBuf<TBool> iResultPckg ; +// + +void CBTNumericComparator::DoRequest() + { + // Start the RNotifier plugin that deals with authorisation. + + ... + + TBTDeviceName deviceName = KNullDesC ; + + iNumericComparisonParamsPckg = TBTNumericComparisonParams( iDevAddr, + deviceName, + iNumericValue, + TBTNumericComparisonParams::ERemoteCanConfirm, + iInternallyInitiated); + + iNotifier.StartNotifierAndGetResponse( iStatus, + KBTNumericComparisonNotifierUid, + iNumericComparisonParamsPckg, + iResultPckg); + SetActive(); + } +

From the code above you can see that the Numeric Comparision +Notifier is identified by the UIDKBTNumericComparisonNotifierUid and +that it must handle data in TBTNumericComparisonParams (which +is packaged into TBTNumericComparisonParamsPckg for inter-process +transfer).

The code fragment below shows how to extract the numeric +comparison data within a notifier.

NOTE: You will need to implement +all of the virtual functions in MEikSrvNotifierBase2.

+class CNumericComparisonNotifier : public CEikDialog, public MEikSrvNotifierBase2 + { +public: + + ... + + // from MEikSrvNotifierBase2 + void StartL ( const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage ) ; + + ... + + void Complete( TBool aDecision, TInt aReason ) ; + +private: + TInt iRepySlot ; + TNotifierInfo iInfo ; + RMessage2 iMessage ; + TBTNumeriComparisonParamsPckg iNumericComparisonParamsPckg ; + TBTDevAddr iAddr ; + TBTDeviceName iName ; + TUint32 iNumericalValue ; + + } ; + + + +//-------------------------------- + +... + +void CNumericComparisionNotifier::StartL( const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage ) + { + + iMessage = RMessage2( aMessage ) ; // keep a copy ofthe message so that it can be completed later. + iReplySlot = aReplySlot ; // copy the reply slot too + + // Extract the comparison parameters from the buffer + + iNumericComparisonParamsPckg.Copy( aBuffer ) ; + + iAddr = iNumericComparisonParamsPckg().DeviceAddress() ; + iName = iNumericComparisonParamsPckg().DeviceName() ; + iNumericalValue = iNumericComparisonParamsPckg().NumericalValue() ; + + ... + + RouseSleepingDialog() ; + + } + +

Your dialog must display iNumericalValue and +ask the user if the number displayed is the same as the number displayed on +the other Bluetooth device. The user must be able to select 'Yes' or 'No'.

The StartL() function +above must return quickly so it must not wait for the user's response. Your +notifier must complete the message (iMessage) as shown below +when the user enters a response.

+void CNumericComparisionNotifier::Complete( TBool aDecision, TInt aReason ) + { + if ( aReason == KErrNone ) + { + TInt err = iMessage.Write( iReplySlot, TPckgC<TBool>( aDecision ) ) ; + iMessage.Complete( err ) ; + } + else + { + iMessage.Complete( aReason ) ; + } + } +

Passkey +Notifier

A passkey notifier is required for SSP MITM authentication +when the user must type a number on a remote device which has a keypad and +no display. The notifier displays the number that the user must type. In the +code below the notifier also displays a '*' character as the user types each +digit into the remote device.

The Bluetooth Security Manager uses +the following code to ask the Notifier Framework to display the passkey notifier.

+ +// defined in header file(s) + +TBTDevAddr iDevAddr ; +RNotifier iNotifier ; +TUint32 iNumericValue ; // the passkey number +TBool iInternallyInitiated ; +TBTPasskeyDisplayParamsPckg iPasskeyDisplayParamsPckg ; +TBTDeviceNameUpdateParamsPckg iDeviceNameUpdateParamsPckg; +TBuf8<1> iResultPckg ; + +void CBTPasskeyEntry::DoRequest() + { + // Start the RNotifier plugin that deals with authorisation. + + ... + + TBTDeviceName deviceName ; + + deviceName = KNullDesC ; + + iPasskeyDisplayParamsPckg = TBTPasskeyDisplayParams( iDevAddr, + deviceName, + iNumericValue, + iInternallyInitiated ) ; + + iNotifier.StartNotifierAndGetResponse( iStatus, + KBTPasskeyDisplayNotifierUid, + iPasskeyDisplayParamsPckg, + iResultPckg ) ; + SetActive() ; + + } + +

From the code above you can see that the Passkey Notifier +is identified by the UIDKBTPasskeyNotifierUid and that it +must handle data in TBTPasskeyDisplayParams (which is packaged +into TBTPasskeyDisplayParamsPckg for inter-process transfer).

As +the user enters passkey digits into the remote device the Security Manager +also uses RNotifier::UpdateNotifierAndGetResponse() to send TBTPasskeyDisplayUpdateParams (packaged +in TBTPasskeyDisplayUdateParamsPckg) to the notifier. Your +notifier must use this information to reflect the key presses on the remote +device.

The code fragment below shows how to extract the passkey data +within a notifier.

NOTE: You will need to implement all of the virtual +functions in MEikSrvNotifierBase2.

+class CPasskeyNotifier : public CEikDialog, public MEikSrvNotifierBase2 + { +public: + + ... + + // from MEikSrvNotifierBase2 + void StartL( const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage ) ; + TPtrC8 UpdateL( const TDesC8& aBuffer ) ; // new information + + ... + +private: + TInt iRepySlot ; + TNotifierInfo iInfo ; + RMessage2 iMessage ; + TBTPasskeyDisplayParamsPckg iPasskeyDisplayParamsPckg ; + TBTDevAddr iAddr ; + TBTDeviceName iName ; + TUint32 iNumericalValue ; // the passkey number + + } ; + +//-------------------------------- + +... + +void CPasskeyNotifier::StartL( const TDesC8& aBuffer, TInt aReplySlot, const RMessagePtr2& aMessage ) + { + + iMessage = RMessage2(aMessage); // keep a copy ofthe message so that it can be completed later. + iReplySlot = aReplySlot ; // copy the reply slot too + + // Extract the comparison parameters from the buffer + + iPasskeyDisplayParamsPckg.Copy( aBuffer ) ; + + iAddr = iPasskeyDisplayParamsPckg().DeviceAddress() ; + iName = iPasskeyDisplayParamsPckg().DeviceName() ; + iNumericValue = iPasskeyDisplayParamsPckg().NumericalValue() ; + + + ... + + RouseSleepingDialog() ; // display the passkey + + ... + + } + +void CPasskeyNotifier::UpdateL( const TDesC8& aBuffer ) + { + + // extract the contents of the buffer + + TBTNotifierUpdateParamsPckg2 pckgRaw ; + pckgRaw.Copy( aBuffer.Left( pckgRaw.MaxLength() ) ) ; + + // update the dialog to reflect the keys pressed on the remote device + + if ( pckgRaw().Type() == TBTNotifierUpdateParams2::EPasskeyDisplay ) + { + TBTPasskeyDisplayUpdateParamsPckg pckg ; + pckg.Copy( aBuffer ) ; + HCIPasskeyEntryNotificationType keypressNotification = pckg().KeypressNotification() ; + + switch (keypressNotification) + { + case EPasskeyEntryStarted : + { + break ; + } + case EPasskeyDigitEntered : + { + // display '*' + break ; + } + case EPasskeyDigitDeleted : + { + // remove '*', reposition cursor + break ; + } + case EPasskeyCleared : + { + // clear display, reposition cursor + break ; + } + case EPasskeyEntryCompleted : + { + // hide the dialog + ExitSleepingDialog() ; + break; + } + default : + break ; + } + else if( pckgRaw().Type() == TBTNotifierUpdateParams2::EDeviceName ) + { + // handle name update + } + return KNullDesC8() ; + } + + + +

Out of Band +(OOB) authentication

Introduction

Out +of Band authentication is achieved using a communication method other than +Bluetooth. Once OOB authentication has succeeded an encrypted Bluetooth channel +is opened between the two devices.

The OOB API, RBluetoothOobData, +allows an application handling OOB authentication to provide pairing information +for a remote device.

RBluetoothOobData allows +an application handling OOB authentication to retrieve pairing information +for the local device.

Using +the OOB API

The OOB data API is provided by the Pairing Server +(part of the Security Manager).

+ +#include <pairing.h> + + RBluetoothPairingServer pairingServer ; + RBluetoothOobData OobData ; + + + // Connect to the Pairing server + + TInt err = pairingServer.connect() ; + + // Paring session + + err = OobData.Open( iPairingServer ) ; + + + // Use the API pass hash and randomizer values to and from the pairing server. + + ... + + + // Tidy up + + OobData.Close() ; + PairingServer.Close() ; + +

The API has three primary functions:

RefreshLocalOobData() - +This function causes the Bluetooth controller to generate new hash and randomizer +values for the local device. To retrieve the new values call ReadLocalOobData()

ReadLocalOobData() - +This function returns the hash and randomizer values that the Bluetooth controller +is currently using.

ProvideRemoteOobData() - Use +this function to pass OOB data about a remote device to the Bluetooth sub-system. +Three versions of the function are available which take slightly different +parameters. Information provided using one of these functions can be cleared +using ClearRemoteOobData().

Dedicated bonding

Introduction

Dedicated bonding is intended for applications +which bond with a specific Bluetooth device.

Using the dedicated bonding API

+ +#include <pairing.h> + + RBluetoothPairingServer pairingServer ; + RBluetoothDedicatedBondingInitiator bonder ; + TBTDevAddr addr ; + TRequstStatus status ; + + + // Connect to the Pairing server + + TInt err = pairingServer.connect() ; + + + // Use the Bluetooth address of the remote device bonder.Start( pairingServer, addr, status ) ; + + + // Wait for the request to complete + + User::WaitForRequest(status); + + + // Close the connection with the bonder (Must be closed before bonding with another device) + + bonder.Close(); + + pairingServer.Close() ; + +