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  * This internal callback is used by CA layer to
  70  * retrieve all credential types from SRM
  71  *
  72  * @param[out]  list of enabled credential types for CA handshake
  73  *
  74  */
  75 typedef void (*CAgetCredentialTypesHandler)(bool * list);
  76 /**
  77  * Binary structure containing PKIX related info
  78  * own certificate chain, public key, CA's and CRL's
  79  */
  80 typedef struct
  81 {
  82     // own certificate chain
  83     ByteArray_t crt;
  84     // own public key
  85     ByteArray_t key;
  86     // trusted CA's
  87     ByteArray_t ca;
  88     // trusted CRL's
  89     ByteArray_t crl;
  90 } PkiInfo_t;
  91
  92 /**
  93  * Register callback to receive credential types.
  94  * @param[in] credTypesCallback callback to get cerdential types
  95  * @return ::CA_STATUS_OK
  96  */
  97 CAResult_t CAregisterGetCredentialTypesCallback(CAgetCredentialTypesHandler credTypesCallback);
  98 /**
  99  * Register callback to receive the result of TLS handshake.
 100  * @param[in] tlsHandshakeCallback callback for get tls handshake result
 101  * @return ::CA_STATUS_OK
 102  */
 103 CAResult_t CAregisterSslHandshakeCallback(CAErrorCallback tlsHandshakeCallback);
 104
 105 /**
 106  * Register callback to get TLS PSK credentials.
 107  * @param[in]   getTLSCredentials    GetDTLS Credetials callback.
 108  * @return  ::CA_STATUS_OK
 109  */
 110 CAResult_t CAregisterPskCredentialsHandler(CAgetPskCredentialsHandler getTlsCredentials);
 111
 112 /**
 113  * @brief   Callback function type for getting PKIX info
 114  *
 115  * @param   inf[out]   PKIX related info
 116  *
 117  * @return  NONE
 118  */
 119 typedef void (*CAgetPkixInfoHandler)(PkiInfo_t * inf);
 120
 121 //TODO
 122 CAResult_t CAregisterPkixInfoHandler(CAgetPkixInfoHandler getPkixInfoHandler);
 123
 124 /**
 125  * Select the cipher suite for dtls handshake.
 126  *
 127  * @param[in] cipher  cipher suite (Note : Make sure endianness).
 128  *                    0xC018 : TLS_ECDH_anon_WITH_AES_128_CBC_SHA
 129  *                    0xC0A8 : TLS_PSK_WITH_AES_128_CCM_8
 130  *                    0xC0AE : TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8
 131  *
 132  * @retval  ::CA_STATUS_OK    Successful.
 133  * @retval  ::CA_STATUS_INVALID_PARAM  Invalid input arguments.
 134  * @retval  ::CA_STATUS_FAILED Operation failed.
 135  */
 136 CAResult_t CASelectCipherSuite(const uint16_t cipher, CATransportAdapter_t adapter);
 137
 138 /**
 139  * Enable TLS_ECDH_anon_WITH_AES_128_CBC_SHA cipher suite in dtls.
 140  *
 141  * @param[in] enable  TRUE/FALSE enables/disables anonymous cipher suite.
 142  *
 143  * @retval  ::CA_STATUS_OK    Successful.
 144  * @retval  ::CA_STATUS_FAILED Operation failed.
 145  *
 146  * @note anonymous cipher suite should only be enabled for 'JustWorks' provisioning.
 147  */
 148 CAResult_t CAEnableAnonECDHCipherSuite(const bool enable);
 149
 150
 151 /**
 152  * Generate ownerPSK using PRF.
 153  * OwnerPSK = TLS-PRF('master key' , 'oic.sec.doxm.jw',
 154  *                    'ID of new device(Resource Server)',
 155  *                    'ID of owner smart-phone(Provisioning Server)')
 156  *
 157  * @param[in] endpoint  information of network address.
 158  * @param[in] label  Ownership transfer method e.g)"oic.sec.doxm.jw".
 159  * @param[in] labelLen  Byte length of label.
 160  * @param[in] rsrcServerDeviceID  ID of new device(Resource Server).
 161  * @param[in] rsrcServerDeviceIDLen  Byte length of rsrcServerDeviceID.
 162  * @param[in] provServerDeviceID  label of previous owner.
 163  * @param[in] provServerDeviceIDLen  byte length of provServerDeviceID.
 164  * @param[in,out] ownerPSK  Output buffer for owner PSK.
 165  * @param[in] ownerPskSize  Byte length of the ownerPSK to be generated.
 166  *
 167  * @retval  ::CA_STATUS_OK    Successful.
 168  * @retval  ::CA_STATUS_FAILED Operation failed.
 169  */
 170 CAResult_t CAGenerateOwnerPSK(const CAEndpoint_t *endpoint,
 171                               const uint8_t* label, const size_t labelLen,
 172                               const uint8_t* rsrcServerDeviceID,
 173                               const size_t rsrcServerDeviceIDLen,
 174                               const uint8_t* provServerDeviceID,
 175                               const size_t provServerDeviceIDLen,
 176                               uint8_t* ownerPSK, const size_t ownerPskSize);
 177
 178 /**
 179  * Initiate DTLS handshake with selected cipher suite.
 180  *
 181  * @param[in] endpoint  information of network address.
 182  *
 183  * @retval  ::CA_STATUS_OK    Successful.
 184  * @retval  ::CA_STATUS_FAILED Operation failed.
 185  */
 186 CAResult_t CAInitiateHandshake(const CAEndpoint_t *endpoint);
 187
 188 /**
 189  * Close the DTLS session.
 190  *
 191  * @param[in] endpoint  information of network address.
 192  *
 193  * @retval  ::CA_STATUS_OK    Successful.
 194  * @retval  ::CA_STATUS_FAILED Operation failed.
 195  */
 196 CAResult_t CAcloseSslSession(const CAEndpoint_t *endpoint);
 197
 198 /**
 199  * Initiate TLS handshake with selected cipher suite.
 200  *
 201  * @param[in] endpoint information of network address.
 202  *
 203  * @retval  ::CA_STATUS_OK    Successful.
 204  * @retval  ::CA_STATUS_FAILED Operation failed.
 205  */
 206 CAResult_t CAinitiateSslHandshake(const CAEndpoint_t *endpoint);
 207
 208 /**
 209  * Close the DTLS session.
 210  *
 211  * @param[in] endpoint  information of network address.
 212  *
 213  * @retval  ::CA_STATUS_OK    Successful.
 214  * @retval  ::CA_STATUS_FAILED Operation failed.
 215  */
 216 CAResult_t CAcloseSslConnection(const CAEndpoint_t *endpoint);
 217
 218 #ifdef __cplusplus
 219 } /* extern "C" */
 220 #endif
 221
 222
 223 #endif /* CA_SECURITY_INTERFACE_H_ */
 224