resource/csdk/connectivity/api/casecurityinterface.h

   1 /* *****************************************************************
   2  *
   3  * Copyright 2015 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 Security APIs for Resource Model to use.
  25  */
  26
  27 #ifndef CA_SECURITY_INTERFACE_H_
  28 #define CA_SECURITY_INTERFACE_H_
  29
  30
  31 #include "cacommon.h"
  32 #include "byte_array.h"
  33
  34 #ifdef __cplusplus
  35 extern "C"
  36 {
  37 #endif
  38
  39 /**
  40  * @enum CADtlsPskCredType_t
  41  * Type of PSK credential required during DTLS handshake
  42  * It does not make much sense in bringing in all definitions from dtls.h into here.
  43  * Therefore, redefining them here.
  44  */
  45 typedef enum
  46 {
  47     CA_DTLS_PSK_HINT,
  48     CA_DTLS_PSK_IDENTITY,
  49     CA_DTLS_PSK_KEY
  50 } CADtlsPskCredType_t;
  51
  52 /**
  53  * This internal callback is used by CA layer to
  54  * retrieve PSK credentials from SRM.
  55  *
  56  * @param[in]  type type of PSK data required by CA layer during DTLS handshake set.
  57  * @param[in]  desc    Additional request information.
  58  * @param[in]  desc_len The actual length of desc.
  59  * @param[out] result  Must be filled with the requested information.
  60  * @param[in]  result_length  Maximum size of @p result.
  61  *
  62  * @return The number of bytes written to @p result or a value
  63  *         less than zero on error.
  64  */
  65 typedef int (*CAgetPskCredentialsHandler)(CADtlsPskCredType_t type,
  66               const uint8_t *desc, size_t desc_len,
  67               uint8_t *result, size_t result_length);
  68
  69 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
  70 #ifdef MULTIPLE_OWNER
  71 /**
  72  * API to get a secure connected peer information
  73  *
  74  * @param[in] peer peer information includs IP address and port.
  75  *
  76  * @return  secure connected peer information on success, otherwise NULL
  77  */
  78 const CASecureEndpoint_t *CAGetSecureEndpointData(const CAEndpoint_t *peer);
  79 #endif //MULTIPLE_OWNER
  80
  81 /**
  82  * Adds a bit to the attributes field of a secure endpoint.
  83  *
  84  * @param[in]  peer         remote address
  85  * @param[in]  newAttribute bit to be added to the attributes field
  86  *
  87  * @return  true if the secure endpoint has been found, false otherwise.
  88  */
  89 bool CASetSecureEndpointAttribute(const CAEndpoint_t* peer, uint32_t newAttribute);
  90
  91 /**
  92  * Gets the attributes field of a secure endpoint.
  93  *
  94  * @param[in]  peer          remote address
  95  * @param[out] allAttributes all the attributes bits for that remote address
  96  *
  97  * @return  true if the secure endpoint has been found, false otherwise.
  98  */
  99 bool CAGetSecureEndpointAttributes(const CAEndpoint_t* peer, uint32_t* allAttributes);
 100 #endif // #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
 101
 102 /**
 103  * This internal callback is used by CA layer to
 104  * retrieve all credential types from SRM
 105  *
 106  * @param[out]  list of enabled credential types for CA handshake
 107  *
 108  */
 109 typedef void (*CAgetCredentialTypesHandler)(bool * list);
 110 /**
 111  * Binary structure containing PKIX related info
 112  * own certificate chain, public key, CA's and CRL's
 113  */
 114 typedef struct
 115 {
 116     // own certificate chain
 117     ByteArray_t crt;
 118     // own public key
 119     ByteArray_t key;
 120     // trusted CA's
 121     ByteArray_t ca;
 122     // trusted CRL's
 123     ByteArray_t crl;
 124 } PkiInfo_t;
 125
 126 /**
 127  * Register callback to get types of TLS suites.
 128  * @param[in]   getCredTypesHandler    Get types of TLS suites callback.
 129  * @return  ::CA_STATUS_OK or appropriate error code.
 130  */
 131 CAResult_t CAregisterGetCredentialTypesHandler(CAgetCredentialTypesHandler getCredTypesHandler);
 132
 133 /**
 134  * Register callback to receive the result of TLS handshake.
 135  * @param[in] tlsHandshakeCallback callback for get tls handshake result
 136  * @return ::CA_STATUS_OK
 137  */
 138 CAResult_t CAregisterSslHandshakeCallback(CAErrorCallback tlsHandshakeCallback);
 139
 140 /**
 141  * Register callback to get TLS PSK credentials.
 142  * @param[in]   getTlsCredentials    GetDTLS Credetials callback.
 143  * @return  ::CA_STATUS_OK
 144  */
 145 CAResult_t CAregisterPskCredentialsHandler(CAgetPskCredentialsHandler getTlsCredentials);
 146
 147 /**
 148  * @brief   Callback function type for getting PKIX info
 149  *
 150  * @param   inf[out]   PKIX related info
 151  *
 152  * @return  NONE
 153  */
 154 typedef void (*CAgetPkixInfoHandler)(PkiInfo_t * inf);
 155
 156 /**
 157  * Register callback to get PKIX related info.
 158  * @param[in]   getPkixInfoHandler    Get PKIX related info callback.
 159  * @return  ::CA_STATUS_OK or appropriate error code.
 160  */
 161 CAResult_t CAregisterPkixInfoHandler(CAgetPkixInfoHandler getPkixInfoHandler);
 162
 163 /**
 164  * Select the cipher suite for dtls handshake.
 165  *
 166  * @param[in] cipher  cipher suite (Note : Make sure endianness).
 167  *                        TLS_RSA_WITH_AES_256_CBC_SHA256          0x3D
 168  *                        TLS_RSA_WITH_AES_128_GCM_SHA256          0x009C
 169  *                        TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256  0xC02B
 170  *                        TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8       0xC0AE
 171  *                        TLS_ECDHE_ECDSA_WITH_AES_128_CCM         0xC0AC
 172  *                        TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256  0xC023
 173  *                        TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384  0xC024
 174  *                        TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384  0xC02C
 175  *                        TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256    0xC037
 176  *                        TLS_ECDH_anon_WITH_AES_128_CBC_SHA       0xC018
 177  * @param[in] adapter  transport adapter (TCP/IP/BLE)
 178  *
 179  * @retval  ::CA_STATUS_OK    Successful.
 180  * @retval  ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
 181  * @retval  ::CA_STATUS_FAILED Operation failed.
 182  */
 183 CAResult_t CASelectCipherSuite(const uint16_t cipher, CATransportAdapter_t adapter);
 184
 185 /**
 186  * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls.
 187  *
 188  * @param[in] enable  TRUE/FALSE enables/disables anonymous cipher suite.
 189  *
 190  * @retval  ::CA_STATUS_OK    Successful.
 191  * @retval  ::CA_STATUS_FAILED Operation failed.
 192  *
 193  * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
 194  */
 195 CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
 196
 197
 198 /**
 199  * Generate ownerPSK using PRF.
 200  * OwnerPSK = TLS-PRF('master key' , 'oic.sec.doxm.jw',
 201  *                    'ID of new device(Resource Server)',
 202  *                    'ID of owner smart-phone(Provisioning Server)')
 203  *
 204  * @param[in] endpoint  information of network address.
 205  * @param[in] label  Ownership transfer method e.g)"oic.sec.doxm.jw".
 206  * @param[in] labelLen  Byte length of label.
 207  * @param[in] rsrcServerDeviceID  ID of new device(Resource Server).
 208  * @param[in] rsrcServerDeviceIDLen  Byte length of rsrcServerDeviceID.
 209  * @param[in] provServerDeviceID  label of previous owner.
 210  * @param[in] provServerDeviceIDLen  byte length of provServerDeviceID.
 211  * @param[in,out] ownerPSK  Output buffer for owner PSK.
 212  * @param[in] ownerPskSize  Byte length of the ownerPSK to be generated.
 213  *
 214  * @retval  ::CA_STATUS_OK    Successful.
 215  * @retval  ::CA_STATUS_FAILED Operation failed.
 216  */
 217 CAResult_t CAGenerateOwnerPSK(const CAEndpoint_t *endpoint,
 218                               const uint8_t* label, const size_t labelLen,
 219                               const uint8_t* rsrcServerDeviceID,
 220                               const size_t rsrcServerDeviceIDLen,
 221                               const uint8_t* provServerDeviceID,
 222                               const size_t provServerDeviceIDLen,
 223                               uint8_t* ownerPSK, const size_t ownerPskSize);
 224
 225 /**
 226  * Initiate DTLS handshake with selected cipher suite.
 227  *
 228  * @param[in] endpoint  information of network address.
 229  *
 230  * @retval  ::CA_STATUS_OK    Successful.
 231  * @retval  ::CA_STATUS_FAILED Operation failed.
 232  */
 233 CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
 234
 235 /**
 236  * Close the DTLS session.
 237  *
 238  * @param[in] endpoint  information of network address.
 239  *
 240  * @retval  ::CA_STATUS_OK    Successful.
 241  * @retval  ::CA_STATUS_FAILED Operation failed.
 242  */
 243 CAResult_t CAcloseSslSession(const CAEndpoint_t *endpoint);
 244
 245 /**
 246  * Initiate TLS handshake with selected cipher suite.
 247  *
 248  * @param[in] endpoint information of network address.
 249  *
 250  * @retval  ::CA_STATUS_OK    Successful.
 251  * @retval  ::CA_STATUS_FAILED Operation failed.
 252  */
 253 CAResult_t CAinitiateSslHandshake(const CAEndpoint_t *endpoint);
 254
 255 /**
 256  * Close the DTLS session.
 257  *
 258  * @param[in] endpoint  information of network address.
 259  *
 260  * @retval  ::CA_STATUS_OK    Successful.
 261  * @retval  ::CA_STATUS_FAILED Operation failed.
 262  */
 263 CAResult_t CAcloseSslConnection(const CAEndpoint_t *endpoint);
 264
 265
 266 /**
 267  * Close All of DTLS sessions.
 268  */
 269 void CAcloseSslConnectionAll(CATransportAdapter_t transportType);
 270
 271 #ifdef __cplusplus
 272 } /* extern "C" */
 273 #endif
 274
 275
 276 #endif /* CA_SECURITY_INTERFACE_H_ */
 277