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 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
  31 #include "mbedtls/ssl.h"
  32 #include "mbedtls/x509_crt.h"
  33 #endif //__WITH_DTLS__ or __WITH_TLS__
  34 #include "cacommon.h"
  35 #include "byte_array.h"
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #endif
  41
  42 /**
  43  * @enum CADtlsPskCredType_t
  44  * Type of PSK credential required during DTLS handshake
  45  * It does not make much sense in bringing in all definitions from dtls.h into here.
  46  * Therefore, redefining them here.
  47  */
  48 typedef enum
  49 {
  50     CA_DTLS_PSK_HINT,
  51     CA_DTLS_PSK_IDENTITY,
  52     CA_DTLS_PSK_KEY
  53 } CADtlsPskCredType_t;
  54
  55 /**
  56  *@enum CASslEkcbRole_t
  57  * type of SSL role to be used when invoking export key callback
  58  */
  59 typedef enum
  60 {
  61     CA_SSL_EKCB_CLIENT = 0,
  62     CA_SSL_EKCB_SERVER = 1
  63 }CASslEkcbRole_t;
  64
  65 /**
  66  *@enum CASslEkcbProtocol_t
  67  * type of SSL protocol(TLS or DTLS) to be used when invoking export key callback
  68  */
  69 typedef enum
  70 {
  71     CA_SSL_EKCB_TLS = 0,
  72     CA_SSL_EKCB_DTLS = 1
  73 }CASslEkcbProtocol_t;
  74
  75 /**
  76  * This internal callback is used by CA layer to
  77  * retrieve PSK credentials from SRM.
  78  *
  79  * @param[in]  type type of PSK data required by CA layer during DTLS handshake set.
  80  * @param[in]  desc    Additional request information.
  81  * @param[in]  desc_len The actual length of desc.
  82  * @param[out] result  Must be filled with the requested information.
  83  * @param[in]  result_length  Maximum size of @p result.
  84  *
  85  * @return The number of bytes written to @p result or a value
  86  *         less than zero on error.
  87  */
  88 typedef int (*CAgetPskCredentialsHandler)(CADtlsPskCredType_t type,
  89               const uint8_t *desc, size_t desc_len,
  90               uint8_t *result, size_t result_length);
  91
  92 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
  93 #ifdef MULTIPLE_OWNER
  94 /**
  95  * API to get a secure connected peer information
  96  *
  97  * @param[in] peer peer information includs IP address and port.
  98  *
  99  * @return  secure connected peer information on success, otherwise NULL
 100  */
 101 const CASecureEndpoint_t *CAGetSecureEndpointData(const CAEndpoint_t *peer);
 102 #endif //MULTIPLE_OWNER
 103 #endif
 104
 105 /**
 106  * This internal callback is used by CA layer to
 107  * retrieve all credential types from SRM
 108  *
 109  * @param[out]  list of enabled credential types for CA handshake
 110  *
 111  */
 112 typedef void (*CAgetCredentialTypesHandler)(bool * list);
 113 /**
 114  * Binary structure containing PKIX related info
 115  * own certificate chain, public key, CA's and CRL's
 116  */
 117 typedef struct
 118 {
 119     // own certificate chain
 120     ByteArray_t crt;
 121     // own public key
 122     ByteArray_t key;
 123     // trusted CA's
 124     ByteArray_t ca;
 125     // trusted CRL's
 126     ByteArray_t crl;
 127 } PkiInfo_t;
 128
 129 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
 130 /**
 131  * this callback will be invoked to utilize peer certificate information
 132  */
 133 typedef int (*PeerCertCallback)(void *ctx, const mbedtls_x509_crt *peerCert,
 134         int depth);
 135
 136 /**
 137  * API to set callback used to utilize peer certificate information
 138  * @param[in] peerCertCallback callback to utilize certificate information
 139  *
 140  * return CA_STATUS_OK on success
 141  */
 142 CAResult_t CAsetPeerCertCallback(void *ctx, PeerCertCallback peerCertCallback);
 143 #endif
 144
 145 /**
 146  * Register callback to receive credential types.
 147  * @param[in] credTypesCallback callback to get cerdential types
 148  * @return ::CA_STATUS_OK
 149  */
 150 CAResult_t CAregisterGetCredentialTypesHandler(CAgetCredentialTypesHandler credTypesCallback);
 151 /**
 152  * Register callback to receive the result of TLS handshake.
 153  * @param[in] tlsHandshakeCallback callback for get tls handshake result
 154  * @return ::CA_STATUS_OK
 155  */
 156 CAResult_t CAregisterSslHandshakeCallback(CAErrorCallback tlsHandshakeCallback);
 157
 158 /**
 159  * Register callback to get TLS PSK credentials.
 160  * @param[in]   getTLSCredentials    GetDTLS Credetials callback.
 161  * @return  ::CA_STATUS_OK
 162  */
 163 CAResult_t CAregisterPskCredentialsHandler(CAgetPskCredentialsHandler getTlsCredentials);
 164
 165 /**
 166  * @brief   Callback function type for getting PKIX info
 167  *
 168  * @param   inf[out]   PKIX related info
 169  *
 170  * @return  NONE
 171  */
 172 typedef void (*CAgetPkixInfoHandler)(PkiInfo_t * inf);
 173
 174 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
 175 /**
 176  * @brief   Callback function type for setup PK context
 177  *
 178  * @param   pkCtx[in]   mbedtls's PK context
 179  *
 180  * @return  0 on success
 181  */
 182 typedef int (*CAsetupPkContextHandler)(mbedtls_pk_context * pkCtx);
 183
 184 /**
 185  * Register callback to setup PK Context
 186  * @param[in]   setupPkContextCallback    Callback function to setup PK context.
 187  * @return  ::CA_STATUS_OK or appropriate error code.
 188  */
 189 CAResult_t CAregisterSetupPkContextHandler(CAsetupPkContextHandler setupPkContextHandler);
 190 #endif //__WITH_DTLS__ or __WITH_TLS__
 191
 192 /**
 193  * Register callback to get PKIX related info.
 194  * @param[in]   getPkixInfoHandler    Get PKIX related info callback.
 195  * @return  ::CA_STATUS_OK or appropriate error code.
 196  */
 197 CAResult_t CAregisterPkixInfoHandler(CAgetPkixInfoHandler getPkixInfoHandler);
 198 /**
 199  * Register callback to get types of TLS suites.
 200  * @param[in]   getCredTypesHandler    Get types of TLS suites callback.
 201  * @return  ::CA_STATUS_OK or appropriate error code.
 202  */
 203 CAResult_t CAregisterGetCredentialTypesHandler(CAgetCredentialTypesHandler getCredTypesHandler);
 204
 205 /**
 206  * Select the cipher suite for dtls handshake.
 207  *
 208  * @param[in] cipher  cipher suite (Note : Make sure endianness).
 209  *                        TLS_RSA_WITH_AES_256_CBC_SHA256          0x3D
 210  *                        TLS_RSA_WITH_AES_128_GCM_SHA256          0x009C
 211  *                        TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256  0xC02B
 212  *                        TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8       0xC0AE
 213  *                        TLS_ECDHE_ECDSA_WITH_AES_128_CCM         0xC0AC
 214  *                        TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256  0xC023
 215  *                        TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384  0xC024
 216  *                        TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384  0xC02C
 217  *                        TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256    0xC037
 218  *                        TLS_ECDH_anon_WITH_AES_128_CBC_SHA       0xC018
 219  * @param[in] adapter  transport adapter (TCP/IP/BLE)
 220  *
 221  * @retval  ::CA_STATUS_OK    Successful.
 222  * @retval  ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
 223  * @retval  ::CA_STATUS_FAILED Operation failed.
 224  */
 225 CAResult_t CASelectCipherSuite(const uint16_t cipher, CATransportAdapter_t adapter);
 226
 227 /**
 228  * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls.
 229  *
 230  * @param[in] enable  TRUE/FALSE enables/disables anonymous cipher suite.
 231  *
 232  * @retval  ::CA_STATUS_OK    Successful.
 233  * @retval  ::CA_STATUS_FAILED Operation failed.
 234  *
 235  * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
 236  */
 237 CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
 238
 239
 240 /**
 241  * Generate ownerPSK using PRF.
 242  * OwnerPSK = TLS-PRF('master key' , 'oic.sec.doxm.jw',
 243  *                    'ID of new device(Resource Server)',
 244  *                    'ID of owner smart-phone(Provisioning Server)')
 245  *
 246  * @param[in] endpoint  information of network address.
 247  * @param[in] label  Ownership transfer method e.g)"oic.sec.doxm.jw".
 248  * @param[in] labelLen  Byte length of label.
 249  * @param[in] rsrcServerDeviceID  ID of new device(Resource Server).
 250  * @param[in] rsrcServerDeviceIDLen  Byte length of rsrcServerDeviceID.
 251  * @param[in] provServerDeviceID  label of previous owner.
 252  * @param[in] provServerDeviceIDLen  byte length of provServerDeviceID.
 253  * @param[in,out] ownerPSK  Output buffer for owner PSK.
 254  * @param[in] ownerPskSize  Byte length of the ownerPSK to be generated.
 255  *
 256  * @retval  ::CA_STATUS_OK    Successful.
 257  * @retval  ::CA_STATUS_FAILED Operation failed.
 258  */
 259 CAResult_t CAGenerateOwnerPSK(const CAEndpoint_t *endpoint,
 260                               const uint8_t* label, const size_t labelLen,
 261                               const uint8_t* rsrcServerDeviceID,
 262                               const size_t rsrcServerDeviceIDLen,
 263                               const uint8_t* provServerDeviceID,
 264                               const size_t provServerDeviceIDLen,
 265                               uint8_t* ownerPSK, const size_t ownerPskSize);
 266
 267 /**
 268  * Initiate DTLS handshake with selected cipher suite.
 269  *
 270  * @param[in] endpoint  information of network address.
 271  *
 272  * @retval  ::CA_STATUS_OK    Successful.
 273  * @retval  ::CA_STATUS_FAILED Operation failed.
 274  */
 275 CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
 276
 277 /**
 278  * Close the DTLS session.
 279  *
 280  * @param[in] endpoint  information of network address.
 281  *
 282  * @retval  ::CA_STATUS_OK    Successful.
 283  * @retval  ::CA_STATUS_FAILED Operation failed.
 284  */
 285 CAResult_t CAcloseSslSession(const CAEndpoint_t *endpoint);
 286
 287 /**
 288  * Initiate TLS handshake with selected cipher suite.
 289  *
 290  * @param[in] endpoint information of network address.
 291  *
 292  * @retval  ::CA_STATUS_OK    Successful.
 293  * @retval  ::CA_STATUS_FAILED Operation failed.
 294  */
 295 CAResult_t CAinitiateSslHandshake(const CAEndpoint_t *endpoint);
 296
 297 /**
 298  * Close the DTLS session.
 299  *
 300  * @param[in] endpoint  information of network address.
 301  *
 302  * @retval  ::CA_STATUS_OK    Successful.
 303  * @retval  ::CA_STATUS_FAILED Operation failed.
 304  */
 305 CAResult_t CAcloseSslConnection(const CAEndpoint_t *endpoint);
 306
 307 /**
 308  * Close the TLS session using UUID
 309  *
 310  * @param[in] identity  UUID of target device
 311  * @param[in] idLength Byte length of 'identity'
 312  *
 313  * @retval  ::CA_STATUS_OK    Successful.
 314  * @retval  ::CA_STATUS_FAILED Operation failed.
 315  */
 316 CAResult_t CAcloseSslConnectionUsingUuid(const uint8_t *identity, size_t idLength);
 317
 318 /**
 319  * Close All of DTLS sessions.
 320  */
 321 void CAcloseSslConnectionAll(CATransportAdapter_t transportType);
 322
 323 #if defined(__WITH_TLS__) || defined(__WITH_DTLS__)
 324
 325 /**
 326  * @brief           Callback type: Export key block and master secret
 327  * @note            This is required for certain uses of TLS, e.g. EAP-TLS
 328  *                  (RFC 5216) and Thread. The key pointers are ephemeral and
 329  *                  therefore must not be stored. The master secret and keys
 330  *                  should not be used directly except as an input to a key
 331  *                  derivation function.
 332  *
 333  * @aram[in] masterSecret        Pointer to master secret (fixed length: 48 bytes)
 334  * @param[in] keyBlock        Pointer to key block, see RFC 5246 section 6.3
 335  *                  (variable length: 2 * maclen + 2 * keylen + 2 * ivlen).
 336  * @param[in] maclen    MAC length
 337  * @param[in] keylen    Key length
 338  * @param[in] ivlen     IV length
 339  */
 340 typedef void (*SslExportKeysCallback_t)(const unsigned char* masterSecret,
 341                                         const unsigned char* keyBlock,
 342                                         size_t macLen, size_t keyLen, size_t ivLen);
 343
 344 /**
 345  * API to set a export SSL(TLS/DTLS) key callback.
 346  * This callback will be invoked when SSL handshake occured.
 347  *
 348  * @param[in] exportKeysCb implementation of SslExportKeysCallback_t
 349  * @param[in] protocol CA_SSL_EKCB_TLS=TLS, CA_SSL_EKCB_DTLS=DTLS (@ref CASslEkcbProtocol_t)
 350  * @param[in] role CA_SSL_EKCB_CLIENT=client, CA_SSL_EKCB_SERVER=server (@ref CASslEkcbRole_t)
 351  *
 352  * @return CA_STATUS_OK on success, otherwise fail.
 353  */
 354 CAResult_t CASetSslExportKeysCallback(SslExportKeysCallback_t exportKeysCb,
 355                                       CASslEkcbProtocol_t protocol, CASslEkcbRole_t role);
 356
 357 #endif //__WITH_TLS__ or __WITH_DTLS__
 358
 359
 360 #ifdef __cplusplus
 361 } /* extern "C" */
 362 #endif
 363
 364
 365 #endif /* CA_SECURITY_INTERFACE_H_ */
 366