User Tools

Site Tools


provisioning

Provisioning

Provisioning Manager could act as a security administrator of IoT devices in its IP subnet. When new device is introduced in the IP subnet, Provisioning Manager takes the ownership of the new device and provisions security information such as credential and access control policy to manage new device securely. If PM doesn’t take ownership and provide proper security policy to the newly introduced device in its IP subnet, the new device might be under control of unwanted subjects and perform undesirable operations such as turning on the light during midnight and ignoring user’s commands.

Features

The Provisioning Manager has three major roles:

  • Ownership Transferring
  • Security management of owned devices (Credentials, Access Control List of the owned devices).
  • Direct pairing

Transferring Ownership

When performing this role, PM discovers un-owned devices from the network and tries to transfer ownership of the discovered device to the admin (provisioning manager application). Ownership Transfer Manager sub-module is in charge of this role. Current version supports following methods of ownership transfer

  • “Just-works” ownership transfer method
  • “Random PIN based” ownership transfer method

Security management of owned devices

When performing this role, PM provisions credentials and ACL to the owned devices. Also, PM has a capability to revoke credentials from every owned device in the network and remove ACL on the provisioned device. To support revocation, PM has to keep tracks of provisioned credentials and ACLs. The provisioning database manager keeps provisioned credential history to manage OIC network. Provisioning Database Manager and Secure Resource Provider sub-modules are in charge of this role.

Direct Pairing

In an ideal IoT scenario, various tool(s) and/or services (e.g. provisioning tool (PT), credential management service(CMS), access manager service(AMS), and so on) establish security features for IoT devices. These tool(s) and/or services are assumed to be available all the time. However, this assumption may not always be true in real life. For example, consider a user who has a PT on his/her mobile phone for IoT devices at home. Assume that a new device is introduced while he/she has gone out with the phone. Then the security features for this new device cannot be provisioned as the PT is not available.

Consider another scenario in which Person A wants to control a device owned by Person B for some time. As the device is owned by Person B, Person A cannot even discover the device he/she wants to control and claim ownership in order to control it.

A Direct Pairing method enables a security establishment between two IoT devices without any help of security tools and/or services. This may apply to the follow user scenarios;

  1. An immediate use of a new IoT device when provisioning tools/services are not available
  2. Access and control to user IoT devices by a guest IoT device
  3. Access and control among user IoT devices provisioned or owned by different provisioning tools/services

Architecture

Block Diagram of Provisioning Module

Sequence Diagrams

Sequence Diagram Just works ownership Transfer

Sequence Diagram Random PIN ownership Transfer

Sequence Diagram Direct pairing

Direct Pairing consists of 2 steps: direct pairing configuration sequence and device pairing sequence

Direct pairing configuration sequence

After the Ownership Transfer, the Direct Pairing configuration API of the Provisioning Manager is responsible for provisioning the necessary configuration resources for the Direct Pairing to the Server device, given that the IoT device supports Direct Pairing. The pre-configuration resources (/oic/sec/pconf) contain the following information: - Whether or not Direct Pairing is enabled - Supported Pairing methods - The pre-configured PIN (if pre-configured PIN D2D Pairing is supported) - Pre-configured access control list(ACL) template containing ACL information On the application layer, the user may decide the preferred methods of Direct Pairing and the PIN to be used for Direct Pairing.

Current version supports the following methods of Direct Pairing: - Pre-configured pairing method - Random-PIN pairing method

Device pairing sequence

During the device pairing between a Client device and a Server device, the Direct Pairing instance provides Resource Manager with APIs needed for creating Device Pairing resources at the Secure Virtual Resource database. Through Device Pairing discovery API, the Client device discovers the pre-configuration of the Server device created during Device Pairing configuration. Once the method of Direct Pairing is chosen, the Client will enter the PIN (pre-configured or random) in order to continue with pairing process. The Client and Server each creates Direct Pairing resources at the Secure Virtual Resource database and a secure channel between the two devices is established using the PIN. The SRM of the Server device will create ACL based on the pre-configured ACL template. The device pairing step finishes with the exchange of confirmation messages between the two devices. After Direct Pairing is done, the Client can establish a secure channel using the newly created credential resource for the Direct Pairing, and the ACL stored in the Direct Pairing resource database of the Server will allow the Policy Engine of the Server to grant access to and control over secure resources to the Client device.

C APIs

Provisioning database APIs

1.jpg 2.jpg

Provisioning Manager APIs

3.jpg 4.jpg 5.jpg 6.jpg 7.jpg

Direct Pairing APIs

C++ API

9.jpg 10.jpg 11.jpg 12.jpg 13.jpg

Android API

14.jpg 15.jpg 16.jpg 17.jpg

Sample Application

Simple server and provisioning client

This section introduces how to run sample applications which includes discovery of devices on network, ownership transfer, provisioning of ACL, provisioning of direct pairing, provisioning credentials for pairwise things, check linked status of a selected device, unlink of pairwise things and removal of a selected device. There are three sample applications: 2 for sample servers (i.e. justworks and random pin) and a Provisioning Client.

