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     /**
 183      * This class represents a secure virtual device, which can be provisioned by the
 184      * provisioning client.
 185      */
 186     class OCSecureResource
 187     {
 188         private:
 189             std::weak_ptr<std::recursive_mutex> m_csdkLock;
 190             OCProvisionDev_t *devPtr;   // pointer to device.
 191
 192         public:
 193             OCSecureResource();
 194             OCSecureResource(std::weak_ptr<std::recursive_mutex> csdkLock, OCProvisionDev_t *dPtr);
 195
 196             ~OCSecureResource();
 197
 198             /**
 199              * API to provision credentials between two devices and ACLs for the devices who
 200              * act as a server.
 201              *
 202              * @param cred  Type of credentials & key size to be provisioned to the device.
 203              * @param acl1  ACL for device 1. If this is not required set NULL.
 204              * @param device2  Second device to be provisioned.
 205              * @param acl2  ACL for device 2. If this is not required set NULL.
 206              * @param resultCallback Callback will be called when provisioning request receives
 207              *                           a response from first resource server.
 208              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 209              */
 210             OCStackResult provisionPairwiseDevices(const Credential &cred, const OicSecAcl_t* acl1,
 211                     const OCSecureResource &device2, const OicSecAcl_t* acl2,
 212                     ResultCallBack resultCallback);
 213
 214             /**
 215              * API to do ownership transfer for un-owned device.
 216              *
 217              * @param resultCallback Result callback function to be invoked when
 218              *                           ownership transfer finished.
 219              * @return ::OC_STACK_OK in case of success and other value otherwise.
 220              */
 221             OCStackResult doOwnershipTransfer(ResultCallBack resultCallback);
 222
 223             /**
 224              * API to send ACL information to resource.
 225              *
 226              * @param acl ACL to provision.
 227              * @param resultCallback Callback will be called when provisioning request
 228              *                           receives a response from resource server.
 229              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 230              */
 231             OCStackResult provisionACL(const OicSecAcl_t* acl,
 232                     ResultCallBack resultCallback);
 233
 234             /**
 235              * API to provision credential to devices.
 236              *
 237              * @param cred Type of credentials to be provisioned to the device.
 238              * @param device2 Second device' instance, representing resource to be provisioned.
 239              * @param resultCallback Callback will be called when provisioning request receives
 240              *                           a response from first resource server.
 241              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 242              */
 243             OCStackResult provisionCredentials(const Credential &cred,
 244                     const OCSecureResource &device2,
 245                     ResultCallBack resultCallback);
 246
 247            /**
 248             * API to remove the credential & relationship between the two devices.
 249             *
 250             * @param device2 Second device information to be unlinked.
 251             * @param resultCallback Callback provided by API user, callback will be called when
 252             *            device unlink is finished.
 253             * @return  ::OC_STACK_OK in case of success and other value otherwise.
 254             */
 255             OCStackResult unlinkDevices(const OCSecureResource &device2,
 256                     ResultCallBack resultCallback);
 257
 258             /**
 259              * API to remove device credential from all devices in subnet.
 260              *
 261              * @param resultCallback Callback provided by API user, callback will be called when
 262              *            credential revocation is finished.
 263              * @param waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device
 264              *            discovery in seconds.
 265              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 266              */
 267             OCStackResult removeDevice(unsigned short waitTimeForOwnedDeviceDiscovery,
 268                     ResultCallBack resultCallback);
 269
 270             /**
 271              * This method is used to get linked devices' IDs.
 272              *
 273              * @param uuidList Information about the list of linked devices uuids.
 274              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 275              */
 276             OCStackResult getLinkedDevices(UuidList_t &uuidList);
 277
 278             /**
 279              * API to get the device ID of this resource.
 280              * @return device ID.
 281              */
 282             std::string getDeviceID();
 283
 284             /**
 285              * API to get the information of device for provisioning.
 286              * @return  @ref OCProvisionDev_t Reference provides information of device for provisioning.
 287              */
 288             OCProvisionDev_t* getDevPtr()const;
 289
 290             /**
 291              * This function returns the device's IP address.
 292              * @return device address.
 293              */
 294             std::string getDevAddr();
 295
 296             /**
 297              * This function returns the device's Status.
 298              * @return Device status (1 = ON and 2 = OFF).
 299              */
 300             int getDeviceStatus();
 301
 302             /**
 303              * This function provides the owned status of the device.
 304              * @return Device owned status.
 305              */
 306             bool getOwnedStatus();
 307
 308         private:
 309             /**
 310              * Common callback wrapper, which will be called from OC-APIs.
 311              */
 312             static void callbackWrapper(void* ctx, int nOfRes,
 313                     OCProvisionResult_t *arr, bool hasError);
 314
 315             void validateSecureResource();
 316     };
 317
 318 }
 319 #endif // OC_PROVISIONINGMANAGER_CXX_H_