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 two major roles:

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

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.

Architecture

Block Diagram of Provisioning Module

provisioning_module_architecture.jpg

Sequence Diagrams

Sequence Diagram Just works ownership Transfer

Sequence Diagram Random PIN ownership Transfer

C APIs

Provisioning database APIs

1.jpg 2.jpg

Provisioning Manager APIs

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

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 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)
** 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 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

ACE(ACL) modification

  • Select ‘4. Modify entity’
  • Select ‘1. Modify ACE’

  • Input the number of ACE

  • Select menu and modify

Doxm addition

  • Select ‘2. Add entity’

  • Input values

  • Verify that the doxm was successfully saved.

  • Supported menus for modifying doxm

Pstat addition

  • Select ‘2. Add entity’

  • Input values

  • Verify that the pstat was successfully saved

  • Supported menus for modifying pstat

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/10/16 06:15 by Sangjoon Je