IoTivity Provisioning Manager Design Specification v0.1d

Transcription

1 IoTivity Provisioning Manager Design Specification v0.1d Contributing Authors (alphabetical order): Ashwini Kumar Chul Lee Randeep Singh Sandeep Sharma WooChul Shim 1

2 Table of Contents Background... 3 Terminology... 3 Provisioning Manager (PM) Overview... 4 Ownership Transfer Manager (OTM)... 6 Secure Resource Provider (SRP)... 9 Provision ACL... 9 Provision Credential Revoke ACL Revoke Credential Provisioning Database Manager (PDM) Public Provisioning Manager API C++/Android API Support

3 Revision History Version Date Author(s) Summary 0.1 6/12/2015 Randeep, Initial draft WooChul 0.1a 6/29/2015 Randeep Added Implementation details in Revoke Credentials. 0.1a 7/3/2015 WooChul Added PDM Added abstracted Credential Revocation flows. 0.1b 7/22/2015 Chul Lee Added OTM callback and sequence flow. Added public OC API. 0.1c 9/30/2015 Ashwini, Sandeep Added C++/Android API information 0.1d 10/13/2015 WooChul Added brief for the role of Provisioning Manager Background The reader is assumed to be familiar with the IoTivity Security. Terminology Term Provisioning Credential Access Control List Device ID Ownership Transfer 3

4 Provisioning Manager (PM) Overview Why do we need Provisioning Manager? Figure 1. The Role of Provisioning Manager Provisioning Manager could be 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 command. Figure 2. Simple illustration of provisioned device and not provisioned device 4

5 Figure 3. Provisioning Manager Module Block Diagram The Provisioning Manager has two major roles: Ownership Transferring, and 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 5

6 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. Ownership Transfer Manager (OTM) When provisioning manager (PM) application receives supported Ownership transfer methods from the resource server during the ownership transfer process, PM selects the most secure ownership transfer method and continues the remained ownership transfer process. Since provisioning manager has to accept various ownership transfer methods (OxM), OTM should provide proper callbacks to each OxM. The provided callbacks should be implemented by each OxM developer. In order to add new OxM, OxM developer should implement four callbacks below. 1. Function to load secret value used to derive temporal key to establish a DTLS session and save this generated temporal key to /oic/sec/cred. - Callback Name: loadsecretcb - Prototypes: typedef OCStackResult (*OTMLoadSecret)(OTMContext_t* otmctx); 2. Function to establish a temporary DTLS session. In this callback, ciphersuite will not be specified. All enable ciphersuites will be sent. The temporal key generated during step 1 will be used to create secure session. - Callback Name : createsecuresessioncb - Prototypes : typedef OCStackResult (*OTMCreateSecureSession)(OTMContext_t* otmctx); 3. Function generating payload for selecting ownership transfer method. This payload will be sent to the un-owned resource server. - Callback Name : createselectoxmpayloadcb - Prototypes : typedef char* (*OTMCreatePayloadCallback)(OTMContext_t* otmctx); 4. Function generating payload for finalizing ownership transfer method. This payload generally includes status change information such as owned=true. This payload will be sent to un-owned resource server. - Callback Name : createownertransferpayloadcb - Prototypes : typedef char* (*OTMCreatePayloadCallback)(OTMContext_t* otmctx); 6

7 After ownership transfer method callbacks are implemented, provisioning application developer should register these callback functions by invoking OCSetOwnerTransferCallbackData API. OTM will use these callback functions internally to continue ownership transfer according to the selected OxM. Figure2 is a diagram representing the function call sequence of ownership transfer in the provisioning manager application. Figure 4. Ownership transfer sequence diagram OTM supports Just works OxM and PIN based OxM by default. But OCSetOwnerTransferCallbackData should be invoked in the provisioning application side as follows: 7

