939af6335edcfb487d934c063570e7d936121639
[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  * function to save ACL which has several ACE into Acl of SVR.\r
173  *\r
174  * @param acl ACL to be saved in Acl of SVR.\r
175  * @return  OC_STACK_OK in case of success and other value otherwise.\r
176  */\r
177 OCStackResult OCSaveACL(const OicSecAcl_t* acl);\r
178 \r
179 /**\r
180  * this function requests CRED information to resource.\r
181  *\r
182  * @param[in] ctx Application context would be returned in result callback.\r
183  * @param[in] selectedDeviceInfo Selected target device.\r
184  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
185               request recieves a response from resource server.\r
186  * @return  OC_STACK_OK in case of success and other value otherwise.\r
187  */\r
188 OCStackResult OCGetCredResource(void* ctx, const OCProvisionDev_t *selectedDeviceInfo,\r
189                              OCProvisionResultCB resultCallback);\r
190 \r
191 /**\r
192  * this function requests ACL information to resource.\r
193  *\r
194  * @param[in] ctx Application context would be returned in result callback.\r
195  * @param[in] selectedDeviceInfo Selected target device.\r
196  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
197               request recieves a response from resource server.\r
198  * @return  OC_STACK_OK in case of success and other value otherwise.\r
199  */\r
200 OCStackResult OCGetACLResource(void* ctx, const OCProvisionDev_t *selectedDeviceInfo,\r
201                              OCProvisionResultCB resultCallback);\r
202 \r
203 /**\r
204  * this function sends Direct-Pairing Configuration to a device.\r
205  *\r
206  * @param[in] ctx Application context would be returned in result callback.\r
207  * @param[in] selectedDeviceInfo Selected target device.\r
208  * @param[in] pconf PCONF pointer.\r
209  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
210               request recieves a response from resource server.\r
211  * @return  OC_STACK_OK in case of success and other value otherwise.\r
212  */\r
213 OCStackResult OCProvisionDirectPairing(void* ctx, const OCProvisionDev_t *selectedDeviceInfo, OicSecPconf_t *pconf,\r
214                              OCProvisionResultCB resultCallback);\r
215 \r
216 /**\r
217  * API to provision credential to devices.\r
218  *\r
219  * @param[in] ctx Application context would be returned in result callback.\r
220  * @param[in] type Type of credentials to be provisioned to the device.\r
221  * @param[in] pDev1 Pointer to OCProvisionDev_t instance,respresenting resource to be provsioned.\r
222    @param[in] pDev2 Pointer to OCProvisionDev_t instance,respresenting resource to be provsioned.\r
223  * @param[in] resultCallback callback provided by API user, callback will be called when\r
224  *            provisioning request recieves a response from first resource server.\r
225  * @return OC_STACK_OK in case of success and other value otherwise.\r
226  */\r
227 OCStackResult OCProvisionCredentials(void *ctx, OicSecCredType_t type, size_t keySize,\r
228                                       const OCProvisionDev_t *pDev1,\r
229                                       const OCProvisionDev_t *pDev2,\r
230                                       OCProvisionResultCB resultCallback);\r
231 \r
232 #ifdef _ENABLE_MULTIPLE_OWNER_\r
233 /**\r
234  * API to provision preconfigured PIN to device(NOT LIST).\r
235  * If device does not support the Preconfigured PIN OxM,\r
236  * OCProvisionPreconfPin API will be update the device's Doxm\r
237  * and then try prevonfigured PIN provisioning once again.\r
238  *\r
239  * @param[in] ctx Application context would be returned in result callback.\r
240  * @param[in] targetDeviceInfo Selected target device.\r
241  * @param[in] preconfPin string of preconfigured PIN.\r
242  * @param[in] preconfPinLen string length of 'preconfPin'.\r
243  * @param[in] resultCallback callback provided by API user, callback will be called when\r
244  *            provisioning request recieves a response from first resource server.\r
245  * @return OC_STACK_OK in case of success and other value otherwise.\r
246  */\r
247 OCStackResult OCProvisionPreconfPin(void* ctx,\r
248                                                OCProvisionDev_t *targetDeviceInfo,\r
249                                                const char * preconfPin, size_t preconfPinLen,\r
250                                                OCProvisionResultCB resultCallback);\r
251 \r
252 /**\r
253  * API to add preconfigured PIN to local SVR DB.\r
254  *\r
255  * @param[in] targetDeviceInfo Selected target device.\r
256  * @param[in] preconfPIN Preconfig PIN which is used while multiple owner authentication\r
257  * @param[in] preconfPINLen Byte length of preconfig PIN\r
258  * @return OC_STACK_OK in case of success and other value otherwise.\r
259  */\r
260 OCStackResult OCAddPreconfigPIN(const OCProvisionDev_t *targetDeviceInfo,\r
261                                  const char* preconfPIN, size_t preconfPINLen);\r
262 \r
263 /**\r
264  * API to update 'doxm.mom' to resource server.\r
265  *\r
266  * @param[in] targetDeviceInfo Selected target device.\r
267  * @param[in] momType Mode of multiple ownership transfer (ref. oic.sec.mom)\r
268  * @param[in] resultCallback callback provided by API user, callback will be called when\r
269  *            POST 'mom' request recieves a response from resource server.\r
270  * @return OC_STACK_OK in case of success and other value otherwise.\r
271  */\r
272 OCStackResult OCChangeMOTMode(void *ctx, const OCProvisionDev_t *targetDeviceInfo,\r
273                             const OicSecMomType_t momType, OCProvisionResultCB resultCallback);\r
274 \r
275 /**\r
276  * API to update 'doxm.oxmsel' to resource server.\r
277  *\r
278  * @param[in] targetDeviceInfo Selected target device.\r
279  * @param[in] oxmSelValue Method of multiple ownership transfer (ref. oic.sec.oxm)\r
280  * @param[in] resultCallback callback provided by API user, callback will be called when\r
281  *            POST 'oxmsel' request recieves a response from resource server.\r
282  * @return OC_STACK_OK in case of success and other value otherwise.\r
283  */\r
284 OCStackResult OCSelectMOTMethod(void *ctx, const OCProvisionDev_t *targetDeviceInfo,\r
285                                  const OicSecOxm_t oxmSelValue, OCProvisionResultCB resultCallback);\r
286 #endif //_ENABLE_MULTIPLE_OWNER_\r
287 \r
288 /**\r
289  * Function to unlink devices.\r
290  * This function will remove the credential & relasionship between the two devices.\r
291  *\r
292  * @param[in] ctx Application context would be returned in result callback\r
293  * @param[in] pTargetDev1 fitst device information to be unlinked.\r
294  * @param[in] pTargetDev2 second device information to be unlinked.\r
295  * @param[in] resultCallback callback provided by API user, callback will be called when\r
296  *            device unlink is finished.\r
297  * @return OC_STACK_OK in case of success and other value otherwise.\r
298  */\r
299 OCStackResult OCUnlinkDevices(void* ctx,\r
300                               const OCProvisionDev_t* pTargetDev1,\r
301                               const OCProvisionDev_t* pTargetDev2,\r
302                               OCProvisionResultCB resultCallback);\r
303 \r
304 /**\r
305  * Function for device revocation\r
306  * This function will remove credential of target device from all devices in subnet.\r
307  *\r
308  * @param[in] ctx Application context would be returned in result callback\r
309  * @param[in] waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device discovery.(seconds)\r
310  * @param[in] pTargetDev Device information to be revoked.\r
311  * @param[in] resultCallback callback provided by API user, callback will be called when\r
312  *            credential revocation is finished.\r
313  * @return OC_STACK_OK in case of success and other value otherwise.\r
314  *         if OC_STACK_OK is returned, the caller of this API should wait for callback.\r
315  *         OC_STACK_CONTINUE means operation is success but no need to wait for callback.\r
316  */\r
317 OCStackResult OCRemoveDevice(void* ctx,\r
318                              unsigned short waitTimeForOwnedDeviceDiscovery,\r
319                              const OCProvisionDev_t* pTargetDev,\r
320                              OCProvisionResultCB resultCallback);\r
321 \r
322 /*\r
323 * Function to device revocation\r
324 * This function will remove credential of target device from all devices in subnet.\r
325 *\r
326 * @param[in] ctx Application context would be returned in result callback\r
327 * @param[in] waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device discovery.(seconds)\r
328 * @param[in] pTargetDev Device information to be revoked.\r
329 * @param[in] resultCallback callback provided by API user, callback will be called when\r
330 *            credential revocation is finished.\r
331  * @return  OC_STACK_OK in case of success and other value otherwise.\r
332 */\r
333 OCStackResult OCRemoveDeviceWithUuid(void* ctx,\r
334                                      unsigned short waitTimeForOwnedDeviceDiscovery,\r
335                                      const OicUuid_t* pTargetUuid,\r
336                                      OCProvisionResultCB resultCallback);\r
337 \r
338 /*\r
339  * Function to reset the target device.\r
340  * This function will remove credential and ACL of target device from all devices in subnet.\r
341  *\r
342  * @param[in] ctx Application context would be returned in result callback\r
343  * @param[in] waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device discovery.(seconds)\r
344  * @param[in] pTargetDev Device information to be revoked.\r
345  * @param[in] resultCallback callback provided by API user, callback will be called when\r
346  *            credential revocation is finished.\r
347  * @return  OC_STACK_OK in case of success and other value otherwise.\r
348  */\r
349 OCStackResult OCResetDevice(void* ctx, unsigned short waitTimeForOwnedDeviceDiscovery,\r
350                             const OCProvisionDev_t* pTargetDev,\r
351                             OCProvisionResultCB resultCallback);\r
352 \r
353 /**\r
354  * API to get status of all the devices in current subnet. The status include endpoint information\r
355  * and doxm information which can be extracted duing owned and unowned discovery. Along with this\r
356  * information. The API will provide information about devices' status\r
357  * Device can have following states\r
358  *  - ON/OFF: Device is switched on or off.\r
359  *\r
360  * NOTE: Caller need to call OCDeleteDiscoveredDevices to delete memory allocated by this API for out\r
361  * variables pOwnedDevList and pUnownedDevList.\r
362  *\r
363  * @param[in] waitime Wait time for the API. The wait time will be divided by 2, and half of wait time\r
364  * will be used for unowned discovery and remaining half for owned discovery. So the wait time should be\r
365  * equal to or more than 2.\r
366  * @param[out] pOwnedDevList  list of owned devices.\r
367  * @param[out] pUnownedDevList  list of unowned devices.\r
368  * @return OC_STACK_OK in case of success and other value otherwise.\r
369  */\r
370 OCStackResult OCGetDevInfoFromNetwork(unsigned short waittime,\r
371                                        OCProvisionDev_t** pOwnedDevList,\r
372                                        OCProvisionDev_t** pUnownedDevList);\r
373 /**\r
374  * This method is used to get linked devices' IDs.\r
375  *\r
376  * @param[in] uuidOfDevice a target device's uuid.\r
377  * @param[out] uuidList information about the list of linked devices' uuids.\r
378  * @param[out] numOfDevices total number of linked devices.\r
379  * @return OC_STACK_OK in case of success and other value otherwise.\r
380  */\r
381 OCStackResult OCGetLinkedStatus(const OicUuid_t* uuidOfDevice,\r
382                                   OCUuidList_t** uuidList,\r
383                                   size_t* numOfDevices);\r
384 \r
385 /**\r
386  * API to delete memory allocated to linked list created by OCDiscover_XXX_Devices API.\r
387  *\r
388  * @param[in] pList Pointer to OCProvisionDev_t which should be deleted.\r
389  */\r
390 void OCDeleteDiscoveredDevices(OCProvisionDev_t *pList);\r
391 \r
392 /**\r
393  * API to delete memory allocated to OicUuid_t list.\r
394  *\r
395  * @param[in] pList Pointer to OicUuid_t list which should be deleted.\r
396  */\r
397 void OCDeleteUuidList(OCUuidList_t* pList);\r
398 \r
399 /**\r
400  * This function deletes ACL data.\r
401  *\r
402  * @param pAcl Pointer to OicSecAcl_t structure.\r
403  */\r
404 void OCDeleteACLList(OicSecAcl_t* pAcl);\r
405 \r
406 /**\r
407  * This function deletes PDACL data.\r
408  *\r
409  * @param pPdAcl Pointer to OicSecPdAcl_t structure.\r
410  */\r
411 void OCDeletePdAclList(OicSecPdAcl_t* pPdAcl);\r
412 \r
413 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)\r
414 /**\r
415  * this function sends CRL information to resource.\r
416  *\r
417  * @param[in] ctx Application context would be returned in result callback.\r
418  * @param[in] selectedDeviceInfo Selected target device.\r
419  * @param[in] crl CRL to provision.\r
420  * @param[in] resultCallback callback provided by API user, callback will be called when provisioning\r
421               request recieves a response from resource server.\r
422  * @return  OC_STACK_OK in case of success and other value otherwise.\r
423  */\r
424 OCStackResult OCProvisionCRL(void* ctx, const OCProvisionDev_t *selectedDeviceInfo, OicSecCrl_t *crl,\r
425                              OCProvisionResultCB resultCallback);\r
426 \r
427 /**\r
428  * function to provision Trust certificate chain to devices.\r
429  *\r
430  * @param[in] ctx Application context would be returned in result callback.\r
431  * @param[in] type Type of credentials to be provisioned to the device.\r
432  * @param[in] credId CredId of trust certificate chain to be provisioned to the device.\r
433  * @param[in] selectedDeviceInfo Pointer to OCProvisionDev_t instance,respresenting resource to be provsioned.\r
434  * @param[in] resultCallback callback provided by API user, callback will be called when\r
435  *            provisioning request recieves a response from first resource server.\r
436  * @return  OC_STACK_OK in case of success and other value otherwise.\r
437  */\r
438 OCStackResult OCProvisionTrustCertChain(void *ctx, OicSecCredType_t type, uint16_t credId,\r
439                                       const OCProvisionDev_t *selectedDeviceInfo,\r
440                                       OCProvisionResultCB resultCallback);\r
441 /**\r
442  * function to save Trust certificate chain into Cred of SVR.\r
443  *\r
444  * @param[in] trustCertChain Trust certificate chain to be saved in Cred of SVR.\r
445  * @param[in] chainSize Size of trust certificate chain to be saved in Cred of SVR\r
446  * @param[in] encodingType Encoding type of trust certificate chain to be saved in Cred of SVR\r
447  * @param[out] credId CredId of saved trust certificate chain in Cred of SVR.\r
448  * @return  OC_STACK_OK in case of success and other value otherwise.\r
449  */\r
450 OCStackResult OCSaveTrustCertChain(uint8_t *trustCertChain, size_t chainSize,\r
451                                         OicEncodingType_t encodingType, uint16_t *credId);\r
452 \r
453 #endif // __WITH_DTLS__ || __WITH_TLS__\r
454 \r
455 \r
456 #ifdef __cplusplus\r
457 }\r
458 #endif // __cplusplus\r
459 \r
460 #endif /* OCPROVISIONINGMANAGER_H_ */\r