[IOT-3260] Delete roles at the TLS disconnect
[iotivity.git] / resource / csdk / security / include / internal / rolesresource.h
1 //******************************************************************
2 //
3 // Copyright 2017 Microsoft
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_ROLESR_H
22 #define IOTVT_SRM_ROLESR_H
23
24 #if defined(__WITH_DTLS__) || defined(__WITH_TLS__)
25
26 #include "cainterface.h"
27 #include "experimental/securevirtualresourcetypes.h"
28 #include "octypes.h"
29
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
34 typedef struct RoleCertChain {
35     uint32_t                credId;             /**< locally assigned ID number for use with DELETE */
36     OicSecKey_t             certificate;        /**< certificate chain including leaf and intermediate CA certificates */
37
38     struct RoleCertChain    *next;              /**< next chain in list */
39 } RoleCertChain_t;
40
41 /**
42  * Initialize the roles resource.
43  *
44  * @return OC_STACK_OK if successful; error otherwise
45  */
46 OCStackResult InitRolesResource(void);
47
48 /**
49  * De-initialize the roles resource.
50  *
51  * @return OC_STACK_OK if successful; error otherwise
52  */
53 OCStackResult DeInitRolesResource(void);
54
55 /**
56  * Register the PSK credential being used for authentication. This is used by the cred resource
57  * to inform the roles resource a symmetric PSK has a particular role associated with it.
58  *
59  * @param[in]  cred         PSK credential to register
60  *
61  * @return OC_STACK_OK if role credential is successfully registered; error otherwise.
62  */
63 OCStackResult RegisterSymmetricCredentialRole(const OicSecCred_t *cred);
64
65 /**
66  * Retrieve the roles asserted by a given endpoint with certificates.
67  *
68  * @param[in] endpoint      Endpoint to retrieve roles for
69  * @param[out] roles        Pointer to receive array of OicSecRole_t objects containing roles for this endpoint
70  *                          On success, caller must free the received array with OICFree when finished
71  * @param[out] roleCount    Variable to receive length of roles array.
72  *
73  * @note If the endpoint is found but has not asserted any roles with certificates,
74  *       OC_STACK_OK will be returned, but NULL will be returned in roles and 0 in roleCount.
75  *
76  * @return OC_STACK_OK if list of roles is successfully populated; error otherwise.
77  */
78 OCStackResult GetEndpointRoles(const CAEndpoint_t *endpoint, OicSecRole_t **roles, size_t *roleCount);
79
80 /**
81  * This function converts a CBOR payload into a list of role certificates.
82  * Caller needs to call 'OICFree' on *roleCertList after use.
83  *
84  * @param[in] cborPayload Received CBOR payload to extract the role cert list from
85  * @param[in] size Size of cborPayload
86  * @param[out] roleCertList Pointer to receive linked list of RoleCertChain_t objects
87  *             On success, caller must call FreeRoleCertChainList on *roleCertList when finished
88  *
89  * @return OC_STACK_OK if payload is successfully converted; error code otherwise
90  */
91 OCStackResult CBORPayloadToRoles(const uint8_t *cborPayload, size_t size, RoleCertChain_t **roleCertList);
92
93 /**
94  * This function converts a list of role certificates into a CBOR payload.
95  * Caller needs to call 'OICFree' on *cborPayload after use.
96  *
97  * @param[in] roles Linked list of RoleCertChain_t objects
98  * @param[out] cborPayload Pointer to receive the CBOR payload
99  *             On success, caller must call OICFree on *cborPayload when finished
100  * @param[out] size Pointer to receive size of cborPayload
101  *
102  * @return OC_STACK_OK if payload is successfully converted; error code otherwise
103  */
104 OCStackResult RolesToCBORPayload(const RoleCertChain_t *roles, uint8_t **cborPayload, size_t *cborSize);
105
106 /**
107  * Free the memory used by a list of RoleCertChain_t objects created by CBORPayloadToRoles.
108  *
109  * @param[in] roleCertList List received from CBORPayloadToRoles
110  */
111 void FreeRoleCertChainList(RoleCertChain_t *roleCertList);
112
113 /**
114  * Callback to delete all roles on TLS session closure
115  *
116  * @param[out] uuid     peer's UUID
117  * @param[out] uuidLen  peer's UUID length
118  *
119  * @return  NONE
120 */
121 void DeleteRolesCB(const unsigned char *uuid, size_t uuidLen);
122
123 #ifdef __cplusplus
124 }
125 #endif
126
127 #endif /* defined(__WITH_DTLS__) || defined(__WITH_TLS__) */
128
129 #endif /* IOTVT_SRM_ROLESR_H */