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