security: publish securevirtualresourcetypes.h
[iotivity.git] / resource / csdk / security / include / pinoxmcommon.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 PIN_CALLBACK_DEF_H_
22 #define PIN_CALLBACK_DEF_H_
23
24 #include "experimental/securevirtualresourcetypes.h"
25 #include "casecurityinterface.h"
26
27 #ifdef __cplusplus
28  extern "C" {
29 #endif // __cplusplus
30
31 #define OXM_RANDOM_PIN_DEFAULT_SIZE (8)
32 #define OXM_RANDOM_PIN_DEFAULT_PIN_TYPE (NUM_PIN | LOWERCASE_CHAR_PIN | UPPERCASE_CHAR_PIN)
33 #define OXM_RANDOM_PIN_MIN_SIZE (4)
34 #define OXM_RANDOM_PIN_MAX_SIZE (32)
35 #define OXM_PRECONFIG_PIN_MAX_SIZE (OXM_RANDOM_PIN_MAX_SIZE)
36
37 /** Number of PIN type */
38 #define OXM_PIN_TYPE_COUNT 3
39
40 /**
41  * PIN type definition.
42  * This type supports multiple bit set.
43  * e.g.) NUM_PIN | UPPERCASE_CHAR_PIN
44  */
45 typedef enum OicSecPinType{
46     NUM_PIN            = (0x1 << 0),    //Numeric PIN
47     UPPERCASE_CHAR_PIN = (0x1 << 1),    //uppercase character PIN
48     LOWERCASE_CHAR_PIN = (0x1 << 2)     //lowercase character PIN
49 }OicSecPinType_t;
50
51 /**
52  * Function pointer to display pin code.
53  */
54 typedef void (OC_CALL *GeneratePinCallback)(char* pinData, size_t pinSize);
55
56 /**
57  * Function pointer to display pin code, with context.
58  */
59 typedef void(OC_CALL *DisplayPinCallbackWithContext)(char* pinData, size_t pinSize, void* context);
60
61 /**
62  * Function pointer to close the displied PIN.
63  */
64 typedef void (OC_CALL *ClosePinDisplayCallback)(void);
65
66 /**
67  * Function pointer to input pin code.
68  */
69 typedef void (OC_CALL *InputPinCallback)(char* pinBuf, size_t bufSize);
70
71 /**
72  * Function pointer to input pin code, with context and device information.
73  */
74 typedef void(OC_CALL *InputPinCallbackWithContext)(OicUuid_t deviceId, char* pinBuffer, size_t pinBufferSize, void* context);
75
76 /**
77  * Function to set the display PIN callback from the user.
78  *
79  * @deprecated Use SetDisplayPinWithContextCB instead.
80  *
81  * @param pinCB implementation of generate PIN callback.
82  */
83 void OC_CALL SetGeneratePinCB(GeneratePinCallback pinCB);
84
85 /**
86  * Function to set the display PIN callback from the user with context.
87  *
88  * @param displayPinCB  implementation of display PIN callback.
89  * @param context       context to return in the callback.
90  *
91  * @return OC_STACK_OK in case of success or other value in case of error.
92  *         OC_STACK_INVALID_PARAM if pinCB is invalid.
93  *         OC_STACK_DUPLICATE_REQUEST if a display pin callback has already been set.
94  */
95 OCStackResult OC_CALL SetDisplayPinWithContextCB(DisplayPinCallbackWithContext displayPinCB, void* context);
96
97 /**
98  * Function to set the input PIN callback from the user.
99  *
100  * @deprecated Use SetInputPinWithContextCB instead.
101  *
102  * @param pinCB implementation of input PIN callback.
103  */
104 void OC_CALL SetInputPinCB(InputPinCallback pinCB);
105
106 /**
107  * Function to set the input PIN callback from the user with context.
108  *
109  * @param inputPinCB  implementation of input PIN callback.
110  * @param context     context to return in the callback.
111  *
112  * @return OC_STACK_OK in case of success or other value in case of error.
113  *         OC_STACK_INVALID_PARAM if pinCB is invalid.
114  *         OC_STACK_DUPLICATE_REQUEST if an input pin callback has already been set.
115  */
116 OCStackResult OC_CALL SetInputPinWithContextCB(InputPinCallbackWithContext inputPinCB, void* context);
117
118 /**
119  * Function to set the close PIN callback
120  * This callback will be invoked when PIN based OTM is finished.
121  *
122  * @param closeCB implementation of close PIN callback.
123  */
124 void OC_CALL SetClosePinDisplayCB(ClosePinDisplayCallback closeCB);
125
126 /**
127  * Function to unset the input PIN callback.
128  * NOTE : Do not call this function while PIN based ownership transfer is in progress.
129  *
130  * @deprecated Use UnsetInputPinWithContextCB instead.
131  *
132  */
133 void OC_CALL UnsetInputPinCB();
134
135 /**
136  * Function to unset the input PIN callback.
137  * NOTE : Do not call this function while PIN based ownership transfer is in progress.
138  */
139 void OC_CALL UnsetInputPinWithContextCB();
140
141 /**
142  * Function to unset the PIN generation callback.
143  * NOTE : Do not call this function while PIN based ownership transfer is in progress.
144  *
145  * @deprecated Use UnsetDisplayPinWithContextCB instead.
146  *
147  */
148 void OC_CALL UnsetGeneratePinCB();
149
150 /**
151  * Function to unset the PIN display callback.
152  * NOTE : Do not call this function while PIN based ownership transfer is in progress.
153  */
154 void OC_CALL UnsetDisplayPinWithContextCB();
155
156 /**
157  * Function to unset the PIN close callback.
158  * NOTE : Do not call this function while PIN based ownership transfer is in progress.
159  */
160 void OC_CALL UnsetClosePinCB();
161
162 /**
163  * Function to generate a random PIN.
164  * This function will send a generated PIN to the user via the callback that was set in
165  * SetGeneratePinCB or SetGeneratePinWithContextCB.
166  *
167  * @param pinBuffer is the reference to the buffer to store the generated PIN data.
168  * @param bufferSize is the size of buffer.
169  *
170  * @return ::OC_STACK_OK in case of success or other value in case of error.
171  */
172 OCStackResult OC_CALL GeneratePin(char* pinBuffer, size_t bufferSize);
173
174 /**
175  * Function to get a pin for a device.
176  * This function will acquire a pin from the user via the callback that was set in
177  * SetInputPinCB or SetInputPinWithContextCB.
178  *
179  * @param[in] deviceId is the device that is requesting a pin
180  * @param[in,out] pinBuffer is the reference to the buffer to store the inputed PIN data.
181  * @param[in] bufferSize is the size of buffer.
182  *
183  * @return ::OC_STACK_OK in case of success or other value in ccase of error.
184  */
185 OCStackResult InputPin(OicUuid_t deviceId, char* pinBuffer, size_t bufferSize);
186
187 /**
188  * Function to invoke the callback for close a PIN display.
189  */
190 void ClosePinDisplay();
191
192
193 #ifdef MULTIPLE_OWNER
194 /**
195  * Function to save the Pre-configured PIN.
196  *
197  * @param[in] pinBuffer PIN data
198  * @param[in] pinLength byte length of PIN
199  *
200  * @return ::OC_STACK_SUCCESS in case of success or other value in ccase of error.
201  */
202 OCStackResult OC_CALL SetPreconfigPin(const char *pinBuffer, size_t pinLength);
203 #endif
204
205 /**
206  * Function to set the policy for random PIN generation
207  *
208  * @param[in] pinSize Byte length of random PIN
209  * @param[in] pinType Type of random PIN (ref OicSecPinType)
210  *
211  * @return ::OC_STACK_OK in case of success or other value in case of error.
212  */
213 OCStackResult OC_CALL SetRandomPinPolicy(size_t pinSize, OicSecPinType_t pinType);
214
215 #ifdef __WITH_DTLS__
216
217 /**
218  * This function is used by OTM and SRM to
219  * register device UUID is required to derive the temporal PSK.
220  */
221 void SetUuidForPinBasedOxm(const OicUuid_t* uuid);
222
223 /**
224  * This internal callback is used while Random PIN based OTM.
225  * This callback will be used to establish a temporary secure session according to
226  * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256.
227  *
228  * @param[in]  type type of PSK data required by tinyDTLS layer during DTLS handshake.
229  * @param[in]  UNUSED1 UNUSED.
230  * @param[in]  UNUSED2 UNUSED.
231  * @param[out] result  Must be filled with the requested information.
232  * @param[in]  result_length  Maximum size of @p result.
233  *
234  * @return The number of bytes written to @p result or a value
235  *         less than zero on error.
236  */
237 int32_t GetDtlsPskForRandomPinOxm( CADtlsPskCredType_t type,
238               const unsigned char *UNUSED1, size_t UNUSED2,
239               unsigned char *result, size_t result_length);
240
241 #ifdef MULTIPLE_OWNER
242 /**
243  * This internal callback is used while Random PIN based MOT.
244  * This callback will be used to establish a temporary secure session according to
245  * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256.
246  *
247  * @param[in]  type type of PSK data required by tinyDTLS layer during DTLS handshake.
248  * @param[in]  UNUSED1 UNUSED.
249  * @param[in]  UNUSED2 UNUSED.
250  * @param[out] result  Must be filled with the requested information.
251  * @param[in]  result_length  Maximum size of @p result.
252  *
253  * @return The number of bytes written to @p result or a value
254  *         less than zero on error.
255  */
256 int32_t GetDtlsPskForMotRandomPinOxm( CADtlsPskCredType_t type,
257               const unsigned char *UNUSED1, size_t UNUSED2,
258               unsigned char *result, size_t result_length);
259
260
261 /**
262  * This internal callback is used while Preconfigured-PIN OTM.
263  * This callback will be used to establish a temporary secure session according to
264  * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256.
265  *
266  * @param[in]  type type of PSK data required by tinyDTLS layer during DTLS handshake.
267  * @param[in]  UNUSED1 UNUSED.
268  * @param[in]  UNUSED2 UNUSED.
269  * @param[out] result  Must be filled with the requested information.
270  * @param[in]  result_length  Maximum size of @p result.
271  *
272  * @return The number of bytes written to @p result or a value
273  *         less than zero on error.
274  */
275 int32_t GetDtlsPskForPreconfPinOxm( CADtlsPskCredType_t type,
276               const unsigned char *UNUSED1, size_t UNUSED2,
277               unsigned char *result, size_t result_length);
278
279
280 /**
281  * This internal callback is used while Preconfigured-PIN MOT.
282  * This callback will be used to establish a temporary secure session according to
283  * TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256.
284  *
285  * @param[in]  type type of PSK data required by tinyDTLS layer during DTLS handshake.
286  * @param[in]  UNUSED1 UNUSED.
287  * @param[in]  UNUSED2 UNUSED.
288  * @param[out] result  Must be filled with the requested information.
289  * @param[in]  result_length  Maximum size of @p result.
290  *
291  * @return The number of bytes written to @p result or a value
292  *         less than zero on error.
293  */
294 int32_t GetDtlsPskForMotPreconfPinOxm( CADtlsPskCredType_t type,
295               const unsigned char *UNUSED1, size_t UNUSED2,
296               unsigned char *result, size_t result_length);
297
298 #endif //MULTIPLE_OWNER
299
300
301 /**
302  * API to derive the PSK based on PIN and new device's UUID.
303  * New device's UUID should be set through SetUuidForPinBasedOxm() API before this API is invoked.
304  *
305  * @param[out] result generated PSK
306  *
307  * @return 0 for success, otherwise error.
308  */
309 int DerivePSKUsingPIN(uint8_t* result);
310
311 #endif //__WITH_DTLS__
312
313 #ifdef __cplusplus
314 }
315 #endif
316
317 #endif //PIN_CALLBACK_DEF_H_