8 OTMCallbackData_t justworkscbdata = {}; justworkscbdata.createsecuresessioncb = CreateSecureSessionJustWorksCallback; justworkscbdata.createselectoxmpayloadcb = CreateJustWorksSelectOxmPayload; justworkscbdata.createownertransferpayloadcb = CreateJustWorksOwnerTransferPayload; OTMSetOwnershipTransferCallbackData(OIC_JUST_WORKS, &justworkscbdata); OTMCallbackData_t pinbasedcbdata = {}; pinbasedcbdata.loadsecretcb = InputPinCodeCallback; pinbasedcbdata.createsecuresessioncb = CreateSecureSessionRandomPinCallbak; pinbasedcbdata.createselectoxmpayloadcb = CreatePinBasedSelectOxmPayload; pinbasedcbdata.createownertransferpayloadcb = CreatePinBasedOwnerTransferPayload; OTMSetOwnershipTransferCallbackData(OIC_RANDOM_DEVICE_PIN, &pinbasedcbdata); Code 1. Sample code to register the OxM callback In case of Just works OxM, loadsecretcb doesn t have a role to do during the Just works ownership transfer because Just works OxM will use anonymous ciphersuite to establish a temporary DTLS session (TLS_ECDH_anon_WITH_AES_128_CBC_SHA256). Thus, secret value isn t required to establish a DTLS session. In case of PIN based OxM, loadsecretcb ask user to poke the PIN value. This PIN number is used to derive temporal key to establish temporary DTLS session. After the temporary DTLS session is established, remaining proceed of ownership transfer is the same. Figure 3 and figure 4 decribe detailed process of each OxM. Figure 5. Just-works OxM flow 8

9 Figure 6. "Random PIN based" OxM flow Secure Resource Provider (SRP) Secure resource provider (SRP) APIs of provisioning manager are responsible for provisioning secure resources to resource server(s). Secure resources provisioning include ACL provisioning and credentials provisioning. Following are the SRP capabilities - Provisioning of ACL to a specific device. (/oic/sec/acl) - Generating credential resource currently only supports symmetric credential provisioning; Current supported length of key is 128 and 256 bits and provisioning generated credentials. (/oic/sec/cred) - Providing pair-wise credential and ACL between two devices, Single API is capable of provisioning credentials and provisioning ACL, so that two devices can communicate over secure channel. Provision ACL ACL provisioning API of provisioning manager can provisioning ACL resource to resource server. 9

10 User can define ACL according to the need and this API can be used to send generated ACL to resource server over secure channel. In order to provision ACL to proper target resource server, we need to discover devices using owned discovery; owned discovery is provided with provisioning manager as a utility module. Owned discovery returns list of already owned devices. Provision Credential Figure 7. ACL Provisioning sequence diagram Credential provisioning API of provisioning manager is responsible for provisioning credential resource to resource server. Current version supports generation of symmetric key of size 128 bits and 256 bits and generated key will be provisioned to devices. Provision credential APIs always work with a pair of devices which need credential so that communicate over secure channel because current provisioning manager support only symmetric key type credential. In order to use this API we need to use owned discovery to get list of devices and from that list we can choose devices that needs credential provisioning. 10

11 Figure 8. Credential Provisioning sequence diagram Revoke ACL (Future Work) PM should be able to remove inappropriate or invalid ACL resource on the target resource server. Thus, PM should have capability of GET current ACL resources on the target resource server for review of the ACL resources. The OicSecAcl_t in securevirtualresourcetypes.h is used to contain the received ACL resources. After reviewing by an administrator, the admin may remove or update the ACL resource. If the admin wants to remove all ACL, PM can send a DELETE request on /oic/sec/acl of the resource server. If the admin wants update, User can create new ACL by reviewing ACL and then can send DELETE request on /oic/sec/acl to delete the old ACL and then POST new ACL. Example Query for ACL revocation DELETE oic/sec/acl & PUT oic/sec/acl: Query would reset ACL to default state. This is supported now. Partial update with GET and PUT request is not allowed now. Whole update with DELETE and POST is allowed. 11

