resource/csdk/security/include/internal/credresource.h

   1 //******************************************************************
   2 //
   3 // Copyright 2015 Intel Mobile Communications GmbH 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 #ifndef IOTVT_SRM_CREDR_H
  22 #define IOTVT_SRM_CREDR_H
  23
  24 #include "cainterface.h"
  25 #include "securevirtualresourcetypes.h"
  26 #include "octypes.h"
  27 #include <cbor.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /**
  34  * Initialize credential resource by loading data from persistent storage.
  35  *
  36  * @return ::OC_STACK_OK, if initialization is successful, else ::OC_STACK_ERROR if
  37  * initialization fails.
  38  */
  39 OCStackResult InitCredResource();
  40
  41 /**
  42  * Perform cleanup for credential resources.
  43  *
  44  * @return ::OC_STACK_OK, if no errors. ::OC_STACK_ERROR, if stack process error.
  45  * ::OC_STACK_NO_RESOURCE, if resource not found.
  46  * ::OC_STACK_INVALID_PARAM, if invalid param.
  47  */
  48 OCStackResult DeInitCredResource();
  49
  50 /**
  51  * This method is used by tinydtls/SRM to retrieve credential for given subject.
  52  *
  53  * @param subjectId for which credential is required.
  54  *
  55  * @return reference to @ref OicSecCred_t, if credential is found, else NULL, if credential
  56  * not found.
  57  */
  58 OicSecCred_t* GetCredResourceData(const OicUuid_t* subjectId);
  59
  60 /**
  61  * This method is used by SRM to retrieve credential entry for given credId.
  62  *
  63  * @note Caller needs to release this memory by calling DeleteCredList().
  64  *
  65  * @param credId for which credential is required.
  66  *
  67  * @return reference to @ref OicSecCred_t, if credential is found, else NULL, if credential
  68  * not found.
  69  */
  70 OicSecCred_t* GetCredEntryByCredId(const uint16_t credId);
  71
  72 /**
  73  * This function converts credential data into CBOR format.
  74  * Caller needs to invoke 'free' when done using returned string.
  75  *
  76  * @param cred is the pointer to instance of OicSecCred_t structure.
  77  * @param cborPayload is the CBOR converted value.
  78  * @param cborSize is the size of the CBOR.
  79  * @param secureFlag shows fill or not private key.
  80  *
  81  * @return ::OC_STACK_OK if conversion is successful, else ::OC_STACK_ERROR if unsuccessful.
  82  */
  83 OCStackResult CredToCBORPayload(const OicSecCred_t* cred, uint8_t **cborPayload,
  84                                 size_t *cborSize, int secureFlag);
  85
  86 #ifdef MULTIPLE_OWNER
  87 /**
  88  * Function to check the credential access of SubOwner
  89  *
  90  * @param[in] uuid SubOwner's UUID
  91  * @param[in] cborPayload CBOR payload of credential
  92  * @param[in] size Byte length of cborPayload
  93  *
  94  * @return ::true for valid access, otherwise invalid access
  95  */
  96 bool IsValidCredentialAccessForSubOwner(const OicUuid_t* uuid, const uint8_t *cborPayload, size_t size);
  97 #endif //MULTIPLE_OWNER
  98
  99 /**
 100  * This function generates the bin credential data.
 101  *
 102  * @param subject pointer to subject of this credential.
 103  * @param credType credential type.
 104  * @param publicData public data such as public key.
 105  * @param privateData private data such as private key.
 106  * @param rownerID Resource owner's UUID.
 107  * @param eownerID Entry owner's UUID.
 108  *
 109  * @return pointer to instance of @ref OicSecCred_t if successful. else NULL in case of error.
 110
 111  */
 112 OicSecCred_t * GenerateCredential(const OicUuid_t* subject, OicSecCredType_t credType,
 113                      const OicSecKey_t * publicData, const OicSecKey_t * privateData,
 114                      const OicUuid_t * rownerID, const OicUuid_t * eownerID);
 115
 116 /**
 117  * This function adds the new cred to the credential list.
 118  *
 119  * @param cred is the pointer to new credential.
 120  *
 121  * @return ::OC_STACK_OK, cred not NULL and persistent storage gets updated.
 122  * ::OC_STACK_ERROR, cred is NULL or fails to update persistent storage.
 123  */
 124 OCStackResult AddCredential(OicSecCred_t * cred);
 125
 126 /**
 127  * Function to remove the credential from SVR DB.
 128  *
 129  * @param subject is the Credential Subject to be deleted.
 130  *
 131  * @return ::OC_STACK_OK for success, or errorcode otherwise.
 132  */
 133 OCStackResult RemoveCredential(const OicUuid_t *subject);
 134
 135 /**
 136  * Function to remove the credential from SVR DB.
 137  *
 138  * @param credId is the Credential ID to be deleted.
 139  *
 140  * @return ::OC_STACK_OK for success, or errorcode otherwise.
 141  */
 142 OCStackResult RemoveCredentialByCredId(uint16_t credId);
 143
 144 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
 145 /**
 146  * This internal callback is used by lower stack (i.e. CA layer) to
 147  * retrieve PSK credentials from RI security layer.
 148  *
 149  * @param type of PSK data required by CA layer during DTLS handshake.
 150  * @param desc Additional request information.
 151  * @param desc_len is the actual length of desc.
 152  * @param result  is must be filled with the requested information.
 153  * @param result_length is the maximum size of @p result.
 154  *
 155  * @return The number of bytes written to @p result or a value
 156  *         less than zero on error.
 157  */
 158 int32_t GetDtlsPskCredentials( CADtlsPskCredType_t type,
 159               const unsigned char *desc, size_t desc_len,
 160               unsigned char *result, size_t result_length);
 161
 162 /**
 163  * Add temporal PSK to PIN based OxM.
 164  *
 165  * @param tmpSubject is the UUID of target device
 166  * @param credType is the type of credential to be added
 167  * @param pin is the numeric characters
 168  * @param pinSize is the length of 'pin'
 169  * @param rownerID Resource owner's UUID
 170  * @param tmpCredSubject is the generated credential's subject.
 171  *
 172  * @return ::OC_STACK_OK for success or else errorcode.
 173  */
 174 OCStackResult AddTmpPskWithPIN(const OicUuid_t* tmpSubject, OicSecCredType_t credType,
 175                             const char * pin, size_t pinSize,
 176                             const OicUuid_t * rownerID,
 177                             OicUuid_t* tmpCredSubject);
 178
 179 #endif // __WITH_DTLS__ or __WITH_TLS__
 180
 181 /**
 182  * Function to getting credential list
 183  *
 184  * @return instance of @ref OicSecCred_t
 185  */
 186 const OicSecCred_t* GetCredList();
 187
 188 /**
 189  * Function to deallocate allocated memory to OicSecCred_t.
 190  *
 191  * @param cred pointer to cred type.
 192  *
 193  */
 194 void DeleteCredList(OicSecCred_t* cred);
 195
 196 /**
 197  * Internal function to update resource owner
 198  *
 199  * @param newROwner new owner
 200  *
 201  * @retval ::OC_STACK_OK for Success, otherwise some error value
 202  */
 203 OCStackResult SetCredRownerId(const OicUuid_t* newROwner);
 204
 205 /**
 206  * Gets the OicUuid_t value for the rownerid of the cred resource.
 207  *
 208  * @param rowneruuid a pointer to be assigned to the rowneruuid property
 209  * @return ::OC_STACK_OK if rowneruuid is assigned correctly, else ::OC_STACK_ERROR.
 210  */
 211 OCStackResult GetCredRownerId(OicUuid_t *rowneruuid);
 212
 213 #if defined(__WITH_TLS__) || defined(__WITH_DTLS__)
 214 /**
 215  * Used by role certificate validator to get CA certificates as PEM
 216  *
 217  * @param[out] crt certificates to be filled.
 218  * @param[in] usage credential usage string.
 219  */
 220 OCStackResult GetPemCaCert(ByteArray_t * crt, const char * usage);
 221 /**
 222  * Used by mbedTLS to retrieve own certificate chain
 223  *
 224  * @param[out] crt certificate chain to be filled.
 225  * @param[in] usage credential usage string.
 226  */
 227 void GetPemOwnCert(ByteArray_t * crt, const char * usage);
 228 /**
 229  * Used by mbedTLS to retrieve owm private key
 230  *
 231  * @param[out] key key to be filled.
 232  * @param[in] usage credential usage string.
 233  */
 234 void GetDerKey(ByteArray_t * key, const char * usage);
 235 /**
 236  * Used by CA to retrieve credential types
 237  *
 238  * @param[out] key key to be filled.
 239  * @param[in] usage credential usage string.
 240  */
 241 void InitCipherSuiteListInternal(bool *list, const char * usage);
 242 #endif // __WITH_TLS__
 243
 244 // Helpers shared by cred and roles resources
 245 CborError SerializeEncodingToCbor(CborEncoder *rootMap, const char *tag, const OicSecKey_t *value);
 246 CborError SerializeSecOptToCbor(CborEncoder *rootMap, const char *tag, const OicSecOpt_t *value);
 247 CborError DeserializeEncodingFromCbor(CborValue *rootMap, OicSecKey_t *value);
 248 CborError DeserializeSecOptFromCbor(CborValue *rootMap, OicSecOpt_t *value);
 249
 250 #ifdef __cplusplus
 251 }
 252 #endif
 253
 254 #endif //IOTVT_SRM_CREDR_H