Source code location of the sample code

iotivity/resource/csdk/security/provisioning/sample/ 

Binary location after source code build (for Linux build)

iotivity/out/linux/x86_64/release/resource/csdk/security/provisioning/sample  

How to execute sample

Preliminary, run server applications sampleserver_justworks and sampleserver_randompin as follows:

iotivity/out/linux/x86_64/release/resource/csdk/security/provisioning/sample/  ./sampleserver_justworks 
iotivity/out/linux/x86_64/release/resource/csdk/security/provisioning/sample/  ./sampleserver_randompin 

Now, run a provisioning client application as follows:

iotivity/out/linux/x86_64/release/resource/csdk/security/provisioning/sample/  ./provisioningclient
************************************************************
****** OIC Provisioning Client with using C-level API ******
************************************************************
** [A] DISCOVER DEVICES ON NETWORK
** 10. Discover All Un/Owned Devices on Network
** 11. Discover Only Unowned Devices on Network
** 12. Discover Only Owned Devices on Network
 
** [B] REGISTER/OWN ALL DISCOVERED UNOWNED DEVICES
** 20. Register/Own All Discovered Unowned Devices
 
** [C] PROVISION/LINK PAIRWISE THINGS
** 30. Provision/Link Pairwise Things
** 31. Provision Credentials for Pairwise Things
** 32. Provision the Selected Access Control List(ACL)
** 33. Provision Direct-Pairing Configuration
** 34. Check Linked Status of the Selected Device on PRVN DB
 
** [D] UNLINK PAIRWISE THINGS
** 40. Unlink Pairwise Things
 
** [E] REMOVE THE SELECTED DEVICE
** 50. Remove the Selected Device
 
** [F] EXIT PROVISIONING CLIENT
** 99. Exit Provisioning Client
************************************************************
 
>> Enter Menu Number:

Once provisioning client application is executed you can see the log on your screen like above, it confirms that all preliminary steps are done successfully.

Discover unowned devices

First step is to discover only the unowned devices on the network. If you select option “11” in the above screen, you will get the list of all unowned devices on the network.

** 11. Discover Only Unowned Devices on Network
OUTPUT:
> Discovered Unowned Devices
     [1] 64697265-6374-7061-6972-696E67446576 
     [2] 72616E64-5069-6E44-6576-557569643030

As you can see on your screen there are two unowned devices on the network (namely sampleserver_justworks and sampleserver_randompin)

Ownership transfer of unowned devices

Now the next step is ownership transfer of the unowned devices. If you select option “20”, this will register (transfer ownership) all the unowned devices on the network.

** 20. Register/Own All Discovered Unowned Devices
> Discovered Unowned Devices
   > INPUT PIN:
NOTE: While registering the sampleserver_randompin application a PIN is generated at sampleserver_randompin side, the same has to be manually entered at the provisioningclient.
e.g  On sampleserver_randompin side the display will be like
SAMPLE_RANDOMPIN: ============================
SAMPLE_RANDOMPIN:     PIN CODE : 73883075
SAMPLE_RANDOMPIN: ============================
 
copy the same PIN at provisioningclient.
 
OUTPUT:
> Registered Discovered Unowned Devices
> Please Discover Owned Devices for the Registered Result, with [10|12] Menu

Once the ownership transfer for both the devices are done, it can be verified by selecting option “12”.

** 12. Discover Only Owned Devices on Network
> Discovered owned Devices
OUTPUT:
[1] 64697265-6374-7061-6972-696E67446576 
[2] 72616E64-5069-6E44-6576-557569643030

Provision the Access Control List (ACL)

Select option “32” to provision the ACL

** 32. Provision the Selected Access Control List (ACL)
OUTPUT:
>> Enter Menu Number: 32
 
   > Enter Device Number, for Provisioning ACL: 1
   **** Create ACL for the Selected Device[1]
   > [A] Enter Subject Device Number: 2
   > [B] Enter Number of Accessed Resources (under 16): 1
         Enter Each Accessed Resource Name (each under 128 char)
         Enter Accessed Resource[1] Name: door
   > [C] Enter Permission for This Access
         Enter CREATE Permission (y/n): y
         Enter READ Permission (y/n): y
         Enter WRITE Permission (y/n): y
         Enter DELETE Permission (y/n): y
         Enter NOTIFY Permission (y/n): y
   > [D] Enter Owner Device Number: 1
 
> Provisioned Selected ACL

Provisioning of direct pairing

Select option “33” to provision direct pairing configuration.

>> Enter Menu Number: 33
OUTPUT:
   > Enter Device Number, for Provisioning Direct-Pairing: 1
   > SUCCESS to provision Direct-Pairing !!

Provisioning credentials for pairwise things

Select option “31” to provision credentials for pairwise things.

** 31. Provision Credentials for Pairwise Things
OUTPUT:
>> Enter Menu Number: 31
 
> Enter Device[1] Number, for Linking CRED(s): 1
> Enter Device[2] Number, for Linking CRED(s): 2
	Select PSK length..
   1 - 128bit(Default)
   2 - 256bit
	1
 
