1 /* ****************************************************************
3 * Copyright 2014 Samsung Electronics All Rights Reserved.
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 ******************************************************************/
24 * This file contains the APIs for Resource Model to use.
27 #ifndef CA_INTERFACE_H_
28 #define CA_INTERFACE_H_
31 * Connectivity Abstraction Interface APIs.
36 #include "ocsecurityconfig.h"
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.
50 typedef void (*CARequestCallback)(const CAEndpoint_t *object,
51 const CARequestInfo_t *requestInfo);
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.
58 typedef void (*CAResponseCallback)(const CAEndpoint_t *object,
59 const CAResponseInfo_t *responseInfo);
61 * Callback function type for error.
62 * @param[out] object remote device information.
63 * @param[out] errorInfo CA Error information.
65 typedef void (*CAErrorCallback)(const CAEndpoint_t *object,
66 const CAErrorInfo_t *errorInfo);
71 * Binary blob containing device identity and the credentials for all devices
72 * trusted by this device.
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;
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.
87 typedef void (*CAGetDTLSCredentialsHandler)(CADtlsPskCredsBlob_t **credInfo);
88 #endif //__WITH_DTLS__
91 * Initialize the connectivity abstraction module.
92 * It will initialize adapters, thread pool and other modules based on the platform
93 * compilation options.
95 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
97 CAResult_t CAInitialize();
100 * Terminate the connectivity abstraction module.
101 * All threads, data structures are destroyed for next initializations.
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
111 CAResult_t CAStartListeningServer();
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
119 CAResult_t CAStartDiscoveryServer();
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
130 void CARegisterHandler(CARequestCallback ReqHandler, CAResponseCallback RespHandler,
131 CAErrorCallback ErrorHandler);
135 * Register callback to get DTLS PSK credentials.
136 * @param[in] GetDTLSCredentials GetDTLS Credetials callback.
137 * @return ::CA_STATUS_OK
139 CAResult_t CARegisterDTLSCredentialsHandler(CAGetDTLSCredentialsHandler GetDTLSCredentials);
140 #endif //__WITH_DTLS__
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
153 CAResult_t CACreateEndpoint(CATransportFlags_t flags,
154 CATransportAdapter_t adapter,
157 CAEndpoint_t **object);
160 * Destroy the remote endpoint created.
161 * @param[in] object Remote Endpoint object created with CACreateEndpoint.
163 void CADestroyEndpoint(CAEndpoint_t *object);
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
174 CAResult_t CAGenerateToken(CAToken_t *token, uint8_t tokenLength);
177 * Destroy the token generated by CAGenerateToken.
178 * @param[in] token token to be freed.
180 void CADestroyToken(CAToken_t token);
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
189 CAResult_t CASendRequest(const CAEndpoint_t *object, const CARequestInfo_t *requestInfo);
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
198 CAResult_t CASendResponse(const CAEndpoint_t *object, const CAResponseInfo_t *responseInfo);
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
207 CAResult_t CASendNotification(const CAEndpoint_t *object,
208 const CAResponseInfo_t *responseInfo);
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
216 CAResult_t CASelectNetwork(CATransportAdapter_t interestedNetwork);
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
223 CAResult_t CAUnSelectNetwork(CATransportAdapter_t nonInterestedNetwork);
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
233 CAResult_t CAGetNetworkInformation(CAEndpoint_t **info, uint32_t *size);
236 * To Handle the Request or Response.
237 * @return ::CA_STATUS_OK
239 CAResult_t CAHandleRequestResponse();
243 * Set Remote Access information for XMPP Client.
244 * @param[in] caraInfo remote access info.
246 * @return ::CA_STATUS_OK
248 CAResult_t CASetRAInfo(const CARAInfo_t *caraInfo);
255 * Select the cipher suite for dtls handshake.
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
262 * @retval ::CA_STATUS_OK Successful.
263 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments.
264 * @retval ::CA_STATUS_FAILED Operation failed.
266 CAResult_t CASelectCipherSuite(const uint16_t cipher);
269 * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls
271 * @param[in] enable TRUE/FALSE enables/disables anonymous cipher suite.
273 * @retval ::CA_STATUS_OK Successful.
274 * @retval ::CA_STATUS_FAILED Operation failed.
276 * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
278 CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
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)')
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.
297 * @retval ::CA_STATUS_OK Successful.
298 * @retval ::CA_STATUS_FAILED Operation failed.
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);
309 * Initiate DTLS handshake with selected cipher suite.
311 * @param[in] endpoint information of network address.
313 * @retval ::CA_STATUS_OK Successful.
314 * @retval ::CA_STATUS_FAILED Operation failed.
316 CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
319 * Close the DTLS session.
321 * @param[in] endpoint information of network address.
323 * @retval ::CA_STATUS_OK Successful.
324 * @retval ::CA_STATUS_FAILED Operation failed.
326 CAResult_t CACloseDtlsSession(const CAEndpoint_t *endpoint);
328 #endif /* __WITH_DTLS__ */
334 #endif /* CA_INTERFACE_H_ */