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 #ifdef __WITH_X509__
  31 #include "pki.h"
  32 #endif //__WITH_X509__
  33
  34 #include "cacommon.h"
  35
  36 #ifdef __WITH_TLS__
  37 #include "byte_array.h"
  38 #endif
  39
  40 #ifdef __cplusplus
  41 extern "C"
  42 {
  43 #endif
  44
  45
  46 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
  47 /**
  48  * @enum CADtlsPskCredType_t
  49  * Type of PSK credential required during DTLS handshake
  50  * It does not make much sense in bringing in all definitions from dtls.h into here.
  51  * Therefore, redefining them here.
  52  */
  53 typedef enum
  54 {
  55     CA_DTLS_PSK_HINT,
  56     CA_DTLS_PSK_IDENTITY,
  57     CA_DTLS_PSK_KEY
  58 } CADtlsPskCredType_t;
  59
  60 /**
  61  * This internal callback is used by CA layer to
  62  * retrieve PSK credentials from SRM.
  63  *
  64  * @param[in]  type type of PSK data required by CA layer during DTLS handshake set.
  65  * @param[in]  desc    Additional request information.
  66  * @param[in]  desc_len The actual length of desc.
  67  * @param[out] result  Must be filled with the requested information.
  68  * @param[in]  result_length  Maximum size of @p result.
  69  *
  70  * @return The number of bytes written to @p result or a value
  71  *         less than zero on error.
  72  */
  73 typedef int (*CAGetDTLSPskCredentialsHandler)(CADtlsPskCredType_t type,
  74               const uint8_t *desc, size_t desc_len,
  75               uint8_t *result, size_t result_length);
  76 #endif // __WITH_DTLS__ or __WITH_TLS__
  77 #ifdef __WITH_DTLS__
  78
  79 /**
  80  * Register callback to receive the result of DTLS handshake.
  81  * @param[in] dtlsHandshakeCallback callback for get dtls handshake result
  82  * @return ::CA_STATUS_OK
  83  */
  84 CAResult_t CARegisterDTLSHandshakeCallback(CAErrorCallback dtlsHandshakeCallback);
  85
  86 /**
  87  * Register callback to get DTLS PSK credentials.
  88  * @param[in]   GetDTLSCredentials    GetDTLS Credetials callback.
  89  * @return  ::CA_STATUS_OK
  90  */
  91 CAResult_t CARegisterDTLSCredentialsHandler(CAGetDTLSPskCredentialsHandler GetDTLSCredentials);
  92
  93 #endif //__WITH_DTLS__
  94
  95
  96 #ifdef __WITH_TLS__
  97 /**
  98  * Binary structure containing PKIX related info
  99  * own certificate chain, public key, CA's and CRL's
 100  */
 101 typedef struct
 102 {
 103     // own certificate chain
 104     ByteArray crt;
 105     // own public key
 106     ByteArray key;
 107     // trusted CA's
 108     ByteArray ca;
 109     // trusted CRL's
 110     ByteArray crl;
 111 } PkiInfo_t;
 112
 113 /**
 114  * Register callback to receive the result of TLS handshake.
 115  * @param[in] tlsHandshakeCallback callback for get tls handshake result
 116  * @return ::CA_STATUS_OK
 117  */
 118 CAResult_t CAregisterTlsHandshakeCallback(CAErrorCallback tlsHandshakeCallback);
 119
 120 /**
 121  * Register callback to get TLS PSK credentials.
 122  * @param[in]   getTLSCredentials    GetDTLS Credetials callback.
 123  * @return  ::CA_STATUS_OK
 124  */
 125 CAResult_t CAregisterTlsCredentialsHandler(CAGetDTLSPskCredentialsHandler getTlsCredentials);
 126
 127 /**
 128  * @brief   Callback function type for getting PKIX info
 129  *
 130  * @param   inf[out]   PKIX related info
 131  *
 132  * @return  NONE
 133  */
 134 typedef void (*CAgetPkixInfoHandler)(PkiInfo_t * inf);
 135
 136 //TODO
 137 void GetPkixInfo(PkiInfo_t * inf);
 138 CAResult_t CAregisterPkixInfoHandler(CAgetPkixInfoHandler getPkixInfoHandler);
 139 #endif //__WITH_TLS__
 140
 141 #ifdef __WITH_X509__
 142 /**
 143  * Binary structure containing certificate chain and certificate credentials
 144  * for this device.
 145  */
 146 typedef struct
 147 {
 148     // certificate message  for DTLS
 149     unsigned char certificateChain[MAX_CERT_MESSAGE_LEN];
 150     // length of the certificate message
 151     uint32_t  certificateChainLen;
 152     // number of certificates in  certificate message
 153     uint8_t   chainLen;
 154     // x component of EC public key
 155     uint8_t   rootPublicKeyX[PUBLIC_KEY_SIZE / 2];
 156     // y component of EC public key
 157     uint8_t   rootPublicKeyY[PUBLIC_KEY_SIZE / 2];
 158     // EC private key
 159     uint8_t   devicePrivateKey[PRIVATE_KEY_SIZE];
 160
 161 } CADtlsX509Creds_t;
 162
 163 /**
 164  * @brief   Callback function type for getting certificate credentials.
 165  * @param   credInfo          [OUT] Certificate credentials info. Handler has to allocate new memory for
 166  *                                  credInfo which is then freed by CA
 167  * @return  NONE
 168  */
 169 typedef int (*CAGetDTLSX509CredentialsHandler)(CADtlsX509Creds_t *credInfo);
 170 /**
 171  * @brief   Callback function type for getting CRL.
 172  * @param   crlInfo          [OUT] Certificate credentials info. Handler has to allocate new memory for
 173  *                                  credInfo which is then freed by CA
 174  * @return  NONE
 175  */
 176 typedef void (*CAGetDTLSCrlHandler)(ByteArray* crlInfo);
 177
 178 /**
 179  * @brief   Register callback to get DTLS Cert credentials.
 180  * @param   GetCertCredentials   [IN] GetCert Credetials callback
 181  * @return  #CA_STATUS_OK
 182  */
 183 CAResult_t CARegisterDTLSX509CredentialsHandler(CAGetDTLSX509CredentialsHandler GetX509Credentials);
 184 /**
 185  * @brief   Register callback to get CRL.
 186  * @param   GetCrl   [IN] GetCrl callback
 187  * @return  #CA_STATUS_OK
 188  */
 189 CAResult_t CARegisterDTLSCrlHandler(CAGetDTLSCrlHandler GetCrl);
 190 #endif //__WITH_X509__
 191
 192
 193 #ifdef __WITH_DTLS__
 194
 195 /**
 196  * Select the cipher suite for dtls handshake.
 197  *
 198  * @param[in] cipher  cipher suite (Note : Make sure endianness).
 199  *                    0xC018 : TLS_ECDH_anon_WITH_AES_128_CBC_SHA
 200  *                    0xC0A8 : TLS_PSK_WITH_AES_128_CCM_8
 201  *                    0xC0AE : TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
 202  *
 203  * @retval  ::CA_STATUS_OK    Successful.
 204  * @retval  ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
 205  * @retval  ::CA_STATUS_FAILED Operation failed.
 206  */
 207 CAResult_t CASelectCipherSuite(const uint16_t cipher, CATransportAdapter_t adapter);
 208
 209 /**
 210  * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls.
 211  *
 212  * @param[in] enable  TRUE/FALSE enables/disables anonymous cipher suite.
 213  *
 214  * @retval  ::CA_STATUS_OK    Successful.
 215  * @retval  ::CA_STATUS_FAILED Operation failed.
 216  *
 217  * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
 218  */
 219 CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
 220
 221
 222 /**
 223  * Generate ownerPSK using PRF.
 224  * OwnerPSK = TLS-PRF('master key' , 'oic.sec.doxm.jw',
 225  *                    'ID of new device(Resource Server)',
 226  *                    'ID of owner smart-phone(Provisioning Server)')
 227  *
 228  * @param[in] endpoint  information of network address.
 229  * @param[in] label  Ownership transfer method e.g)"oic.sec.doxm.jw".
 230  * @param[in] labelLen  Byte length of label.
 231  * @param[in] rsrcServerDeviceID  ID of new device(Resource Server).
 232  * @param[in] rsrcServerDeviceIDLen  Byte length of rsrcServerDeviceID.
 233  * @param[in] provServerDeviceID  label of previous owner.
 234  * @param[in] provServerDeviceIDLen  byte length of provServerDeviceID.
 235  * @param[in,out] ownerPSK  Output buffer for owner PSK.
 236  * @param[in] ownerPSKSize  Byte length of the ownerPSK to be generated.
 237  *
 238  * @retval  ::CA_STATUS_OK    Successful.
 239  * @retval  ::CA_STATUS_FAILED Operation failed.
 240  */
 241 CAResult_t CAGenerateOwnerPSK(const CAEndpoint_t *endpoint,
 242                               const uint8_t* label, const size_t labelLen,
 243                               const uint8_t* rsrcServerDeviceID,
 244                               const size_t rsrcServerDeviceIDLen,
 245                               const uint8_t* provServerDeviceID,
 246                               const size_t provServerDeviceIDLen,
 247                               uint8_t* ownerPSK, const size_t ownerPSKSize);
 248
 249 /**
 250  * Initiate DTLS handshake with selected cipher suite.
 251  *
 252  * @param[in] endpoint  information of network address.
 253  *
 254  * @retval  ::CA_STATUS_OK    Successful.
 255  * @retval  ::CA_STATUS_FAILED Operation failed.
 256  */
 257 CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
 258
 259 /**
 260  * Close the DTLS session.
 261  *
 262  * @param[in] endpoint  information of network address.
 263  *
 264  * @retval  ::CA_STATUS_OK    Successful.
 265  * @retval  ::CA_STATUS_FAILED Operation failed.
 266  */
 267 CAResult_t CACloseDtlsSession(const CAEndpoint_t *endpoint);
 268
 269 #endif /* __WITH_DTLS__ */
 270
 271 #ifdef __WITH_TLS__
 272
 273 /**
 274  * Initiate TLS handshake with selected cipher suite.
 275  *
 276  * @param[in] endpoint information of network address.
 277  *
 278  * @retval  ::CA_STATUS_OK    Successful.
 279  * @retval  ::CA_STATUS_FAILED Operation failed.
 280  */
 281 CAResult_t CAinitiateTlsHandshake(const CAEndpoint_t *endpoint);
 282
 283 /**
 284  * Close the DTLS session.
 285  *
 286  * @param[in] endpoint  information of network address.
 287  *
 288  * @retval  ::CA_STATUS_OK    Successful.
 289  * @retval  ::CA_STATUS_FAILED Operation failed.
 290  */
 291 CAResult_t CAcloseTlsConnection(const CAEndpoint_t *endpoint);
 292
 293 #endif /* __WITH_TLS__ */
 294
 295 #ifdef __cplusplus
 296 } /* extern "C" */
 297 #endif
 298
 299
 300 #endif /* CA_SECURITY_INTERFACE_H_ */
 301