Merge branch '1.3-rel' (5fdb8a1)
[iotivity.git] / resource / csdk / security / include / experimental / doxmresource.h
1 //******************************************************************
2 //
3 // Copyright 2015 Intel Mobile Communications GmbH 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 IOTVT_SRM_DOXM_H
22 #define IOTVT_SRM_DOXM_H
23
24 #include "octypes.h"
25 #ifdef MULTIPLE_OWNER
26 #include "cacommon.h"
27 #endif //MULTIPLE_OWNER
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 // NOTE that this enum must match the gDoxmPropertyAccessModes
34 // table in doxmresource.c
35 typedef enum {
36     DOXM_OXMS = 1,
37     DOXM_OXMSEL,
38     DOXM_SCT,
39     DOXM_OWNED,
40 #ifdef MULTIPLE_OWNER
41     DOXM_SUBOWNER,
42     DOXM_MOM,
43 #endif // MULTIPLE_OWNER
44     DOXM_DEVICEUUID,
45     DOXM_DEVOWNERUUID,
46     DOXM_ROWNERUUID,
47     DOXM_PROPERTY_COUNT
48 } DoxmProperty_t;
49
50 /**
51  * Initialize DOXM resource by loading data from persistent storage.
52  *
53  * @return ::OC_STACK_OK for Success, otherwise some error value.
54  */
55 OCStackResult InitDoxmResource();
56
57 /**
58  * Perform cleanup for DOXM resources.
59  *
60  * @return ::OC_STACK_OK for Success, otherwise some error value.
61  */
62 OCStackResult DeInitDoxmResource();
63
64 /**
65  * This method is used by SRM to retrieve DOXM resource data.
66  *
67  * @return reference to @ref OicSecDoxm_t, binary format of Doxm resource data.
68  */
69 const OicSecDoxm_t* GetDoxmResourceData();
70
71 /**
72  * This method converts CBOR DOXM into binary DOXM.
73  * The CBOR DOXM can be from persistent database or
74  * or received as PUT/POST request.
75  *
76  * @param cborPayload is a doxm data in cbor.
77  * @note Caller needs to invoke OCFree after done using the return pointer.
78  * @param doxm is the pointer to @ref OicSecDoxm_t.
79  * @param size of the cborPayload. In case value is 0, CBOR_SIZE value is assigned.
80  *
81  * @return ::OC_STACK_OK for Success, otherwise some error value.
82  */
83 OCStackResult CBORPayloadToDoxm(const uint8_t *cborPayload, size_t size,
84                                 OicSecDoxm_t **doxm);
85
86 /**
87  * Converts DOXM into CBOR payload, including only the
88  * Properties marked "true" in the propertiesToInclude array.
89  *
90  * @param doxm pointer to the initialized doxm structure.
91  * @param payload pointer to doxm cbor payload.
92  * @param size of the cbor payload converted. It is 0 in case of error,
93  *     else a positive value if succcessful.
94  * @param propertiesToInclude Array of bools, size "DOXM_PROPERTY_COUNT",
95  *     where "true" indicates the corresponding property should be
96  *     included in the CBOR representation that is created.
97  *
98  * @return ::OC_STACK_OK for Success, otherwise some error value.
99  */
100  OCStackResult DoxmToCBORPayloadPartial(const OicSecDoxm_t *doxm,
101         uint8_t **payload, size_t *size, const bool *propertiesToInclude);
102
103
104 /**
105  * Converts DOXM into cbor payload, including all Properties for a
106  * full representation.
107  *
108  * @param doxm pointer to the initialized doxm structure.
109  * @param payload pointer to doxm cbor payload.
110  * @param size of the cbor payload converted. It is 0 in case of error,
111  *     else a positive value if succcessful.
112  *
113  * @return ::OC_STACK_OK for Success, otherwise some error value.
114  */
115 OCStackResult DoxmToCBORPayload(const OicSecDoxm_t *doxm,
116         uint8_t **payload, size_t *size);
117
118 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
119 /**
120  * Enables Anon DH ciphersuite if device unowned and Just Works OTM is selected.
121  * Otherwise, does nothing.
122  *
123  * @param[out] enabled TRUE if Anon DH ciphersuite enabled, else FALSE
124  *
125  * @retval  ::OC_STACK_OK No errors.
126  * @retval  ::OC_STACK_ERROR An error occured.
127  */
128 OCStackResult EnableAnonCipherSuiteIfUnOwnedAndJustWorksSelected(bool *enabled);
129 #endif // __WITH_DTLS__ or __WITH_TLS__
130
131 #if defined(__WITH_DTLS__) || defined (__WITH_TLS__)
132 /**
133  * API to save the seed value to generate device UUID.
134  *
135  * @param seed buffer of seed value.
136  * @param seedSize byte length of seed
137  *
138  * @return ::OC_STACK_OK for Success, otherwise some error value.
139  */
140 OCStackResult SetDoxmDeviceIDSeed(const uint8_t* seed, size_t seedSize);
141 #endif
142
143 /**
144  * Get the doxm.deviceuuid value for this device.
145  *
146  * @param[out] deviceuuid ptr to contain a copy of doxm.deviceuuid value.
147  * @return ::OC_STACK_OK if value is copied successfully, else ::OC_STACK_ERROR.
148  */
149 OCStackResult GetDoxmDeviceID(OicUuid_t *deviceuuid);
150
151 /**
152  * Set the doxm.deviceuuid value for this device.
153  *
154  * @param[in] deviceuuid ptr to value to be copied into doxm.deviceuuid.
155  * @return ::OC_STACK_OK if value is copied successfully, else ::OC_STACK_ERROR.
156  */
157 OCStackResult SetDoxmDeviceID(const OicUuid_t *deviceuuid);
158
159 /**
160  * Get the doxm.devowneruuid value for this device.
161  *
162  * @param[out] devowneruuid ptr to contain a copy of doxm.devowneruuid value.
163  * @return ::OC_STACK_OK if value is copied successfully, else ::OC_STACK_ERROR.
164  */
165 OCStackResult GetDoxmDevOwnerId(OicUuid_t *devowneruuid);
166
167 /**
168  * Set the doxm.deviceuuid value for this device.
169  *
170  * @param[in] deviceuuid ptr to value to be copied into doxm.deviceuuid.
171  * @return ::OC_STACK_OK if value is copied successfully, else ::OC_STACK_ERROR.
172  */
173 OCStackResult SetDoxmDevOwnerId(const OicUuid_t *devowneruuid);
174
175 /**
176  * Get the doxm.isowned value for this device.
177  *
178  * @param[out] isowned ptr to contain a copy of doxm.isowned value.
179  * @return ::OC_STACK_OK if value is copied successfully, else ::OC_STACK_ERROR.
180  */
181 OCStackResult GetDoxmIsOwned(bool *isowned);
182
183 /**
184  * Set the doxm.isowned value for this device.
185  *
186  * @param[in] isowned ptr to value to be copied into doxm.isowned.
187  * @return ::OC_STACK_OK if value is copied successfully, else ::OC_STACK_ERROR.
188  */
189 OCStackResult SetDoxmIsOwned(const bool isowned);
190
191 /**
192  * Get the doxm.rowneruuid value for this device.
193  *
194  * @param[out] rowneruuid ptr to contain a copy of rowneruuid value.
195  * @return ::OC_STACK_OK if value is copied successfully, else ::OC_STACK_ERROR.
196  */
197 OCStackResult GetDoxmRownerId(OicUuid_t *rowneruuid);
198
199 /**
200  * Set the doxm.rowneruuid value for this device.
201  *
202  * @param[in] rowneruuid ptr to value to be copied into doxm.rowneruuid.
203  * @return ::OC_STACK_OK if value is copied successfully, else ::OC_STACK_ERROR.
204  */
205 OCStackResult SetDoxmRownerId(const OicUuid_t *rowneruuid);
206
207 #ifdef MULTIPLE_OWNER
208 /**
209  * Compare the UUID to SubOwner.
210  *
211  * @param[in] uuid device UUID
212  *
213  * @return true if uuid exists in the SubOwner list of doxm, else false.
214  */
215 bool IsSubOwner(const OicUuid_t* uuid);
216
217 /**
218  * Function to set a MOT status
219  *
220  * @param enable whether the MOT is enabled. (true=enable, false=disable)
221  */
222 OCStackResult SetMOTStatus(bool enable);
223
224 #endif //MULTIPLE_OWNER
225
226 /** This function deallocates the memory for OicSecDoxm_t .
227  *
228  * @param doxm is the pointer to @ref OicSecDoxm_t.
229  */
230 void DeleteDoxmBinData(OicSecDoxm_t* doxm);
231
232 /** This function checks if two sets of /oic/sec/doxm properties are identical.
233  *
234  * @param doxm1 is a pointer to the first @ref OicSecDoxm_t data.
235  * @param doxm2 is a pointer to the second @ref OicSecDoxm_t data.
236  *
237  * @return true if all of the properties are identical, else false.
238  */
239 bool AreDoxmBinPropertyValuesEqual(OicSecDoxm_t* doxm1, OicSecDoxm_t* doxm2);
240
241 #if defined(__WITH_DTLS__) && defined(MULTIPLE_OWNER)
242 /**
243  * Callback function to handle MOT DTLS handshake result.
244  * @param[out]   object           remote device information.
245  * @param[out]   errorInfo        CA Error information.
246  */
247 CAResult_t MultipleOwnerDTLSHandshakeCB(const CAEndpoint_t *object,
248                                         const CAErrorInfo_t *errorInfo);
249 #endif //__WITH_DTLS__ && MULTIPLE_OWNER
250
251 /**
252  * Internal function to change doxm resource to Ready for Normal Operation.
253  *
254  * @param newROwner new owner
255  *
256  * @retval ::OC_STACK_OK for Success, otherwise some error value
257  */
258 OCStackResult SetDoxmSelfOwnership(const OicUuid_t* newROwner);
259
260 /**
261  * Internal function to update the writable properties of an /oic/sec/doxm
262  * struct with the values from another /oic/sec/doxm struct.
263  *
264  * @param src is a pointer to the source @ref OicSecDoxm_t data.
265  * @param dst is a pointer to the destination @ref OicSecDoxm_t data.
266  *
267  * @retval ::OC_STACK_OK for Success, otherwise some error value
268  */
269 OCStackResult DoxmUpdateWriteableProperty(const OicSecDoxm_t* src, OicSecDoxm_t* dst);
270
271 #ifdef __cplusplus
272 }
273 #endif
274
275 #endif //IOTVT_SRM_DOXMR_H