resource/include/OCProvisioningManager.hpp

   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             * API to read Trust certificate chain from SVR.
 241             * Caller must free when done using the returned trust certificate
 242             * @param[in] credId CredId of trust certificate chain in SVR.
 243             * @param[out] trustCertChain Trust certificate chain.
 244             * @param[out] chainSize Size of trust certificate chain
 245             * @return  OC_STACK_OK in case of success and other value otherwise.
 246             */
 247             static OCStackResult readTrustCertChain(uint16_t credId, uint8_t **trustCertChain,
 248                                      size_t *chainSize);
 249
 250             /**
 251              * API to register Notifier for trustCertChain change.
 252              *
 253              * @param[in] TrustCertChainChangeCB trustCertChain Change will be
 254              * notified asynchronously. User need to "delete[]" trustCertChain
 255              * in the callback function.
 256              * @return  OC_STACK_OK in case of success and other value otherwise.
 257              */
 258             static OCStackResult registerTrustCertChangeNotifier(CertChainCallBack);
 259
 260             /**
 261              * API to remove Already registered Notifier.
 262              *
 263              *@return  OC_STACK_OK always, kept it for symmetry.
 264              */
 265             static OCStackResult removeTrustCertChangeNotifier();
 266
 267             /**
 268              * Notifier wrapper for trustCertChain change.
 269              *
 270              * @param[in] ctx  User context returned in callback
 271              * @param[in] credId  trustCertChain changed for this ID
 272              * @param[in] trustCertChain trustcertchain binary blob
 273              * @param[in] chainSize size of trustCertChain
 274              */
 275             static void certCallbackWrapper(void* ctx, uint16_t credId, uint8_t *trustCertChain,
 276                                 size_t chainSize);
 277 #endif // __WITH_DTLS__ || __WITH_TLS__
 278
 279     };
 280
 281     /**
 282      * This class represents a secure virtual device, which can be provisioned by the
 283      * provisioning client.
 284      */
 285     class OCSecureResource
 286     {
 287         private:
 288             std::weak_ptr<std::recursive_mutex> m_csdkLock;
 289             OCProvisionDev_t *devPtr;   // pointer to device.
 290
 291         public:
 292             OCSecureResource();
 293             OCSecureResource(std::weak_ptr<std::recursive_mutex> csdkLock, OCProvisionDev_t *dPtr);
 294
 295             ~OCSecureResource();
 296
 297             /**
 298              * API to provision credentials between two devices and ACLs for the devices who
 299              * act as a server.
 300              *
 301              * @param cred  Type of credentials & key size to be provisioned to the device.
 302              * @param acl1  ACL for device 1. If this is not required set NULL.
 303              * @param device2  Second device to be provisioned.
 304              * @param acl2  ACL for device 2. If this is not required set NULL.
 305              * @param resultCallback Callback will be called when provisioning request receives
 306              *                           a response from first resource server.
 307              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 308              */
 309             OCStackResult provisionPairwiseDevices(const Credential &cred, const OicSecAcl_t* acl1,
 310                     const OCSecureResource &device2, const OicSecAcl_t* acl2,
 311                     ResultCallBack resultCallback);
 312
 313             /**
 314              * API to do ownership transfer for un-owned device.
 315              *
 316              * @param resultCallback Result callback function to be invoked when
 317              *                           ownership transfer finished.
 318              * @return ::OC_STACK_OK in case of success and other value otherwise.
 319              */
 320             OCStackResult doOwnershipTransfer(ResultCallBack resultCallback);
 321
 322             /**
 323              * API to send ACL information to resource.
 324              *
 325              * @param acl ACL to provision.
 326              * @param resultCallback Callback will be called when provisioning request
 327              *                           receives a response from resource server.
 328              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 329              */
 330             OCStackResult provisionACL(const OicSecAcl_t* acl,
 331                     ResultCallBack resultCallback);
 332
 333             /**
 334              * API to provision credential to devices.
 335              *
 336              * @param cred Type of credentials to be provisioned to the device.
 337              * @param device2 Second device' instance, representing resource to be provisioned.
 338              * @param resultCallback Callback will be called when provisioning request receives
 339              *                           a response from first resource server.
 340              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 341              */
 342             OCStackResult provisionCredentials(const Credential &cred,
 343                     const OCSecureResource &device2,
 344                     ResultCallBack resultCallback);
 345
 346            /**
 347             * API to remove the credential & relationship between the two devices.
 348             *
 349             * @param device2 Second device information to be unlinked.
 350             * @param resultCallback Callback provided by API user, callback will be called when
 351             *            device unlink is finished.
 352             * @return  ::OC_STACK_OK in case of success and other value otherwise.
 353             */
 354             OCStackResult unlinkDevices(const OCSecureResource &device2,
 355                     ResultCallBack resultCallback);
 356
 357             /**
 358              * API to remove device credential from all devices in subnet.
 359              *
 360              * @param resultCallback Callback provided by API user, callback will be called when
 361              *            credential revocation is finished.
 362              * @param waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device
 363              *            discovery in seconds.
 364              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 365              */
 366             OCStackResult removeDevice(unsigned short waitTimeForOwnedDeviceDiscovery,
 367                     ResultCallBack resultCallback);
 368
 369             /**
 370              * API to provision DirectPairing to devices.
 371              *
 372              * @param pconf pointer to PCONF (Pairing Configuration).
 373              * @param resultCallback Callback will be called when provisioning request receives
 374              *                           a response from first resource server.
 375              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 376              */
 377             OCStackResult provisionDirectPairing(const OicSecPconf_t *pconf,
 378                     ResultCallBack resultCallback);
 379
 380 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
 381             /**
 382              * API to provision cert.
 383              *
 384              * @param type type of cred.
 385              * @param credId id of cert.
 386              * @param resultCallback Callback will be called when provisioning request
 387              *                           receives a response from resource server.
 388              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 389              */
 390             OCStackResult provisionTrustCertChain(OicSecCredType_t type, uint16_t credId,
 391                     ResultCallBack resultCallback);
 392
 393 #endif // __WITH_DTLS__ or __WITH_TLS__
 394
 395             /**
 396              * This method is used to get linked devices' IDs.
 397              *
 398              * @param uuidList Information about the list of linked devices uuids.
 399              * @return  ::OC_STACK_OK in case of success and other value otherwise.
 400              */
 401             OCStackResult getLinkedDevices(UuidList_t &uuidList);
 402
 403             /**
 404              * API to get the device ID of this resource.
 405              * @return device ID.
 406              */
 407             std::string getDeviceID();
 408
 409             /**
 410              * API to get the information of device for provisioning.
 411              * @return  @ref OCProvisionDev_t Reference provides information of device for provisioning.
 412              */
 413             OCProvisionDev_t* getDevPtr()const;
 414
 415             /**
 416              * This function returns the device's IP address.
 417              * @return device address.
 418              */
 419             std::string getDevAddr();
 420
 421             /**
 422              * This function returns the device's Status.
 423              * @return Device status (1 = ON and 2 = OFF).
 424              */
 425             int getDeviceStatus();
 426
 427             /**
 428              * This function provides the owned status of the device.
 429              * @return Device owned status.
 430              */
 431             bool getOwnedStatus();
 432
 433
 434             /**
 435              * Common callback wrapper, which will be called from OC-APIs.
 436              */
 437             static void callbackWrapper(void* ctx, int nOfRes,
 438                     OCProvisionResult_t *arr, bool hasError);
 439
 440         private:
 441             void validateSecureResource();
 442     };
 443
 444 }
 445 #endif // OC_PROVISIONINGMANAGER_CXX_H_