12 DELETE oic/sec/acl?subjectid=xxx&&rsrc=yyyy. ACE consist of subject, resource, permission and owners to successful search a ACE among the list of ACEs we need to provide pair of subject and resource. Then particular entry of that resource from list can be removed. This query is not supported right now but might be supported later Revoke Credential PM should have capability to remove already provisioned credentials of selected device on every owned device in the network in order to keep valid trust relationships among owned devices. Revocation of the provisioned credential from every provisioned device should be performed whenever one of the provisioned devices is removed from the network for some reason (lost, stolen, resale and etc). To identify which devices are related to the removed device, PM should keep track of credential provisioning history and manage the history by using database. After identifying which devices have the credential which should be revoked, DELETE request to the /oic/sec/cred is sent by PM. Credential revocation flow can be varied according to the credential types. (Symmetric key and certificate will be covered) As credential revocation is multiple request response process, in which Provisioning tool will send request to all the devices which share credential with a device for which credentials are to be deleted. In case during this process some devices are turned off. Then we can t remove credentials from them and their DB would contain stale credential entries. To overcome this problem we can create call to check and update network according to provisioning DB. Every time we send credential revocation request we have to wait for specific time to wait for response. If we didn t get the response back then we can assume that that particular device is stale and currently is unable to respond to request and we have to perform credential revocation again on this device in future. 12

13 Figure 9. Abstracted device revocation sequence diagram Above diagram shows device revocation sequence. Resource server 1, Resource server 2 and Resource server 3 (further referred as RS1, RS2 and RS3) are already provisioned and admin wants to delete RS3 from network so user calls an API to delete the device (RS3). PM first search the Provisioning Database module (PDM) to get information about all the devices which shares pairwise credential with the RS3. DELETE request to delete the credential is sent to devices listed in previous step. 13

14 Figure 10. Abstracted a pairwise credential revocation sequence diagram In case we have two devices which are provisioned with pairwise credential and admin want to revoke those credentials so that those two devices cannot communicate over secure channel. Suppose RS3 and RS2 are provisioned with pairwise credentials and admin wants to revoke it. PM will send delete request to RS3 to delete credential corresponding to RS2 and send delete request to RS2 to delete credential corresponding to RS3. Provisioning Database Manager (PDM) The initial version of PDM will provide APIs for managing credential provisioning history. (We will consider ACL later). Since persistent storage is platform (OS and H/W) specific, the application should provide required functions to the PDM and the PDM provides them to the PM. Open: If we fix the data structure for managing credential provisioning history, there could be a no chance to utilize exist database solution such as SQLite. Otherwise, if we don t fix the data structure, the complexity of application developer is increased dramatically. We should have to think about what level of abstraction is proper for application developer and the management complexity is high enough to use database management system. 14

15 What kinds of data are saved into this Provisioning Database? - Credential provisioning history to maintain network properly, ACL provisioning information to provide useful security information to administrator. In case of certificate based credential management, Certificate Authority s subject name, public/private key, issued history and certificate which is only used to issue device certificate can be stored into the provisioning database. * We can use file or database, the implementation could be varied according to the storage type. Current explanation assumes that we are going to use SQLite DB. Following are the explanation of interfaces exposed by PDM to PM OCStackResult PDMInit(); This function performs the initialization operations like opening DB connection OCStackResult PDMAddDevice(OicUuid_t* UUID); It adds the device UUID information to persistent storage. It will be called after every successful ownership transfer. OCStackResult PDMLinkDevices(OicUuid_t *UUID1, OicUuid_t *UUID2); It saves the link information of two devices in persistent storage, Every time after successful credential provisioning between two devices. This API is called to save the link information. OCStackResult PDMUnlinkDevices(OicUuid_t *UUID1, OicUuid_t *UUID2); It removes the link information from persistent storage. Every time after successful credential revocation between two devices this API is called to remove the link information. OCStackResult PDMDeleteDevice(OicUuid_t *UUID); It removes complete information of device including all the link information and device s owned information from persistent storage. This API is called along device revocation API. OCStackResult PDMGetOwnedDevices(OCUuidList_t** uuidlist, size_t* numofdevices); This API fetches owned device list from persistent storage and provide list to its caller. OCStackResult PDMGetLinkedDevices(OicUuid_t* UUID, OCUuidList_t** UUIDLIST, size_t* numofdevices); This API fetches the information of credential pair links from the persistent storage 15

