Use `URI` all caps in documentation
[iotivity.git] / resource / csdk / security / include / internal / secureresourcemanager.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 SECURITYRESOURCEMANAGER_H_
22 #define SECURITYRESOURCEMANAGER_H_
23
24 #include "experimental/securevirtualresourcetypes.h"
25 #include "cainterface.h"
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 typedef enum SubjectIdentityType
32 {
33     SUBJECT_ID_TYPE_ERROR = 0,
34     SUBJECT_ID_TYPE_UUID,     // Subject refers to a UUID
35     SUBJECT_ID_TYPE_ROLE,     // Subject refers to a Role
36 } SubjectIdentityType_t;
37
38 /**
39  * The context for a single request to be processed by the Security
40  * Resource Manager.
41  */
42 typedef struct SRMRequestContext
43 {
44     const CAEndpoint_t      *endPoint;                          // ptr to the Endpoint for this request
45     OicSecSvrType_t         resourceType;                       // SVR type (or "not an SVR")
46     char                    resourceUri[MAX_URI_LENGTH + 1];    // URI of the requested resource
47     uint16_t                requestedPermission;                // bitmask permissions of request
48     CAResponseInfo_t        responseInfo;                       // The response for this request
49     bool                    responseSent;                       // Is servicing this request complete?
50     SRMAccessResponse_t     responseVal;                        // The SRM internal response code
51     const CARequestInfo_t   *requestInfo;                       // ptr to info for this request
52     bool                    resourceIsOcSecure;                 // Was Resource created w OC_SECURE bit set?
53     bool                    resourceIsOcNonsecure;              // Was Resource created w OC_NONSECURE bit set?
54     bool                    secureChannel;                      // Was request recv'd over secure channel?
55     bool                    slowResponseSent;                   // Is a full response still needed?
56     OicSecDiscoverable_t    discoverable;                       // Is resource discoverable?
57     SubjectIdentityType_t   subjectIdType;                      // The type of Subject ID in this
58                                                                 // request.
59     OicUuid_t               subjectUuid;                        // The UUID of the Subject (valid
60                                                                 // iff IdType is UUID_TYPE).
61     // Developer note: when adding support for an additional type (e.g.
62     // ROLE_TYPE) suggest adding a new var to hold the Subject ID for that type.
63 #ifdef MULTIPLE_OWNER
64     uint8_t*                payload;
65     size_t                  payloadSize;
66 #endif //MULTIPLE_OWNER
67 } SRMRequestContext_t;
68
69 /**
70  * Register Persistent storage callback.
71  *
72  * @param[in] persistentStorageHandler  Pointers to open, read, write, close & unlink handlers.
73  *
74  * @return ::OC_STACK_OK  is no errors and successful. ::OC_STACK_INVALID_PARAM for invalid parameter.
75  */
76 OCStackResult SRMRegisterPersistentStorageHandler(OCPersistentStorage* persistentStorageHandler);
77
78 /**
79  * Get Persistent storage handler pointer.
80  *
81  * @return The pointer to Persistent Storage callback handler.
82  */
83 OCPersistentStorage* SRMGetPersistentStorageHandler(void);
84
85 /**
86  * Register request and response callbacks. Requests and responses are delivered in these callbacks.
87  *
88  * @param reqHandler Request handler callback ( for GET,PUT ..etc)
89  * @param respHandler Response handler callback.
90  * @param errHandler Error handler callback.
91  *
92  * @return ::OC_STACK_OK  is no errors and successful. ::OC_STACK_INVALID_PARAM for invalid parameter.
93  */
94 OCStackResult SRMRegisterHandler(CARequestCallback reqHandler,
95                                  CAResponseCallback respHandler,
96                                  CAErrorCallback errHandler);
97
98 /**
99  * Initialize all secure resources ( /oic/sec/cred, /oic/sec/acl, /oic/sec/pstat etc).
100  * @return  ::OC_STACK_OK for Success, otherwise some error value.
101  */
102 OCStackResult SRMInitSecureResources(void);
103
104 /**
105  * Perform cleanup for secure resources ( /oic/sec/cred, /oic/sec/acl, /oic/sec/pstat etc).
106  */
107 void SRMDeInitSecureResources(void);
108
109 /**
110  * Provisioning API response callback.
111  *
112  * @param object endpoint instance.
113  * @param responseInfo instance of CAResponseInfo_t structure.
114  *
115  * @return true if received response is for provisioning API false otherwise.
116  */
117 typedef bool (*SPResponseCallback) (const CAEndpoint_t *object,
118                                     const CAResponseInfo_t *responseInfo);
119 /**
120  * Get the resource type from the URI.
121  * @param[in]   uri Pointers to security resource URI.
122  * @return  SVR type (note that "NOT_A_SVR_RESOURCE" is returned if not a SVR)
123  */
124 OicSecSvrType_t GetSvrTypeFromUri(const char* uri);
125
126 extern const OicSecRole_t EMPTY_ROLE;
127
128 /**
129  * Determine if a role is non-empty.
130  *
131  * @param[in]  role     Role to check
132  *
133  * @return true if role is non-empty, false if role is empty
134  */
135 bool IsNonEmptyRole(const OicSecRole_t *role);
136
137 #ifdef __cplusplus
138 }
139 #endif
140
141 #endif /* SECURITYRESOURCEMANAGER_H_ */