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 * Stops the server from receiving the multicast traffic. This is used by sleeping
115 * device to not receives the multicast traffic.
116 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED
118 CAResult_t CAStopListeningServer();
121 * Starts discovery servers.
122 * This API is used by resource required clients for listening multicast requests.
123 * Based on the adapters configurations, different kinds of servers are started.
124 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED
126 CAResult_t CAStartDiscoveryServer();
129 * Register request callbacks and response callbacks.
130 * Requests and responses are delivered these callbacks.
131 * @param[in] ReqHandler Request callback ( for GET,PUT ..etc).
132 * @param[in] RespHandler Response Handler Callback.
133 * @see CARequestCallback
134 * @see CAResponseCallback
135 * @see CAErrorCallback
137 void CARegisterHandler(CARequestCallback ReqHandler, CAResponseCallback RespHandler,
138 CAErrorCallback ErrorHandler);
142 * Register callback to get DTLS PSK credentials.
143 * @param[in] GetDTLSCredentials GetDTLS Credetials callback.
144 * @return ::CA_STATUS_OK
146 CAResult_t CARegisterDTLSCredentialsHandler(CAGetDTLSCredentialsHandler GetDTLSCredentials);
147 #endif //__WITH_DTLS__
150 * Create an endpoint description.
151 * @param[in] flags how the adapter should be used.
152 * @param[in] adapter which adapter to use.
153 * @param[in] addr string representation of address.
154 * @param[in] port port (for IP_ADAPTER).
155 * @param[in] endpoint Endpoint which contains the above.
156 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED
157 * @remark The created Remote endpoint can be freed using CADestroyEndpoint().
158 * @see CADestroyEndpoint
160 CAResult_t CACreateEndpoint(CATransportFlags_t flags,
161 CATransportAdapter_t adapter,
164 CAEndpoint_t **object);
167 * Destroy the remote endpoint created.
168 * @param[in] object Remote Endpoint object created with CACreateEndpoint.
170 void CADestroyEndpoint(CAEndpoint_t *object);
173 * Generating the token for matching the request and response.
174 * @param[in] token Token for the request.
175 * @param[in] tokenLength length of the token.
176 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or
177 * ::CA_MEMORY_ALLOC_FAILED or ::CA_STATUS_NOT_INITIALIZED
178 * @remark Token memory is destroyed by the caller using CADestroyToken().
179 * @see CADestroyToken
181 CAResult_t CAGenerateToken(CAToken_t *token, uint8_t tokenLength);
184 * Destroy the token generated by CAGenerateToken.
185 * @param[in] token token to be freed.
187 void CADestroyToken(CAToken_t token);
190 * Send control Request on a resource.
191 * @param[in] object Endpoint where the payload need to be sent.
192 * This endpoint is delivered with Request or response callback.
193 * @param[in] requestInfo Information for the request.
194 * @return ::CA_STATUS_OK ::CA_STATUS_FAILED ::CA_MEMORY_ALLOC_FAILED
196 CAResult_t CASendRequest(const CAEndpoint_t *object, const CARequestInfo_t *requestInfo);
200 * @param[in] object Endpoint where the payload need to be sent.
201 * This endpoint is delivered with Request or response callback.
202 * @param[in] responseInfo Information for the response.
203 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
205 CAResult_t CASendResponse(const CAEndpoint_t *object, const CAResponseInfo_t *responseInfo);
208 * Send notification to the remote object.
209 * @param[in] object Endpoint where the payload need to be sent.
210 * This endpoint is delivered with Request or response callback.
211 * @param[in] responseInfo Information for the response.
212 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
214 CAResult_t CASendNotification(const CAEndpoint_t *object,
215 const CAResponseInfo_t *responseInfo);
218 * Select network to use.
219 * @param[in] interestedNetwork Connectivity Type enum.
220 * @return ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or
221 * ::CA_STATUS_FAILED or ::CA_NOT_SUPPORTED
223 CAResult_t CASelectNetwork(CATransportAdapter_t interestedNetwork);
226 * Select network to unuse.
227 * @param[in] nonInterestedNetwork Connectivity Type enum.
228 * @return ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or ::CA_STATUS_FAILED
230 CAResult_t CAUnSelectNetwork(CATransportAdapter_t nonInterestedNetwork);
233 * Get network information.
234 * It should be destroyed by the caller as it Get Information.
235 * @param[out] info LocalConnectivity objects
236 * @param[out] size No Of Array objects
237 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or
238 * ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
240 CAResult_t CAGetNetworkInformation(CAEndpoint_t **info, uint32_t *size);
243 * To Handle the Request or Response.
244 * @return ::CA_STATUS_OK
246 CAResult_t CAHandleRequestResponse();
250 * Set Remote Access information for XMPP Client.
251 * @param[in] caraInfo remote access info.
253 * @return ::CA_STATUS_OK
255 CAResult_t CASetRAInfo(const CARAInfo_t *caraInfo);
262 * Select the cipher suite for dtls handshake.
264 * @param[in] cipher cipher suite (Note : Make sure endianness).
265 * 0xC018 : TLS_ECDH_anon_WITH_AES_128_CBC_SHA
266 * 0xC0A8 : TLS_PSK_WITH_AES_128_CCM_8
267 * 0xC0AE : TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
269 * @retval ::CA_STATUS_OK Successful.
270 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments.
271 * @retval ::CA_STATUS_FAILED Operation failed.
273 CAResult_t CASelectCipherSuite(const uint16_t cipher);
276 * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls.
278 * @param[in] enable TRUE/FALSE enables/disables anonymous cipher suite.
280 * @retval ::CA_STATUS_OK Successful.
281 * @retval ::CA_STATUS_FAILED Operation failed.
283 * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
285 CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
289 * Generate ownerPSK using PRF.
290 * OwnerPSK = TLS-PRF('master key' , 'oic.sec.doxm.jw',
291 * 'ID of new device(Resource Server)',
292 * 'ID of owner smart-phone(Provisioning Server)')
294 * @param[in] endpoint information of network address.
295 * @param[in] label Ownership transfer method e.g)"oic.sec.doxm.jw".
296 * @param[in] labelLen Byte length of label.
297 * @param[in] rsrcServerDeviceID ID of new device(Resource Server).
298 * @param[in] rsrcServerDeviceIDLen Byte length of rsrcServerDeviceID.
299 * @param[in] provServerDeviceID label of previous owner.
300 * @param[in] provServerDeviceIDLen byte length of provServerDeviceID.
301 * @param[in,out] ownerPSK Output buffer for owner PSK.
302 * @param[in] ownerPSKSize Byte length of the ownerPSK to be generated.
304 * @retval ::CA_STATUS_OK Successful.
305 * @retval ::CA_STATUS_FAILED Operation failed.
307 CAResult_t CAGenerateOwnerPSK(const CAEndpoint_t *endpoint,
308 const uint8_t* label, const size_t labelLen,
309 const uint8_t* rsrcServerDeviceID,
310 const size_t rsrcServerDeviceIDLen,
311 const uint8_t* provServerDeviceID,
312 const size_t provServerDeviceIDLen,
313 uint8_t* ownerPSK, const size_t ownerPSKSize);
316 * Initiate DTLS handshake with selected cipher suite.
318 * @param[in] endpoint information of network address.
320 * @retval ::CA_STATUS_OK Successful.
321 * @retval ::CA_STATUS_FAILED Operation failed.
323 CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
326 * Close the DTLS session.
328 * @param[in] endpoint information of network address.
330 * @retval ::CA_STATUS_OK Successful.
331 * @retval ::CA_STATUS_FAILED Operation failed.
333 CAResult_t CACloseDtlsSession(const CAEndpoint_t *endpoint);
335 #endif /* __WITH_DTLS__ */
341 #endif /* CA_INTERFACE_H_ */