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"
40 #endif //__WITH_X509__
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.
53 typedef void (*CARequestCallback)(const CAEndpoint_t *object,
54 const CARequestInfo_t *requestInfo);
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.
61 typedef void (*CAResponseCallback)(const CAEndpoint_t *object,
62 const CAResponseInfo_t *responseInfo);
64 * Callback function type for error.
65 * @param[out] object remote device information.
66 * @param[out] errorInfo CA Error information.
68 typedef void (*CAErrorCallback)(const CAEndpoint_t *object,
69 const CAErrorInfo_t *errorInfo);
74 * Binary blob containing device identity and the credentials for all devices
75 * trusted by this device.
79 unsigned char identity[DTLS_PSK_ID_LEN]; /** identity of self. */
80 uint32_t num; /** number of credentials in this blob. */
81 OCDtlsPskCreds *creds; /** list of credentials. Size of this
82 array is determined by 'num' variable. */
83 } CADtlsPskCredsBlob_t;
86 * Callback function type for getting DTLS credentials.
87 * @param[out] credInfo DTLS credentials info. Handler has to allocate new memory for.
88 * both credInfo and credInfo->creds which is then freed by CA.
90 typedef void (*CAGetDTLSCredentialsHandler)(CADtlsPskCredsBlob_t **credInfo);
91 #endif //__WITH_DTLS__
95 * Binary structure containing certificate chain and certificate credentials
100 // certificate message for DTLS
101 unsigned char certificateChain[MAX_CERT_MESSAGE_LEN];
102 // length of the certificate message
103 uint32_t certificateChainLen;
104 // number of certificates in certificate message
106 // x component of EC public key
107 uint8_t rootPublicKeyX[PUBLIC_KEY_SIZE / 2];
108 // y component of EC public key
109 uint8_t rootPublicKeyY[PUBLIC_KEY_SIZE / 2];
111 uint8_t devicePrivateKey[PRIVATE_KEY_SIZE];
116 * @brief Callback function type for getting certificate credentials.
117 * @param credInfo [OUT] Certificate credentials info. Handler has to allocate new memory for
118 * credInfo which is then freed by CA
121 typedef void (*CAGetCertCredentialsHandler)(CADtlsCertCreds_t *credInfo);
122 #endif //__WITH_X509__
125 * Initialize the connectivity abstraction module.
126 * It will initialize adapters, thread pool and other modules based on the platform
127 * compilation options.
129 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
131 CAResult_t CAInitialize();
134 * Terminate the connectivity abstraction module.
135 * All threads, data structures are destroyed for next initializations.
140 * Starts listening servers.
141 * This API is used by resource hosting server for listening multicast requests.
142 * Based on the adapters configurations, different kinds of servers are started.
143 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED
145 CAResult_t CAStartListeningServer();
148 * Starts discovery servers.
149 * This API is used by resource required clients for listening multicast requests.
150 * Based on the adapters configurations, different kinds of servers are started.
151 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED
153 CAResult_t CAStartDiscoveryServer();
156 * Register request callbacks and response callbacks.
157 * Requests and responses are delivered these callbacks.
158 * @param[in] ReqHandler Request callback ( for GET,PUT ..etc).
159 * @param[in] RespHandler Response Handler Callback.
160 * @see CARequestCallback
161 * @see CAResponseCallback
162 * @see CAErrorCallback
164 void CARegisterHandler(CARequestCallback ReqHandler, CAResponseCallback RespHandler,
165 CAErrorCallback ErrorHandler);
169 * Register callback to get DTLS PSK credentials.
170 * @param[in] GetDTLSCredentials GetDTLS Credetials callback.
171 * @return ::CA_STATUS_OK
173 CAResult_t CARegisterDTLSCredentialsHandler(CAGetDTLSCredentialsHandler GetDTLSCredentials);
174 #endif //__WITH_DTLS__
178 * @brief Register callback to get DTLS Cert credentials.
179 * @param GetCertCredentials [IN] GetCert Credetials callback
180 * @return #CA_STATUS_OK
182 CAResult_t CARegisterCertCredentialsHandler(CAGetCertCredentialsHandler GetCertCredentials);
183 #endif //__WITH_X509__
186 * Create an endpoint description.
187 * @param[in] flags how the adapter should be used.
188 * @param[in] adapter which adapter to use.
189 * @param[in] addr string representation of address.
190 * @param[in] port port (for IP_ADAPTER).
191 * @param[in] endpoint Endpoint which contains the above.
192 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED
193 * @remark The created Remote endpoint can be freed using CADestroyEndpoint().
194 * @see CADestroyEndpoint
196 CAResult_t CACreateEndpoint(CATransportFlags_t flags,
197 CATransportAdapter_t adapter,
200 CAEndpoint_t **object);
203 * Destroy the remote endpoint created.
204 * @param[in] object Remote Endpoint object created with CACreateEndpoint.
206 void CADestroyEndpoint(CAEndpoint_t *object);
209 * Generating the token for matching the request and response.
210 * @param[in] token Token for the request.
211 * @param[in] tokenLength length of the token.
212 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or
213 * ::CA_MEMORY_ALLOC_FAILED or ::CA_STATUS_NOT_INITIALIZED
214 * @remark Token memory is destroyed by the caller using CADestroyToken().
215 * @see CADestroyToken
217 CAResult_t CAGenerateToken(CAToken_t *token, uint8_t tokenLength);
220 * Destroy the token generated by CAGenerateToken.
221 * @param[in] token token to be freed.
223 void CADestroyToken(CAToken_t token);
226 * Send control Request on a resource.
227 * @param[in] object Endpoint where the payload need to be sent.
228 * This endpoint is delivered with Request or response callback.
229 * @param[in] requestInfo Information for the request.
230 * @return ::CA_STATUS_OK ::CA_STATUS_FAILED ::CA_MEMORY_ALLOC_FAILED
232 CAResult_t CASendRequest(const CAEndpoint_t *object, const CARequestInfo_t *requestInfo);
236 * @param[in] object Endpoint where the payload need to be sent.
237 * This endpoint is delivered with Request or response callback.
238 * @param[in] responseInfo Information for the response.
239 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
241 CAResult_t CASendResponse(const CAEndpoint_t *object, const CAResponseInfo_t *responseInfo);
244 * Send notification to the remote object.
245 * @param[in] object Endpoint where the payload need to be sent.
246 * This endpoint is delivered with Request or response callback.
247 * @param[in] responseInfo Information for the response.
248 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
250 CAResult_t CASendNotification(const CAEndpoint_t *object,
251 const CAResponseInfo_t *responseInfo);
254 * Select network to use.
255 * @param[in] interestedNetwork Connectivity Type enum.
256 * @return ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or
257 * ::CA_STATUS_FAILED or ::CA_NOT_SUPPORTED
259 CAResult_t CASelectNetwork(CATransportAdapter_t interestedNetwork);
262 * Select network to unuse.
263 * @param[in] nonInterestedNetwork Connectivity Type enum.
264 * @return ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or ::CA_STATUS_FAILED
266 CAResult_t CAUnSelectNetwork(CATransportAdapter_t nonInterestedNetwork);
269 * Get network information.
270 * It should be destroyed by the caller as it Get Information.
271 * @param[out] info LocalConnectivity objects
272 * @param[out] size No Of Array objects
273 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or
274 * ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
276 CAResult_t CAGetNetworkInformation(CAEndpoint_t **info, uint32_t *size);
279 * To Handle the Request or Response.
280 * @return ::CA_STATUS_OK
282 CAResult_t CAHandleRequestResponse();
286 * Set Remote Access information for XMPP Client.
287 * @param[in] caraInfo remote access info.
289 * @return ::CA_STATUS_OK
291 CAResult_t CASetRAInfo(const CARAInfo_t *caraInfo);
298 * Select the cipher suite for dtls handshake.
300 * @param[IN] cipher cipher suite (Note : Make sure endianness)
301 * 0xC018 : TLS_ECDH_anon_WITH_AES_128_CBC_SHA
302 * 0xC0A8 : TLS_PSK_WITH_AES_128_CCM_8
303 * 0xC0AE : TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
305 * @retval ::CA_STATUS_OK Successful.
306 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments.
307 * @retval ::CA_STATUS_FAILED Operation failed.
309 CAResult_t CASelectCipherSuite(const uint16_t cipher);
312 * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls
314 * @param[in] enable TRUE/FALSE enables/disables anonymous cipher suite.
316 * @retval ::CA_STATUS_OK Successful.
317 * @retval ::CA_STATUS_FAILED Operation failed.
319 * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
321 CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
325 * Generate ownerPSK using PRF.
326 * OwnerPSK = TLS-PRF('master key' , 'oic.sec.doxm.jw',
327 * 'ID of new device(Resource Server)',
328 * 'ID of owner smart-phone(Provisioning Server)')
330 * @param[in] endpoint information of network address.
331 * @param[in] label Ownership transfer method e.g)"oic.sec.doxm.jw".
332 * @param[in] labelLen Byte length of label.
333 * @param[in] rsrcServerDeviceID ID of new device(Resource Server).
334 * @param[in] rsrcServerDeviceIDLen Byte length of rsrcServerDeviceID.
335 * @param[in] provServerDeviceID label of previous owner.
336 * @param[in] provServerDeviceIDLen byte length of provServerDeviceID.
337 * @param[in,out] ownerPSK Output buffer for owner PSK.
338 * @param[in] ownerPSKSize Byte length of the ownerPSK to be generated.
340 * @retval ::CA_STATUS_OK Successful.
341 * @retval ::CA_STATUS_FAILED Operation failed.
343 CAResult_t CAGenerateOwnerPSK(const CAEndpoint_t *endpoint,
344 const uint8_t* label, const size_t labelLen,
345 const uint8_t* rsrcServerDeviceID,
346 const size_t rsrcServerDeviceIDLen,
347 const uint8_t* provServerDeviceID,
348 const size_t provServerDeviceIDLen,
349 uint8_t* ownerPSK, const size_t ownerPSKSize);
352 * Initiate DTLS handshake with selected cipher suite.
354 * @param[in] endpoint information of network address.
356 * @retval ::CA_STATUS_OK Successful.
357 * @retval ::CA_STATUS_FAILED Operation failed.
359 CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
362 * Close the DTLS session.
364 * @param[in] endpoint information of network address.
366 * @retval ::CA_STATUS_OK Successful.
367 * @retval ::CA_STATUS_FAILED Operation failed.
369 CAResult_t CACloseDtlsSession(const CAEndpoint_t *endpoint);
371 #endif /* __WITH_DTLS__ */
377 #endif /* CA_INTERFACE_H_ */