security: publish securevirtualresourcetypes.h
[iotivity.git] / resource / csdk / security / provisioning / include / internal / secureresourceprovider.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 SRP_SECURERESOURCEPROVIDER_H
22 #define SRP_SECURERESOURCEPROVIDER_H
23
24 #include "ocstack.h"
25 #include "experimental/securevirtualresourcetypes.h"
26 #include "pmtypes.h"
27 #include "octypes.h"
28
29
30 #ifdef __cplusplus
31 extern "C"
32 {
33 #endif
34
35 /**
36  * API to send ACL information to resource.
37  *
38  * @param[in] ctx Application context to be returned in result callback.
39  * @param[in] selectedDeviceInfo Selected target device.
40  * @param[in] aclVersion Version of the ACL resource to access
41  * @param[in] acl ACL to provision.
42  * @param[in] resultCallback callback provided by API user, callback will be called when
43  *            provisioning request recieves a response from resource server.
44  * @return OC_STACK_OK in case of success and other value otherwise.
45  */
46 OCStackResult SRPProvisionACL(void *ctx, const OCProvisionDev_t *selectedDeviceInfo,
47                                         OicSecAcl_t *acl, OicSecAclVersion_t aclVersion, OCProvisionResultCB resultCallback);
48
49 /**
50  * API to save ACL which has several ACE into Acl of SVR.
51  *
52  * @param acl ACL to be saved in Acl of SVR.
53  * @return  OC_STACK_OK in case of success and other value otherwise.
54  */
55 OCStackResult SRPSaveACL(const OicSecAcl_t *acl);
56
57 /**
58  * API to request CRED information to resource.
59  *
60  * @param[in] ctx Application context to be returned in result callback.
61  * @param[in] selectedDeviceInfo Selected target device.
62  * @param[in] resultCallback callback provided by API user, callback will be called when
63  *            provisioning request recieves a response from resource server.
64  * @return OC_STACK_OK in case of success and other value otherwise.
65  */
66 OCStackResult SRPGetCredResource(void *ctx, const OCProvisionDev_t *selectedDeviceInfo,
67         OCProvisionResultCB resultCallback);
68
69 /**
70  * API to request ACL information to resource.
71  *
72  * @param[in] ctx Application context to be returned in result callback.
73  * @param[in] selectedDeviceInfo Selected target device.
74  * @param[in] aclVersion Version of ACL resource to query
75  * @param[in] resultCallback callback provided by API user, callback will be called when
76  *            provisioning request recieves a response from resource server.
77  * @return OC_STACK_OK in case of success and other value otherwise.
78  */
79 OCStackResult SRPGetACLResource(void *ctx, const OCProvisionDev_t *selectedDeviceInfo,
80         OicSecAclVersion_t aclVersion, OCProvisionResultCB resultCallback);
81
82 /**
83  * API to request the Certificate Signing Request (CSR) resource.
84  *
85  * @param[in] ctx Application context to be returned in result callback.
86  * @param[in] selectedDeviceInfo Selected target device.
87  * @param[in] resultCallback callback provided by API user, callback will be called when
88  *            provisioning request recieves a response from resource server.
89  * @return OC_STACK_OK in case of success and other value otherwise.
90  */
91 OCStackResult SRPGetCSRResource(void *ctx, const OCProvisionDev_t *selectedDeviceInfo,
92                                 OCGetCSRResultCB resultCallback);
93
94 /**
95  * API to request the Roles resource.
96  *
97  * @param[in] ctx Application context to be returned in result callback.
98  * @param[in] selectedDeviceInfo Selected target device.
99  * @param[in] resultCallback Callback provided by API user. Callback will be called when
100  *            provisioning request receives a response from resource server.
101  * @return OC_STACK_OK in case of success or error value otherwise.
102  */
103 OCStackResult SRPGetRolesResource(void *ctx, const OCProvisionDev_t *selectedDeviceInfo,
104                                   OCGetRolesResultCB resultCallback);
105
106 /**
107  * This function requests the device delete a particular role certificate by credId.
108  *
109  * @param[in] ctx Application context that is returned in the result callback.
110  * @param[in] selectedDeviceInfo Selected target device.
111  * @param[in] resultCallback callback provided by the API user. Callback will be called when request receives
112  *            a response from the resource server.
113  * @param[in] credId credId to request be deleted.
114  *
115  * @return OC_STACK_OK in case of success, and error value otherwise.
116  */
117 OCStackResult SRPDeleteRoleCertificateByCredId(void *ctx, const OCProvisionDev_t *selectedDeviceInfo,
118                                                OCProvisionResultCB resultCallback, uint32_t credId);
119
120 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
121
122 /**
123  * function to provision Trust certificate chain to devices.
124  *
125  * @param[in] ctx Application context to be returned in result callback.
126  * @param[in] type Type of credentials to be provisioned to the device.
127  * @param[in] credId CredId of trust certificate chain to be provisioned to the device.
128  * @param[in] selectedDeviceInfo Pointer to OCProvisionDev_t instance,respresenting resource to be provsioned.
129  * @param[in] resultCallback callback provided by API user, callback will be called when
130  *            provisioning request recieves a response from first resource server.
131  * @return  OC_STACK_OK in case of success and other value otherwise.
132  */
133 OCStackResult SRPProvisionTrustCertChain(void *ctx, OicSecCredType_t type, uint16_t credId,
134                                       const OCProvisionDev_t *selectedDeviceInfo,
135                                       OCProvisionResultCB resultCallback);
136
137 /**
138  * function to save Trust certificate chain into Cred of SVR.
139  *
140  * @param[in] trustCertChain Trust certificate chain to be saved in Cred of SVR.
141  * @param[in] chainSize Size of trust certificate chain to be saved in Cred of SVR
142  * @param[in] encodingType Encoding type of trust certificate chain to be saved in Cred of SVR
143  * @param[out] credId CredId of saved trust certificate chain in Cred of SVR.
144  * @return  OC_STACK_OK in case of success and other value otherwise.
145  */
146 OCStackResult SRPSaveTrustCertChain(const uint8_t *trustCertChain, size_t chainSize,
147                                         OicEncodingType_t encodingType,uint16_t *credId);
148
149 /**
150  * function to save own certificate chain into Cred of SVR.
151  *
152  * @param[in] cert own certificate chain to be saved in Cred of SVR.
153  * @param[in] key own secret key to be saved in Cred of SVR.
154  * @param[out] credId CredId of saved trust certificate chain in Cred of SVR.
155  * @return  OC_STACK_OK in case of success and other value otherwise.
156  */
157 OCStackResult SRPSaveOwnCertChain(OicSecKey_t * cert, OicSecKey_t * key, uint16_t *credId);
158
159 /**
160  * function to save own role certificate into Cred of SVR.
161  *
162  * @param[in] cert Certificate chain to be saved in Cred of SVR
163  * @param[out] credId CredId of saved trust certificate chain in Cred of SVR.
164  * @return  OC_STACK_OK in case of success and other value otherwise.
165  *
166  * @note The certificate public key must be the same as public key in the identity
167  *       certificate (installed by SRPSaveOwnCertChain).
168  */
169 OCStackResult SRPSaveOwnRoleCert(OicSecKey_t * cert, uint16_t *credId);
170
171 /**
172  * function to register callback, for getting notification for TrustCertChain change.
173  *
174  * @param[in] ctx user context to be passed.
175  * @param[in] TrustCertChainChangeCB notifier callback function
176  * @return OC_STACK_OK in case of success and other value otherwise.
177  */
178 OCStackResult SRPRegisterTrustCertChainNotifier(void *ctx, TrustCertChainChangeCB callback);
179
180 /**
181  * function to de-register TrustCertChain notification callback.
182  */
183 void SRPRemoveTrustCertChainNotifier(void);
184
185 #endif // __WITH_DTLS__ || __WITH_TLS__
186 /**
187  * API to send Direct-Pairing Configuration to a device.
188  *
189  * @param[in] ctx Application context to be returned in result callback.
190  * @param[in] selectedDeviceInfo Selected target device.
191  * @param[in] pconf PCONF pointer.
192  * @param[in] resultCallback callback provided by API user, callback will be called when
193  *            provisioning request recieves a response from resource server.
194  * @return OC_STACK_OK in case of success and other value otherwise.
195  */
196 OCStackResult SRPProvisionDirectPairing(void *ctx, const OCProvisionDev_t *selectedDeviceInfo,
197                                         OicSecPconf_t *pconf, OCProvisionResultCB resultCallback);
198
199 /**
200  * API to send Direct-Pairing Configuration to a device.
201  *
202  * @param[in] selectedDeviceInfo Selected target device.
203  * @param[in] pconf PCONF pointer.
204  * @param[in] resultCallback callback provided by API user, callback will be called when
205  *            provisioning request recieves a response from resource server.
206  * @return OC_STACK_OK in case of success and other value otherwise.
207  */
208 OCStackResult SRPProvisionDirectPairing(void *ctx, const OCProvisionDev_t *selectedDeviceInfo,
209                                         OicSecPconf_t *pconf, OCProvisionResultCB resultCallback);
210
211 /**
212  * API to provision credential to devices.
213  *
214  * @param[in] ctx Application context to be returned in result callback.
215  * @param[in] type Type of credentials to be provisioned to the device.
216  * @param[in] keySize size of key
217  * @param[in] pDev1 Pointer to PMOwnedDeviceInfo_t instance, representing the resource to be provisioned.
218  * @param[in] pDev2 Pointer to PMOwnedDeviceInfo_t instance, representing the resource to be provisioned.
219  *                  Use NULL to indicate the local device.
220  * @param[in] pemCert When provisioning a certificate (type is SIGNED_ASYMMETRIC_KEY), this is the
221  *                    certificate, encoded as PEM.
222  * @param[in] role1 When provisioning a PSK (type is SYMMETRIC_PAIR_WISE_KEY), this is the role which
223  *                  the device indicated by pDev1 will also have when communicating with pDev2. Use NULL
224  *                  to associate no role with this credential.
225  * @param[in] role2 When provisioning a PSK (type is SYMMETRIC_PAIR_WISE_KEY), this is the role which
226  *                  the device indicated by pDev1 will also have when communicating with pDev2. Use NULL
227  *                  to associate no role with this credential.
228  * @param[in] resultCallback callback provided by API user, callback will be called when
229  *            provisioning request recieves a response from first resource server.
230  * @return OC_STACK_OK in case of success and other value otherwise.
231  */
232 OCStackResult SRPProvisionCredentials(void *ctx,OicSecCredType_t type, size_t keySize,
233                                       const OCProvisionDev_t *pDev1,
234                                       const OCProvisionDev_t *pDev2,
235                                       const char* pemCert,
236                                       const OicSecRole_t *role1,
237                                       const OicSecRole_t *role2,
238                                       OCProvisionResultCB resultCallback);
239  /**
240  * API to provision credential to devices with DOS.
241  *
242  * @param[in] ctx Application context to be returned in result callback.
243  * @param[in] type Type of credentials to be provisioned to the device.
244  * @param[in] keySize size of key
245  * @param[in] pDev1 Pointer to PMOwnedDeviceInfo_t instance, representing the resource to be provisioned.
246  * @param[in] pDev2 Pointer to PMOwnedDeviceInfo_t instance, representing the resource to be provisioned.
247  * @param[in] resultCallback callback provided by API user, callback will be called when
248  *            provisioning request recieves a response from first resource server.
249  * @return OC_STACK_OK in case of success and other value otherwise.
250  */
251 OCStackResult SRPProvisionCredentialsDos(void *ctx,OicSecCredType_t type, size_t keySize,
252                                       const OCProvisionDev_t *pDev1,
253                                       const OCProvisionDev_t *pDev2,
254                                       OCProvisionResultCB resultCallback);
255
256 /**
257  * Function to unlink devices.
258  * This function will remove the credential & relationship between the two devices.
259  *
260  * @param[in] ctx Application context to be returned in result callback
261  * @param[in] pTargetDev1 first device information to be unlinked.
262  * @param[in] pTargetDev2 second device information to be unlinked.
263  * @param[in] resultCallback callback provided by API user, callback will be called when
264  *            device unlink is finished.
265  *            when there is an error, this user callback is called immediately.
266  * @return OC_STACK_OK in case of success and other value otherwise.
267  */
268 OCStackResult SRPUnlinkDevices(void* ctx,
269                               const OCProvisionDev_t* pTargetDev1,
270                               const OCProvisionDev_t* pTargetDev2,
271                               OCProvisionResultCB resultCallback);
272
273 /**
274  * Function to device revocation.
275  * This function will remove credential of target device from all devices in subnet.
276  *
277  * @param[in] ctx Application context to be returned in result callback
278  * @param[in] waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device discovery.(seconds)
279  * @param[in] pTargetDev Device information to be revoked.
280  * @param[in] resultCallback callback provided by API user, callback will be called when
281  *            credential revocation is finished.
282  *            when there is an error, this user callback is called immediately.
283  * @return OC_STACK_OK in case of success and other value otherwise.
284  *         If OC_STACK_OK is returned, the caller of this API should wait for callback.
285  *         OC_STACK_CONTINUE means operation is success but no request is need to be initiated.
286  */
287 OCStackResult SRPRemoveDevice(void* ctx,
288                               unsigned short waitTimeForOwnedDeviceDiscovery,
289                               const OCProvisionDev_t* pTargetDev,
290                               OCProvisionResultCB resultCallback);
291
292 /**
293  * Function to device revocation
294  * This function will remove credential of target device from all devices in subnet.
295  *
296  * @param[in] ctx Application context to be returned in result callback
297  * @param[in] pOwnedDevList List of owned devices
298  * @param[in] pTargetDev Device information to be revoked.
299  * @param[in] resultCallback callback provided by API user, callback will be called when
300  *            credential revocation is finished.
301  * @return  OC_STACK_OK in case of success and other value otherwise.
302  *          If OC_STACK_OK is returned, the caller of this API should wait for callback.
303  *          OC_STACK_CONTINUE means operation is success but no request is need to be initiated.
304  */
305 OCStackResult SRPRemoveDeviceWithoutDiscovery(void* ctx, const OCProvisionDev_t* pOwnedDevList,
306                              const OCProvisionDev_t* pTargetDev, OCProvisionResultCB resultCallback);
307
308 /**
309  * Function to sync-up credential and ACL of the target device.
310  * This function will remove credential and ACL of target device from all devices in subnet.
311  *
312  * @param[in] ctx Application context to be returned in result callback
313  * @param[in] waitTimeForOwnedDeviceDiscovery Maximum wait time for owned device discovery.(seconds)
314  * @param[in] pTargetDev Device information to be revoked.
315  * @param[in] resultCallback callback provided by API user, callback will be called when
316  *            credential revocation is finished.
317  *            when there is an error, this user callback is called immediately.
318  * @return OC_STACK_OK in case of success and other value otherwise.
319  *         If OC_STACK_OK is returned, the caller of this API should wait for callback.
320  *         OC_STACK_CONTINUE means operation is success but no request is need to be initiated.
321  */
322 OCStackResult SRPSyncDevice(void* ctx, unsigned short waitTimeForOwnedDeviceDiscovery,
323                          const OCProvisionDev_t* pTargetDev, OCProvisionResultCB resultCallback);
324
325 /**
326  * Function for remote reset
327  * This function will send pstat POST(modify) message to the target device
328  * to change current mode to reset state in order to initiate remote reset.
329  *
330  * @param[in] pTargetDev Device information to be revoked.
331  * @param[in] resultCallback callback provided by API user, callback will be called when
332  *            credential revocation is finished.
333  *            when there is an error, this user callback is called immediately.
334  * @return OC_STACK_OK in case of success and other value otherwise.
335  *         If OC_STACK_OK is returned, the caller of this API should wait for callback.
336  *         OC_STACK_CONTINUE means operation is success but no request is need to be initiated.
337  */
338 OCStackResult SRPResetDevice(const OCProvisionDev_t* pTargetDev,
339         OCProvisionResultCB resultCallback);
340
341 /**
342  * Function to read Trust certificate chain from SVR.
343  * Caller must free when done using the returned trust certificate
344  * @param[in] credId CredId of trust certificate chain in SVR.
345  * @param[out] trustCertChain Trust certificate chain.
346  * @param[out] chainSize Size of trust certificate chain
347  * @return  OC_STACK_OK in case of success and other value otherwise.
348  */
349 OCStackResult SRPReadTrustCertChain(uint16_t credId, uint8_t **trustCertChain,
350                                      size_t *chainSize);
351 #ifdef __cplusplus
352 }
353 #endif
354 #endif //SRP_SECURERESOURCEPROVIDER_H