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