> Provisioned Selected Pairwise Credentials

Check Linked Status of the Selected Device

Select option “34” to check linked status of the selected device

>> Enter Menu Number: 34
OUTPUT:
> Enter Device Number, for Checking Linked Status on PRVN DB: 1
Checking Selected Link Status on PRVN DB..
> Checked Selected Link Status on PRVN DB
 [1] 72616E64-5069-6E44-6576-557569643030

Select option “40” to unlink pairwise things

>> Enter Menu Number: 40
OUTPUT:
> Enter Device[1] Number, for Unlinking Devices: 1
> Enter Device[2] Number, for Unlinking Devices: 2
 
> Unlinked Selected Pairwise Devices
> Please Check Device's Status for the Unlinked Result, with [34] Menu

Remove the Selected Device

Select option “50” to remove the selected device

>> Enter Menu Number: 50
OUTPUT:
> Enter Device Number, for Removing Device: 2
   Removing Selected Owned Device..
> Removed Selected Owned Device
 > Please Discover Owned Devices for the Registered Result, with [10|12] Menu

IoTivity Device UUID & SVR DB Reset

Device UUID Generation

  • The Device UUID is determined when secure resources are initialized.
  • If “deviceuuid” property of doxm resource is not empty in SVR DB (.dat file), the stored value is used as device UUID
  • If it is empty, a new UUID is generated when secure resources are initialized
    • Random UUID is generated: OCGenerateUuid().
    • Seed-based UUID is generated with seed input parameter. This will be used to support UUID uniqueness for each iotivity instance.

For instance, MAC address seed may be entered into “deviceuuid” using SetDoxmDeviceID().

  • If UUID seed value is set, UUID will be generated based on seed value. The UUID ensures uniqueness for the same seed. Also the seed value must be set before the iotivity stack is initialized. (Specifically before the OCInit is invoked)
  • UUID seed value can be set using the following API:
    • C
      • OCStackResult SetDeviceIdSeed(const uint8_t* seed, size_t seedSize)
      • Header : resource/csdk/security/include/srmutility.h
    • C++
      • static OCStackResult OCSecure::setDeviceIdSeed(const uint8_t* seed, size_t seedSize)
      • Header : resource/include/OCProvisioningManager.hpp
    • Java
      • public static int setDeviceIdSeed(byte[] seed) in OcProvisioning class
      • File : android/android_api/base/src/main/java/org/iotivity/base/OcProvisioning.java

Device UUID Backup

  • Once secure resources are initialized, a backup security data is created as “Reset Profile” and saved to SVR DB
  • The UUID is also included in Reset Profile
  • During security reset in factory reset process, the backup data saved in Reset Profile replace the entire SVR DB
  • As the Reset Profile contains the original UUID information, the device UUID is restored and remains the same after security reset

SVR DB Reset

  • Once secure resources are initialized in IoTivity stack, the entire SVR DB is copied and this copy is stored in SVR DB as “resetpf” (Reset Profile)
  • This back-up copy stores the values of SVR DB at its initiation
  • When SVR DB Reset is called (both remote and local), the data stored in “resetpf” is read from SVR DB and replace the entire data in the persistent storage, hence restoring the original SVR DB
  • A client may initiate SVR DB Reset of a server via remote reset by calling OCResetDevice()
  • A device may reset its own SVR DB by calling OCResetSVRDB()

Note : SVR DB is for Security Virtual Resource which contains OCF-standard security resources such as doxm/pstat/cred/acl…etc.

SVR DB Editor User manual

SVR DB Editor

  • This tool provides the following functions
    • Shows each security virtual resources
    • Edit(such as add, delete and modify) each security virtual resources

NOTE : Currently, some features are not supported

  • Doxm modification
  • Pstat modification

Build and Run

  • [Build]
    • $ scons resource/csdk/security/tool SECURED=1
  • [Run]
    • $ cd [build dir]/resource/csdk/security/tool
    • $ ./svrdbeditor [SVR DB path]
  • The edit and print menu for each resource is provided as shown below:

  • Each editing function provides the following sub-functions

Specific usage examples

ACE(ACL) addition

  • Select ‘3. Edit ACL Resource.’

  • Select ‘2. Add entity’

  • Input the detail for new ACE

  • Verify that the certificate was successfully saved

D2S Certificate addition

  • Trust CA certificate chain
  • Primary certificate key pair (optional for mutual authentication)

Note : it will be sample or test purpose, as for the commercial version, this resource may be refering to security element such as TZ or eSE.(you can see TZ wrapper guide document in iotivity)

Trust CA certificate chain addition

  • Select ‘2. Edit Credential Resource.’

  • Select ‘2. Add entity’

  • Input the information of Trust CA certificate

  • Verify that the certificate was successfully saved

Primary certificate key pair addition

(optional for mutual authentication)
  • Select ‘2. Edit Credential Resource.’

  • Select ‘2. Add entity’

  • Input the encoding type and file path for Key & Cert

  • Verify that the key & certificate was successfully saved

provisioning.txt · Last modified: 2017/02/16 08:47 by saurabh sharma