src/include/cynara-client-async.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        cynara-client-async.h
  18  * @author      Marcin Niesluchowski <m.niesluchow@samsung.com>
  19  * @version     1.0
  20  * @brief       This file contains asynchronous client APIs of Cynara available
  21  *              with libcynara-client-asynchronous.
  22  */
  23
  24
  25 #ifndef CYNARA_CLIENT_ASYNC_H
  26 #define CYNARA_CLIENT_ASYNC_H
  27
  28 #include <cstdint>
  29
  30 /**
  31  * \name Return Codes
  32  * exported by the foundation API.
  33  * result codes begin with the start error code and extend into negative direction.
  34  * @{
  35 */
  36
  37 /*! \brief   indicating the result of the one specific API is successful or access is allowed */
  38 #define CYNARA_ASYNC_API_SUCCESS                0
  39
  40 /*! \brief   indicating that access that was checked is denied */
  41 #define CYNARA_ASYNC_API_ACCESS_DENIED         -1
  42
  43 /*! \brief   indicating that answer was not yet received */
  44 #define CYNARA_ASYNC_API_ANSWER_NOT_READY      -2
  45
  46 /*! \brief   indicating that client is already connected */
  47 #define CYNARA_ASYNC_API_ALREADY_CONNECTED     -3
  48
  49 /*! \brief   indicating system is running out of memory state */
  50 #define CYNARA_ASYNC_API_OUT_OF_MEMORY         -4
  51
  52 /*! \brief   indicating the API's parameter is malformed */
  53 #define CYNARA_ASYNC_API_INVALID_PARAM         -5
  54
  55 /*! \brief   service not available */
  56 #define CYNARA_ASYNC_API_SERVICE_NOT_AVAILABLE -6
  57
  58 /** @}*/
  59
  60 #ifdef __cplusplus
  61 extern "C" {
  62 #endif
  63
  64 typedef struct cynara_async cynara_async;
  65 typedef struct cynara_async_configuration cynara_async_configuration;
  66 typedef uint16_t cynara_check_id;
  67
  68 /**
  69  * \par Description:
  70  * Initialize cynara-async-client library with given configuration.
  71  * Create structure used in following API calls.
  72  *
  73  * \par Purpose:
  74  * This API must be used prior to calling cynara_async_connect function.
  75  *
  76  * \par Typical use case:
  77  * Once before a service can call cynara_async_connect.
  78  *
  79  * \par Method of function operation:
  80  * This API initializes inner library structures and in case of success creates
  81  * and returns cynara_async structure.
  82  *
  83  * \par Sync (or) Async:
  84  * This is a synchronous API.
  85  *
  86  * \par Thread-safety:
  87  * This function is NOT thread-safe. If functions from described API are called by multithreaded
  88  * application from different threads, they must be put into protected critical section.
  89  *
  90  * \par Important notes:
  91  * Structure cynara_async created by cynara_async_initialize call should be released
  92  * with cynara_async_finish.
  93  *
  94  * \param[out] pp_cynara Placeholder for created cynara_async structure.
  95  * \param[in] p_conf Configuration for cynara-async-client library. NULL for default parameters.
  96  *
  97  * \return CYNARA_ASYNC_API_SUCCESS on success, or error code on error.
  98  */
  99
 100 int cynara_async_initialize(cynara_async **pp_cynara,
 101                             const cynara_async_configuration *p_conf);
 102
 103 /**
 104  * \par Description:
 105  * Release cynara-async-client library and destroy structure created with cynara_async_initialize.
 106  *
 107  * \par Purpose:
 108  * This API should be used to clean up after usage of cynara-async-client library.
 109  *
 110  * \par Typical use case:
 111  * Once after all checks have been answered.
 112  *
 113  * \par Method of function operation:
 114  * This API releases inner library structure and destroys cynara_async structure. All pending
 115  * requests are cancelled.
 116  *
 117  * \par Sync (or) Async:
 118  * This is a synchronous API.
 119  *
 120  * \par Thread-safety:
 121  * This function is NOT thread-safe. If functions from described API are called by multithreaded
 122  * application from different threads, they must be put into protected critical section.
 123  *
 124  * \par Important notes:
 125  * No other call to cynara-async-client library should be made after call to cynara_async_finish.
 126  *
 127  * \param[in] p_cynara cynara_async structure.
 128  *
 129  * \return CYNARA_ASYNC_API_SUCCESS on success, or error code on error.
 130  */
 131 int cynara_async_finish(cynara_async *p_cynara);
 132
 133 /**
 134  * \par Description:
 135  * Connect with cynara server.
 136  *
 137  * \par Purpose:
 138  * This API must be used prior to calling cynara_async_check and cynara_async_receive.
 139  *
 140  * \par Typical use case:
 141  * After initiating cynara_async structure and after connection with cynara server has been lost.
 142  *
 143  * \par Method of function operation:
 144  * This API connects to cynara server and provides socket descriptor of this connection.
 145  *
 146  * \par Sync (or) Async:
 147  * This is a synchronous API.
 148  *
 149  * \par Thread-safety:
 150  * This function is NOT thread-safe. If functions from described API are called by multithreaded
 151  * application from different threads, they must be put into protected critical section.
 152  *
 153  * \par Important notes:
 154  * Call to cynara_async_check needs cynara_async structure to be created first by
 155  * cynara_async_initialize.
 156  *
 157  * \param[in] p_cynara cynara_async structure.
 158  * \param[out] p_sock_fd Placeholder for connection socket descriptor.
 159  *
 160  * \return CYNARA_ASYNC_API_SUCCESS on success, CYNARA_ASYNC_API_ALREADY_CONNECTED when client is
 161  * already connected or error code on error.
 162  */
 163 int cynara_async_connect(cynara_async *p_cynara, int *p_sock_fd);
 164
 165 /**
 166  * \par Description:
 167  * Check client, user access for given privilege.
 168  *
 169  * \par Purpose:
 170  * This API should be used to check if a user running application identified as client
 171  * has access to a privilege.
 172  *
 173  * \par Typical use case:
 174  * A service wants to ask Cynara daemon, if a client demanding access to some privilege
 175  * has proper rights. Despite the fact that the final response has been received, if there are
 176  * still some pending checks, cynara_async_receive MUST be called after this call until not ready
 177  * answer is returned. If service does not get answer after this sequence, it may get it
 178  * asynchronously by calling cynara_async_receive.
 179  *
 180  * \par Method of function operation:
 181  * Client (a process / application) demanding access to a privilege is running as some user.
 182  * For such triple an access to a privilege is checked by calling cynara.
 183  * Depending on defined policy, an external application may be launched to ask user a question,
 184  * e.g. if [s]he wants to allow client to use a privilege. Additional parameter client_session
 185  * may be used to distinguish between client session (e.g. for allowing access only for this
 186  * particular application launch). If final answer is not returned, id of current check should
 187  * be received.
 188  *
 189  * \par Sync (or) Async:
 190  * This is an asynchronous API.
 191  *
 192  * \par Thread-safety:
 193  * This function is NOT thread-safe. If functions from described API are called by multithreaded
 194  * application from different threads, they must be put into protected critical section.
 195  *
 196  * \par Important notes:
 197  * An external application may be launched to allow user interaction in granting or denying access.
 198  * Call cynara_async_cancel to cancel pending request. Call to cynara_async_check needs
 199  * cynara_async structure to be created first and connected with cynara daemon. To do that call
 200  * cynara_async_initialize and cynara_async_connect.
 201  *
 202  * \param[in] p_cynara cynara_async structure.
 203  * \param[in] client Application or process identifier.
 204  * \param[in] client_session Session of client (connection, launch).
 205  * \param[in] user User running client.
 206  * \param[in] privilege Privilege that is a subject of a check.
 207  * \param[out] p_check_id Placeholder for check id.
 208  *
 209  * \return CYNARA_ASYNC_API_SUCCESS on success (access granted), CYNARA_API_ACCESS_DENIED
 210  * on access denial, CYNARA_ASYNC_API_ANSWER_NOT_READY on asynchronous request sent
 211  * or other error code on error.
 212  */
 213 int cynara_async_check(cynara_async *p_cynara,
 214                        const char *client, const char *client_session,
 215                        const char *user, const char *privilege,
 216                        cynara_check_id *p_check_id);
 217
 218 /**
 219  * \par Description:
 220  * Receive answer of cynara_async_check call from cynara daemon.
 221  *
 222  * \par Purpose:
 223  * This API should be used to receive answer on single check not answered by cynara_async_check.
 224  *
 225  * \par Typical use case:
 226  * After calling cynara_async_check, if there are still pending checks, this function MUST be
 227  * called until not ready answer is returned. After that, answer can be received by this call
 228  * if a read event occurs on socket received by cynara_async_connect. It MUST be called then
 229  * the same way as after cynara_async_check.
 230  *
 231  * \par Method of function operation:
 232  * Receives answer sent by cynara daemon in response to cynara_async_check call.
 233  *
 234  * \par Sync (or) Async:
 235  * This is an asynchronous API.
 236  *
 237  * \par Thread-safety:
 238  * This function is NOT thread-safe. If functions from described API are called by multithreaded
 239  * application from different threads, they must be put into protected critical section.
 240  *
 241  * \par Important notes:
 242  * An external application may be launched to allow user interaction in granting or denying access.
 243  * Call cynara_async_cancel to cancel pending request. Call to cynara_async_receive needs
 244  * cynara_async structure to be created first and connected with cynara daemon. To do that call
 245  * cynara_async_initialize and cynara_async_connect. As multiple answers can be available at once,
 246  * cynara_async_receive MUST be called until not ready answer is returned.
 247  *
 248  * \param[in] p_cynara cynara_async structure.
 249  * \param[out] p_check_id Placeholder for check id.
 250  *
 251  * \return CYNARA_ASYNC_API_SUCCESS on success (access granted), CYNARA_API_ACCESS_DENIED
 252  * on access denial, CYNARA_ASYNC_API_ANSWER_NOT_READY on answer not yet fully received
 253  * or other error code on error.
 254  */
 255 int cynara_async_receive(cynara_async *p_cynara, cynara_check_id *p_check_id);
 256
 257 /**
 258  * \par Description:
 259  * Cancel check request created by cynara_async_check.
 260  *
 261  * \par Purpose:
 262  * This API should be used to cancel check request created by cynara_async_check.
 263  *
 264  * \par Typical use case:
 265  * A service did not get final answer in cynara_async_check call and answer did not come yet
 266  * due to check hanging on user decision to allow or deny privilege.
 267  *
 268  * \par Method of function operation:
 269  * Cancels check request created by cynara_async_check call.
 270  *
 271  * \par Sync (or) Async:
 272  * This is an asynchronous API.
 273  *
 274  * \par Thread-safety:
 275  * This function is NOT thread-safe. If functions from described API are called by multithreaded
 276  * application from different threads, they must be put into protected critical section.
 277  *
 278  * \par Important notes:
 279  * Call to cynara_async_cancel needs cynara_async structure to be created first and connected
 280  * with cynara daemon. To do that call cynara_async_initialize and cynara_async_connect.
 281  *
 282  * \param[in] p_cynara cynara_async structure.
 283  * \param[in] check_id Check id to be cancelled
 284  *
 285  * \return CYNARA_ASYNC_API_SUCCESS on success or other error code on error.
 286  */
 287 int cynara_async_cancel(cynara_async *p_cynara, cynara_check_id check_id);
 288
 289
 290 #ifdef __cplusplus
 291 }
 292 #endif
 293
 294 #endif /* CYNARA_CLIENT_ASYNC_H */