Merge "Merge branch 'remote-access2'"
[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 #ifdef __WITH_X509__
39 #include "pki.h"
40 #endif //__WITH_X509__
41
42 #ifdef __cplusplus
43 extern "C"
44 {
45 #endif
46
47 /**
48  * Callback function type for request delivery.
49  * @param[out]   object       Endpoint object from which the request is received.
50  *                            It contains endpoint address based on the connectivity type.
51  * @param[out]   requestInfo  Info for resource model to understand about the request.
52  */
53 typedef void (*CARequestCallback)(const CAEndpoint_t *object,
54                                   const CARequestInfo_t *requestInfo);
55
56 /**
57  * Callback function type for response delivery.
58  * @param[out]   object           Endpoint object from which the response is received.
59  * @param[out]   responseInfo     Identifier which needs to be mapped with response.
60  */
61 typedef void (*CAResponseCallback)(const CAEndpoint_t *object,
62                                    const CAResponseInfo_t *responseInfo);
63 /**
64  * Callback function type for error.
65  * @param[out]   object           remote device information.
66  * @param[out]   errorInfo        CA Error information.
67  */
68 typedef void (*CAErrorCallback)(const CAEndpoint_t *object,
69                                 const CAErrorInfo_t *errorInfo);
70 #ifdef RA_ADAPTER
71
72 /**
73  * Callback for bound JID
74  * @param[out]   jid           Boud Jabber Identifier.
75  */
76 typedef void (*CAJidBoundCallback)(char *jid);
77
78 /**
79  * CA Remote Access information for XMPP Client
80  *
81  */
82 typedef struct
83 {
84     char *hostName;     /**< XMPP server hostname */
85     uint16_t port;      /**< XMPP server serivce port */
86     char *xmppDomain;  /**< XMPP login domain */
87     char *userName;     /**< login username */
88     char *password;     /**< login password */
89     char *resource;     /**< specific resource for login */
90     char *userJid;     /**< specific JID for login */
91     CAJidBoundCallback jidBoundCallback;  /**< callback when JID bound */
92 } CARAInfo_t;
93
94 #endif //RA_ADAPTER
95
96 #ifdef __WITH_DTLS__
97
98 /**
99  * Binary blob containing device identity and the credentials for all devices
100  * trusted by this device.
101  */
102 typedef struct
103 {
104    unsigned char identity[DTLS_PSK_ID_LEN]; /** identity of self. */
105    uint32_t num;                            /** number of credentials in this blob. */
106    OCDtlsPskCreds *creds;                   /** list of credentials. Size of this
107                                                 array is determined by 'num' variable. */
108 } CADtlsPskCredsBlob_t;
109
110 /**
111  * Callback function type for getting DTLS credentials.
112  * @param[out]   credInfo     DTLS credentials info. Handler has to allocate new memory for.
113  *                            both credInfo and credInfo->creds which is then freed by CA.
114  */
115 typedef void (*CAGetDTLSCredentialsHandler)(CADtlsPskCredsBlob_t **credInfo);
116 #endif //__WITH_DTLS__
117
118 #ifdef __WITH_X509__
119 /**
120  * Binary structure containing certificate chain and certificate credentials
121  * for this device.
122  */
123 typedef struct
124 {
125     // certificate message  for DTLS
126     unsigned char certificateChain[MAX_CERT_MESSAGE_LEN];
127     // length of the certificate message
128     uint32_t  certificateChainLen;
129     // number of certificates in  certificate message
130     uint8_t   chainLen;
131     // x component of EC public key
132     uint8_t   rootPublicKeyX[PUBLIC_KEY_SIZE / 2];
133     // y component of EC public key
134     uint8_t   rootPublicKeyY[PUBLIC_KEY_SIZE / 2];
135     // EC private key
136     uint8_t   devicePrivateKey[PRIVATE_KEY_SIZE];
137
138 } CADtlsX509Creds_t;
139
140 /**
141  * @brief   Callback function type for getting certificate credentials.
142  * @param   credInfo          [OUT] Certificate credentials info. Handler has to allocate new memory for
143  *                                  credInfo which is then freed by CA
144  * @return  NONE
145  */
146 typedef int (*CAGetDTLSX509CredentialsHandler)(CADtlsX509Creds_t *credInfo);
147 /**
148  * @brief   Callback function type for getting CRL.
149  * @param   crlInfo          [OUT] Certificate credentials info. Handler has to allocate new memory for
150  *                                  credInfo which is then freed by CA
151  * @return  NONE
152  */
153 typedef void (*CAGetDTLSCrlHandler)(ByteArray crlInfo);
154 #endif //__WITH_X509__
155
156 /**
157  * Initialize the connectivity abstraction module.
158  * It will initialize adapters, thread pool and other modules based on the platform
159  * compilation options.
160  *
161  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
162  */
163 CAResult_t CAInitialize();
164
165 /**
166  * Terminate the connectivity abstraction module.
167  * All threads, data structures are destroyed for next initializations.
168  */
169 void CATerminate();
170
171 /**
172  * Starts listening servers.
173  * This API is used by resource hosting server for listening multicast requests.
174  * Based on the adapters configurations, different kinds of servers are started.
175  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
176  */
177 CAResult_t CAStartListeningServer();
178
179 /**
180  * Starts discovery servers.
181  * This API is used by resource required clients for listening multicast requests.
182  * Based on the adapters configurations, different kinds of servers are started.
183  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
184  */
185 CAResult_t CAStartDiscoveryServer();
186
187 /**
188  * Register request callbacks and response callbacks.
189  *          Requests and responses are delivered these callbacks.
190  * @param[in]   ReqHandler    Request callback ( for GET,PUT ..etc).
191  * @param[in]   RespHandler   Response Handler Callback.
192  * @see     CARequestCallback
193  * @see     CAResponseCallback
194  * @see     CAErrorCallback
195  */
196 void CARegisterHandler(CARequestCallback ReqHandler, CAResponseCallback RespHandler,
197                        CAErrorCallback ErrorHandler);
198
199 #ifdef __WITH_DTLS__
200 /**
201  * Register callback to get DTLS PSK credentials.
202  * @param[in]   GetDTLSCredentials    GetDTLS Credetials callback.
203  * @return  ::CA_STATUS_OK
204  */
205 CAResult_t CARegisterDTLSCredentialsHandler(CAGetDTLSCredentialsHandler GetDTLSCredentials);
206 #endif //__WITH_DTLS__
207
208 #ifdef __WITH_X509__
209 /**
210  * @brief   Register callback to get DTLS Cert credentials.
211  * @param   GetCertCredentials   [IN] GetCert Credetials callback
212  * @return  #CA_STATUS_OK
213  */
214 CAResult_t CARegisterDTLSX509CredentialsHandler(CAGetDTLSX509CredentialsHandler GetX509Credentials);
215 /**
216  * @brief   Register callback to get CRL.
217  * @param   GetCrl   [IN] GetCrl callback
218  * @return  #CA_STATUS_OK
219  */
220 CAResult_t CARegisterDTLSCrlHandler(CAGetDTLSCrlHandler GetCrl);
221 #endif //__WITH_X509__
222
223 /**
224  * Create an endpoint description.
225  * @param[in]   flags                 how the adapter should be used.
226  * @param[in]   adapter               which adapter to use.
227  * @param[in]   addr                  string representation of address.
228  * @param[in]   port                  port (for IP_ADAPTER).
229  * @param[in]   endpoint              Endpoint which contains the above.
230  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED
231  * @remark  The created Remote endpoint can be freed using CADestroyEndpoint().
232  * @see     CADestroyEndpoint
233  */
234 CAResult_t CACreateEndpoint(CATransportFlags_t flags,
235                             CATransportAdapter_t adapter,
236                             const char *addr,
237                             uint16_t port,
238                             CAEndpoint_t **object);
239
240 /**
241  * Destroy the remote endpoint created.
242  * @param[in]   object   Remote Endpoint object created with CACreateEndpoint.
243  */
244 void CADestroyEndpoint(CAEndpoint_t *object);
245
246 /**
247  * Generating the token for matching the request and response.
248  * @param[in]   token            Token for the request.
249  * @param[in]   tokenLength      length of the token.
250  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or
251  *          ::CA_MEMORY_ALLOC_FAILED or ::CA_STATUS_NOT_INITIALIZED
252  * @remark  Token memory is destroyed by the caller using CADestroyToken().
253  * @see     CADestroyToken
254  */
255 CAResult_t CAGenerateToken(CAToken_t *token, uint8_t tokenLength);
256
257 /**
258  * Destroy the token generated by CAGenerateToken.
259  * @param[in]   token    token to be freed.
260  */
261 void CADestroyToken(CAToken_t token);
262
263 /**
264  * Send control Request on a resource.
265  * @param[in]   object       Endpoint where the payload need to be sent.
266  *                           This endpoint is delivered with Request or response callback.
267  * @param[in]   requestInfo  Information for the request.
268  * @return  ::CA_STATUS_OK ::CA_STATUS_FAILED ::CA_MEMORY_ALLOC_FAILED
269  */
270 CAResult_t CASendRequest(const CAEndpoint_t *object, const CARequestInfo_t *requestInfo);
271
272 /**
273  * Send the response.
274  * @param[in]   object           Endpoint where the payload need to be sent.
275  *                               This endpoint is delivered with Request or response callback.
276  * @param[in]   responseInfo     Information for the response.
277  * @return  ::CA_STATUS_OK or  ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
278  */
279 CAResult_t CASendResponse(const CAEndpoint_t *object, const CAResponseInfo_t *responseInfo);
280
281 /**
282  * Send notification to the remote object.
283  * @param[in]   object           Endpoint where the payload need to be sent.
284  *                               This endpoint is delivered with Request or response callback.
285  * @param[in]   responseInfo     Information for the response.
286  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
287  */
288 CAResult_t CASendNotification(const CAEndpoint_t *object,
289                       const  CAResponseInfo_t *responseInfo);
290
291 /**
292  * Select network to use.
293  * @param[in]   interestedNetwork    Connectivity Type enum.
294  * @return  ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or
295  *          ::CA_STATUS_FAILED or ::CA_NOT_SUPPORTED
296  */
297 CAResult_t CASelectNetwork(CATransportAdapter_t interestedNetwork);
298
299 /**
300  * Select network to unuse.
301  * @param[in]   nonInterestedNetwork     Connectivity Type enum.
302  * @return  ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or ::CA_STATUS_FAILED
303  */
304 CAResult_t CAUnSelectNetwork(CATransportAdapter_t nonInterestedNetwork);
305
306 /**
307  * Get network information.
308  * It should be destroyed by the caller as it Get Information.
309  * @param[out]   info     LocalConnectivity objects
310  * @param[out]   size     No Of Array objects
311  * @return  ::CA_STATUS_OK or ::CA_STATUS_FAILED or
312  *          ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
313  */
314 CAResult_t CAGetNetworkInformation(CAEndpoint_t **info, uint32_t *size);
315
316 /**
317  * To Handle the Request or Response.
318  * @return   ::CA_STATUS_OK
319  */
320 CAResult_t CAHandleRequestResponse();
321
322 #ifdef RA_ADAPTER
323 /**
324  * Set Remote Access information for XMPP Client.
325  * @param[in]   caraInfo          remote access info.
326  *
327  * @return  ::CA_STATUS_OK
328  */
329 CAResult_t CASetRAInfo(const CARAInfo_t *caraInfo);
330 #endif
331
332
333 #ifdef __WITH_DTLS__
334
335 /**
336  * Select the cipher suite for dtls handshake.
337  *
338  * @param[in] cipher  cipher suite (Note : Make sure endianness).
339  *                    0xC018 : TLS_ECDH_anon_WITH_AES_128_CBC_SHA
340  *                    0xC0A8 : TLS_PSK_WITH_AES_128_CCM_8
341  *                    0xC0AE : TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
342  *
343  * @retval  ::CA_STATUS_OK    Successful.
344  * @retval  ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
345  * @retval  ::CA_STATUS_FAILED Operation failed.
346  */
347 CAResult_t CASelectCipherSuite(const uint16_t cipher);
348
349 /**
350  * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls.
351  *
352  * @param[in] enable  TRUE/FALSE enables/disables anonymous cipher suite.
353  *
354  * @retval  ::CA_STATUS_OK    Successful.
355  * @retval  ::CA_STATUS_FAILED Operation failed.
356  *
357  * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
358  */
359 CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
360
361
362 /**
363  * Generate ownerPSK using PRF.
364  * OwnerPSK = TLS-PRF('master key' , 'oic.sec.doxm.jw',
365  *                    'ID of new device(Resource Server)',
366  *                    'ID of owner smart-phone(Provisioning Server)')
367  *
368  * @param[in] endpoint  information of network address.
369  * @param[in] label  Ownership transfer method e.g)"oic.sec.doxm.jw".
370  * @param[in] labelLen  Byte length of label.
371  * @param[in] rsrcServerDeviceID  ID of new device(Resource Server).
372  * @param[in] rsrcServerDeviceIDLen  Byte length of rsrcServerDeviceID.
373  * @param[in] provServerDeviceID  label of previous owner.
374  * @param[in] provServerDeviceIDLen  byte length of provServerDeviceID.
375  * @param[in,out] ownerPSK  Output buffer for owner PSK.
376  * @param[in] ownerPSKSize  Byte length of the ownerPSK to be generated.
377  *
378  * @retval  ::CA_STATUS_OK    Successful.
379  * @retval  ::CA_STATUS_FAILED Operation failed.
380  */
381 CAResult_t CAGenerateOwnerPSK(const CAEndpoint_t *endpoint,
382                               const uint8_t* label, const size_t labelLen,
383                               const uint8_t* rsrcServerDeviceID,
384                               const size_t rsrcServerDeviceIDLen,
385                               const uint8_t* provServerDeviceID,
386                               const size_t provServerDeviceIDLen,
387                               uint8_t* ownerPSK, const size_t ownerPSKSize);
388
389 /**
390  * Initiate DTLS handshake with selected cipher suite.
391  *
392  * @param[in] endpoint  information of network address.
393  *
394  * @retval  ::CA_STATUS_OK    Successful.
395  * @retval  ::CA_STATUS_FAILED Operation failed.
396  */
397 CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
398
399 /**
400  * Close the DTLS session.
401  *
402  * @param[in] endpoint  information of network address.
403  *
404  * @retval  ::CA_STATUS_OK    Successful.
405  * @retval  ::CA_STATUS_FAILED Operation failed.
406  */
407 CAResult_t CACloseDtlsSession(const CAEndpoint_t *endpoint);
408
409 #endif /* __WITH_DTLS__ */
410
411 #ifdef __cplusplus
412 } /* extern "C" */
413 #endif
414
415 #endif /* CA_INTERFACE_H_ */
416