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     typedef std::function<void(uint16_t credId, uint8_t *trustCertChain,
  40             size_t chainSize)>CertChainCallBack;
  41
  42     struct ProvisionContext
  43     {
  44         ResultCallBack callback;
  45         ProvisionContext(ResultCallBack cb) : callback(cb){}
  46     };
  47
  48     struct TrustCertChainContext
  49     {
  50         CertChainCallBack callback;
  51         TrustCertChainContext(CertChainCallBack cb) : callback(cb){}
  52     };
  53     /**
  54      * This class is for credential's to be set to devices.
  55      * The types supported are
  56      *              0:  no security mode
  57      *              1:  symmetric pair-wise key
  58      *              2:  symmetric group key
  59      *              4:  asymmetric key
  60      *              8:  signed asymmetric key (aka certificate)
  61      *              16: PIN /password
  62      */
  63     class Credential
  64     {
  65             OicSecCredType_t type;
  66             size_t keySize;
  67         public:
  68             Credential() = default;
  69             Credential(OicSecCredType_t type, size_t size) : type(type), keySize(size)
  70             {}
  71
  72             /**
  73              * API to get credential type of device.
  74              * @return credential type of device.
  75              */
  76             OicSecCredType_t getCredentialType() const
  77             {
  78                 return type;
  79             }
  80
  81             /**
  82              * API to get size of credential key type.
  83              * @return size of credential key type.
  84              */
  85             size_t getCredentialKeySize() const
  86             {
  87                 return keySize;
  88             }
  89
  90             /**
  91              * API to set credential type of device.
  92              * Device can have following credential types
  93              *  - symmetric pair-wise key
  94              *  - symmetric group key
  95              *  - asymmetric key
  96              *  - signed asymmetric key (aka certificate)
  97              *  - PIN /password
  98              * @param type credential type.
  99              */
 100             void setCredentialType(OicSecCredType_t type)
 101             {
 102                 this->type = type;
 103             }
 104
 105             /**
 106              * API to set size of credential key type.
 107              * @param keySize credential key size.
 108              * @note can be either 128 or 256 for symmetric pair-wise key
 109              */
 110             void setCredentialKeySize(size_t keySize)
 111             {
 112                 this->keySize = keySize;
 113             }
 114     };
 115
 116     class OCSecure
 117     {
 118         public:
 119             /**
 120              * The API is responsible for initialization of the provisioning manager. It will load
 121              * provisioning database which have owned device's list and their linked status.
 122              *
 123              * @param dbPath file path of the sqlite3 database.
 124              *
 125              * @return ::OC_STACK_OK in case of success and other value otherwise.
 126              */
 127             static OCStackResult provisionInit(const std::string& dbPath);
 128
 129             /**
 130              * API is responsible for discovery of devices in it's subnet. It will list
 131              * all the device in subnet which are not yet owned.
 132              *
 133              * @param timeout Timeout in seconds, time until which function will listen to
 134              *                    responses from server before returning the list of devices.
 135              * @param list List of candidate devices to be provisioned.
 136              * @return ::OC_STACK_OK in case of success and other value otherwise.
 137              */
 138             static OCStackResult discoverUnownedDevices(unsigned short timeout,
 139                     DeviceList_t &list);
 140
 141             /**
 142              * API is responsible for discovery of devices in it's subnet. It will list
 143              * all the device in subnet which are already owned by calling provisioning client.
 144              *
 145              * @param timeout Timeout in seconds, time until which function will listen to
 146              *                    responses from server before returning the list of devices.
 147              * @param list List of owned devices.
 148              * @return ::OC_STACK_OK in case of success and other value otherwise.
 149              */
 150             static OCStackResult discoverOwnedDevices(unsigned short timeout,
 151                     DeviceList_t &list);
 152
 153             /**
 154              * API is responsible for discovery of devices in specified endpoint/deviceID.
 155              * And this function will only return the specified device's response.
 156              *
 157              * @param timeout Timeout in seconds, time until which function will listen to
 158              *                    responses from server before returning the specified device.
 159              * @param deviceID  deviceID of target device
 160              * @param foundDevice OCSecureResource object of found device.
 161              * @return ::OC_STACK_OK in case of success and other value otherwise.\n
 162              *         ::OC_STACK_INVALID_PARAM when deviceID is NULL or ppFoundDevice is not
 163              *                                  initailized.
 164              */
 165             static OCStackResult discoverSingleDevice(unsigned short timeout,
 166                     const OicUuid_t* deviceID,
 167                     std::shared_ptr<OCSecureResource> &foundDevice);
 168
 169             /**
 170              * API for registering Ownership transfer methods for a particular transfer Type.
 171              *
 172              * @param oxm Ownership transfer method.
 173              * @param callbackData CallbackData Methods for ownership transfer.
 174              * @param inputPin Callback method to input pin for verification.
 175              * @return ::OC_STACK_OK in case of success and other value otherwise.
 176              */
 177             static OCStackResult setOwnerTransferCallbackData(OicSecOxm_t oxm,
 178                     OTMCallbackData_t* callbackData, InputPinCallback inputPin);
 179
 180             /**
 181              * API to get status of all the devices in current subnet. The status include endpoint
 182              * information and doxm information which can be extracted during owned and unowned
 183              * discovery. Along with this information, API will provide information about
 184              * devices' status.
 185              * Device can have following states
 186              *  - ON/OFF: Device is switched on or off.
 187              *
 188              * @param timeout Wait time for the API.
 189              * @param ownedDevList  List of owned devices.
 190              * @param unownedDevList  List of unowned devices.
 191              * @return ::OC_STACK_OK in case of success and other value otherwise.
 192              */
 193             static OCStackResult getDevInfoFromNetwork(unsigned short timeout,
 194                     DeviceList_t &ownedDevList,
 195                     DeviceList_t &unownedDevList);
 196             /**
 197              * Server API to register callback to display stack generated PIN.
 198              *
 199              * @param displayPin Callback Method to Display generated PIN.
 200              * @return ::OC_STACK_OK in case of success and other value otherwise.
 201              */
 202             static OCStackResult setDisplayPinCB(GeneratePinCallback displayPin);
 203
 204             /**
 205              * API to remove device credential and ACL from all devices in subnet.
 206              *
 207              * @param resultCallback Callback provided by API user, callback will be called when
 208              *            credential revocation is finished.
 209              * @param uuid Device uuid to be revoked.
 210              * @param waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device
 211              *            discovery in seconds.
 212              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 213              */
 214             static OCStackResult removeDeviceWithUuid(unsigned short waitTimeForOwnedDeviceDiscovery,
 215                     std::string uuid,
 216                     ResultCallBack resultCallback);
 217
 218             /**
 219              * API to save ACL which has several ACE into Acl of SVR.
 220              *
 221              * @param acl ACL to be saved in Acl of SVR.
 222              * @return  OC_STACK_OK in case of success and other value otherwise.
 223              */
 224             static OCStackResult saveACL(const OicSecAcl_t* acl);
 225
 226 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
 227             /**
 228              * API to save Trust certificate chain into Cred of SVR.
 229              *
 230              * @param[in] trustCertChain Trust certificate chain to be saved in Cred of SVR.
 231              * @param[in] chainSize Size of trust certificate chain to be saved in Cred of SVR
 232              * @param[in] encodingType Encoding type of trust certificate chain to be saved in Cred of SVR
 233              * @param[out] credId CredId of saved trust certificate chain in Cred of SVR.
 234              * @return  OC_STACK_OK in case of success and other value otherwise.
 235              */
 236             static OCStackResult saveTrustCertChain(uint8_t *trustCertChain, size_t chainSize,
 237                                         OicEncodingType_t encodingType, uint16_t *credId);
 238
 239
 240             /**
 241              * API to read Trust certificate chain from SVR.
 242              * Caller must free when done using the returned trust certificate
 243              * @param[in] credId CredId of trust certificate chain in SVR.
 244              * @param[out] trustCertChain Trust certificate chain.
 245              * @param[out] chainSize Size of trust certificate chain
 246              * @return  OC_STACK_OK in case of success and other value otherwise.
 247              */
 248             static OCStackResult readTrustCertChain(uint16_t credId, uint8_t **trustCertChain,
 249                                      size_t *chainSize);
 250
 251             /**
 252              * API to register Notifier for trustCertChain change.
 253              *
 254              * @param[in] TrustCertChainChangeCB trustCertChain Change will be
 255              * notified asynchronously. User need to "delete[]" trustCertChain
 256              * in the callback function.
 257              * @return  OC_STACK_OK in case of success and other value otherwise.
 258              */
 259             static OCStackResult registerTrustCertChangeNotifier(CertChainCallBack);
 260
 261             /**
 262              * API to remove Already registered Notifier.
 263              *
 264              *@return  OC_STACK_OK always, kept it for symmetry.
 265              */
 266             static OCStackResult removeTrustCertChangeNotifier();
 267
 268             /**
 269              * Notifier wrapper for trustCertChain change.
 270              *
 271              * @param[in] ctx  User context returned in callback
 272              * @param[in] credId  trustCertChain changed for this ID
 273              * @param[in] trustCertChain trustcertchain binary blob
 274              * @param[in] chainSize size of trustCertChain
 275              */
 276             static void certCallbackWrapper(void* ctx, uint16_t credId, uint8_t *trustCertChain,
 277                                 size_t chainSize);
 278 #endif // __WITH_DTLS__ || __WITH_TLS__
 279
 280     };
 281
 282     /**
 283      * This class represents a secure virtual device, which can be provisioned by the
 284      * provisioning client.
 285      */
 286     class OCSecureResource
 287     {
 288         private:
 289             std::weak_ptr<std::recursive_mutex> m_csdkLock;
 290             OCProvisionDev_t *devPtr;   // pointer to device.
 291
 292         public:
 293             OCSecureResource();
 294             OCSecureResource(std::weak_ptr<std::recursive_mutex> csdkLock, OCProvisionDev_t *dPtr);
 295
 296             ~OCSecureResource();
 297
 298             /**
 299              * API to provision credentials between two devices and ACLs for the devices who
 300              * act as a server.
 301              *
 302              * @param cred  Type of credentials & key size to be provisioned to the device.
 303              * @param acl1  ACL for device 1. If this is not required set NULL.
 304              * @param device2  Second device to be provisioned.
 305              * @param acl2  ACL for device 2. If this is not required set NULL.
 306              * @param resultCallback Callback will be called when provisioning request receives
 307              *                           a response from first resource server.
 308              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 309              */
 310             OCStackResult provisionPairwiseDevices(const Credential &cred, const OicSecAcl_t* acl1,
 311                     const OCSecureResource &device2, const OicSecAcl_t* acl2,
 312                     ResultCallBack resultCallback);
 313
 314             /**
 315              * API to do ownership transfer for un-owned device.
 316              *
 317              * @param resultCallback Result callback function to be invoked when
 318              *                           ownership transfer finished.
 319              * @return ::OC_STACK_OK in case of success and other value otherwise.
 320              */
 321             OCStackResult doOwnershipTransfer(ResultCallBack resultCallback);
 322
 323             /**
 324              * API to send ACL information to resource.
 325              *
 326              * @param acl ACL to provision.
 327              * @param resultCallback Callback will be called when provisioning request
 328              *                           receives a response from resource server.
 329              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 330              */
 331             OCStackResult provisionACL(const OicSecAcl_t* acl,
 332                     ResultCallBack resultCallback);
 333
 334             /**
 335              * API to provision credential to devices.
 336              *
 337              * @param cred Type of credentials to be provisioned to the device.
 338              * @param device2 Second device' instance, representing resource to be provisioned.
 339              * @param resultCallback Callback will be called when provisioning request receives
 340              *                           a response from first resource server.
 341              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 342              */
 343             OCStackResult provisionCredentials(const Credential &cred,
 344                     const OCSecureResource &device2,
 345                     ResultCallBack resultCallback);
 346
 347            /**
 348             * API to remove the credential & relationship between the two devices.
 349             *
 350             * @param device2 Second device information to be unlinked.
 351             * @param resultCallback Callback provided by API user, callback will be called when
 352             *            device unlink is finished.
 353             * @return  ::OC_STACK_OK in case of success and other value otherwise.
 354             */
 355             OCStackResult unlinkDevices(const OCSecureResource &device2,
 356                     ResultCallBack resultCallback);
 357
 358             /**
 359              * API to remove device credential from all devices in subnet.
 360              *
 361              * @param resultCallback Callback provided by API user, callback will be called when
 362              *            credential revocation is finished.
 363              * @param waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device
 364              *            discovery in seconds.
 365              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 366              */
 367             OCStackResult removeDevice(unsigned short waitTimeForOwnedDeviceDiscovery,
 368                     ResultCallBack resultCallback);
 369
 370             /**
 371              * API to provision DirectPairing to devices.
 372              *
 373              * @param pconf pointer to PCONF (Pairing Configuration).
 374              * @param resultCallback Callback will be called when provisioning request receives
 375              *                           a response from first resource server.
 376              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 377              */
 378             OCStackResult provisionDirectPairing(const OicSecPconf_t *pconf,
 379                     ResultCallBack resultCallback);
 380
 381 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
 382             /**
 383              * API to provision cert.
 384              *
 385              * @param type type of cred.
 386              * @param credId id of cert.
 387              * @param resultCallback Callback will be called when provisioning request
 388              *                           receives a response from resource server.
 389              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 390              */
 391             OCStackResult provisionTrustCertChain(OicSecCredType_t type, uint16_t credId,
 392                     ResultCallBack resultCallback);
 393
 394 #endif // __WITH_DTLS__ or __WITH_TLS__
 395
 396             /**
 397              * This method is used to get linked devices' IDs.
 398              *
 399              * @param uuidList Information about the list of linked devices uuids.
 400              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 401              */
 402             OCStackResult getLinkedDevices(UuidList_t &uuidList);
 403
 404             /**
 405              * API to get the device ID of this resource.
 406              * @return device ID.
 407              */
 408             std::string getDeviceID();
 409
 410             /**
 411              * API to get the information of device for provisioning.
 412              * @return  @ref OCProvisionDev_t Reference provides information of device for provisioning.
 413              */
 414             OCProvisionDev_t* getDevPtr()const;
 415
 416             /**
 417              * This function returns the device's IP address.
 418              * @return device address.
 419              */
 420             std::string getDevAddr();
 421
 422             /**
 423              * This function returns the device's Status.
 424              * @return Device status (1 = ON and 2 = OFF).
 425              */
 426             int getDeviceStatus();
 427
 428             /**
 429              * This function provides the owned status of the device.
 430              * @return Device owned status.
 431              */
 432             bool getOwnedStatus();
 433
 434
 435             /**
 436              * Common callback wrapper, which will be called from OC-APIs.
 437              */
 438             static void callbackWrapper(void* ctx, int nOfRes,
 439                     OCProvisionResult_t *arr, bool hasError);
 440
 441         private:
 442             void validateSecureResource();
 443     };
 444
 445 }
 446 #endif // OC_PROVISIONINGMANAGER_CXX_H_