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