16 and provides a list of all the devices which are linked to specified device Id. OCStackResult PDMGetToBeUnlinkedDevices(OCPairList** staledevlist, size_t* numofdevices); This API lists all the devices of which credential were supposed to be removed but these devices didn t respond to the revocation call due to some uncontrollable external factors (like power off). OCStackResult PDMIsLinksExists(const OicUuid_t* uuidofdevice1, const OicUuid_t* uuidofdevice2, bool* result); This API is used by provisioning manager to check does the link exists between Two devices or not. OCStackResult PDMSetLinkStale(const OicUuid_t* uuidofdevice1, const OicUuid_t* uuidofdevice2); This method is used by provisioning manager to update linked status as stale. OCStackResult PDMClose(); API to perform tasks like closing of DB connection. Public Provisioning Manager API OCStackResult OCInitPM(const char* dbpath) The function is responsible for initialization of the provisioning manager. It will load provisioning database which have owned device's list and their linked status. (Future work: If there is a device(s) which has not up-to-date credentials, this function will automatically try to update the device(s).) OCStackResult OCDiscoverUnownedDevices(unsigned short waittime, OCProvisionDev_t **pplist) The function is responsible for discovery of device is current subnet. It will list all the device in subnet which are not yet owned. OCStackResult OCDiscoverOwnedDevices(unsigned short timeout, OCProvisionDev_t **pplist) The function is responsible for discovery of owned device is current subnet. It will list all the device in subnet which are owned by calling provisioning client. 16

17 OCStackResult OCDoOwnershipTransfer(void *ctx, OCProvisionDev_t *targetdevice, OCProvisionResultCB resultcallback) API to performing ownership transfer for unowned devices. The device list obtained from OCDiscoverUnownedDevices can be used as first parameter. The Second parameter passed to the result callback function that will be called when ownership transfer is finished. The result callback is invoked only once all the ownership transfer is finished. OCStackResult OCSetOwnerTransferCallbackData(OicSecOxm_t oxm, OTMCallbackData_t *callbackdata) API to register for particuar OxM(ownership transfer method)'s callback function. Implementation of callback function will be provided in resource/csdk/security/provisioning/include/oxm*.h. OCStackResult OCProvisionPairwiseDevices(void *ctx, OicSecCredType_t type, size_t keysize, const OCProvisionDev_t *pdev1, OicSecAcl_t *pdev1acl, const OCProvisionDev_t *pdev2, OicSecAcl_t *pdev2acl, OCProvisionResultCB resultcallback) API to provision credentials between two devices and ACLs for the devices who act as a server. OCStackResult OCProvisionACL(void *ctx, const OCProvisionDev_t *selecteddeviceinfo, OicSecAcl_t *acl, OCProvisionResultCB resultcallback) API to send ACL information to resource. OCStackResult OCProvisionCredentials(void *ctx,oicseccredtype_t type, size_t keysize, const OCProvisionDev_t *pdev1, const OCProvisionDev_t *pdev2, OCProvisionResultCB resultcallback) API to provision credential to devices. void OCDeleteDiscoveredDevices(OCProvisionDev_t *plist) API to delete memory allocated to linked list created by OCDiscover_XXX_Devices API. OCStackResult OCUnlinkDevice(void *ctx, const OCProvisionDev_t* ptargetdev1, const OCProvisionDev_t* ptargetdev2, OCProvisionResultCB resultcallback) This function will remove the credential & relationship between the two devices. 17

