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 is responsible for discovery of devices in specified endpoint/deviceID.
 148              * And this function will only return the specified device's response.
 149              *
 150              * @param timeout Timeout in seconds, time until which function will listen to
 151              *                    responses from server before returning the specified device.
 152              * @param deviceID  deviceID of target device
 153              * @param foundDevice OCSecureResource object of found device.
 154              * @return ::OC_STACK_OK in case of success and other value otherwise.\n
 155              *         ::OC_STACK_INVALID_PARAM when deviceID is NULL or ppFoundDevice is not
 156              *                                  initailized.
 157              */
 158             static OCStackResult discoverSingleDevice(unsigned short timeout,
 159                     const OicUuid_t* deviceID,
 160                     std::shared_ptr<OCSecureResource> &foundDevice);
 161
 162             /**
 163              * API for registering Ownership transfer methods for a particular transfer Type.
 164              *
 165              * @param oxm Ownership transfer method.
 166              * @param callbackData CallbackData Methods for ownership transfer.
 167              * @param inputPin Callback method to input pin for verification.
 168              * @return ::OC_STACK_OK in case of success and other value otherwise.
 169              */
 170             static OCStackResult setOwnerTransferCallbackData(OicSecOxm_t oxm,
 171                     OTMCallbackData_t* callbackData, InputPinCallback inputPin);
 172
 173             /**
 174              * API to get status of all the devices in current subnet. The status include endpoint
 175              * information and doxm information which can be extracted during owned and unowned
 176              * discovery. Along with this information, API will provide information about
 177              * devices' status.
 178              * Device can have following states
 179              *  - ON/OFF: Device is switched on or off.
 180              *
 181              * @param timeout Wait time for the API.
 182              * @param ownedDevList  List of owned devices.
 183              * @param unownedDevList  List of unowned devices.
 184              * @return ::OC_STACK_OK in case of success and other value otherwise.
 185              */
 186             static OCStackResult getDevInfoFromNetwork(unsigned short timeout,
 187                     DeviceList_t &ownedDevList,
 188                     DeviceList_t &unownedDevList);
 189             /**
 190              * Server API to register callback to display stack generated PIN.
 191              *
 192              * @param displayPin Callback Method to Display generated PIN.
 193              * @return ::OC_STACK_OK in case of success and other value otherwise.
 194              */
 195             static OCStackResult setDisplayPinCB(GeneratePinCallback displayPin);
 196
 197             /**
 198              * API to remove device credential and ACL from all devices in subnet.
 199              *
 200              * @param resultCallback Callback provided by API user, callback will be called when
 201              *            credential revocation is finished.
 202              * @param uuid Device uuid to be revoked.
 203              * @param waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device
 204              *            discovery in seconds.
 205              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 206              */
 207             static OCStackResult removeDeviceWithUuid(unsigned short waitTimeForOwnedDeviceDiscovery,
 208                     std::string uuid,
 209                     ResultCallBack resultCallback);
 210
 211             /**
 212              * API to save ACL which has several ACE into Acl of SVR.
 213              *
 214              * @param acl ACL to be saved in Acl of SVR.
 215              * @return  OC_STACK_OK in case of success and other value otherwise.
 216              */
 217             static OCStackResult saveACL(const OicSecAcl_t* acl);
 218
 219 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
 220             /**
 221              * API to save Trust certificate chain into Cred of SVR.
 222              *
 223              * @param[in] trustCertChain Trust certificate chain to be saved in Cred of SVR.
 224              * @param[in] chainSize Size of trust certificate chain to be saved in Cred of SVR
 225              * @param[in] encodingType Encoding type of trust certificate chain to be saved in Cred of SVR
 226              * @param[out] credId CredId of saved trust certificate chain in Cred of SVR.
 227              * @return  OC_STACK_OK in case of success and other value otherwise.
 228              */
 229             static OCStackResult saveTrustCertChain(uint8_t *trustCertChain, size_t chainSize,
 230                                         OicEncodingType_t encodingType, uint16_t *credId);
 231 #endif // __WITH_DTLS__ || __WITH_TLS__
 232
 233     };
 234
 235     /**
 236      * This class represents a secure virtual device, which can be provisioned by the
 237      * provisioning client.
 238      */
 239     class OCSecureResource
 240     {
 241         private:
 242             std::weak_ptr<std::recursive_mutex> m_csdkLock;
 243             OCProvisionDev_t *devPtr;   // pointer to device.
 244
 245         public:
 246             OCSecureResource();
 247             OCSecureResource(std::weak_ptr<std::recursive_mutex> csdkLock, OCProvisionDev_t *dPtr);
 248
 249             ~OCSecureResource();
 250
 251             /**
 252              * API to provision credentials between two devices and ACLs for the devices who
 253              * act as a server.
 254              *
 255              * @param cred  Type of credentials & key size to be provisioned to the device.
 256              * @param acl1  ACL for device 1. If this is not required set NULL.
 257              * @param device2  Second device to be provisioned.
 258              * @param acl2  ACL for device 2. If this is not required set NULL.
 259              * @param resultCallback Callback will be called when provisioning request receives
 260              *                           a response from first resource server.
 261              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 262              */
 263             OCStackResult provisionPairwiseDevices(const Credential &cred, const OicSecAcl_t* acl1,
 264                     const OCSecureResource &device2, const OicSecAcl_t* acl2,
 265                     ResultCallBack resultCallback);
 266
 267             /**
 268              * API to do ownership transfer for un-owned device.
 269              *
 270              * @param resultCallback Result callback function to be invoked when
 271              *                           ownership transfer finished.
 272              * @return ::OC_STACK_OK in case of success and other value otherwise.
 273              */
 274             OCStackResult doOwnershipTransfer(ResultCallBack resultCallback);
 275
 276             /**
 277              * API to send ACL information to resource.
 278              *
 279              * @param acl ACL to provision.
 280              * @param resultCallback Callback will be called when provisioning request
 281              *                           receives a response from resource server.
 282              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 283              */
 284             OCStackResult provisionACL(const OicSecAcl_t* acl,
 285                     ResultCallBack resultCallback);
 286
 287             /**
 288              * API to provision credential to devices.
 289              *
 290              * @param cred Type of credentials to be provisioned to the device.
 291              * @param device2 Second device' instance, representing resource to be provisioned.
 292              * @param resultCallback Callback will be called when provisioning request receives
 293              *                           a response from first resource server.
 294              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 295              */
 296             OCStackResult provisionCredentials(const Credential &cred,
 297                     const OCSecureResource &device2,
 298                     ResultCallBack resultCallback);
 299
 300            /**
 301             * API to remove the credential & relationship between the two devices.
 302             *
 303             * @param device2 Second device information to be unlinked.
 304             * @param resultCallback Callback provided by API user, callback will be called when
 305             *            device unlink is finished.
 306             * @return  ::OC_STACK_OK in case of success and other value otherwise.
 307             */
 308             OCStackResult unlinkDevices(const OCSecureResource &device2,
 309                     ResultCallBack resultCallback);
 310
 311             /**
 312              * API to remove device credential from all devices in subnet.
 313              *
 314              * @param resultCallback Callback provided by API user, callback will be called when
 315              *            credential revocation is finished.
 316              * @param waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device
 317              *            discovery in seconds.
 318              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 319              */
 320             OCStackResult removeDevice(unsigned short waitTimeForOwnedDeviceDiscovery,
 321                     ResultCallBack resultCallback);
 322
 323             /**
 324              * API to provision DirectPairing to devices.
 325              *
 326              * @param pconf pointer to PCONF (Pairing Configuration).
 327              * @param resultCallback Callback will be called when provisioning request receives
 328              *                           a response from first resource server.
 329              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 330              */
 331             OCStackResult provisionDirectPairing(const OicSecPconf_t *pconf,
 332                     ResultCallBack resultCallback);
 333
 334 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
 335             /**
 336              * API to provision cert.
 337              *
 338              * @param type type of cred.
 339              * @param credId id of cert.
 340              * @param resultCallback Callback will be called when provisioning request
 341              *                           receives a response from resource server.
 342              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 343              */
 344             OCStackResult provisionTrustCertChain(OicSecCredType_t type, uint16_t credId,
 345                     ResultCallBack resultCallback);
 346
 347 #endif // __WITH_DTLS__ or __WITH_TLS__
 348
 349             /**
 350              * This method is used to get linked devices' IDs.
 351              *
 352              * @param uuidList Information about the list of linked devices uuids.
 353              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 354              */
 355             OCStackResult getLinkedDevices(UuidList_t &uuidList);
 356
 357             /**
 358              * API to get the device ID of this resource.
 359              * @return device ID.
 360              */
 361             std::string getDeviceID();
 362
 363             /**
 364              * API to get the information of device for provisioning.
 365              * @return  @ref OCProvisionDev_t Reference provides information of device for provisioning.
 366              */
 367             OCProvisionDev_t* getDevPtr()const;
 368
 369             /**
 370              * This function returns the device's IP address.
 371              * @return device address.
 372              */
 373             std::string getDevAddr();
 374
 375             /**
 376              * This function returns the device's Status.
 377              * @return Device status (1 = ON and 2 = OFF).
 378              */
 379             int getDeviceStatus();
 380
 381             /**
 382              * This function provides the owned status of the device.
 383              * @return Device owned status.
 384              */
 385             bool getOwnedStatus();
 386
 387
 388             /**
 389              * Common callback wrapper, which will be called from OC-APIs.
 390              */
 391             static void callbackWrapper(void* ctx, int nOfRes,
 392                     OCProvisionResult_t *arr, bool hasError);
 393
 394         private:
 395             void validateSecureResource();
 396     };
 397
 398 }
 399 #endif // OC_PROVISIONINGMANAGER_CXX_H_