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