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 int (*CAGetDTLSX509CredentialsHandler)(CADtlsX509Creds_t *credInfo);
123 * @brief Callback function type for getting CRL.
124 * @param crlInfo [OUT] Certificate credentials info. Handler has to allocate new memory for
125 * credInfo which is then freed by CA
128 typedef void (*CAGetDTLSCrlHandler)(ByteArray crlInfo);
129 #endif //__WITH_X509__
132 * Initialize the connectivity abstraction module.
133 * It will initialize adapters, thread pool and other modules based on the platform
134 * compilation options.
136 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
138 CAResult_t CAInitialize();
141 * Terminate the connectivity abstraction module.
142 * All threads, data structures are destroyed for next initializations.
147 * Starts listening servers.
148 * This API is used by resource hosting server for listening multicast requests.
149 * Based on the adapters configurations, different kinds of servers are started.
150 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED
152 CAResult_t CAStartListeningServer();
155 * Starts discovery servers.
156 * This API is used by resource required clients for listening multicast requests.
157 * Based on the adapters configurations, different kinds of servers are started.
158 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED
160 CAResult_t CAStartDiscoveryServer();
163 * Register request callbacks and response callbacks.
164 * Requests and responses are delivered these callbacks.
165 * @param[in] ReqHandler Request callback ( for GET,PUT ..etc).
166 * @param[in] RespHandler Response Handler Callback.
167 * @see CARequestCallback
168 * @see CAResponseCallback
169 * @see CAErrorCallback
171 void CARegisterHandler(CARequestCallback ReqHandler, CAResponseCallback RespHandler,
172 CAErrorCallback ErrorHandler);
176 * Register callback to get DTLS PSK credentials.
177 * @param[in] GetDTLSCredentials GetDTLS Credetials callback.
178 * @return ::CA_STATUS_OK
180 CAResult_t CARegisterDTLSCredentialsHandler(CAGetDTLSCredentialsHandler GetDTLSCredentials);
181 #endif //__WITH_DTLS__
185 * @brief Register callback to get DTLS Cert credentials.
186 * @param GetCertCredentials [IN] GetCert Credetials callback
187 * @return #CA_STATUS_OK
189 CAResult_t CARegisterDTLSX509CredentialsHandler(CAGetDTLSX509CredentialsHandler GetX509Credentials);
191 * @brief Register callback to get CRL.
192 * @param GetCrl [IN] GetCrl callback
193 * @return #CA_STATUS_OK
195 CAResult_t CARegisterDTLSCrlHandler(CAGetDTLSCrlHandler GetCrl);
196 #endif //__WITH_X509__
199 * Create an endpoint description.
200 * @param[in] flags how the adapter should be used.
201 * @param[in] adapter which adapter to use.
202 * @param[in] addr string representation of address.
203 * @param[in] port port (for IP_ADAPTER).
204 * @param[in] endpoint Endpoint which contains the above.
205 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED
206 * @remark The created Remote endpoint can be freed using CADestroyEndpoint().
207 * @see CADestroyEndpoint
209 CAResult_t CACreateEndpoint(CATransportFlags_t flags,
210 CATransportAdapter_t adapter,
213 CAEndpoint_t **object);
216 * Destroy the remote endpoint created.
217 * @param[in] object Remote Endpoint object created with CACreateEndpoint.
219 void CADestroyEndpoint(CAEndpoint_t *object);
222 * Generating the token for matching the request and response.
223 * @param[in] token Token for the request.
224 * @param[in] tokenLength length of the token.
225 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or
226 * ::CA_MEMORY_ALLOC_FAILED or ::CA_STATUS_NOT_INITIALIZED
227 * @remark Token memory is destroyed by the caller using CADestroyToken().
228 * @see CADestroyToken
230 CAResult_t CAGenerateToken(CAToken_t *token, uint8_t tokenLength);
233 * Destroy the token generated by CAGenerateToken.
234 * @param[in] token token to be freed.
236 void CADestroyToken(CAToken_t token);
239 * Send control Request on a resource.
240 * @param[in] object Endpoint where the payload need to be sent.
241 * This endpoint is delivered with Request or response callback.
242 * @param[in] requestInfo Information for the request.
243 * @return ::CA_STATUS_OK ::CA_STATUS_FAILED ::CA_MEMORY_ALLOC_FAILED
245 CAResult_t CASendRequest(const CAEndpoint_t *object, const CARequestInfo_t *requestInfo);
249 * @param[in] object Endpoint where the payload need to be sent.
250 * This endpoint is delivered with Request or response callback.
251 * @param[in] responseInfo Information for the response.
252 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
254 CAResult_t CASendResponse(const CAEndpoint_t *object, const CAResponseInfo_t *responseInfo);
257 * Send notification to the remote object.
258 * @param[in] object Endpoint where the payload need to be sent.
259 * This endpoint is delivered with Request or response callback.
260 * @param[in] responseInfo Information for the response.
261 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or ::CA_MEMORY_ALLOC_FAILED
263 CAResult_t CASendNotification(const CAEndpoint_t *object,
264 const CAResponseInfo_t *responseInfo);
267 * Select network to use.
268 * @param[in] interestedNetwork Connectivity Type enum.
269 * @return ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or
270 * ::CA_STATUS_FAILED or ::CA_NOT_SUPPORTED
272 CAResult_t CASelectNetwork(CATransportAdapter_t interestedNetwork);
275 * Select network to unuse.
276 * @param[in] nonInterestedNetwork Connectivity Type enum.
277 * @return ::CA_STATUS_OK or ::CA_NOT_SUPPORTED or ::CA_STATUS_FAILED
279 CAResult_t CAUnSelectNetwork(CATransportAdapter_t nonInterestedNetwork);
282 * Get network information.
283 * It should be destroyed by the caller as it Get Information.
284 * @param[out] info LocalConnectivity objects
285 * @param[out] size No Of Array objects
286 * @return ::CA_STATUS_OK or ::CA_STATUS_FAILED or
287 * ::CA_STATUS_INVALID_PARAM or ::CA_MEMORY_ALLOC_FAILED
289 CAResult_t CAGetNetworkInformation(CAEndpoint_t **info, uint32_t *size);
292 * To Handle the Request or Response.
293 * @return ::CA_STATUS_OK
295 CAResult_t CAHandleRequestResponse();
299 * Set Remote Access information for XMPP Client.
300 * @param[in] caraInfo remote access info.
302 * @return ::CA_STATUS_OK
304 CAResult_t CASetRAInfo(const CARAInfo_t *caraInfo);
311 * Select the cipher suite for dtls handshake.
313 * @param[in] cipher cipher suite (Note : Make sure endianness).
314 * 0xC018 : TLS_ECDH_anon_WITH_AES_128_CBC_SHA
315 * 0xC0A8 : TLS_PSK_WITH_AES_128_CCM_8
316 * 0xC0AE : TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
318 * @retval ::CA_STATUS_OK Successful.
319 * @retval ::CA_STATUS_INVALID_PARAM Invalid input arguments.
320 * @retval ::CA_STATUS_FAILED Operation failed.
322 CAResult_t CASelectCipherSuite(const uint16_t cipher);
325 * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls.
327 * @param[in] enable TRUE/FALSE enables/disables anonymous cipher suite.
329 * @retval ::CA_STATUS_OK Successful.
330 * @retval ::CA_STATUS_FAILED Operation failed.
332 * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
334 CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
338 * Generate ownerPSK using PRF.
339 * OwnerPSK = TLS-PRF('master key' , 'oic.sec.doxm.jw',
340 * 'ID of new device(Resource Server)',
341 * 'ID of owner smart-phone(Provisioning Server)')
343 * @param[in] endpoint information of network address.
344 * @param[in] label Ownership transfer method e.g)"oic.sec.doxm.jw".
345 * @param[in] labelLen Byte length of label.
346 * @param[in] rsrcServerDeviceID ID of new device(Resource Server).
347 * @param[in] rsrcServerDeviceIDLen Byte length of rsrcServerDeviceID.
348 * @param[in] provServerDeviceID label of previous owner.
349 * @param[in] provServerDeviceIDLen byte length of provServerDeviceID.
350 * @param[in,out] ownerPSK Output buffer for owner PSK.
351 * @param[in] ownerPSKSize Byte length of the ownerPSK to be generated.
353 * @retval ::CA_STATUS_OK Successful.
354 * @retval ::CA_STATUS_FAILED Operation failed.
356 CAResult_t CAGenerateOwnerPSK(const CAEndpoint_t *endpoint,
357 const uint8_t* label, const size_t labelLen,
358 const uint8_t* rsrcServerDeviceID,
359 const size_t rsrcServerDeviceIDLen,
360 const uint8_t* provServerDeviceID,
361 const size_t provServerDeviceIDLen,
362 uint8_t* ownerPSK, const size_t ownerPSKSize);
365 * Initiate DTLS handshake with selected cipher suite.
367 * @param[in] endpoint information of network address.
369 * @retval ::CA_STATUS_OK Successful.
370 * @retval ::CA_STATUS_FAILED Operation failed.
372 CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
375 * Close the DTLS session.
377 * @param[in] endpoint information of network address.
379 * @retval ::CA_STATUS_OK Successful.
380 * @retval ::CA_STATUS_FAILED Operation failed.
382 CAResult_t CACloseDtlsSession(const CAEndpoint_t *endpoint);
384 #endif /* __WITH_DTLS__ */
390 #endif /* CA_INTERFACE_H_ */