resource-container: Install unit tests
[iotivity.git] / resource / csdk / security / include / srmutility.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_UTILITY_H
22 #define IOTVT_SRM_UTILITY_H
23
24 #include "ocstack.h"
25 #include "experimental/securevirtualresourcetypes.h"
26 #ifdef __cplusplus
27 extern "C"
28 {
29 #endif
30 #include <coap/uri.h>
31 #ifdef __cplusplus
32 }
33 #endif
34
35 #ifdef __cplusplus
36 extern "C" {
37 #endif // __cplusplus
38
39 typedef struct OicParseQueryIter OicParseQueryIter_t;
40
41 /**
42  * OicRestQueryIter data structure is used for book-keeping
43  * sub-REST query's attribute's and value's, starting location &
44  * length between calls to GetNextQuery(). This struct needs
45  * to be first initialized with ParseQueryIterInit().
46  *
47  */
48 struct OicParseQueryIter
49 {
50     unsigned char * attrPos;    /**< stating location of attribute. */
51     size_t attrLen;             /**< length of the attribute. */
52     unsigned char * valPos;     /**< starting location of value. */
53     size_t valLen;              /**< length of the value. */
54     coap_parse_iterator_t pi;   /**< coap struct for tokenizing the query.*/
55 };
56
57 /**
58  * Macro to verify success of operation.
59  * eg: VERIFY_SUCCESS(TAG, OC_STACK_OK == foo(), ERROR);
60  * @note Invoking function must define "exit:" label for goto functionality to work correctly.
61  */
62 #ifndef VERIFY_SUCCESS
63 #define VERIFY_SUCCESS(tag, op, logLevel) do{ if (!(op)) \
64             {OIC_LOG((logLevel), tag, #op " failed!!"); goto exit; } }while(0)
65 #endif
66
67 /**
68  * Macro to verify a conditional, if fails, log supplied message and goto exit
69  * eg: VERIFY_SUCCESS_OR_LOG_AND_EXIT(TAG, OC_STACK_OK == foo(), ERROR);
70  * @note Invoking function must define "exit:" label for goto functionality to work correctly.
71  */
72 #define VERIFY_OR_LOG_AND_EXIT(tag, op, msg, logLevel) do{ if (!(op)) \
73             {OIC_LOG((logLevel), tag, msg); goto exit; } }while(0)
74
75 /**
76  * Macro to verify expression evaluates to bool true.
77  * eg: VERIFY_TRUE_OR_EXIT(TAG, OC_STACK_OK == foo(), ERROR);
78  * @note Invoking function must define "exit:" label for goto functionality to work correctly.
79  */
80 #ifndef VERIFY_TRUE_OR_EXIT
81 #define VERIFY_TRUE_OR_EXIT(tag, op, logLevel) do{ if (!(op)) \
82             {OIC_LOG_V((logLevel), tag, "%s:" #op "evaluates to false!",__func__); \
83             goto exit; } }while(0)
84 #endif
85
86 /**
87  * Macro to verify success of operation.
88  * eg: VERIFY_SUCCESS_RETURN(TAG, OC_STACK_OK == foo(), ERROR, OC_STACK_ERROR);
89  */
90 #ifndef VERIFY_SUCCESS_RETURN
91 #define VERIFY_SUCCESS_RETURN(tag, op, logLevel, retValue) do { if (!(op)) \
92             {OIC_LOG((logLevel), tag, #op " failed!!"); return retValue;} } while(0)
93 #endif
94
95 /**
96  * Macro to verify argument is not equal to NULL.
97  * eg: VERIFY_NOT_NULL(TAG, ptrData, ERROR);
98  * @note Invoking function must define "exit:" label for goto functionality to work correctly.
99  */
100 #ifndef VERIFY_NOT_NULL
101 #define VERIFY_NOT_NULL(tag, arg, logLevel) do{ if (NULL == (arg)) \
102             { OIC_LOG((logLevel), tag, #arg " is NULL"); goto exit; } }while(0)
103 #endif
104
105 /**
106  * Macro to verify argument is not equal to NULL.
107  * eg: VERIFY_NOT_NULL_RETURN(TAG, ptrData, ERROR, OC_STACK_ERROR);
108  */
109 #ifndef VERIFY_NOT_NULL_RETURN
110 #define VERIFY_NOT_NULL_RETURN(tag, arg, logLevel, retValue) do { if (NULL == (arg)) \
111             { OIC_LOG((logLevel), tag, #arg " is NULL"); return retValue; } } while(0)
112 #endif
113
114 /**
115  * Macro to log an mbedtls error
116  * For mbedtls functions that return 0 as non-error
117  * @note Invoker must provide message buffer, and must include "mbedtls/error.h"
118  */
119 #define LOG_MBED_ERROR(tag, ret, buf, bufSize, logLevel) do{ if (0!=(ret)) { \
120     mbedtls_strerror((ret), (buf), (bufSize));                               \
121     OIC_LOG_V((logLevel), (tag), "mbedtls error:  %s", (buf)); } }while(0)
122
123 /**
124  * This method initializes the @ref OicParseQueryIter_t struct.
125  *
126  * @param query is the REST query, to be parsed.
127  * @param parseIter is the @ref OicParseQueryIter_t struct, to be initialized based on the query.
128  */
129 void ParseQueryIterInit(const unsigned char * query, OicParseQueryIter_t * parseIter);
130
131 /**
132  * This method fills the @ref OicParseQueryIter_t struct with next REST query's
133  * attribute's and value's information.
134  *
135  * @param parseIter is the @ref OicParseQueryIter_t struct, has next query's attribute's
136  *  & value's info.
137  *
138  * @return reference to the @ref OicParseQueryIter_t if it has parsed query info, else
139  * NULL if it has no query to parse.
140  */
141 OicParseQueryIter_t * GetNextQuery(OicParseQueryIter_t * parseIter);
142
143 /**
144  * Function to getting string of ownership transfer method
145  *
146  * @param oxmType ownership transfer method
147  *
148  * @return string value of ownership transfer method
149  */
150 const char* GetOxmString(OicSecOxm_t oxmType);
151
152 /**
153  * This method converts UUID to canonical format string.
154  *
155  * @param uuid Device UUID
156  * @param strUuid converted UUID in canonical format
157  * @return OC_STACK_OK for success.
158  *
159  * @note Caller needs to invoke OICFree after done using the return pointer
160  */
161 OCStackResult ConvertUuidToStr(const OicUuid_t* uuid, char** strUuid);
162
163
164 /**
165  * This method converts string UUID to OicUuid_t.
166  *
167  * @param strUuid Device UUID in string format
168  * @param uuid converted UUID in OicUuid_t format
169  * @return OC_STACK_OK for success.
170  *
171  */
172 OCStackResult OC_CALL ConvertStrToUuid(const char* strUuid, OicUuid_t* uuid);
173
174 /**
175  * Is the URI for a Device Configuration Resource as defined
176  * by Security Specification.
177  *
178  * @return true IFF the uri is for a DCR
179  */
180 bool IsDeviceConfigurationResourceUri(const char *uri);
181
182 /**
183  * Is the URI for a Non0Configuration Resource as defined
184  * by Security Specification.
185  *
186  * @return true IFF the uri is for a NCR
187  */
188 bool IsNonConfigurationResourceUri(const char *uri);
189
190 /**
191  * Compares two OicUuid_t structs.
192  *
193  * @return true if the two OicUuid_t structs are equal, else false.
194  */
195 bool UuidCmp(const OicUuid_t *firstId, const OicUuid_t *secondId);
196
197 extern const OicUuid_t THE_NIL_UUID;
198
199 /**
200  * OicUuid_t to Nil UUID {.id={0000000000000000}}
201  *
202  * @return true if the OicUuid_t is the Nil UUID
203  */
204 bool IsNilUuid(const OicUuid_t *uuid);
205
206 #if defined(__WITH_DTLS__) || defined (__WITH_TLS__)
207 /**
208  * API to save the seed value to generate device UUID.
209  * Seed value MUST be unique per device (e.g. MAC address)
210  *
211  * @param seed buffer of seed value.
212  * @param seedSize byte length of seed
213  *
214  * @return ::OC_STACK_OK for Success, otherwise some error value.
215  */
216 OCStackResult OC_CALL SetDeviceIdSeed(const uint8_t* seed, size_t seedSize);
217 #endif
218
219 /**
220  * Is the URI for a Security Virtual Resource as defined
221  * by Security Specification.
222  *
223  * @return true IFF the uri is for a SVR
224  */
225 bool SRMIsSecurityResourceURI(const char* uri);
226
227 /**
228  * Log OicUuid_t structs.
229  */
230 void LogUuid(const OicUuid_t* uuid);
231
232 #ifdef __cplusplus
233 }
234 #endif // __cplusplus
235
236 #endif //IOTVT_SRM_UTILITY_H