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
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /**
  33  * Initialize credential resource by loading data from persistent storage.
  34  *
  35  * @return ::OC_STACK_OK, if initialization is successful, else ::OC_STACK_ERROR if
  36  * initialization fails.
  37  */
  38 OCStackResult InitCredResource();
  39
  40 /**
  41  * Perform cleanup for credential resources.
  42  *
  43  * @return ::OC_STACK_OK, if no errors. ::OC_STACK_ERROR, if stack process error.
  44  * ::OC_STACK_NO_RESOURCE, if resource not found.
  45  * ::OC_STACK_INVALID_PARAM, if invalid param.
  46  */
  47 OCStackResult DeInitCredResource();
  48
  49 /**
  50  * This method is used by tinydtls/SRM to retrieve credential for given subject.
  51  *
  52  * @param subjectId for which credential is required.
  53  *
  54  * @return reference to @ref OicSecCred_t, if credential is found, else NULL, if credential
  55  * not found.
  56  */
  57 const OicSecCred_t* GetCredResourceData(const OicUuid_t* subjectId);
  58
  59 /**
  60  * This function converts credential data into CBOR format.
  61  * Caller needs to invoke 'free' when done using returned string.
  62  *
  63  * @param cred is the pointer to instance of OicSecCred_t structure.
  64  * @param cborPayload is the CBOR converted value.
  65  * @param cborSize is the size of the CBOR.
  66  *
  67  * @return ::OC_STACK_OK if conversion is successful, else ::OC_STACK_ERROR if unsuccessful.
  68  */
  69 OCStackResult CredToCBORPayload(const OicSecCred_t* cred, uint8_t **cborPayload,
  70                                 size_t *cborSize);
  71
  72 /**
  73  * This function generates the bin credential data.
  74  *
  75  * @param subject pointer to subject of this credential.
  76  * @param credType credential type.
  77  * @param publicData public data such as public key.
  78  * @param privateData private data such as private key.
  79  * @param ownersLen length of owners array
  80  * @param owners array of owners.
  81  *
  82  * @return pointer to instance of @ref OicSecCred_t if successful. else NULL in case of error.
  83
  84  */
  85 OicSecCred_t * GenerateCredential(const OicUuid_t* subject, OicSecCredType_t credType,
  86                      const uint8_t * publicData, const uint8_t * privateData,
  87                      size_t ownersLen, const OicUuid_t * owners);
  88
  89 /**
  90  * This function adds the new cred to the credential list.
  91  *
  92  * @param cred is the pointer to new credential.
  93  *
  94  * @return ::OC_STACK_OK, cred not NULL and persistent storage gets updated.
  95  * ::OC_STACK_ERROR, cred is NULL or fails to update persistent storage.
  96  */
  97 OCStackResult AddCredential(OicSecCred_t * cred);
  98
  99 /**
 100  * Function to remove the credential from SVR DB.
 101  *
 102  * @param credId is the Credential ID to be deleted.
 103  *
 104  * @return ::OC_STACK_OK for success, or errorcode otherwise.
 105  */
 106 OCStackResult RemoveCredential(const OicUuid_t *credId);
 107
 108 /**
 109  * Remove all credential data on credential resource and persistent storage
 110  *
 111  * @retval
 112  *     OC_STACK_OK              - no errors
 113  *     OC_STACK_ERROR           - stack process error
 114  */
 115 OCStackResult RemoveAllCredentials(void);
 116
 117 #if defined(__WITH_DTLS__)
 118 /**
 119  * This internal callback is used by lower stack (i.e. CA layer) to
 120  * retrieve PSK credentials from RI security layer.
 121  *
 122  * @param type of PSK data required by CA layer during DTLS handshake.
 123  * @param desc Additional request information.
 124  * @param desc_len is the actual length of desc.
 125  * @param result  is must be filled with the requested information.
 126  * @param result_length is the maximum size of @p result.
 127  *
 128  * @return The number of bytes written to @p result or a value
 129  *         less than zero on error.
 130  */
 131 int32_t GetDtlsPskCredentials( CADtlsPskCredType_t type,
 132               const unsigned char *desc, size_t desc_len,
 133               unsigned char *result, size_t result_length);
 134
 135 /**
 136  * Add temporal PSK to PIN based OxM.
 137  *
 138  * @param tmpSubject is the UUID of target device
 139  * @param credType is the type of credential to be added
 140  * @param pin is the numeric characters
 141  * @param pinSize is the length of 'pin'
 142  * @param ownersLen is the number of owners
 143  * @param owners is the array of owners
 144  * @param tmpCredSubject is the generated credential's subject.
 145  *
 146  * @return ::OC_STACK_OK for success or else errorcode.
 147  */
 148 OCStackResult AddTmpPskWithPIN(const OicUuid_t* tmpSubject, OicSecCredType_t credType,
 149                             const char * pin, size_t pinSize,
 150                             size_t ownersLen, const OicUuid_t * owners,
 151                             OicUuid_t* tmpCredSubject);
 152
 153 #endif /* __WITH_DTLS__ */
 154
 155 #ifdef __WITH_X509__
 156 /**
 157  * This function is used toretrieve certificate credentials from RI security layer.
 158  *
 159  * @param credInfo is the binary structure containing certificate credentials
 160  *
 161  * @return 0 on success.
 162  */
 163 int GetDtlsX509Credentials(CADtlsX509Creds_t *credInfo);
 164 #endif /*__WITH_X509__*/
 165
 166 /**
 167  * Function to deallocate allocated memory to OicSecCred_t.
 168  *
 169  * @param cred pointer to cred type.
 170  *
 171  */
 172 void DeleteCredList(OicSecCred_t* cred);
 173
 174 #ifdef __cplusplus
 175 }
 176 #endif
 177
 178 #endif //IOTVT_SRM_CREDR_H