Multiple Ownership Transfer support.
[platform/upstream/iotivity.git] / 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 #ifdef _ENABLE_MULTIPLE_OWNER_\r
28 #include "securevirtualresourcetypes.h"\r
29 #endif //_ENABLE_MULTIPLE_OWNER_\r
30 \r
31 #ifdef __cplusplus\r
32 extern "C" {\r
33 #endif // __cplusplus\r
34 \r
35 /**\r
36  * The function is responsible for initializaton of the provisioning manager. It will load\r
37  * provisioning database which have owned device's list and their linked status.\r
38  * TODO: In addition, if there is a device(s) which has not up-to-date credentials, this function will\r
39  * automatically try to update the deivce(s).\r
40  *\r
41  * @param[in] dbPath file path of the sqlite3 db\r
42  *\r
43  * @return OC_STACK_OK in case of success and other value otherwise.\r
44  */\r
45 OCStackResult OCInitPM(const char* dbPath);\r
46 \r
47 /**\r
48  * The function is responsible for discovery of owned/unowned device is specified endpoint/deviceID.\r
49  * It will return the found device even though timeout is not exceeded.\r
50  *\r
51  * @param[in] timeout Timeout in seconds, value till which function will listen to responses from\r
52  *                    server before returning the device.\r
53  * @param[in] deviceID         deviceID of target device.\r
54  * @param[out] ppFoundDevice     OCProvisionDev_t of found device\r
55  * @return OTM_SUCCESS in case of success and other value otherwise.\r
56  */\r
57 OCStackResult OCDiscoverSingleDevice(unsigned short timeout, const OicUuid_t* deviceID,\r
58                              OCProvisionDev_t **ppFoundDevice);\r
59 \r
60 /**\r
61  * The function is responsible for discovery of device is current subnet. It will list\r
62  * all the device in subnet which are not yet owned. Please call OCInit with OC_CLIENT_SERVER as\r
63  * OCMode.\r
64  *\r
65  * @param[in] timeout Timeout in seconds, value till which function will listen to responses from\r
66  *                    server before returning the list of devices.\r
67  * @param[out] ppList List of candidate devices to be provisioned\r
68  * @return OTM_SUCCESS in case of success and other value otherwise.\r
69  */\r
70 OCStackResult OCDiscoverUnownedDevices(unsigned short waittime, OCProvisionDev_t **ppList);\r
71 \r
72 /**\r
73  * Do ownership transfer for un-owned device.\r
74  *\r
75  * @param[in] ctx Application context would be returned in result callback\r
76  * @param[in] targetDevices List of devices to perform ownership transfer.\r
77  * @param[in] resultCallback Result callback function to be invoked when ownership transfer finished.\r
78  * @return OC_STACK_OK in case of success and other value otherwise.\r
79  */\r
80 OCStackResult OCDoOwnershipTransfer(void* ctx,\r
81                                     OCProvisionDev_t *targetDevices,\r
82                                     OCProvisionResultCB resultCallback);\r
83 \r
84 #ifdef _ENABLE_MULTIPLE_OWNER_\r
85 /**\r
86  * API to perfrom multiple ownership transfer for MOT enabled device.\r
87  *\r
88  * @param[in] ctx Application context would be returned in result callback\r
89  * @param[in] targetDevices List of devices to perform ownership transfer.\r
90  * @param[in] resultCallback Result callback function to be invoked when ownership transfer finished.\r
91  * @return OC_STACK_OK in case of success and other value otherwise.\r
92  */\r
93 OCStackResult OCDoMultipleOwnershipTransfer(void* ctx,\r
94                                       OCProvisionDev_t *targetDevices,\r
95                                       OCProvisionResultCB resultCallback);\r
96 #endif //_ENABLE_MULTIPLE_OWNER_\r
97 \r
98 /**\r
99  * API to register for particular OxM.\r
100  *\r
101  * @param[in] Ownership transfer method.\r
102  * @param[in] Implementation of callback functions for owership transfer.\r
103  * @return OC_STACK_OK in case of success and other value otherwise.\r
104  */\r
105 OCStackResult OCSetOwnerTransferCallbackData(OicSecOxm_t oxm, OTMCallbackData_t* callbackData);\r
106 \r
107 /**\r
108  * The function is responsible for discovery of owned device is current subnet. It will list\r
109  * all the device in subnet which are owned by calling provisioning client.\r
110  *\r
111  * @param[in] timeout Timeout in seconds, value till which function will listen to responses from\r
112  *                    server before returning the list of devices.\r
113  * @param[out] ppList List of device owned by provisioning tool.\r
114  * @return OTM_SUCCESS in case of success and other value otherwise.\r
115  */\r
116 OCStackResult OCDiscoverOwnedDevices(unsigned short timeout, OCProvisionDev_t **ppList);\r
117 \r
118 #ifdef _ENABLE_MULTIPLE_OWNER_\r
119 /**\r
120  * The function is responsible for discovery of MOT enabled device is current subnet.\r
121  *\r
122  * @param[in] timeout Timeout in seconds, value till which function will listen to responses from\r
123  *                    server before returning the list of devices.\r
124  * @param[out] ppList List of MOT enabled devices.\r
125  * @return OC_STACK_OK in case of success and other value otherwise.\r
126  */\r
127 OCStackResult OCDiscoverMultipleOwnerEnabledDevices(unsigned short timeout, OCProvisionDev_t **ppList);\r
128 \r
129 /**\r
130  * The function is responsible for discovery of Multiple Owned device is current subnet.\r
131  *\r
132  * @param[in] timeout Timeout in seconds, value till which function will listen to responses from\r
133  *                    server before returning the list of devices.\r
134  * @param[out] ppList List of Multiple Owned devices.\r
135  * @return OC_STACK_OK in case of success and other value otherwise.\r
136  */\r
137 OCStackResult OCDiscoverMultipleOwnedDevices(unsigned short timeout, OCProvisionDev_t **ppList);\r
138 #endif //_ENABLE_MULTIPLE_OWNER_\r
139 \r
140 /**\r
141  * API to provision credentials between two devices and ACLs for the devices who act as a server.\r
142  *\r
143  * @param[in] ctx Application context would be returned in result callback.\r
144  * @param[in] type Type of credentials to be provisioned to the device.\r
145  * @param[in] pDev1 Pointer to OCProvisionDev_t instance,respresenting device to be provisioned.\r
146  * @param[in] acl ACL for device 1. If this is not required set NULL.\r
147  * @param[in] pDev2 Pointer to OCProvisionDev_t instance,respresenting device to be provisioned.\r
148  * @param[in] acl ACL for device 2. If this is not required set NULL.\r
149  * @param[in] resultCallback callback provided by API user, callback will be called when\r
150  *            provisioning request recieves a response from first resource server.\r
151  * @return OC_STACK_OK in case of success and other value otherwise.\r
152  */\r
153 OCStackResult OCProvisionPairwiseDevices(void* ctx, OicSecCredType_t type, size_t keySize,\r
154                                          const OCProvisionDev_t *pDev1, OicSecAcl_t *pDev1Acl,\r
155                                          const OCProvisionDev_t *pDev2, OicSecAcl_t *pDev2Acl,\r
156                                          OCProvisionResultCB resultCallback);\r
157 \r
158 /**\r
159  * API to send ACL information to device.\r
160  *\r
161  * @param[in] ctx Application context would be returned in result callback.\r
162  * @param[in] selectedDeviceInfo Selected target device.\r
163  * @param[in] acl ACL to provision.\r
164  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
165               request recieves a response from resource server.\r
166  * @return OC_STACK_OK in case of success and other value otherwise.\r
167  */\r
168 OCStackResult OCProvisionACL(void *ctx, const OCProvisionDev_t *selectedDeviceInfo, OicSecAcl_t *acl,\r
169                              OCProvisionResultCB resultCallback);\r
170 \r
171 /**\r
172  * this function requests CRED information to resource.\r
173  *\r
174  * @param[in] ctx Application context would be returned in result callback.\r
175  * @param[in] selectedDeviceInfo Selected target device.\r
176  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
177               request recieves a response from resource server.\r
178  * @return  OC_STACK_OK in case of success and other value otherwise.\r
179  */\r
180 OCStackResult OCGetCredResource(void* ctx, const OCProvisionDev_t *selectedDeviceInfo,\r
181                              OCProvisionResultCB resultCallback);\r
182 \r
183 /**\r
184  * this function requests ACL information to resource.\r
185  *\r
186  * @param[in] ctx Application context would be returned in result callback.\r
187  * @param[in] selectedDeviceInfo Selected target device.\r
188  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
189               request recieves a response from resource server.\r
190  * @return  OC_STACK_OK in case of success and other value otherwise.\r
191  */\r
192 OCStackResult OCGetACLResource(void* ctx, const OCProvisionDev_t *selectedDeviceInfo,\r
193                              OCProvisionResultCB resultCallback);\r
194 \r
195 /**\r
196  * this function sends Direct-Pairing Configuration to a device.\r
197  *\r
198  * @param[in] ctx Application context would be returned in result callback.\r
199  * @param[in] selectedDeviceInfo Selected target device.\r
200  * @param[in] pconf PCONF pointer.\r
201  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
202               request recieves a response from resource server.\r
203  * @return  OC_STACK_OK in case of success and other value otherwise.\r
204  */\r
205 OCStackResult OCProvisionDirectPairing(void* ctx, const OCProvisionDev_t *selectedDeviceInfo, OicSecPconf_t *pconf,\r
206                              OCProvisionResultCB resultCallback);\r
207 \r
208 /**\r
209  * API to provision credential to devices.\r
210  *\r
211  * @param[in] ctx Application context would be returned in result callback.\r
212  * @param[in] type Type of credentials to be provisioned to the device.\r
213  * @param[in] pDev1 Pointer to OCProvisionDev_t instance,respresenting resource to be provsioned.\r
214    @param[in] pDev2 Pointer to OCProvisionDev_t instance,respresenting resource to be provsioned.\r
215  * @param[in] resultCallback callback provided by API user, callback will be called when\r
216  *            provisioning request recieves a response from first resource server.\r
217  * @return OC_STACK_OK in case of success and other value otherwise.\r
218  */\r
219 OCStackResult OCProvisionCredentials(void *ctx, OicSecCredType_t type, size_t keySize,\r
220                                       const OCProvisionDev_t *pDev1,\r
221                                       const OCProvisionDev_t *pDev2,\r
222                                       OCProvisionResultCB resultCallback);\r
223 \r
224 #ifdef _ENABLE_MULTIPLE_OWNER_\r
225 /**\r
226  * API to provision preconfigured PIN to device(NOT LIST).\r
227  * If device does not support the Preconfigured PIN OxM,\r
228  * OCProvisionPreconfPin API will be update the device's Doxm\r
229  * and then try prevonfigured PIN provisioning once again.\r
230  *\r
231  * @param[in] ctx Application context would be returned in result callback.\r
232  * @param[in] targetDeviceInfo Selected target device.\r
233  * @param[in] preconfPin string of preconfigured PIN.\r
234  * @param[in] preconfPinLen string length of 'preconfPin'.\r
235  * @param[in] resultCallback callback provided by API user, callback will be called when\r
236  *            provisioning request recieves a response from first resource server.\r
237  * @return OC_STACK_OK in case of success and other value otherwise.\r
238  */\r
239 OCStackResult OCProvisionPreconfPin(void* ctx,\r
240                                                OCProvisionDev_t *targetDeviceInfo,\r
241                                                const char * preconfPin, size_t preconfPinLen,\r
242                                                OCProvisionResultCB resultCallback);\r
243 \r
244 /**\r
245  * API to add preconfigured PIN to local SVR DB.\r
246  *\r
247  * @param[in] targetDeviceInfo Selected target device.\r
248  * @param[in] preconfPIN Preconfig PIN which is used while multiple owner authentication\r
249  * @param[in] preconfPINLen Byte length of preconfig PIN\r
250  * @return OC_STACK_OK in case of success and other value otherwise.\r
251  */\r
252 OCStackResult OCAddPreconfigPIN(const OCProvisionDev_t *targetDeviceInfo,\r
253                                  const char* preconfPIN, size_t preconfPINLen);\r
254 \r
255 /**\r
256  * API to update 'doxm.mom' to resource server.\r
257  *\r
258  * @param[in] targetDeviceInfo Selected target device.\r
259  * @param[in] momType Mode of multiple ownership transfer (ref. oic.sec.mom)\r
260  * @param[in] resultCallback callback provided by API user, callback will be called when\r
261  *            POST 'mom' request recieves a response from resource server.\r
262  * @return OC_STACK_OK in case of success and other value otherwise.\r
263  */\r
264 OCStackResult OCChangeMOTMode(void *ctx, const OCProvisionDev_t *targetDeviceInfo,\r
265                             const OicSecMomType_t momType, OCProvisionResultCB resultCallback);\r
266 \r
267 /**\r
268  * API to update 'doxm.oxmsel' to resource server.\r
269  *\r
270  * @param[in] targetDeviceInfo Selected target device.\r
271  * @param[in] oxmSelValue Method of multiple ownership transfer (ref. oic.sec.oxm)\r
272  * @param[in] resultCallback callback provided by API user, callback will be called when\r
273  *            POST 'oxmsel' request recieves a response from resource server.\r
274  * @return OC_STACK_OK in case of success and other value otherwise.\r
275  */\r
276 OCStackResult OCSelectMOTMethod(void *ctx, const OCProvisionDev_t *targetDeviceInfo,\r
277                                  const OicSecOxm_t oxmSelValue, OCProvisionResultCB resultCallback);\r
278 #endif //_ENABLE_MULTIPLE_OWNER_\r
279 \r
280 /**\r
281  * Function to unlink devices.\r
282  * This function will remove the credential & relasionship between the two devices.\r
283  *\r
284  * @param[in] ctx Application context would be returned in result callback\r
285  * @param[in] pTargetDev1 fitst device information to be unlinked.\r
286  * @param[in] pTargetDev2 second device information to be unlinked.\r
287  * @param[in] resultCallback callback provided by API user, callback will be called when\r
288  *            device unlink is finished.\r
289  * @return OC_STACK_OK in case of success and other value otherwise.\r
290  */\r
291 OCStackResult OCUnlinkDevices(void* ctx,\r
292                               const OCProvisionDev_t* pTargetDev1,\r
293                               const OCProvisionDev_t* pTargetDev2,\r
294                               OCProvisionResultCB resultCallback);\r
295 \r
296 /**\r
297  * Function for device revocation\r
298  * This function will remove credential of target device from all devices in subnet.\r
299  *\r
300  * @param[in] ctx Application context would be returned in result callback\r
301  * @param[in] waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device discovery.(seconds)\r
302  * @param[in] pTargetDev Device information to be revoked.\r
303  * @param[in] resultCallback callback provided by API user, callback will be called when\r
304  *            credential revocation is finished.\r
305  * @return OC_STACK_OK in case of success and other value otherwise.\r
306  *         if OC_STACK_OK is returned, the caller of this API should wait for callback.\r
307  *         OC_STACK_CONTINUE means operation is success but no need to wait for callback.\r
308  */\r
309 OCStackResult OCRemoveDevice(void* ctx,\r
310                              unsigned short waitTimeForOwnedDeviceDiscovery,\r
311                              const OCProvisionDev_t* pTargetDev,\r
312                              OCProvisionResultCB resultCallback);\r
313 \r
314 /*\r
315 * Function to device revocation\r
316 * This function will remove credential of target device from all devices in subnet.\r
317 *\r
318 * @param[in] ctx Application context would be returned in result callback\r
319 * @param[in] waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device discovery.(seconds)\r
320 * @param[in] pTargetDev Device information to be revoked.\r
321 * @param[in] resultCallback callback provided by API user, callback will be called when\r
322 *            credential revocation is finished.\r
323  * @return  OC_STACK_OK in case of success and other value otherwise.\r
324 */\r
325 OCStackResult OCRemoveDeviceWithUuid(void* ctx,\r
326                                      unsigned short waitTimeForOwnedDeviceDiscovery,\r
327                                      const OicUuid_t* pTargetUuid,\r
328                                      OCProvisionResultCB resultCallback);\r
329 \r
330 /*\r
331  * Function to reset the target device.\r
332  * This function will remove credential and ACL of target device from all devices in subnet.\r
333  *\r
334  * @param[in] ctx Application context would be returned in result callback\r
335  * @param[in] waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device discovery.(seconds)\r
336  * @param[in] pTargetDev Device information to be revoked.\r
337  * @param[in] resultCallback callback provided by API user, callback will be called when\r
338  *            credential revocation is finished.\r
339  * @return  OC_STACK_OK in case of success and other value otherwise.\r
340  */\r
341 OCStackResult OCResetDevice(void* ctx, unsigned short waitTimeForOwnedDeviceDiscovery,\r
342                             const OCProvisionDev_t* pTargetDev,\r
343                             OCProvisionResultCB resultCallback);\r
344 \r
345 /**\r
346  * API to get status of all the devices in current subnet. The status include endpoint information\r
347  * and doxm information which can be extracted duing owned and unowned discovery. Along with this\r
348  * information. The API will provide information about devices' status\r
349  * Device can have following states\r
350  *  - ON/OFF: Device is switched on or off.\r
351  *\r
352  * NOTE: Caller need to call OCDeleteDiscoveredDevices to delete memory allocated by this API for out\r
353  * variables pOwnedDevList and pUnownedDevList.\r
354  *\r
355  * @param[in] waitime Wait time for the API. The wait time will be divided by 2, and half of wait time\r
356  * will be used for unowned discovery and remaining half for owned discovery. So the wait time should be\r
357  * equal to or more than 2.\r
358  * @param[out] pOwnedDevList  list of owned devices.\r
359  * @param[out] pUnownedDevList  list of unowned devices.\r
360  * @return OC_STACK_OK in case of success and other value otherwise.\r
361  */\r
362 OCStackResult OCGetDevInfoFromNetwork(unsigned short waittime,\r
363                                        OCProvisionDev_t** pOwnedDevList,\r
364                                        OCProvisionDev_t** pUnownedDevList);\r
365 /**\r
366  * This method is used to get linked devices' IDs.\r
367  *\r
368  * @param[in] uuidOfDevice a target device's uuid.\r
369  * @param[out] uuidList information about the list of linked devices' uuids.\r
370  * @param[out] numOfDevices total number of linked devices.\r
371  * @return OC_STACK_OK in case of success and other value otherwise.\r
372  */\r
373 OCStackResult OCGetLinkedStatus(const OicUuid_t* uuidOfDevice,\r
374                                   OCUuidList_t** uuidList,\r
375                                   size_t* numOfDevices);\r
376 \r
377 /**\r
378  * API to delete memory allocated to linked list created by OCDiscover_XXX_Devices API.\r
379  *\r
380  * @param[in] pList Pointer to OCProvisionDev_t which should be deleted.\r
381  */\r
382 void OCDeleteDiscoveredDevices(OCProvisionDev_t *pList);\r
383 \r
384 /**\r
385  * API to delete memory allocated to OicUuid_t list.\r
386  *\r
387  * @param[in] pList Pointer to OicUuid_t list which should be deleted.\r
388  */\r
389 void OCDeleteUuidList(OCUuidList_t* pList);\r
390 \r
391 /**\r
392  * This function deletes ACL data.\r
393  *\r
394  * @param pAcl Pointer to OicSecAcl_t structure.\r
395  */\r
396 void OCDeleteACLList(OicSecAcl_t* pAcl);\r
397 \r
398 /**\r
399  * This function deletes PDACL data.\r
400  *\r
401  * @param pPdAcl Pointer to OicSecPdAcl_t structure.\r
402  */\r
403 void OCDeletePdAclList(OicSecPdAcl_t* pPdAcl);\r
404 \r
405 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)\r
406 /**\r
407  * this function sends CRL information to resource.\r
408  *\r
409  * @param[in] ctx Application context would be returned in result callback.\r
410  * @param[in] selectedDeviceInfo Selected target device.\r
411  * @param[in] crl CRL to provision.\r
412  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
413               request recieves a response from resource server.\r
414  * @return  OC_STACK_OK in case of success and other value otherwise.\r
415  */\r
416 OCStackResult OCProvisionCRL(void* ctx, const OCProvisionDev_t *selectedDeviceInfo, OicSecCrl_t *crl,\r
417                              OCProvisionResultCB resultCallback);\r
418 \r
419 /**\r
420  * function to provision Trust certificate chain to devices.\r
421  *\r
422  * @param[in] ctx Application context would be returned in result callback.\r
423  * @param[in] type Type of credentials to be provisioned to the device.\r
424  * @param[in] credId CredId of trust certificate chain to be provisioned to the device.\r
425  * @param[in] selectedDeviceInfo Pointer to OCProvisionDev_t instance,respresenting resource to be provsioned.\r
426  * @param[in] resultCallback callback provided by API user, callback will be called when\r
427  *            provisioning request recieves a response from first resource server.\r
428  * @return  OC_STACK_OK in case of success and other value otherwise.\r
429  */\r
430 OCStackResult OCProvisionTrustCertChain(void *ctx, OicSecCredType_t type, uint16_t credId,\r
431                                       const OCProvisionDev_t *selectedDeviceInfo,\r
432                                       OCProvisionResultCB resultCallback);\r
433 /**\r
434  * function to save Trust certificate chain into Cred of SVR.\r
435  *\r
436  * @param[in] trustCertChain Trust certificate chain to be saved in Cred of SVR.\r
437  * @param[in] chainSize Size of trust certificate chain to be saved in Cred of SVR\r
438  * @param[in] encodingType Encoding type of trust certificate chain to be saved in Cred of SVR\r
439  * @param[out] credId CredId of saved trust certificate chain in Cred of SVR.\r
440  * @return  OC_STACK_OK in case of success and other value otherwise.\r
441  */\r
442 OCStackResult OCSaveTrustCertChain(uint8_t *trustCertChain, size_t chainSize,\r
443                                         OicEncodingType_t encodingType, uint16_t *credId);\r
444 \r
445 #endif // __WITH_DTLS__ || __WITH_TLS__\r
446 \r
447 \r
448 #ifdef __cplusplus\r
449 }\r
450 #endif // __cplusplus\r
451 \r
452 #endif /* OCPROVISIONINGMANAGER_H_ */\r