Merge branch 'master' into simulator
[iotivity.git] / resource / csdk / connectivity / api / cainterface.h
1 /* ****************************************************************
2  *
3  * Copyright 2014 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 /**
22  * @file
23  *
24  * This file contains the APIs for Resource Model to use.
25  */
26
27 #ifndef CA_INTERFACE_H_
28 #define CA_INTERFACE_H_
29
30 /**
31  * Connectivity Abstraction Interface APIs.
32  */
33 #include "cacommon.h"
34
35 #ifdef __WITH_DTLS__
36 #include "ocsecurityconfig.h"
37 #endif
38
39 #ifdef __cplusplus
40 extern "C"
41 {
42 #endif
43
44 /**
45  * Callback function type for request delivery.
46  * @param[out]   object       Endpoint object from which the request is received.
47  *                            It contains endpoint address based on the connectivity type.
48  * @param[out]   requestInfo  Info for resource model to understand about the request.
49  */
50 typedef void (*CARequestCallback)(const CAEndpoint_t *object,
51                                   const CARequestInfo_t *requestInfo);
52
53 /**
54  * Callback function type for response delivery.
55  * @param[out]   object           Endpoint object from which the response is received.
56  * @param[out]   responseInfo     Identifier which needs to be mapped with response.
57  */
58 typedef void (*CAResponseCallback)(const CAEndpoint_t *object,
59                                    const CAResponseInfo_t *responseInfo);
60 /**
61  * Callback function type for error.
62  * @param[out]   object           remote device information.
63  * @param[out]   errorInfo        CA Error information.
64  */
65 typedef void (*CAErrorCallback)(const CAEndpoint_t *object,
66                                 const CAErrorInfo_t *errorInfo);
67
68 #ifdef __WITH_DTLS__
69
70 /**
71  * Binary blob containing device identity and the credentials for all devices
72  * trusted by this device.
73  */
74 typedef struct
75 {
76    unsigned char identity[DTLS_PSK_ID_LEN]; /** identity of self. */
77    uint32_t num;                            /** number of credentials in this blob. */
78    OCDtlsPskCreds *creds;                   /** list of credentials. Size of this
79                                                 array is determined by 'num' variable. */
80 } CADtlsPskCredsBlob_t;
81
82 /**
83  * Callback function type for getting DTLS credentials.
84  * @param[out]   credInfo     DTLS credentials info. Handler has to allocate new memory for.
85  *                            both credInfo and credInfo->creds which is then freed by CA.
86  */
87 typedef void (*CAGetDTLSCredentialsHandler)(CADtlsPskCredsBlob_t **credInfo);
88 #endif //__WITH_DTLS__
89
90 /**
91  * Initialize the connectivity abstraction module.
92  * It will initialize adapters, thread pool and other modules based on the platform
93  * compilation options.
94  *
95  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
96  */
97 CAResult_t CAInitialize();
98
99 /**
100  * Terminate the connectivity abstraction module.
101  * All threads, data structures are destroyed for next initializations.
102  */
103 void CATerminate();
104
105 /**
106  * Starts listening servers.
107  * This API is used by resource hosting server for listening multicast requests.
108  * Based on the adapters configurations, different kinds of servers are started.
109  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
110  */
111 CAResult_t CAStartListeningServer();
112
113 /**
114  * Starts discovery servers.
115  * This API is used by resource required clients for listening multicast requests.
116  * Based on the adapters configurations, different kinds of servers are started.
117  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
118  */
119 CAResult_t CAStartDiscoveryServer();
120
121 /**
122  * Register request callbacks and response callbacks.
123  *          Requests and responses are delivered these callbacks.
124  * @param[in]   ReqHandler    Request callback ( for GET,PUT ..etc).
125  * @param[in]   RespHandler   Response Handler Callback.
126  * @see     CARequestCallback
127  * @see     CAResponseCallback
128  * @see     CAErrorCallback
129  */
130 void CARegisterHandler(CARequestCallback ReqHandler, CAResponseCallback RespHandler,
131                        CAErrorCallback ErrorHandler);
132
133 #ifdef __WITH_DTLS__
134 /**
135  * Register callback to get DTLS PSK credentials.
136  * @param[in]   GetDTLSCredentials    GetDTLS Credetials callback.
137  * @return  ::CA_STATUS_OK
138  */
139 CAResult_t CARegisterDTLSCredentialsHandler(CAGetDTLSCredentialsHandler GetDTLSCredentials);
140 #endif //__WITH_DTLS__
141
142 /**
143  * Create an endpoint description.
144  * @param[in]   flags                 how the adapter should be used.
145  * @param[in]   adapter               which adapter to use.
146  * @param[in]   addr                  string representation of address.
147  * @param[in]   port                  port (for IP_ADAPTER).
148  * @param[in]   endpoint              Endpoint which contains the above.
149  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
150  * @remark  The created Remote endpoint can be freed using CADestroyEndpoint().
151  * @see     CADestroyEndpoint
152  */
153 CAResult_t CACreateEndpoint(CATransportFlags_t flags,
154                             CATransportAdapter_t adapter,
155                             const char *addr,
156                             uint16_t port,
157                             CAEndpoint_t **object);
158
159 /**
160  * Destroy the remote endpoint created.
161  * @param[in]   object   Remote Endpoint object created with CACreateEndpoint.
162  */
163 void CADestroyEndpoint(CAEndpoint_t *object);
164
165 /**
166  * Generating the token for matching the request and response.
167  * @param[in]   token            Token for the request.
168  * @param[in]   tokenLength      length of the token.
169  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or
170  *          ::CA_MEMORY_ALLOC_FAILED or ::CA_STATUS_NOT_INITIALIZED
171  * @remark  Token memory is destroyed by the caller using CADestroyToken().
172  * @see     CADestroyToken
173  */
174 CAResult_t CAGenerateToken(CAToken_t *token, uint8_t tokenLength);
175
176 /**
177  * Destroy the token generated by CAGenerateToken.
178  * @param[in]   token    token to be freed.
179  */
180 void CADestroyToken(CAToken_t token);
181
182 /**
183  * Send control Request on a resource.
184  * @param[in]   object       Endpoint where the payload need to be sent.
185  *                           This endpoint is delivered with Request or response callback.
186  * @param[in]   requestInfo  Information for the request.
187  * @return  ::CA_STATUS_OK ::CA_STATUS_FAILED ::CA_MEMORY_ALLOC_FAILED
188  */
189 CAResult_t CASendRequest(const CAEndpoint_t *object, const CARequestInfo_t *requestInfo);
190
191 /**
192  * Send the response.
193  * @param[in]   object           Endpoint where the payload need to be sent.
194  *                               This endpoint is delivered with Request or response callback.
195  * @param[in]   responseInfo     Information for the response.
196  * @return  ::CA_STATUS_OK or  ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
197  */
198 CAResult_t CASendResponse(const CAEndpoint_t *object, const CAResponseInfo_t *responseInfo);
199
200 /**
201  * Send notification to the remote object.
202  * @param[in]   object           Endpoint where the payload need to be sent.
203  *                               This endpoint is delivered with Request or response callback.
204  * @param[in]   responseInfo     Information for the response.
205  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
206  */
207 CAResult_t CASendNotification(const CAEndpoint_t *object,
208                       const  CAResponseInfo_t *responseInfo);
209
210 /**
211  * Select network to use.
212  * @param[in]   interestedNetwork    Connectivity Type enum.
213  * @return  ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or
214  *          ::CA_STATUS_FAILED or ::CA_NOT_SUPPORTED
215  */
216 CAResult_t CASelectNetwork(CATransportAdapter_t interestedNetwork);
217
218 /**
219  * Select network to unuse.
220  * @param[in]   nonInterestedNetwork     Connectivity Type enum.
221  * @return  ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or ::CA_STATUS_FAILED
222  */
223 CAResult_t CAUnSelectNetwork(CATransportAdapter_t nonInterestedNetwork);
224
225 /**
226  * Get network information.
227  * It should be destroyed by the caller as it Get Information.
228  * @param[out]   info     LocalConnectivity objects
229  * @param[out]   size     No Of Array objects
230  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or
231  *          ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
232  */
233 CAResult_t CAGetNetworkInformation(CAEndpoint_t **info, uint32_t *size);
234
235 /**
236  * To Handle the Request or Response.
237  * @return   ::CA_STATUS_OK
238  */
239 CAResult_t CAHandleRequestResponse();
240
241 #ifdef RA_ADAPTER
242 /**
243  * Set Remote Access information for XMPP Client.
244  * @param[in]   caraInfo          remote access info.
245  *
246  * @return  ::CA_STATUS_OK
247  */
248 CAResult_t CASetRAInfo(const CARAInfo_t *caraInfo);
249 #endif
250
251
252 #ifdef __WITH_DTLS__
253
254 /**
255  * Select the cipher suite for dtls handshake.
256  *
257  * @param[IN] cipher  cipher suite (Note : Make sure endianness)
258  *                               0xC018 : TLS_ECDH_anon_WITH_AES_128_CBC_SHA
259  *                               0xC0A8 : TLS_PSK_WITH_AES_128_CCM_8
260  *                               0xC0AE : TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
261  *
262  * @retval  ::CA_STATUS_OK    Successful.
263  * @retval  ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
264  * @retval  ::CA_STATUS_FAILED Operation failed.
265  */
266 CAResult_t CASelectCipherSuite(const uint16_t cipher);
267
268 /**
269  * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls
270  *
271  * @param[in] enable  TRUE/FALSE enables/disables anonymous cipher suite.
272  *
273  * @retval  ::CA_STATUS_OK    Successful.
274  * @retval  ::CA_STATUS_FAILED Operation failed.
275  *
276  * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
277  */
278 CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
279
280
281 /**
282  * Generate ownerPSK using PRF.
283  * OwnerPSK = TLS-PRF('master key' , 'oic.sec.doxm.jw',
284  *                    'ID of new device(Resource Server)',
285  *                    'ID of owner smart-phone(Provisioning Server)')
286  *
287  * @param[in] endpoint  information of network address.
288  * @param[in] label  Ownership transfer method e.g)"oic.sec.doxm.jw".
289  * @param[in] labelLen  Byte length of label.
290  * @param[in] rsrcServerDeviceID  ID of new device(Resource Server).
291  * @param[in] rsrcServerDeviceIDLen  Byte length of rsrcServerDeviceID.
292  * @param[in] provServerDeviceID  label of previous owner.
293  * @param[in] provServerDeviceIDLen  byte length of provServerDeviceID.
294  * @param[in,out] ownerPSK  Output buffer for owner PSK.
295  * @param[in] ownerPSKSize  Byte length of the ownerPSK to be generated.
296  *
297  * @retval  ::CA_STATUS_OK    Successful.
298  * @retval  ::CA_STATUS_FAILED Operation failed.
299  */
300 CAResult_t CAGenerateOwnerPSK(const CAEndpoint_t *endpoint,
301                               const uint8_t* label, const size_t labelLen,
302                               const uint8_t* rsrcServerDeviceID,
303                               const size_t rsrcServerDeviceIDLen,
304                               const uint8_t* provServerDeviceID,
305                               const size_t provServerDeviceIDLen,
306                               uint8_t* ownerPSK, const size_t ownerPSKSize);
307
308 /**
309  * Initiate DTLS handshake with selected cipher suite.
310  *
311  * @param[in] endpoint  information of network address.
312  *
313  * @retval  ::CA_STATUS_OK    Successful.
314  * @retval  ::CA_STATUS_FAILED Operation failed.
315  */
316 CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
317
318 /**
319  * Close the DTLS session.
320  *
321  * @param[in] endpoint  information of network address.
322  *
323  * @retval  ::CA_STATUS_OK    Successful.
324  * @retval  ::CA_STATUS_FAILED Operation failed.
325  */
326 CAResult_t CACloseDtlsSession(const CAEndpoint_t *endpoint);
327
328 #endif /* __WITH_DTLS__ */
329
330 #ifdef __cplusplus
331 } /* extern "C" */
332 #endif
333
334 #endif /* CA_INTERFACE_H_ */
335