18 OCStackResult OCRemoveDevice(void* ctx, unsigned short waittimeforowneddevicediscovery, const OCProvisionDev_t* ptargetdev, OCProvisionResultCB resultcallback) This function will remove credential of target device from all devices in subnet. OCStackResult OCGetDevInfoFromNetwork(unsigned short waittime, OCProvisionDev_t** powneddevlist, OCProvisionDev_t** UnownedDevList) API to get status of all the devices in current subnet. The status includes endpoint information and doxm information which can be extracted during owned and unowned discovery. Along with this information. The API will provide information about devices' status Device can have following states - ON/OFF: Device is switched on or off. OCStackResult OCGetLinkedStatus(const OicUuid_t* uuidofdevice, OCUuidList_t** uuidlist, size_t* numofdevices) This method is used to get linked devices' IDs. void OCDeleteUuidList (OCUuidList_t* plist) API to delete memory allocated to OicUuid_t list. void OCDeleteACLList (OicSecAcl_t* pacl) API to delete memory allocated to ACL data. OCStackResult OCProvisionCRL(void* ctx, const OCProvisionDev_t *selecteddeviceinfo, OicSecCrl_t *crl, OCProvisionResultCB resultcallback) This function sends CRL information to resource. 18

19 C++/Android API Support All public PM APIs support C++ and Android APIs. These are the list of the APIs. C++ APIs: resource/include Android APIs: Android/android_api/base/jni C++ APIs Class : Credential : this is a data type for managing credentials used by the secure virtual resource. OicSecCredType_t getcredentialtype(); API to get the Credential Type used. The types can be 0: no security mode 1: symmetric pair-wise key 2: symmetric group key 4: asymmetric key 8: signed asymmetric key (aka certificate) 16: PIN /password size_t getcredentialkeysize(); API to get the Credential Key size. void setcredentialtype(oicseccredtype_t type); API to set the Credential Type used. The types can be 0: no security mode 1: symmetric pair-wise key 2: symmetric group key 4: asymmetric key 8: signed asymmetric key (aka certificate) 16: PIN /password void setcredentialkeysize(size_t keysize) API to set the Credential s key size. Class : OcSecure : This class is a collection of common functions, which do not operate resource specific static OCStackResult provisioninit(const std::string &dbpath); API to Initialize provisioning Manager by providing the provisioning database file path dbpath. 19

20 static OCStackResult discoverunowneddevices(unsigned short timeout, DeviceList_t &list); API to discover List of all devices in the subnet which are not yet Owned by the user. static OCStackResult discoverowneddevices(unsigned short timeout, DeviceList_t &list); API to discover List of all devices in the subnet which are Owned by the user. static OCStackResult setownertransfercallbackdata(oicsecoxm_t oxm, OTMCallbackData_t* callbackdata, InputPinCallback inputpin); API to set callback methods for ownership transfer for a particular OxmType (Ownership Transfer Method) and Pin Callback method to Input PIN. static OCStackResult getdevinfofromnetwork(unsigned short timeout, DeviceList_t &owneddevlist, DeviceList_t &unowneddevlist); API to get status of all the devices in current subnet. Device status will include information about - ON/OFF: Device is switched on or off. static OCStackResult setdisplaypincb(generatepincallback displaypin); Server API to register a callback to display the PIN for RANDOM_DEVICE_PIN authentication Class : OcSecureResource : This class represents a secure virtual resource and its state. OCStackResult doownershiptransfer(resultcallback resultcallback); API to start Ownership transfer of un-owned OcSecureResource Object, which was obtained by calling discoverunowneddevices. resultcallback will be called asynchronously with result after ownership transfer is complete. OCStackResult provisionpairwisedevices(const Credential &cred, const OicSecAcl_t* acl1, const OCSecureResource &device2, const OicSecAcl_t* acl2, ResultCallBack resultcallback); API to provision credentials and ACLs between two devices who act as a server. First device is the object for which this API is called. OCStackResult provisioncredentials(const Credential &cred, const OCSecureResource &device2, ResultCallBack resultcallback); API to provision credentials to the device. resultcallback will be called asynchronously with result of credential provisioning. OCStackResult provisionacl(const OicSecAcl_t* acl, ResultCallBack resultcallback); API to send ACL to the device. resultcallback will be called asynchronously with result of ACL provisioning. OCStackResult unlinkdevices(const OCSecureResource &device2, ResultCallBack resultcallback); 20

