src/include/cynara-offline-admin.h

   1 /*
   2  *  Copyright (c) 2014 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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
  15  */
  16 /**
  17  * \file        src/include/cynara-offline-admin.h
  18  * \author      Lukasz Wojciechowski <l.wojciechow@partner.samsung.com>
  19  * \author      Aleksander Zdyb <a.zdyb@samsung.com>
  20  * \version     1.0
  21  * \brief       This file contains administration APIs of cynara available
  22  *              with libcynara-offline-admin.
  23  */
  24
  25 #ifndef CYNARA_OFFLINE_ADMIN_H
  26 #define CYNARA_OFFLINE_ADMIN_H
  27
  28 #include <cynara-admin-types.h>
  29 #include <cynara-client-error.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /**
  36  * \name cynara_offline_admin
  37  * forward declaration of structure allowing initialization of library
  38  * and usage of all libcynara-offline-admin API functions
  39  */
  40 struct cynara_offline_admin;
  41
  42 /**
  43  * \par Description:
  44  * Initialize cynara-offline-admin library.
  45  * Creates structure used in following API calls.
  46  *
  47  * \par Purpose:
  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.
  50  *
  51  * \par Typical use case:
  52  * Once before a service can call other cynara-offline-admin library functions.
  53  *
  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.
  58  *
  59  * \par Sync (or) Async:
  60  * This is a synchronous API.
  61  *
  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.
  65  *
  66  * \param[out] pp_cynara_offline_admin address of pointer for created cynara_offline_admin
  67  *             structure.
  68  *
  69  * \return CYNARA_API_SUCCESS on success, or negative error code otherwise.
  70  *
  71  * \brief Initialize cynara-offline-admin library.
  72  */
  73 int cynara_offline_admin_initialize(struct cynara_offline_admin **pp_cynara_offline_admin);
  74
  75 /**
  76  * \par Description:
  77  * Releases cynara-offline-admin library and destroys structure created
  78  * with cynara_offline_admin_initialize function.
  79  *
  80  * \par Purpose:
  81  * This API should be used to clean up after usage of cynara-offline-admin library.
  82  *
  83  * \par Typical use case:
  84  * Function should be called once, when done with cynara-offline-admin library API usage.
  85  *
  86  * \par Method of function operation:
  87  * This API releases inner library structures and destroys cynara_offline_admin structure.
  88  *
  89  * \par Sync (or) Async:
  90  * This is a synchronous API.
  91  *
  92  * \par Important notes:
  93  * No invocations of cynara-offline-admin library API functions are allowed after call to
  94  * cynara_offline_admin_finish.
  95  *
  96  * \param[in] p_cynara_offline_admin cynara_offline_admin structure created
  97  *            in cynara_offline_admin_initialize.
  98  *
  99  * \return CYNARA_API_SUCCESS on success, or negative error code otherwise.
 100  *
 101  * \brief Release cynara-offline-admin library.
 102  */
 103 int cynara_offline_admin_finish(struct cynara_offline_admin *p_cynara_offline_admin);
 104
 105 /**
 106  * \par Description:
 107  * Manages policies in cynara.
 108  *
 109  * \par Purpose:
 110  * This API should be used to insert, update or delete policies in cynara.
 111  *
 112  * \par Typical use case:
 113  * Enables altering policies by adding, updating or removing records.
 114  *
 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.
 119  *
 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.
 125  *
 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
 129  * cynara database.
 130  * In case of CYNARA_ADMIN_BUCKET, a bucket-pointing policy is updated or inserted into cynara
 131  * database.
 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.
 135  *
 136  * However, considered buckets must exist before referring to them in policies.
 137  *
 138  * \par Sync (or) Async:
 139  * This is a synchronous API.
 140  *
 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
 144  * recommended.
 145  *
 146  * \param[in] p_cynara_offline_admin cynara offline admin structure.
 147  * \param[in] policies NULL terminated array of pointers to policy structures.
 148  *
 149  * \return CYNARA_API_SUCCESS on success, or negative error code otherwise.
 150  *
 151  * \brief Insert, update or delete policies in cynara database.
 152  */
 153 int cynara_offline_admin_set_policies(struct cynara_offline_admin *p_cynara_offline_admin,
 154                                       const struct cynara_admin_policy *const *policies);
 155
 156 /**
 157  * \par Description:
 158  * Adds new, updates or removes existing bucket for policies in cynara.
 159  *
 160  * \par Purpose:
 161  * This API should be used to add, remove or update buckets.
 162  *
 163  * \par Typical use case:
 164  * Enables altering policies database by adding, updating or removing buckets.
 165  *
 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.
 169
 170  * Operation run on a single bucket defined with bucket parameter.
 171
 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.
 176  *
 177  * \par Sync (or) Async:
 178  * This is a synchronous API.
 179  *
 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.
 184  *
 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.
 187  *
 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.
 190  *
 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)
 195  *
 196  * \return CYNARA_API_SUCCESS on success, or negative error code otherwise.
 197  *
 198  * \brief Add, remove or update buckets in cynara database.
 199  */
 200 int cynara_offline_admin_set_bucket(struct cynara_offline_admin *p_cynara_offline_admin,
 201                                     const char *bucket, int operation, const char *extra);
 202
 203 /**
 204  * \par Description:
 205  * Raw check client, user access for given privilege without using plugins extensions.
 206  *
 207  * \par Purpose:
 208  * This API should be used to check type of matching policy for check request.
 209  *
 210  * \par Typical use case:
 211  * Administrator of cynara want to know, what would cynara return to client, if asked about given
 212  * access.
 213  *
 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
 223  *   plugin extensions.
 224  *
 225  * \par Sync (or) Async:
 226  * This is a synchronous API.
 227  *
 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.
 232  *
 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!)
 242  *
 243  * \return CYNARA_API_SUCCESS on success, or error code otherwise.
 244  *
 245  * \brief Raw check client, user access for given privilege without using plugins extensions.
 246  */
 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);
 251
 252 #ifdef __cplusplus
 253 }
 254 #endif
 255
 256 #endif /* CYNARA_OFFLINE_ADMIN_H */