Security Bootstrapping
This document introduces the security bootstrapping support provided to applications in the NDN-Lite library in three parts:
- An overview of the secure sign-on protocol, which is the protocol implemented for security bootstrapping. This section aims to give a brief high level summary of the design of the sign-on protocol, which may help one understand the underlying mechanism and implement the same protocol on a different platform if required.
- The interfaces for application developers to utilize this feature. This section aims to help those developing applications with the NDN-Lite library.
- The current implementation of this protocol over BLE on NRF boards. This section aims to help those who are interested in helping to improve the implementation or as a reference for those who want to better understand the underlying mechanisms of the current implementation of bootstrapping within NDN-Lite.
The paper describing the sign-on protocol is still in the process of submission; it will become available via a link here after it has finished the submission process.
The general goal of the Secure Sign-on Protocol (SSP in short) is to allow a constrained device to automatically and securely retrieve a trust anchor certificate as well as an anchor signed certificate from a trusted controller by local means (i.e., without dependency on the cloud or any other third-party trust center). It is expected to be used in home IoT scenarios, where a user may use their smartphone as a controller, and distribute cryptographic credentials to devices in their home through the sign-on protocol.
Before running the protocol, we assume the device has a piece of confidential information encoded somewhere (such as a QR code or barcode) and has already shared this information with the controller via some out-of-band operation. This information is used to establish the initial trust, so the method of sharing should be secure. This is a common strategy adopted by similar protocols. However, SSP offers stronger protection to the system in case this piece of pre-shared information is somehow revealed (see the sign-on paper linked at the top for more details).
The figure to the left (taken from the original paper) demonstrates the message details of the basic SSP. Note that all keying materials are selected to target a 128-bit security level, and Kt is generated by Diffie-Hellman (e.g., ECDH) with the two parties exchanging N1 and N2 as tokens to perform Diffie-Hellman (see the sign-on paper linked at the top for more details).
The current implementation of the sign-on protocol implements the two way exchange of the basic version of the sign-on protocol through a set of API’s on both the controller side (currently implemented as part of the ndn-lite support library for Android) and the device side (currently a part of the ndn-lite library).
Current implemenation is in POSIX package and ndn-iot-controller. It basically follow the description of standard SSP but actually a variant (while remain the same in the protocol level). Given ndn-lite uses per service per device certificate, devices having more than one capabilities will receive multiple identities with corresponding certificates from the security bootstrapping. The standard SSP only suppport one identity certificate. Thus in the POSIX package, the Interest-2 is implemented with optional multiple interests in case of multiple capabilities a device wants to register. As results, Multiple certificates are given back from controller via mulitiple Data-2. Capability is appended as interest parameter in each Interest-2, and controller will treat each Interest-2 differently by looking at capability field.
Strictly following the SSP design philosophy, all certificates should have been given back in a single Data-2. However, this will aggravate fragmentation status on low MTU links. More than ten capabilities (though ndn-lite does not support more than three at this time) will even trigger fragmentation on 802.11 links. We want to minimize fragmentation behaviors for numerous reasons.
The API for security boostrapping is here.
/**
* Start the security boostrapping process.
* @param device_identifier. INPUT. A string uniquely represent the device, e.g., a randomness.
* @param len. INPUT. The len of the string.
* @param service_list. INPUT. A array of uint8_t, each uint8_t represents a service provided by the device.
* @param list_size. INPUT. The list size.
*/
int
ndn_security_bootstrapping(ndn_face_intf_t* face,
const ndn_bootstrapping_info_t* bootstrapping_info,
const ndn_device_info_t* device_info,
ndn_security_bootstrapping_after_bootstrapping after_bootstrapping);This part is outdated and Bluetooth implementation is in lack of maintanence for long time. But this document might be helpful if you're interested in port Bluetooth to ndn-lite for your own interest
The implementations for Android and ndn-lite both follow a pattern of having lower level sign-on related API’s for processing and constructing sign-on protocol related messages (https://github.com/named-data-iot/ndn-lite/blob/master/app-support/bootstrapping/secure-sign-on-files/secure-sign-on/variants/basic/sign-on-basic-client.h, https://github.com/peurpdapeurp/ndn-lite-android-support-library/blob/master/android_library_and_example/ndnlitesupport/src/main/java/NDNLiteSupport/SignOnBasicControllerBLE/secureSignOn/SignOnController.java), as well as higher level sign-on related API’s that couple these lower level API’s with a specific transport (such as BLE) to give the user an easy to use API for doing bootstrapping (https://github.com/named-data-iot/ndn-lite/blob/master/app-support/bootstrapping/secure-sign-on-files/secure-sign-on-nrf-sdk-ble/sign-on-basic-client-nrf-sdk-ble.h, https://github.com/peurpdapeurp/ndn-lite-android-support-library/blob/master/android_library_and_example/ndnlitesupport/src/main/java/NDNLiteSupport/SignOnBasicControllerBLE/secureSignOn/SignOnController.java). Only the higher level sign-on API’s that are coupled with transport should be used by application developers, and they will be described in the following sections.
In the current implementations, the only transport that the SSP has been implemented over is Bluetooth Low Energy. In the Android API’s, this is called the SecureSignOnControllerBLE object, while in the device API’s this is called the sign-on-basic-client-nrf-sdk-ble object (the device side wrapper for Bluetooth Low Energy and the sign-on protocol client has currently only been implemented for the nRF52840 board, using the libraries the nRF SDK provides for BLE communication). As such, the sections that follow will describe higher level API's related to SSP over BLE only; however, interfaces for SSP over other transport would likely be very similar.
In order to use SSP over BLE in an application using the NDN-Lite library for a constrained device, one only needs to add a call to the program to construct and initialize a sign-on client over BLE singleton.
The figure below shows the function that can be executed to start the sign-on client currently implemented in the NDN-Lite library (for the nRF SDK):
Calling this function will automatically construct a basic SSP client that uses the nRF SDK library’s BLE library as the transport over which sign-on will occur. All SSP related jobs (initializing a sign-on-basic-client object with the appropriate values) and transport related jobs (initializing the ble stack, doing advertisements to be discovered by controllers) will be handled by this function call.
Detailed documentation of the parameters used to initialize the sign-on object can be found in the header files linked at the beginning of this section, although a brief summary will be given here as well (in the order that the parameters appear): Basic SSP variant: This is the variant of the basic SSP client that will be used. Currently, only the ECC_256 variant is implemented; see https://github.com/named-data-iot/ndn-lite/blob/master/app-support/bootstrapping/secure-sign-on-files/secure-sign-on/variants/basic/variants/ecc_256/sign-on-basic-ecc-256-consts.h for more details. If NULL is passed in, the default variant will be used, which is currently the ECC_256 variant of the basic SSP. The main difference between different basic SSP variants is the level of security / type of cryptography (RSA vs ECC) used for security operations within the protocol. Device identifier: This is a series of bytes that should be unique to every device undergoing SSP. It is used to differentiate between devices that undergo SSP for the controller. Device capabilities: This is a series of bytes that encodes the capabilities of the device. There are currently no assignments of the bits in this field; it is there for future use. Secure sign on code: This is a pre-shared secret between the controller and device. It should be generated beforehand and entered manually into the SSP controller and client. KS public key: This is the public key of the KS key pair, which is a pre-shared asymmetric keypair between the SSP controller and client. It should be generated beforehand and entered manually into the SSP controller and client. The format of the key is described in the header files linked at the top of the section. KS private key: This is the private key of the KS key pair. Sign-on completion callback: A callback function for when sign-on completes for the sign-on client being initialized.
In order to use SSP over BLE in an application using the NDN-Lite android support library (which can be found here: https://github.com/peurpdapeurp/ndn-lite-android-support-library) for an Android device, one only needs to add a call to the program to construct and initialize a basic SSP controller over BLE singleton.
The figure below shows the function that can be executed to start the basic SSP controller over BLE currently implemented in the NDN-Lite android support library (for Android devices):
It is important to note in the above figure that before initializing the basic SSP controller over BLE singleton, the following things should be performed first: Initialize the NDN-Lite android support library. Initialize the BLEUnicastConnectionMaintainer singleton. If this is not initialized, neither the BLEFace objects nor the SignOnBasicControllerBLE singleton will behave as they should; see the third section of this document for more details.
It is also important to note that for the SSP protocol to successfully be carried out for a device, it has to be added to the controller’s list of devices that are expected for onboarding through the SSP.
This can be done with the function calls shown in the figure below:
As can be seen in the figure above, after the SignOnBasicControllerBLE singleton has been initialized, the addDevicePendingSignOn function should be called with the NDN Certificate of the KS key pair public key, the device identifier, and the secure sign-on code of the device expected to undergo onboarding through the SSP. It should be noted that in the above example the KS key pair public key certificate is created using the raw KS keypair public key (i.e., the minimal amount of bytes needed to represent the key, the same format as that used in the micro-ecc library which can be found here: https://github.com/kmackay/micro-ecc); it is more secure to have the KS public key certificate be signed by some other mutually trusted party, but the example above is mainly used to demonstrate how the API’s for the basic SSP controller on Android can be used.
More details regarding SSP can be found in the paper linked at the top of the page.
The following section will describe the underlying transport mechanisms of SSP over BLE; this section is mostly for developers who are interested in understanding the underlying mechanisms of the current implementation, and who may want to implement something similar for other platforms.
This section will be split into two parts; the first part will describe the current solution, while the second part will explain why certain design choices were made.
The current transport solution for SSP over BLE is intertwined with the BLE face functionality of the NDN-Lite library; as such, it will be necessary to briefly discuss the current BLE face solution used for the NDN-Lite library. Explanation as to why this is the case is given in the next section.
In the current NDN-Lite BLE face implementation, both BLE 4.2 and BLE 5 are used. The main difference between BLE 4.2 and BLE 5 relevant to this design choice is that BLE 4.2 uses "legacy" advertising, in which the maximum payload is 31 bytes (see https://blog.bluetooth.com/exploring-bluetooth5-whats-new-in-advertising), while BLE 5 can use both "legacy" and "extended" advertising. In "extended" advertising, the theoretical maximum payload is much higher, although in practice on the nRF52840 board the maximum payload is 218 bytes (see https://devzone.nordicsemi.com/f/nordic-q-a/41180/maximum-amount-of-data-that-can-be-sent-through-extended-advertisements-nrf52840), and implementations of BLE 5 on different hardware may differ. As advertisements are the only way to broadcast data in BLE, these advertisement packets are a key part of implementing a multicast face in BLE, as having a larger payload allows for more data to be broadcast without fragmentation and reassembly (this will be addressed more in the next section).
In the current solution, the BLE face of the NDN-Lite library communicates with Android phone based controllers using a BLE unicast connection, while it broadcasts data to other constrained devices using extended advertisements. All of the information exchanged between boards and the controller (whether it be SSP related messages or anything else) is done through a BLE unicast connection, while infrormation exchanged between boards is done through extended advertisements.
The main complication of this system comes from the fact that extended advertisements cannot be done while maintaining a unicast connection, at least on the nRF52840 board (this has been verified through experimentation). However, at the same time, it is desireable to provide an abstraction to users of the NDN-Lite library's BLE face that hides this complication, so that data sent through the NDN-Lite BLE face is sent through both the BLE unicast connection and extended advertising (and thus can be received by both any Android controller the board is maintaining a BLE unicast connection with, and other boards within extended advertisement range).
With the above explanations having been given, what follows is the currently implemented solution to share BLE connectivity in NDN-Lite's BLE face between a BLE unicast connection and BLE 5's extended advertising, in order to allow for an nRF52840 board using the NDN-Lite library to exchange data (both send and receive) with both Android devices and other boards simultaneously.
Devices using the NDN-Lite library can choose to initialize a Basic SSP Client object and / or initialize the BLE face of the Ndn-Lite library. Both of these objects are singletons to simplify implementation. Both of these objects also rely on a backend BLE implementation that handles things like scanning, maintaining unicast connectivity, and transport (sending and receiving information over a unicast connection).
The way that the Basic SSP over BLE client and BLE face work together is essentially as follows: it could be considered that the “stable” state of the device is to be in a unicast connection with an Android controller. If it is not currently in a unicast connection with an Android controller, it is either doing legacy advertisements so that a controller can connect to it if it comes in range, or it is doing extended advertisements.
Whenever a message is sent through the BLE face of the Ndn-Lite library, the BLE face will first try to send the message through a unicast connection with an Android controller. If a unicast connection does not exist, it will simply not send the message through a unicast connection, but if a unicast connection does exist it will send the message through that connection.
After that, if it was connected, the NDN-Lite BLE face will disconnect from the unicast connection it is currently in, and then send the same message it just sent through a unicast connection through extended advertising, so that other boards using the Ndn-Lite library’s BLE face can detect the message as well.
After the BLE face is done sending the message through extended advertising, it will then begin legacy advertising; the expectation here is that the controller will proactively connect to devices advertising an Ndn-Lite related service UUID, so that the device can return to its “stable” state.
The reason being connected to the controller is considered a “stable” state is because this is the state in which the device can receive the most information. If it the device is in a unicast connection, it can still scan for extended advertisements, meaning that if another device sends a message through extended advertising, or an Android controller sends a message through a BLE unicast connection, the device can receive both messages simultaneously.
However, when the device is not connected to an Android controller, it will not be able to receive BLE unicast messages from the controller; hence, when the device disconnects from a controller to do extended advertising, it will only be able to detect messages from other boards doing extended advertising. That is why the device will resume legacy advertising as soon as it is done doing extended advertising; it wants to return to a stable state with a controller so that it can exchange data with as many other entities as possible (both other boards and an Android controller).
The Controller contains a BLEUnicastConnectionManager, which is constantly scanning for devices using the NDN-Lite library, and connecting to them automatically if they are detected. If a device using the NDN-Lite library has initialized either a BLE face or its Basic SSP Client over BLE singleton, it will automatically begin advertising over BLE and will be detectable by an Android device using the NDN-Lite Android Support Library that has initialized its BLEUnicastConnectionManager singleton.
Using an observer pattern, the SignOnControllerBLE object and any BLEFace objects that have been created can observe the BLEUnicastConnectionManager singleton and be notified of when connectivity has been established to NDN-Lite devices, and also accept BLE related messages from them. Both the BLEUnicastConnectionManager and SignOnControllerBLE objects are singletons to simplify the implementation, but BLEFace objects are not; a new BLEFace object should be created for every device with which BLE connectivity is desired.
A current quirk of the implementation is that even after the SSP protocol has been successfully carried out for a particular device, the SignOnControllerBLE object will still receive all BLE messages received from that device through the BLEUnicastConnectionManager (as will all BLEFace objects that have been created); in the current solution, the SignOnControllerBLE object will simply ignore these messages, as it will try to parse them to check if they are valid SSP messages and ignore them if they are not.
Many of the parts of the implementation were necessitated by the fact that no Android phones currently support the detection of BLE 5 extended advertisements. As such, a combination of BLE unicast connectivity and BLE 5 extended advertisements was used to allow for the Android phone acting as a controller and constrained devices (e.g., nRF52840 boards) using the NDN-Lite library to communicate.
The main issue here is that BLE 4.2’s "legacy" advertisements can only contain 31 bytes of payload (we have verified this through implementation, and it is also mentioned in many sources such as this one: https://blog.bluetooth.com/exploring-bluetooth5-whats-new-in-advertising).
It would be ideal for an implementation of a multicast NDN face using BLE advertisements to have a larger payload for advertisements; this is exactly a feature that BLE 5 provides, and so that is what is currently used in the implementation of the BLE face in the Ndn-Lite library, so that the devices can send a reasonably large amount of information (currently up to 218 bytes, see here: https://devzone.nordicsemi.com/f/nordic-q-a/41180/maximum-amount-of-data-that-can-be-sent-through-extended-advertisements-nrf52840) through BLE 5 extended advertisement broadcast to multiple devices simultaneously.
Although fragmentation and reassembly could be used to implement a BLE face using the smaller payload of legacy advertisements, once wider support for BLE 5 is available, it will be helpful to already have an implementation of a BLE multicast face using extended advertising; therefore, the NDN-Lite BLE face uses extended advertising.
However, current support for BLE 5 is inadequate, especially with regards to Android phones. Although several Android phones claim to support BLE 5 and extended advertising (such as the Google Pixel 2, which evaluation was done on), they only offer partial support. For example, we found through experimentation that the Google Pixel 2 can only send extended advertisements, but not detect them. Several other users have had similar issues with other phones: https://devzone.nordicsemi.com/f/nordic-q-a/37885/extended-advertising-with-sdk-15-1-seems-not-to-work
Therefore, currently the implementation on both the controller and device side share BLE connectivity between the BLE faces in their respective implementations, and the sign-on component in their respective implementations (i.e., the SignOnControllerBLE object on the Android side, and the sign-on-basic-client-nrf-sdk-ble object on the device side).
The sharing of BLE connectivity in this way allows for the phone and the boards to communicate with each other in almost all situations, as was described in the previous section.