2 * Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License
17 * \file cynara-offline-admin.h
18 * \author Lukasz Wojciechowski <l.wojciechow@partner.samsung.com>
19 * \author Aleksander Zdyb <a.zdyb@samsung.com>
21 * \brief This file contains administration APIs of cynara available
22 * with libcynara-offline-admin.
25 #ifndef CYNARA_OFFLINE_ADMIN_H
26 #define CYNARA_OFFLINE_ADMIN_H
28 #include <cynara-admin-error.h>
29 #include <cynara-admin-types.h>
36 * \name cynara_offline_admin
37 * forward declaration of structure allowing initialization of library
38 * and usage of all libcynara-offline-admin API functions
40 struct cynara_offline_admin;
44 * Initialize cynara-offline-admin library.
45 * Creates structure used in following API calls.
48 * This function must be invoked prior to other admin API calls. It creates structure needed by
49 * other cynara-offline-admin library API functions.
51 * \par Typical use case:
52 * Once before a service can call other cynara-offline-admin library functions.
54 * \par Method of function operation:
55 * This API initializes inner library structures and in case of success creates cynara_offline_admin
56 * structure and stores pointer to this structure at memory address passed
57 * in pp_cynara_offline_admin parameter.
59 * \par Sync (or) Async:
60 * This is a synchronous API.
62 * \par Important notes:
63 * Structure cynara_offline_admin created by cynara_offline_admin_initialize call should be released
64 * with cynara_offline_admin_finish.
66 * \param[out] pp_cynara_offline_admin address of pointer for created cynara_offline_admin
69 * \return CYNARA_ADMIN_API_SUCCESS on success, or negative error code otherwise.
71 * \brief Initialize cynara-offline-admin library.
73 int cynara_offline_admin_initialize(struct cynara_offline_admin **pp_cynara_offline_admin);
77 * Releases cynara-offline-admin library and destroys structure created
78 * with cynara_offline_admin_initialize function.
81 * This API should be used to clean up after usage of cynara-offline-admin library.
83 * \par Typical use case:
84 * Function should be called once, when done with cynara-offline-admin library API usage.
86 * \par Method of function operation:
87 * This API releases inner library structures and destroys cynara_offline_admin structure.
89 * \par Sync (or) Async:
90 * This is a synchronous API.
92 * \par Important notes:
93 * No invocations of cynara-offline-admin library API functions are allowed after call to
94 * cynara_offline_admin_finish.
96 * \param[in] p_cynara_offline_admin cynara_offline_admin structure created
97 * in cynara_offline_admin_initialize.
99 * \return CYNARA_ADMIN_API_SUCCESS on success, or negative error code otherwise.
101 * \brief Release cynara-offline-admin library.
103 int cynara_offline_admin_finish(struct cynara_offline_admin *p_cynara_offline_admin);
107 * Manages policies in cynara.
110 * This API should be used to insert, update or delete policies in cynara.
112 * \par Typical use case:
113 * Enables altering policies by adding, updating or removing records.
115 * \par Method of function operation:
116 * Policies are arranged into buckets. Every policy is defined in context of some bucket identified
117 * with bucket field (string). A bucket consists of policies identified with tripple: (client, user,
118 * privilege), which is a (unique) key within considered bucket.
120 * Every policy can be one of two types: simple or bucket-pointing policy.
121 * Simple policies have result field with value of CYNARA_ADMIN_DENY or CYNARA_ADMIN_ALLOW.
122 * result_extra field should be NULL in this case.
123 * Bucket-pointing policies have result field with value of CYNARA_ADMIN_BUCKET and name of bucket
124 * they point to in result_extra field.
126 * Type of operation, which is run for every record (single policy) is defined by result field in
127 * cynara_admin_policy structure.
128 * In case of CYNARA_ADMIN_DENY or CYNARA_ADMIN_ALLOW a simple policy is updated or inserted into
130 * In case of CYNARA_ADMIN_BUCKET, a bucket-pointing policy is updated or inserted into cynara
132 * In case of CYNARA_ADMIN_DELETE, a policy is removed from cynara database.
133 * One call of cynara_offline_admin_set_policies can manage many different policies
134 * in different buckets.
136 * However, considered buckets must exist before referring to them in policies.
138 * \par Sync (or) Async:
139 * This is a synchronous API.
141 * \par Important notes:
142 * When plugin API will be specified, there will be more valid types to pass as result.
143 * Numerical values of defines CYNARA_ADMIN_... may change, so usage of defines names is strongly
146 * \param[in] p_cynara_offline_admin cynara offline admin structure.
147 * \param[in] policies NULL terminated array of pointers to policy structures.
149 * \return CYNARA_ADMIN_API_SUCCESS on success, or negative error code otherwise.
151 * \brief Insert, update or delete policies in cynara database.
153 int cynara_offline_admin_set_policies(struct cynara_offline_admin *p_cynara_offline_admin,
154 const struct cynara_admin_policy *const *policies);
158 * Adds new, updates or removes existing bucket for policies in cynara.
161 * This API should be used to add, remove or update buckets.
163 * \par Typical use case:
164 * Enables altering policies database by adding, updating or removing buckets.
166 * \par Method of function operation:
167 * Every bucket has a default policy. During search, if no policy matches the searched key (client,
168 * user, privilege), default policy is returned.
170 * Operation run on a single bucket defined with bucket parameter.
172 * Operation parameter defines what should happen with bucket. In case of:
173 * CYNARA_ADMIN_DENY, a bucket is inserted or updated with CYNARA_ADMIN_DENY default policy;
174 * CYNARA_ADMIN_ALLOW, a bucket is inserted or updated with CYNARA_ADMIN_ALLOW default policy;
175 * CYNARA_ADMIN_DELETE, a bucket is removed with all policies that were kept in it.
177 * \par Sync (or) Async:
178 * This is a synchronous API.
180 * \par Important notes:
181 * When plugin API will be specified, there will be more valid types to pass as operation / default
182 * policy. Numerical values of defines CYNARA_ADMIN_... may change, so usages of provided consts is
183 * strongly recommended.
185 * Default bucket identified with CYNARA_ADMIN_DEFAULT_BUCKET exists always. Its default policy
186 * is preset to DENY (can be altered, however). Default bucket cannot be removed.
188 * Extra parameter will be used to pass additional data to cynara extensions to build more complex
189 * policies, such as ALLOW but for 5 minutes only, or ALLOW if user confirms.
191 * \param[in] p_cynara_offline_admin cynara offline admin structure.
192 * \param[in] bucket bucket name
193 * \param[in] operation type of operation (default policy or CYNARA_ADMIN_DELETE)
194 * \param[in] extra additional data for default policy (will be available with cynara extensions)
196 * \return CYNARA_ADMIN_API_SUCCESS on success, or negative error code otherwise.
198 * \brief Add, remove or update buckets in cynara database.
200 int cynara_offline_admin_set_bucket(struct cynara_offline_admin *p_cynara_offline_admin,
201 const char *bucket, int operation, const char *extra);
205 * Raw check client, user access for given privilege without using plugins extensions.
208 * This API should be used to check type of matching policy for check request.
210 * \par Typical use case:
211 * Administrator of cynara want to know, what would cynara return to client, if asked about given
214 * \par Method of function operation:
215 * Function works almost the same way as cynara_check() client function.
216 * The differences are:
217 * - user can specify bucket, from which search would be started (in case of cynara_check()
218 * it is always the default bucket)
219 * - user can specify if search should be recursive: disabling recursive check will constrain search
220 * to single bucket only, ignoring all policies leading to other buckets (in case of
221 * cynara_check() search is always recursive)
222 * - when matching policy in cynara is found, its result is returned without being interpreted by
225 * \par Sync (or) Async:
226 * This is a synchronous API.
228 * \par Important notes:
229 * (*result_extra) may be set to NULL, if extra data are not used in matched policy
230 * If (*result_extra) is not NULL, it contains a string allocated by cynara offline admin library
231 * with malloc(3) function and must be released with free(3) function.
233 * \param[in] p_cynara_offline_admin cynara offline admin structure.
234 * \param[in] start_bucket name of bucket where search would start.
235 * \param[in] recursive FALSE (== 0) : search is not recursive (single bucket search);
236 * TRUE (!= 0) : search does not ignore policies leading to another buckets.
237 * \param[in] client application or process identifier.
238 * \param[in] user user running client.
239 * \param[in] privilege privilege that is a subject of a check.
240 * \param[out] result placeholder for matched policy type
241 * \param[out] result_extra placeholder for matched policy additional data (see Important Notes!)
243 * \return CYNARA_ADMIN_API_SUCCESS on success, or error code otherwise.
245 * \brief Raw check client, user access for given privilege without using plugins extensions.
247 int cynara_offline_admin_check(struct cynara_offline_admin *p_cynara_offline_admin,
248 const char *start_bucket, const int recursive,
249 const char *client, const char *user, const char *privilege,
250 int *result, char **result_extra);
256 #endif /* CYNARA_OFFLINE_ADMIN_H */