Security Bootstrapping
ndn-lite wiki
An Overview
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.
If you would like to learn more about the sign-on protocol, you can read the original paper here: https://drive.google.com/drive/folders/1JYsbtDlDs6vRmKqGVN4NwHc6n-56udNB?usp=sharing.
***NOTE: The link above does not reflect the final version of the paper, and is only there temporarily until a link to the final version of the paper is available.
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).
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 below. As the only transport over which sign-on has currently been implemented is BLE, the sections below will show interfaces for that sign-on / transport pairing.
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.