resource/include/OCProvisioningManager.h

   1 //****************************************************************
   2 //
   3 // Copyright 2015 Samsung Electronics All Rights Reserved.
   4 //
   5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   6 //
   7 // Licensed under the Apache License, Version 2.0 (the "License");
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //     http://www.apache.org/licenses/LICENSE-2.0
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an "AS IS" BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  20
  21 #ifndef OC_PROVISIONINGMANAGER_CXX_H_
  22 #define OC_PROVISIONINGMANAGER_CXX_H_
  23
  24 #include <thread>
  25
  26 #include "pinoxmcommon.h"
  27 #include "ocprovisioningmanager.h"
  28 #include "OCApi.h"
  29 #include "OCPlatform_impl.h"
  30
  31 namespace OC
  32 {
  33     class OCSecureResource;
  34
  35     typedef std::vector<std::shared_ptr<OCSecureResource>> DeviceList_t;
  36     typedef std::vector<OicUuid_t> UuidList_t;
  37     typedef std::vector<OCProvisionResult_t> PMResultList_t;
  38     typedef std::function<void(PMResultList_t *result, int hasError)> ResultCallBack;
  39
  40     struct ProvisionContext
  41     {
  42         ResultCallBack callback;
  43         ProvisionContext(ResultCallBack cb) : callback(cb){}
  44     };
  45
  46     /**
  47      * This class is for credential's to be set to devices.
  48      * The types supported are
  49      *              0:  no security mode
  50      *              1:  symmetric pair-wise key
  51      *              2:  symmetric group key
  52      *              4:  asymmetric key
  53      *              8:  signed asymmetric key (aka certificate)
  54      *              16: PIN /password
  55      */
  56     class Credential
  57     {
  58             OicSecCredType_t type;
  59             size_t keySize;
  60         public:
  61             Credential() = default;
  62             Credential(OicSecCredType_t type, size_t size) : type(type), keySize(size)
  63             {}
  64
  65             /**
  66              * API to get credential type of device.
  67              * @return credential type of device.
  68              */
  69             OicSecCredType_t getCredentialType() const
  70             {
  71                 return type;
  72             }
  73
  74             /**
  75              * API to get size of credential key type.
  76              * @return size of credential key type.
  77              */
  78             size_t getCredentialKeySize() const
  79             {
  80                 return keySize;
  81             }
  82
  83             /**
  84              * API to set credential type of device.
  85              * Device can have following credential types
  86              *  - symmetric pair-wise key
  87              *  - symmetric group key
  88              *  - asymmetric key
  89              *  - signed asymmetric key (aka certificate)
  90              *  - PIN /password
  91              * @param type credential type.
  92              */
  93             void setCredentialType(OicSecCredType_t type)
  94             {
  95                 this->type = type;
  96             }
  97
  98             /**
  99              * API to set size of credential key type.
 100              * @param keySize credential key size.
 101              * @note can be either 128 or 256 for symmetric pair-wise key
 102              */
 103             void setCredentialKeySize(size_t keySize)
 104             {
 105                 this->keySize = keySize;
 106             }
 107     };
 108
 109     class OCSecure
 110     {
 111         public:
 112             /**
 113              * The API is responsible for initialization of the provisioning manager. It will load
 114              * provisioning database which have owned device's list and their linked status.
 115              *
 116              * @param dbPath file path of the sqlite3 database.
 117              *
 118              * @return ::OC_STACK_OK in case of success and other value otherwise.
 119              */
 120             static OCStackResult provisionInit(const std::string& dbPath);
 121
 122             /**
 123              * API is responsible for discovery of devices in it's subnet. It will list
 124              * all the device in subnet which are not yet owned.
 125              *
 126              * @param timeout Timeout in seconds, time until which function will listen to
 127              *                    responses from server before returning the list of devices.
 128              * @param list List of candidate devices to be provisioned.
 129              * @return ::OC_STACK_OK in case of success and other value otherwise.
 130              */
 131             static OCStackResult discoverUnownedDevices(unsigned short timeout,
 132                     DeviceList_t &list);
 133
 134             /**
 135              * API is responsible for discovery of devices in it's subnet. It will list
 136              * all the device in subnet which are already owned by calling provisioning client.
 137              *
 138              * @param timeout Timeout in seconds, time until which function will listen to
 139              *                    responses from server before returning the list of devices.
 140              * @param list List of owned devices.
 141              * @return ::OC_STACK_OK in case of success and other value otherwise.
 142              */
 143             static OCStackResult discoverOwnedDevices(unsigned short timeout,
 144                     DeviceList_t &list);
 145
 146             /**
 147              * API for registering Ownership transfer methods for a particular transfer Type.
 148              *
 149              * @param oxm Ownership transfer method.
 150              * @param callbackData CallbackData Methods for ownership transfer.
 151              * @param inputPin Callback method to input pin for verification.
 152              * @return ::OC_STACK_OK in case of success and other value otherwise.
 153              */
 154             static OCStackResult setOwnerTransferCallbackData(OicSecOxm_t oxm,
 155                     OTMCallbackData_t* callbackData, InputPinCallback inputPin);
 156
 157             /**
 158              * API to get status of all the devices in current subnet. The status include endpoint
 159              * information and doxm information which can be extracted during owned and unowned
 160              * discovery. Along with this information, API will provide information about
 161              * devices' status.
 162              * Device can have following states
 163              *  - ON/OFF: Device is switched on or off.
 164              *
 165              * @param timeout Wait time for the API.
 166              * @param ownedDevList  List of owned devices.
 167              * @param unownedDevList  List of unowned devices.
 168              * @return ::OC_STACK_OK in case of success and other value otherwise.
 169              */
 170             static OCStackResult getDevInfoFromNetwork(unsigned short timeout,
 171                     DeviceList_t &ownedDevList,
 172                     DeviceList_t &unownedDevList);
 173             /**
 174              * Server API to register callback to display stack generated PIN.
 175              *
 176              * @param displayPin Callback Method to Display generated PIN.
 177              * @return ::OC_STACK_OK in case of success and other value otherwise.
 178              */
 179             static OCStackResult setDisplayPinCB(GeneratePinCallback displayPin);
 180
 181             /**
 182              * API to remove device credential and ACL from all devices in subnet.
 183              *
 184              * @param resultCallback Callback provided by API user, callback will be called when
 185              *            credential revocation is finished.
 186              * @param uuid Device uuid to be revoked.
 187              * @param waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device
 188              *            discovery in seconds.
 189              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 190              */
 191             static OCStackResult removeDeviceWithUuid(unsigned short waitTimeForOwnedDeviceDiscovery,
 192                     std::string uuid,
 193                     ResultCallBack resultCallback);
 194
 195     };
 196
 197     /**
 198      * This class represents a secure virtual device, which can be provisioned by the
 199      * provisioning client.
 200      */
 201     class OCSecureResource
 202     {
 203         private:
 204             std::weak_ptr<std::recursive_mutex> m_csdkLock;
 205             OCProvisionDev_t *devPtr;   // pointer to device.
 206
 207         public:
 208             OCSecureResource();
 209             OCSecureResource(std::weak_ptr<std::recursive_mutex> csdkLock, OCProvisionDev_t *dPtr);
 210
 211             ~OCSecureResource();
 212
 213             /**
 214              * API to provision credentials between two devices and ACLs for the devices who
 215              * act as a server.
 216              *
 217              * @param cred  Type of credentials & key size to be provisioned to the device.
 218              * @param acl1  ACL for device 1. If this is not required set NULL.
 219              * @param device2  Second device to be provisioned.
 220              * @param acl2  ACL for device 2. If this is not required set NULL.
 221              * @param resultCallback Callback will be called when provisioning request receives
 222              *                           a response from first resource server.
 223              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 224              */
 225             OCStackResult provisionPairwiseDevices(const Credential &cred, const OicSecAcl_t* acl1,
 226                     const OCSecureResource &device2, const OicSecAcl_t* acl2,
 227                     ResultCallBack resultCallback);
 228
 229             /**
 230              * API to do ownership transfer for un-owned device.
 231              *
 232              * @param resultCallback Result callback function to be invoked when
 233              *                           ownership transfer finished.
 234              * @return ::OC_STACK_OK in case of success and other value otherwise.
 235              */
 236             OCStackResult doOwnershipTransfer(ResultCallBack resultCallback);
 237
 238             /**
 239              * API to send ACL information to resource.
 240              *
 241              * @param acl ACL to provision.
 242              * @param resultCallback Callback will be called when provisioning request
 243              *                           receives a response from resource server.
 244              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 245              */
 246             OCStackResult provisionACL(const OicSecAcl_t* acl,
 247                     ResultCallBack resultCallback);
 248
 249             /**
 250              * API to provision credential to devices.
 251              *
 252              * @param cred Type of credentials to be provisioned to the device.
 253              * @param device2 Second device' instance, representing resource to be provisioned.
 254              * @param resultCallback Callback will be called when provisioning request receives
 255              *                           a response from first resource server.
 256              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 257              */
 258             OCStackResult provisionCredentials(const Credential &cred,
 259                     const OCSecureResource &device2,
 260                     ResultCallBack resultCallback);
 261
 262            /**
 263             * API to remove the credential & relationship between the two devices.
 264             *
 265             * @param device2 Second device information to be unlinked.
 266             * @param resultCallback Callback provided by API user, callback will be called when
 267             *            device unlink is finished.
 268             * @return  ::OC_STACK_OK in case of success and other value otherwise.
 269             */
 270             OCStackResult unlinkDevices(const OCSecureResource &device2,
 271                     ResultCallBack resultCallback);
 272
 273             /**
 274              * API to remove device credential from all devices in subnet.
 275              *
 276              * @param resultCallback Callback provided by API user, callback will be called when
 277              *            credential revocation is finished.
 278              * @param waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device
 279              *            discovery in seconds.
 280              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 281              */
 282             OCStackResult removeDevice(unsigned short waitTimeForOwnedDeviceDiscovery,
 283                     ResultCallBack resultCallback);
 284
 285             /**
 286              * API to provision DirectPairing to devices.
 287              *
 288              * @param pconf pointer to PCONF (Pairing Configuration).
 289              * @param resultCallback Callback will be called when provisioning request receives
 290              *                           a response from first resource server.
 291              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 292              */
 293             OCStackResult provisionDirectPairing(const OicSecPconf_t *pconf,
 294                     ResultCallBack resultCallback);
 295
 296             /**
 297              * This method is used to get linked devices' IDs.
 298              *
 299              * @param uuidList Information about the list of linked devices uuids.
 300              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 301              */
 302             OCStackResult getLinkedDevices(UuidList_t &uuidList);
 303
 304             /**
 305              * API to get the device ID of this resource.
 306              * @return device ID.
 307              */
 308             std::string getDeviceID();
 309
 310             /**
 311              * API to get the information of device for provisioning.
 312              * @return  @ref OCProvisionDev_t Reference provides information of device for provisioning.
 313              */
 314             OCProvisionDev_t* getDevPtr()const;
 315
 316             /**
 317              * This function returns the device's IP address.
 318              * @return device address.
 319              */
 320             std::string getDevAddr();
 321
 322             /**
 323              * This function returns the device's Status.
 324              * @return Device status (1 = ON and 2 = OFF).
 325              */
 326             int getDeviceStatus();
 327
 328             /**
 329              * This function provides the owned status of the device.
 330              * @return Device owned status.
 331              */
 332             bool getOwnedStatus();
 333
 334
 335             /**
 336              * Common callback wrapper, which will be called from OC-APIs.
 337              */
 338             static void callbackWrapper(void* ctx, int nOfRes,
 339                     OCProvisionResult_t *arr, bool hasError);
 340
 341         private:
 342             void validateSecureResource();
 343     };
 344
 345 }
 346 #endif // OC_PROVISIONINGMANAGER_CXX_H_