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 CAResult_t CAregisterPkixInfoHandler(CAgetPkixInfoHandler getPkixInfoHandler);
 138 #endif //__WITH_TLS__
 139
 140 #ifdef __WITH_X509__
 141 /**
 142  * Binary structure containing certificate chain and certificate credentials
 143  * for this device.
 144  */
 145 typedef struct
 146 {
 147     // certificate message  for DTLS
 148     unsigned char certificateChain[MAX_CERT_MESSAGE_LEN];
 149     // length of the certificate message
 150     uint32_t  certificateChainLen;
 151     // number of certificates in  certificate message
 152     uint8_t   chainLen;
 153     // x component of EC public key
 154     uint8_t   rootPublicKeyX[PUBLIC_KEY_SIZE / 2];
 155     // y component of EC public key
 156     uint8_t   rootPublicKeyY[PUBLIC_KEY_SIZE / 2];
 157     // EC private key
 158     uint8_t   devicePrivateKey[PRIVATE_KEY_SIZE];
 159
 160 } CADtlsX509Creds_t;
 161
 162 /**
 163  * @brief   Callback function type for getting certificate credentials.
 164  * @param   credInfo          [OUT] Certificate credentials info. Handler has to allocate new memory for
 165  *                                  credInfo which is then freed by CA
 166  * @return  NONE
 167  */
 168 typedef int (*CAGetDTLSX509CredentialsHandler)(CADtlsX509Creds_t *credInfo);
 169 /**
 170  * @brief   Callback function type for getting CRL.
 171  * @param   crlInfo          [OUT] Certificate credentials info. Handler has to allocate new memory for
 172  *                                  credInfo which is then freed by CA
 173  * @return  NONE
 174  */
 175 typedef void (*CAGetDTLSCrlHandler)(ByteArray* crlInfo);
 176
 177 /**
 178  * @brief   Register callback to get DTLS Cert credentials.
 179  * @param   GetCertCredentials   [IN] GetCert Credetials callback
 180  * @return  #CA_STATUS_OK
 181  */
 182 CAResult_t CARegisterDTLSX509CredentialsHandler(CAGetDTLSX509CredentialsHandler GetX509Credentials);
 183 /**
 184  * @brief   Register callback to get CRL.
 185  * @param   GetCrl   [IN] GetCrl callback
 186  * @return  #CA_STATUS_OK
 187  */
 188 CAResult_t CARegisterDTLSCrlHandler(CAGetDTLSCrlHandler GetCrl);
 189 #endif //__WITH_X509__
 190
 191
 192 #ifdef __WITH_DTLS__
 193
 194 /**
 195  * Select the cipher suite for dtls handshake.
 196  *
 197  * @param[in] cipher  cipher suite (Note : Make sure endianness).
 198  *                    0xC018 : TLS_ECDH_anon_WITH_AES_128_CBC_SHA
 199  *                    0xC0A8 : TLS_PSK_WITH_AES_128_CCM_8
 200  *                    0xC0AE : TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
 201  *
 202  * @retval  ::CA_STATUS_OK    Successful.
 203  * @retval  ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
 204  * @retval  ::CA_STATUS_FAILED Operation failed.
 205  */
 206 CAResult_t CASelectCipherSuite(const uint16_t cipher, CATransportAdapter_t adapter);
 207
 208 /**
 209  * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls.
 210  *
 211  * @param[in] enable  TRUE/FALSE enables/disables anonymous cipher suite.
 212  *
 213  * @retval  ::CA_STATUS_OK    Successful.
 214  * @retval  ::CA_STATUS_FAILED Operation failed.
 215  *
 216  * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
 217  */
 218 CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
 219
 220
 221 /**
 222  * Generate ownerPSK using PRF.
 223  * OwnerPSK = TLS-PRF('master key' , 'oic.sec.doxm.jw',
 224  *                    'ID of new device(Resource Server)',
 225  *                    'ID of owner smart-phone(Provisioning Server)')
 226  *
 227  * @param[in] endpoint  information of network address.
 228  * @param[in] label  Ownership transfer method e.g)"oic.sec.doxm.jw".
 229  * @param[in] labelLen  Byte length of label.
 230  * @param[in] rsrcServerDeviceID  ID of new device(Resource Server).
 231  * @param[in] rsrcServerDeviceIDLen  Byte length of rsrcServerDeviceID.
 232  * @param[in] provServerDeviceID  label of previous owner.
 233  * @param[in] provServerDeviceIDLen  byte length of provServerDeviceID.
 234  * @param[in,out] ownerPSK  Output buffer for owner PSK.
 235  * @param[in] ownerPSKSize  Byte length of the ownerPSK to be generated.
 236  *
 237  * @retval  ::CA_STATUS_OK    Successful.
 238  * @retval  ::CA_STATUS_FAILED Operation failed.
 239  */
 240 CAResult_t CAGenerateOwnerPSK(const CAEndpoint_t *endpoint,
 241                               const uint8_t* label, const size_t labelLen,
 242                               const uint8_t* rsrcServerDeviceID,
 243                               const size_t rsrcServerDeviceIDLen,
 244                               const uint8_t* provServerDeviceID,
 245                               const size_t provServerDeviceIDLen,
 246                               uint8_t* ownerPSK, const size_t ownerPSKSize);
 247
 248 /**
 249  * Initiate DTLS handshake with selected cipher suite.
 250  *
 251  * @param[in] endpoint  information of network address.
 252  *
 253  * @retval  ::CA_STATUS_OK    Successful.
 254  * @retval  ::CA_STATUS_FAILED Operation failed.
 255  */
 256 CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
 257
 258 /**
 259  * Close the DTLS session.
 260  *
 261  * @param[in] endpoint  information of network address.
 262  *
 263  * @retval  ::CA_STATUS_OK    Successful.
 264  * @retval  ::CA_STATUS_FAILED Operation failed.
 265  */
 266 CAResult_t CACloseDtlsSession(const CAEndpoint_t *endpoint);
 267
 268 #endif /* __WITH_DTLS__ */
 269
 270 #ifdef __WITH_TLS__
 271
 272 /**
 273  * Initiate TLS handshake with selected cipher suite.
 274  *
 275  * @param[in] endpoint information of network address.
 276  *
 277  * @retval  ::CA_STATUS_OK    Successful.
 278  * @retval  ::CA_STATUS_FAILED Operation failed.
 279  */
 280 CAResult_t CAinitiateTlsHandshake(const CAEndpoint_t *endpoint);
 281
 282 /**
 283  * Close the DTLS session.
 284  *
 285  * @param[in] endpoint  information of network address.
 286  *
 287  * @retval  ::CA_STATUS_OK    Successful.
 288  * @retval  ::CA_STATUS_FAILED Operation failed.
 289  */
 290 CAResult_t CAcloseTlsConnection(const CAEndpoint_t *endpoint);
 291
 292 #endif /* __WITH_TLS__ */
 293
 294 #ifdef __cplusplus
 295 } /* extern "C" */
 296 #endif
 297
 298
 299 #endif /* CA_SECURITY_INTERFACE_H_ */
 300