21 API to remove credentials and relationship between two devices. First device is the object for which this API is called. OCStackResult removedevice(unsigned short waittimeforowneddevicediscovery, ResultCallBack resultcallback); API to unlink the device links to each device it is linked with. OCStackResult getlinkeddevices(uuidlist_t &uuidlist); API to get List of all devices it is linked with. std::string getdevaddr(); API to get IP address of the device as a String. std::string getdeviceid(); API to get device ID (UUID) of the device as B64 encoded string. int getdevicestatus(); API to get status of the device. ON or OFF or INVALID bool getownedstatus(); API to get Owned/Unowned status of the device. OWNED or UNOWNED or INVALID Android APIs Class : OcProvisioning : This class is a collection of common functions, which do not operate resource specific public static native void provisioninit(string dbpath) throws OcException; API to Initialize provisioning Manager by providing the provisioning database file path dbpath. public static List<OcSecureResource> discoverunowneddevices(int timeout) throws OcException API to discover List of all devices which are not owned/registered yet in the current subnet. public static List<OcSecureResource> discoverowneddevices(int timeout) throws OcException API to discover List of all devices which are owned/registered by provisioning Client. public static void SetownershipTransferCBdata(OxmType type, PinCallbackListener pincallbacklistener) throws OcException API to set particular OxmType (Ownership Transfer Method) and Pin Callback Listener Interface. Interface will be Implemented by the App developer. public static native void setdisplaypinlistener(displaypinlistener displaypinlistener) throws OcException; 21

22 Server specific API for registering Listener for generated PIN on the server side for displaying on the server screen. public static List<OcSecureResource> getdevicestatuslist(int timeout) throws OcException API to get List of all devices, Owned/registered OR un-owned/un-registered, in the current subnet. Class : OcSecureResource : This class represents a secure virtual resource and its state. public native void doownershiptransfer(doownershiptransferlistener doownershiptransferlistener) throws OcException; API to start Ownership transfer of un-owned/un-registered OcSecureResource Object, which was obtained by calling discoverunowneddevices. doownershiptransferlistener will be Notified un-synchronously with result after ownership transfer. public void provisionpairwisedevices(enumset<credtype> credtypeset, KeySize keysize, Object acl1,object device2, Object acl2, ProvisionPairwiseDevicesListener provisionpairwisedeviceslistener) throws OcException API to provision credentials and ACLs between two devices who act as a server. provisionpairwisedeviceslistener will be notified un-synchronously with results of credential and ACL provisioning between two devices. public void provisioncredentials(enumset<credtype> credtypeset, KeySize keysize, Object device2, ProvisionCredentialsListener provisioncredentialslistener) throws OcException API to provision credentials to the device. provisioncredentialslistener will be notified un-synchronously with result of credential provisioning. public native void provisionacl(object acl, ProvisionAclListener provisionacllistener) throws OcException API to send ACL to the device. provisionacllistener will be notified unsynchronously with result of ACL provisioning. public native void unlinkdevices(object device2, UnlinkDevicesListener unlinkdeviceslistener) throws OcException API to remove credentials and relationship between two devices. unlinkdeviceslistener will be notified un-synchronously with result. public native void removedevice(int timeout, RemoveDeviceListener removedevicelistener) throws OcException; API to unlink the devices to each device it is linked with. removedevicelistener will be notified un-synchronously with result. public native List<String> getlinkeddevices(); API to get List of all devices it is linked with. 22

23 public native String getipaddr(); API to get Stringified IP address. public native String getdeviceid(); API to get device ID of the device. public DeviceStatus getdevicestatus() throws OcException API to get status of the device. ON or OFF or INVALID public OwnedStatus getownedstatus() throws OcException API to get Owned/Unowned status of the device. OWNED or UNOWNED or INVALID 23