resource/csdk/security/provisioning/include/ocprovisioningmanager.h

   1 /* *****************************************************************\r
   2  *\r
   3  * Copyright 2015 Samsung Electronics All Rights Reserved.\r
   4  *\r
   5  *\r
   6  *\r
   7  * Licensed under the Apache License, Version 2.0 (the "License");\r
   8  * you may not use this file except in compliance with the License.\r
   9  * You may obtain a copy of the License at\r
  10  *\r
  11  *     http://www.apache.org/licenses/LICENSE-2.0\r
  12  *\r
  13  * Unless required by applicable law or agreed to in writing, software\r
  14  * distributed under the License is distributed on an "AS IS" BASIS,\r
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  16  * See the License for the specific language governing permissions and\r
  17  * limitations under the License.\r
  18  *\r
  19  * *****************************************************************/\r
  20 \r
  21 #ifndef OCPROVISIONINGMANAGER_H_\r
  22 #define OCPROVISIONINGMANAGER_H_\r
  23 \r
  24 #include "octypes.h"\r
  25 #include "pmtypes.h"\r
  26 #include "ownershiptransfermanager.h"\r
  27 \r
  28 #ifdef __cplusplus\r
  29 extern "C" {\r
  30 #endif // __cplusplus\r
  31 \r
  32 /**\r
  33  * The function is responsible for initializaton of the provisioning manager. It will load\r
  34  * provisioning database which have owned device's list and their linked status.\r
  35  * TODO: In addition, if there is a device(s) which has not up-to-date credentials, this function will\r
  36  * automatically try to update the deivce(s).\r
  37  *\r
  38  * @param[in] dbPath file path of the sqlite3 db\r
  39  *\r
  40  * @return OC_STACK_OK in case of success and other value otherwise.\r
  41  */\r
  42 OCStackResult OCInitPM(const char* dbPath);\r
  43 \r
  44 /**\r
  45  * The function is responsible for discovery of owned/unowned device is specified endpoint.\r
  46  * It will return when found one or more device even though timeout is not exceeded\r
  47  *\r
  48  * @param[in] timeout Timeout in seconds, value till which function will listen to responses from\r
  49  *                    server before returning the list of devices.\r
  50  * @param[in] host               address of target endpoint\r
  51  * @param[in] connType           connectivity type of endpoint\r
  52  * @param[out] ppList            List of device.\r
  53  * @return OTM_SUCCESS in case of success and other value otherwise.\r
  54  */\r
  55 OCStackResult OCDiscoverSecureResource(unsigned short timeout, const char* host,\r
  56                              OCConnectivityType connType, OCProvisionDev_t **ppList);\r
  57 \r
  58 /**\r
  59  * The function is responsible for discovery of device is current subnet. It will list\r
  60  * all the device in subnet which are not yet owned. Please call OCInit with OC_CLIENT_SERVER as\r
  61  * OCMode.\r
  62  *\r
  63  * @param[in] timeout Timeout in seconds, value till which function will listen to responses from\r
  64  *                    server before returning the list of devices.\r
  65  * @param[out] ppList List of candidate devices to be provisioned\r
  66  * @return OTM_SUCCESS in case of success and other value otherwise.\r
  67  */\r
  68 OCStackResult OCDiscoverUnownedDevices(unsigned short waittime, OCProvisionDev_t **ppList);\r
  69 \r
  70 /**\r
  71  * Do ownership transfer for un-owned device.\r
  72  *\r
  73  * @param[in] ctx Application context would be returned in result callback\r
  74  * @param[in] targetDevices List of devices to perform ownership transfer.\r
  75  * @param[in] resultCallback Result callback function to be invoked when ownership transfer finished.\r
  76  * @return OC_STACK_OK in case of success and other value otherwise.\r
  77  */\r
  78 OCStackResult OCDoOwnershipTransfer(void* ctx,\r
  79                                     OCProvisionDev_t *targetDevices,\r
  80                                     OCProvisionResultCB resultCallback);\r
  81 \r
  82 /**\r
  83  * API to register for particular OxM.\r
  84  *\r
  85  * @param[in] Ownership transfer method.\r
  86  * @param[in] Implementation of callback functions for owership transfer.\r
  87  * @return OC_STACK_OK in case of success and other value otherwise.\r
  88  */\r
  89 OCStackResult OCSetOwnerTransferCallbackData(OicSecOxm_t oxm, OTMCallbackData_t* callbackData);\r
  90 \r
  91 /**\r
  92  * The function is responsible for discovery of owned device is current subnet. It will list\r
  93  * all the device in subnet which are owned by calling provisioning client.\r
  94  *\r
  95  * @param[in] timeout Timeout in seconds, value till which function will listen to responses from\r
  96  *                    server before returning the list of devices.\r
  97  * @param[out] ppList List of device owned by provisioning tool.\r
  98  * @return OTM_SUCCESS in case of success and other value otherwise.\r
  99  */\r
 100 OCStackResult OCDiscoverOwnedDevices(unsigned short timeout, OCProvisionDev_t **ppList);\r
 101 \r
 102 /**\r
 103  * API to provision credentials between two devices and ACLs for the devices who act as a server.\r
 104  *\r
 105  * @param[in] ctx Application context would be returned in result callback.\r
 106  * @param[in] type Type of credentials to be provisioned to the device.\r
 107  * @param[in] pDev1 Pointer to OCProvisionDev_t instance,respresenting device to be provisioned.\r
 108  * @param[in] acl ACL for device 1. If this is not required set NULL.\r
 109  * @param[in] pDev2 Pointer to OCProvisionDev_t instance,respresenting device to be provisioned.\r
 110  * @param[in] acl ACL for device 2. If this is not required set NULL.\r
 111  * @param[in] resultCallback callback provided by API user, callback will be called when\r
 112  *            provisioning request recieves a response from first resource server.\r
 113  * @return OC_STACK_OK in case of success and other value otherwise.\r
 114  */\r
 115 OCStackResult OCProvisionPairwiseDevices(void* ctx, OicSecCredType_t type, size_t keySize,\r
 116                                          const OCProvisionDev_t *pDev1, OicSecAcl_t *pDev1Acl,\r
 117                                          const OCProvisionDev_t *pDev2, OicSecAcl_t *pDev2Acl,\r
 118                                          OCProvisionResultCB resultCallback);\r
 119 \r
 120 /**\r
 121  * API to send ACL information to device.\r
 122  *\r
 123  * @param[in] ctx Application context would be returned in result callback.\r
 124  * @param[in] selectedDeviceInfo Selected target device.\r
 125  * @param[in] acl ACL to provision.\r
 126  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
 127               request recieves a response from resource server.\r
 128  * @return OC_STACK_OK in case of success and other value otherwise.\r
 129  */\r
 130 OCStackResult OCProvisionACL(void *ctx, const OCProvisionDev_t *selectedDeviceInfo, OicSecAcl_t *acl,\r
 131                              OCProvisionResultCB resultCallback);\r
 132 \r
 133 /**\r
 134  * this function requests CRED information to resource.\r
 135  *\r
 136  * @param[in] ctx Application context would be returned in result callback.\r
 137  * @param[in] selectedDeviceInfo Selected target device.\r
 138  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
 139               request recieves a response from resource server.\r
 140  * @return  OC_STACK_OK in case of success and other value otherwise.\r
 141  */\r
 142 OCStackResult OCGetCredResource(void* ctx, const OCProvisionDev_t *selectedDeviceInfo,\r
 143                              OCProvisionResultCB resultCallback);\r
 144 \r
 145 /**\r
 146  * this function requests ACL information to resource.\r
 147  *\r
 148  * @param[in] ctx Application context would be returned in result callback.\r
 149  * @param[in] selectedDeviceInfo Selected target device.\r
 150  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
 151               request recieves a response from resource server.\r
 152  * @return  OC_STACK_OK in case of success and other value otherwise.\r
 153  */\r
 154 OCStackResult OCGetACLResource(void* ctx, const OCProvisionDev_t *selectedDeviceInfo,\r
 155                              OCProvisionResultCB resultCallback);\r
 156 \r
 157 /**\r
 158  * this function sends Direct-Pairing Configuration to a device.\r
 159  *\r
 160  * @param[in] ctx Application context would be returned in result callback.\r
 161  * @param[in] selectedDeviceInfo Selected target device.\r
 162  * @param[in] pconf PCONF pointer.\r
 163  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
 164               request recieves a response from resource server.\r
 165  * @return  OC_STACK_OK in case of success and other value otherwise.\r
 166  */\r
 167 OCStackResult OCProvisionDirectPairing(void* ctx, const OCProvisionDev_t *selectedDeviceInfo, OicSecPconf_t *pconf,\r
 168                              OCProvisionResultCB resultCallback);\r
 169 \r
 170 /**\r
 171  * API to provision credential to devices.\r
 172  *\r
 173  * @param[in] ctx Application context would be returned in result callback.\r
 174  * @param[in] type Type of credentials to be provisioned to the device.\r
 175  * @param[in] pDev1 Pointer to OCProvisionDev_t instance,respresenting resource to be provsioned.\r
 176    @param[in] pDev2 Pointer to OCProvisionDev_t instance,respresenting resource to be provsioned.\r
 177  * @param[in] resultCallback callback provided by API user, callback will be called when\r
 178  *            provisioning request recieves a response from first resource server.\r
 179  * @return OC_STACK_OK in case of success and other value otherwise.\r
 180  */\r
 181 OCStackResult OCProvisionCredentials(void *ctx, OicSecCredType_t type, size_t keySize,\r
 182                                       const OCProvisionDev_t *pDev1,\r
 183                                       const OCProvisionDev_t *pDev2,\r
 184                                       OCProvisionResultCB resultCallback);\r
 185 \r
 186 /**\r
 187  * Function to unlink devices.\r
 188  * This function will remove the credential & relasionship between the two devices.\r
 189  *\r
 190  * @param[in] ctx Application context would be returned in result callback\r
 191  * @param[in] pTargetDev1 fitst device information to be unlinked.\r
 192  * @param[in] pTargetDev2 second device information to be unlinked.\r
 193  * @param[in] resultCallback callback provided by API user, callback will be called when\r
 194  *            device unlink is finished.\r
 195  * @return OC_STACK_OK in case of success and other value otherwise.\r
 196  */\r
 197 OCStackResult OCUnlinkDevices(void* ctx,\r
 198                               const OCProvisionDev_t* pTargetDev1,\r
 199                               const OCProvisionDev_t* pTargetDev2,\r
 200                               OCProvisionResultCB resultCallback);\r
 201 \r
 202 /**\r
 203  * Function for device revocation\r
 204  * This function will remove credential of target device from all devices in subnet.\r
 205  *\r
 206  * @param[in] ctx Application context would be returned in result callback\r
 207  * @param[in] waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device discovery.(seconds)\r
 208  * @param[in] pTargetDev Device information to be revoked.\r
 209  * @param[in] resultCallback callback provided by API user, callback will be called when\r
 210  *            credential revocation is finished.\r
 211  * @return OC_STACK_OK in case of success and other value otherwise.\r
 212  *         if OC_STACK_OK is returned, the caller of this API should wait for callback.\r
 213  *         OC_STACK_CONTINUE means operation is success but no need to wait for callback.\r
 214  */\r
 215 OCStackResult OCRemoveDevice(void* ctx,\r
 216                              unsigned short waitTimeForOwnedDeviceDiscovery,\r
 217                              const OCProvisionDev_t* pTargetDev,\r
 218                              OCProvisionResultCB resultCallback);\r
 219 \r
 220 /*\r
 221 * Function to device revocation\r
 222 * This function will remove credential of target device from all devices in subnet.\r
 223 *\r
 224 * @param[in] ctx Application context would be returned in result callback\r
 225 * @param[in] waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device discovery.(seconds)\r
 226 * @param[in] pTargetDev Device information to be revoked.\r
 227 * @param[in] resultCallback callback provided by API user, callback will be called when\r
 228 *            credential revocation is finished.\r
 229  * @return  OC_STACK_OK in case of success and other value otherwise.\r
 230 */\r
 231 OCStackResult OCRemoveDeviceWithUuid(void* ctx,\r
 232                                      unsigned short waitTimeForOwnedDeviceDiscovery,\r
 233                                      const OicUuid_t* pTargetUuid,\r
 234                                      OCProvisionResultCB resultCallback);\r
 235 \r
 236 /*\r
 237  * Function to reset the target device.\r
 238  * This function will remove credential and ACL of target device from all devices in subnet.\r
 239  *\r
 240  * @param[in] ctx Application context would be returned in result callback\r
 241  * @param[in] waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device discovery.(seconds)\r
 242  * @param[in] pTargetDev Device information to be revoked.\r
 243  * @param[in] resultCallback callback provided by API user, callback will be called when\r
 244  *            credential revocation is finished.\r
 245  * @return  OC_STACK_OK in case of success and other value otherwise.\r
 246  */\r
 247 OCStackResult OCResetDevice(void* ctx, unsigned short waitTimeForOwnedDeviceDiscovery,\r
 248                             const OCProvisionDev_t* pTargetDev,\r
 249                             OCProvisionResultCB resultCallback);\r
 250 \r
 251 /**\r
 252  * API to get status of all the devices in current subnet. The status include endpoint information\r
 253  * and doxm information which can be extracted duing owned and unowned discovery. Along with this\r
 254  * information. The API will provide information about devices' status\r
 255  * Device can have following states\r
 256  *  - ON/OFF: Device is switched on or off.\r
 257  *\r
 258  * NOTE: Caller need to call OCDeleteDiscoveredDevices to delete memory allocated by this API for out\r
 259  * variables pOwnedDevList and pUnownedDevList.\r
 260  *\r
 261  * @param[in] waitime Wait time for the API. The wait time will be divided by 2, and half of wait time\r
 262  * will be used for unowned discovery and remaining half for owned discovery. So the wait time should be\r
 263  * equal to or more than 2.\r
 264  * @param[out] pOwnedDevList  list of owned devices.\r
 265  * @param[out] pUnownedDevList  list of unowned devices.\r
 266  * @return OC_STACK_OK in case of success and other value otherwise.\r
 267  */\r
 268 OCStackResult OCGetDevInfoFromNetwork(unsigned short waittime,\r
 269                                        OCProvisionDev_t** pOwnedDevList,\r
 270                                        OCProvisionDev_t** pUnownedDevList);\r
 271 /**\r
 272  * This method is used to get linked devices' IDs.\r
 273  *\r
 274  * @param[in] uuidOfDevice a target device's uuid.\r
 275  * @param[out] uuidList information about the list of linked devices' uuids.\r
 276  * @param[out] numOfDevices total number of linked devices.\r
 277  * @return OC_STACK_OK in case of success and other value otherwise.\r
 278  */\r
 279 OCStackResult OCGetLinkedStatus(const OicUuid_t* uuidOfDevice,\r
 280                                   OCUuidList_t** uuidList,\r
 281                                   size_t* numOfDevices);\r
 282 \r
 283 /**\r
 284  * API to delete memory allocated to linked list created by OCDiscover_XXX_Devices API.\r
 285  *\r
 286  * @param[in] pList Pointer to OCProvisionDev_t which should be deleted.\r
 287  */\r
 288 void OCDeleteDiscoveredDevices(OCProvisionDev_t *pList);\r
 289 \r
 290 /**\r
 291  * API to delete memory allocated to OicUuid_t list.\r
 292  *\r
 293  * @param[in] pList Pointer to OicUuid_t list which should be deleted.\r
 294  */\r
 295 void OCDeleteUuidList(OCUuidList_t* pList);\r
 296 \r
 297 /**\r
 298  * This function deletes ACL data.\r
 299  *\r
 300  * @param pAcl Pointer to OicSecAcl_t structure.\r
 301  */\r
 302 void OCDeleteACLList(OicSecAcl_t* pAcl);\r
 303 \r
 304 /**\r
 305  * This function deletes PDACL data.\r
 306  *\r
 307  * @param pPdAcl Pointer to OicSecPdAcl_t structure.\r
 308  */\r
 309 void OCDeletePdAclList(OicSecPdAcl_t* pPdAcl);\r
 310 \r
 311 #if defined(__WITH_X509__) || defined(__WITH_TLS__)\r
 312 /**\r
 313  * this function sends CRL information to resource.\r
 314  *\r
 315  * @param[in] ctx Application context would be returned in result callback.\r
 316  * @param[in] selectedDeviceInfo Selected target device.\r
 317  * @param[in] crl CRL to provision.\r
 318  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
 319               request recieves a response from resource server.\r
 320  * @return  OC_STACK_OK in case of success and other value otherwise.\r
 321  */\r
 322 OCStackResult OCProvisionCRL(void* ctx, const OCProvisionDev_t *selectedDeviceInfo, OicSecCrl_t *crl,\r
 323                              OCProvisionResultCB resultCallback);\r
 324 \r
 325 /**\r
 326  * function to provision Trust certificate chain to devices.\r
 327  *\r
 328  * @param[in] ctx Application context would be returned in result callback.\r
 329  * @param[in] type Type of credentials to be provisioned to the device.\r
 330  * @param[in] credId CredId of trust certificate chain to be provisioned to the device.\r
 331  * @param[in] selectedDeviceInfo Pointer to OCProvisionDev_t instance,respresenting resource to be provsioned.\r
 332  * @param[in] resultCallback callback provided by API user, callback will be called when\r
 333  *            provisioning request recieves a response from first resource server.\r
 334  * @return  OC_STACK_OK in case of success and other value otherwise.\r
 335  */\r
 336 OCStackResult OCProvisionTrustCertChain(void *ctx, OicSecCredType_t type, uint16_t credId,\r
 337                                       const OCProvisionDev_t *selectedDeviceInfo,\r
 338                                       OCProvisionResultCB resultCallback);\r
 339 /**\r
 340  * function to save Trust certificate chain into Cred of SVR.\r
 341  *\r
 342  * @param[in] trustCertChain Trust certificate chain to be saved in Cred of SVR.\r
 343  * @param[in] chainSize Size of trust certificate chain to be saved in Cred of SVR\r
 344  * @param[in] encodingType Encoding type of trust certificate chain to be saved in Cred of SVR\r
 345  * @param[out] credId CredId of saved trust certificate chain in Cred of SVR.\r
 346  * @return  OC_STACK_OK in case of success and other value otherwise.\r
 347  */\r
 348 OCStackResult OCSaveTrustCertChain(uint8_t *trustCertChain, size_t chainSize,\r
 349                                         OicEncodingType_t encodingType, uint16_t *credId);\r
 350 \r
 351 #endif // __WITH_X509__ || __WITH_TLS__\r
 352 \r
 353 \r
 354 #ifdef __cplusplus\r
 355 }\r
 356 #endif // __cplusplus\r
 357 \r
 358 #endif /* OCPROVISIONINGMANAGER_H_ */\r