diff options
Diffstat (limited to 'include/cynara')
| -rw-r--r-- | include/cynara/cynara-admin-types.h | 91 | ||||
| -rw-r--r-- | include/cynara/cynara-admin.h | 460 | ||||
| -rw-r--r-- | include/cynara/cynara-agent.h | 256 | ||||
| -rw-r--r-- | include/cynara/cynara-client-async.h | 645 | ||||
| -rw-r--r-- | include/cynara/cynara-client-plugin.h | 75 | ||||
| -rw-r--r-- | include/cynara/cynara-client.h | 305 | ||||
| -rw-r--r-- | include/cynara/cynara-creds-commons.h | 132 | ||||
| -rw-r--r-- | include/cynara/cynara-creds-dbus.h | 171 | ||||
| -rw-r--r-- | include/cynara/cynara-creds-gdbus.h | 167 | ||||
| -rw-r--r-- | include/cynara/cynara-creds-self.h | 121 | ||||
| -rw-r--r-- | include/cynara/cynara-creds-socket.h | 161 | ||||
| -rw-r--r-- | include/cynara/cynara-error.h | 148 | ||||
| -rw-r--r-- | include/cynara/cynara-limits.h | 35 | ||||
| -rw-r--r-- | include/cynara/cynara-monitor.h | 421 | ||||
| -rw-r--r-- | include/cynara/cynara-plugin.h | 106 | ||||
| -rw-r--r-- | include/cynara/cynara-policy-types.h | 48 | ||||
| -rw-r--r-- | include/cynara/cynara-session.h | 73 |
17 files changed, 3415 insertions, 0 deletions
diff --git a/include/cynara/cynara-admin-types.h b/include/cynara/cynara-admin-types.h new file mode 100644 index 0000000..95d27b9 --- /dev/null +++ b/include/cynara/cynara-admin-types.h @@ -0,0 +1,91 @@ +/* + * Copyright (c) 2014-2015 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * \file src/include/cynara-admin-types.h + * \author Lukasz Wojciechowski <l.wojciechow@partner.samsung.com> + * \author Aleksander Zdyb <a.zdyb@samsung.com> + * \author Zofia Abramowska <z.abramowska@samsung.com> + * \author Oskar Switalski <o.switalski@samsung.com> + * \version 1.0 + * \brief This file contains structs and consts for cynara admin. + */ + +#ifndef CYNARA_ADMIN_TYPES_H +#define CYNARA_ADMIN_TYPES_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \struct cynara_admin_policy + * \brief Defines single policy + */ +struct cynara_admin_policy { + char *bucket; /**< Name of bucket, in which policy is placed */ + + char *client; /**< Identifier of client (application) */ + char *user; /**< Identifier of user */ + char *privilege; /**< Privilege name */ + + int result; /**< Result of policy */ + char *result_extra; /**< Not always used, may contain some additional result data + like e.g. name of bucket in case result == CYNARA_ADMIN_BUCKET */ +}; + +/** + * \struct cynara_admin_policy_descr + * \brief Describes policy of type given with result + */ + +struct cynara_admin_policy_descr { + int result; /**< Result of policy to describe */ + char *name; /**< Descriptive name of given policy result */ +}; + +/** + * \name Wildcard + * Can replace client, user or privilege name. + * WILDCARD matches any string during check procedure from libcynara-client. + */ +#define CYNARA_ADMIN_WILDCARD "*" + +/** + * \name Name of Default Bucket + * Default bucket - the one that check starts in. + * Default bucket cannot be removed, although its default policy + * (which originally is set to DENY) can be changed. + */ +#define CYNARA_ADMIN_DEFAULT_BUCKET "" + +/** + * \name Any + * Can replace client, user or privilege name. + * ANY matches any string (including WILDCARD) during: + * + * * policy removal with cynara_admin_erase() function + * * listing policies from a single bucket. + * + * Using ANY as default policy for bucket or as policy type of inserted policy record + * is forbidden and will cause CYNARA_API_INVALID_PARAM error. + */ +#define CYNARA_ADMIN_ANY "#" + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_ADMIN_TYPES_H */ diff --git a/include/cynara/cynara-admin.h b/include/cynara/cynara-admin.h new file mode 100644 index 0000000..a0ab0c9 --- /dev/null +++ b/include/cynara/cynara-admin.h @@ -0,0 +1,460 @@ +/* + * Copyright (c) 2014-2015 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * \file src/include/cynara-admin.h + * \author Lukasz Wojciechowski <l.wojciechow@partner.samsung.com> + * \author Zofia Abramowska <z.abramowska@samsung.com> + * \author Oskar Switalski <o.switalski@samsung.com> + * \version 1.0 + * \brief This file contains administration APIs of cynara available with libcynara-admin. + * \example cynara-admin.example + */ + +#ifndef CYNARA_ADMIN_H +#define CYNARA_ADMIN_H + +#include <cynara/cynara-admin-types.h> +#include <cynara/cynara-error.h> +#include <cynara/cynara-limits.h> +#include <cynara/cynara-policy-types.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \struct cynara_admin + * Forward declaration of structure allowing initialization of library + * and usage of all libcynara-admin API functions + */ +struct cynara_admin; + +/** + * \brief Initialize cynara-admin structure. + * + * \par Description: + * Initialize cynara-admin library. + * Creates structure used in following API calls. + * + * \par Purpose: + * This function must be invoked prior to other admin API calls. It creates structure needed by + * other cynara-admin library API functions. + * + * \par Typical use case: + * Once before a service can call other cynara-admin library functions. + * + * \par Method of function operation: + * This API initializes inner library structures and in case of success creates cynara_admin + * structure and stores pointer to this structure at memory address passed in pp_cynara_admin + * parameter. + * + * \par Sync (or) async: + * This is a synchronous API. + * + * \par Important notes: + * Structure cynara_admin created by cynara_admin_initialize() call should be released with + * cynara_admin_finish(). + * + * \param[out] pp_cynara_admin address of pointer for created cynara_admin structure. + * + * \return CYNARA_API_SUCCESS on success, or error code otherwise. + */ +int cynara_admin_initialize(struct cynara_admin **pp_cynara_admin); + +/** + * \brief Release cynara-admin structure. + * + * \par Description: + * Destroys structure created with cynara_admin_initialize() function. + * + * \par Purpose: + * This API should be used to clean up after usage of cynara-admin library. + * + * \par Typical use case: + * Function should be called once, when done with cynara-admin library API usage. + * + * \par Method of function operation: + * This API releases inner library structures and destroys cynara_admin structure. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Important notes: + * No invocations of cynara-admin library API functions are allowed after call to + * cynara_admin_finish(). + * + * \param[in] p_cynara_admin cynara_admin structure created in cynara_admin_initialize(). + * + * \return CYNARA_API_SUCCESS on success, or error code otherwise. + */ +int cynara_admin_finish(struct cynara_admin *p_cynara_admin); + +/** + * \brief Insert, update or delete policies in cynara database. + * + * \par Description: + * Manages policies in cynara. + * + * \par Purpose: + * This API should be used to insert, update or delete policies in cynara. + * + * \par Typical use case: + * Enables privileged services to alter policies by adding, updating or removing records. + * + * \par Method of function operation: + * \parblock + * Policies are arranged into buckets. Every policy is defined in context of some bucket identified + * with bucket field (string). A bucket consists of policies identified with tripple: (client, user, + * privilege), which is a (unique) key within considered bucket. + * + * Every policy can be one of two types: simple or bucket-pointing policy. + * + * * Simple policies have result field with value of CYNARA_ADMIN_DENY or CYNARA_ADMIN_ALLOW. + * result_extra field should be NULL in this case. + * * Bucket-pointing policies have result field with value of CYNARA_ADMIN_BUCKET and name of + * bucket they point to in result_extra field. + * + * + * Type of operation, which is run for every record (single policy) is defined by result field in + * cynara_admin_policy structure. + * + * * In case of CYNARA_ADMIN_DENY or CYNARA_ADMIN_ALLOW a simple policy is updated or inserted into + * cynara database. + * * In case of CYNARA_ADMIN_BUCKET, a bucket-pointing policy is updated or inserted into cynara + * database. + * * In case of CYNARA_ADMIN_DELETE, a policy is removed from cynara database. + * + * One call of cynara_admin_set_policies() can manage many different policies in different buckets. + * However, considered buckets must exist before referring to them in policies. + * \endparblock + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Important notes: + * \parblock + * When plugin API will be specified, there will be more valid types to pass as result. + * Numerical values of defines CYNARA_ADMIN_... may change, so usage of defines names is strongly + * recommended. + * + * Policies size cannot exceed CYNARA_MAX_VECTOR_SIZE excluding last null element and string members + * length cannot exceed CYNARA_MAX_ID_LENGTH, otherwise CYNARA_API_INVALID_PARAM will be returned. + * \endparblock + * + * \param[in] p_cynara_admin cynara admin structure. + * \param[in] policies NULL terminated array of pointers to policy structures. + * + * \return CYNARA_API_SUCCESS on success, or error code otherwise. + */ +int cynara_admin_set_policies(struct cynara_admin *p_cynara_admin, + const struct cynara_admin_policy *const *policies); + +/** + * \brief Add, remove or update buckets in cynara database. + * + * \par Description: + * Adds new, updates or removes existing bucket for policies in cynara. + * + * \par Purpose: + * This API should be used to add, remove or update buckets. + * + * \par Typical use case: + * Enables privileged services to alter policies database by adding, updating or removing buckets. + * + * \par Method of function operation: + * \parblock + * Every bucket has a default policy. During search, if no policy matches the searched key (client, + * user, privilege), default policy is returned. + + * Operation run on a single bucket defined with bucket parameter. + + * Operation parameter defines what should happen with bucket. In case of: + * * CYNARA_ADMIN_DENY, a bucket is inserted or updated with CYNARA_ADMIN_DENY default policy; + * * CYNARA_ADMIN_ALLOW, a bucket is inserted or updated with CYNARA_ADMIN_ALLOW default policy; + * * CYNARA_ADMIN_DELETE, a bucket is removed with all policies that were kept in it. + * \endparblock + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Important notes: + * \parblock + * When plugin API will be specified, there will be more valid types to pass as operation / default + * policy. Numerical values of defines CYNARA_ADMIN_... may change, so usages of provided consts is + * strongly recommended. + * + * String length cannot exceed CYNARA_MAX_ID_LENGTH, otherwise CYNARA_API_INVALID_PARAM will be + * returned. + * + * Default bucket identified with CYNARA_ADMIN_DEFAULT_BUCKET exists always. Its default policy + * is preset to DENY (can be altered, however). Default bucket cannot be removed. + * + * Extra parameter will be used to pass additional data to cynara extensions to build more complex + * policies, such as ALLOW but for 5 minutes only, or ALLOW if user confirms. + * \endparblock + * + * \param[in] p_cynara_admin cynara admin structure. + * \param[in] bucket bucket name + * \param[in] operation type of operation (default policy or CYNARA_ADMIN_DELETE) + * \param[in] extra additional data for default policy (will be available with cynara extensions) + * + * \return CYNARA_API_SUCCESS on success, or error code otherwise. + */ +int cynara_admin_set_bucket(struct cynara_admin *p_cynara_admin, const char *bucket, int operation, + const char *extra); + +/** + * \brief Raw check client and user access for given privilege without using plugins extensions. + * + * \par Description: + * Raw check client and user access for given privilege without using plugins extensions. + * + * \par Purpose: + * This API should be used to check type of matching policy for check request + * + * \par Typical use case: + * Administrator of cynara want to know, what would cynara return to client, if asked about given + * access. + * + * \par Method of function operation: + * \parblock + * Function works almost the same way as cynara_check() client function. + * The differences are: + * * user must specify bucket, from which search would be started (in case of cynara_check() + * it is always the default bucket) + * * user can specify if search should be recursive: disabling recursive check will constrain search + * to single bucket only, ignoring all policies leading to other buckets (in case of + * cynara_check() search is always recursive) + * * when matching policy in cynara is found, its result is returned without being interpreted by + * plugin extensions. + * \endparblock + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Important notes: + * \parblock + * (*result_extra) may be set to NULL, if extra data are not used in matched policy + * If (*result_extra) is not NULL, it contains a string allocated by cynara admin library + * with malloc(3) function and must be released with free(3) function. + * + * String length cannot exceed CYNARA_MAX_ID_LENGTH, otherwise CYNARA_API_INVALID_PARAM will be + * returned. + * \endparblock + * + * \param[in] p_cynara_admin cynara admin structure. + * \param[in] start_bucket name of bucket where search would start. + * \param[in] recursive FALSE (== 0) : single bucket search; + * TRUE (!= 0) : search does not ignore policies leading to another buckets. + * \param[in] client application or process identifier. + * \param[in] user user running client. + * \param[in] privilege privilege that is a subject of a check. + * \param[out] result placeholder for matched policy type. + * \param[out] result_extra placeholder for matched policy additional data (see Important Notes!). + * + * \return CYNARA_API_SUCCESS on success, or error code otherwise. + */ +int cynara_admin_check(struct cynara_admin *p_cynara_admin, + const char *start_bucket, const int recursive, + const char *client, const char *user, const char *privilege, + int *result, char **result_extra); + +/** + * \brief Lists policies from single bucket in cynara database. + * + * \par Description: + * Lists filtered cynara policies from single bucket. + * + * \par Purpose: + * This API should be used to list policies from single bucket. + * + * \par Typical use case: + * List all policies matching defined filter. + * + * \par Method of function operation: + * \parblock + * Policies are arranged into buckets. Every bucket contains set of policies. Each of policies are + * identified with triple {client, user, privilege}. Function lists all policies from single bucket + * with matching client, user and privilege names. + * + * CYNARA_ADMIN_ANY can be used to match any client, user or privilege, e.g. + * + * List with parameters: {client = CYNARA_ADMIN_ANY, user = "alice", privilege = CYNARA_ADMIN_ANY} + * will match all policies related to "alice", so will match {"app1", "alice", "gps"} and + * {CYNARA_ADMIN_WILDCARD, "alice", "sms"}, but won't match {"app3", CYNARA_ADMIN_WILDCARD, "call"}. + * + * List with parameters: {client = "calculator", user = CYNARA_ADMIN_WILDCARD, + * privilege = CYNARA_ADMIN_ANY} will match {"calculator", CYNARA_ADMIN_WILDCARD, "sms"} but won't + * match {CYNARA_ADMIN_WILDCARD, CYNARA_ADMIN_WILDCARD, "sms"} nor {"calculator", "bob", "sms"} + * + * Matching policies are returned as NULL terminated array of pointers to cynara_admin_policy + * structures. + * + * If any of: bucket, client, user, privilege, policies is NULL then CYNARA_API_INVALID_PARAM + * is returned. + * + * If there is no bucket with given name CYNARA_API_BUCKET_NOT_FOUND is returned. + * + * In case of successful call CYNARA_API_SUCCESS is returned and *policies points to newly created + * array of pointers to struct cynara_admin_policy. It is responsibility of caller to release: + * + * * all non-NULL const char* pointers in all cynara_admin_policy structures; + * * all pointers to cynara_admin_policy structures kept in *policies array; + * * *policies array itself. + * + * All allocation made by cynara admin library are done with malloc(3) function and must be released + * with free(3) function. + * \endparblock + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Important notes: + * String length cannot exceed CYNARA_MAX_ID_LENGTH, otherwise CYNARA_API_INVALID_PARAM will be + * returned. + * + * \param[in] p_cynara_admin cynara admin structure. + * \param[in] bucket name. + * \param[in] client filter for client name. + * \param[in] user filter for user name. + * \param[in] privilege filter for privilege. + * \param[out] policies placeholder for NULL terminated array of pointers to policy structures. + * + * \return CYNARA_API_SUCCESS on success, or error code otherwise. + */ +int cynara_admin_list_policies(struct cynara_admin *p_cynara_admin, const char *bucket, + const char *client, const char *user, const char *privilege, + struct cynara_admin_policy ***policies); + +/** + * \brief Erase policies matching filter from cynara database. + * + * \par Description: + * Erase policies matching filter from cynara database. + * + * \par Purpose: + * This API should be used to erase multiple policies with some common key part, + * e.g. all policies related to given user. + * + * \par Typical use case: + * Erase all policies matching defined filter. + * + * \par Method of function operation: + * \parblock + * Policies are arranged into buckets. Every bucket contains set of policies. Each of policies are + * identified with triple {client, user, privilege}. Function erases all policies with matching + * client, user and privilege names. + * + * There are two modes: + * * non-recursive (recursive parameter set to 0) - when policies are erased only from single bucket + * * recursive (recursive parameter set to 1) when policies are removed from given start_bucket and + * all nested buckets. + * + * CYNARA_ADMIN_ANY can be used to match any client, user or privilege, e.g. + * + * Erase with parameters: {client = CYNARA_ADMIN_ANY, user = "alice", privilege = CYNARA_ADMIN_ANY} + * will match all policies related to "alice", so will match {"app1", "alice", "gps"} and + * {CYNARA_ADMIN_WILDCARD, "alice", "sms"}, but won't match {"app3", CYNARA_ADMIN_WILDCARD, "call"}. + * + * Erase with parameters: {client = "calculator", user = CYNARA_ADMIN_WILDCARD, + * privilege = CYNARA_ADMIN_ANY} will match {"calculator", CYNARA_ADMIN_WILDCARD, "sms"} but won't + * match {CYNARA_ADMIN_WILDCARD, CYNARA_ADMIN_WILDCARD, "sms"} nor {"calculator", "bob", "sms"} + * + * If any of: start_bucket, client, user, privilege, policies is NULL then CYNARA_API_INVALID_PARAM + * is returned. + * + * If there is no bucket with given name CYNARA_API_BUCKET_NOT_FOUND is returned. + * + * In case of successful call CYNARA_API_SUCCESS is returned. + * \endparblock + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Important notes: + * String length cannot exceed CYNARA_MAX_ID_LENGTH, otherwise CYNARA_API_INVALID_PARAM will be + * returned. + * + * \param[in] p_cynara_admin cynara admin structure. + * \param[in] start_bucket name of bucket where erase would start. + * \param[in] recursive FALSE (== 0) : erase is not recursive (single bucket erase); \n + * TRUE (!= 0) : erase follows all policies leading to nested buckets + * \param[in] client filter for client name. + * \param[in] user filter for user name. + * \param[in] privilege filter for privilege. + * + * \return CYNARA_API_SUCCESS on success, or error code otherwise. + */ +int cynara_admin_erase(struct cynara_admin *p_cynara_admin, + const char *start_bucket, int recursive, + const char *client, const char *user, const char *privilege); + +/** + * \brief Lists available policies with their name description. + * + * \par Description: + * + * Lists available cynara policy results with name description. + * + * \par Purpose: + * This API should be used to list all available policy results + * (also from cynara extension plugins). + * + * \par Typical use case: + * Gathering information about possible policy results and presenting them to user (using name + * attribute of description). Result can be passed to cynara_admin_set_policies(). + * + * \par Method of function operation: + * \parblock + * Policies are based on policy result number. Policies can be built in (like primitives: ALLOW, + * DENY...) or can be loaded from cynara plugin extensions. This API gives possibility of checking, + * which of these result exist in current cynara server and can be presented to user in a readable + * way (of course additional translation may be needed). + * + * Descriptions of existing policy results are returned as NULL terminated array of pointers of + * cynara_admin_policy_descr structures. + * + * Example output could be {{0, "Deny"}, {11, "AskUser"}, {65535, "Allow"}, NULL} + * + * In case of successful call CYNARA_API_SUCCESS is returned and *descriptions points + * to newly created array of pointers to struct cynara_admin_policy_descr. It is responsibility + * of caller to release: + * + * * all non-NULL char* pointers in all cynara_admin_policy_descr structures; + * * all pointers to cynara_admin_policy_descr structures kept in *descriptions array; + * * *descriptions array itself. + * + * All allocation made by cynara admin library are done with malloc(3) function and must be released + * with free(3) function. + * \endparblock + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \param[in] p_cynara_admin cynara admin structure. + * \param[out] descriptions placeholder for NULL terminated array of pointers of + * description structures. + * + * \return CYNARA_API_SUCCESS on success, or error code otherwise. + */ +int cynara_admin_list_policies_descriptions(struct cynara_admin *p_cynara_admin, + struct cynara_admin_policy_descr ***descriptions); + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_ADMIN_H */ diff --git a/include/cynara/cynara-agent.h b/include/cynara/cynara-agent.h new file mode 100644 index 0000000..3e6d4f0 --- /dev/null +++ b/include/cynara/cynara-agent.h @@ -0,0 +1,256 @@ +/* + * Copyright (c) 2014-2017 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * @file src/include/cynara-agent.h + * @author Adam Malinowski <a.malinowsk2@partner.samsung.com> + * @author Oskar Switalski <o.switalski@samsung.com> + * @version 1.0 + * @brief This file contains agent APIs available with libcynara-agent. + */ + +#ifndef CYNARA_AGENT_H +#define CYNARA_AGENT_H + +#include <stdint.h> + +#include <cynara/cynara-error.h> + +#ifdef __cplusplus +extern "C" { +#endif + +typedef uint16_t cynara_agent_req_id; +typedef struct cynara_agent cynara_agent; + +/** + * \enum cynara_agent_msg_type + * Values specifying type of message. + * + * \var cynara_agent_msg_type::CYNARA_MSG_TYPE_ACTION + * Message of this type indicates its content is a request for performing an action or response to + * such request. + * + * \var cynara_agent_msg_type::CYNARA_MSG_TYPE_CANCEL + * Message of this type indicates its content is a request for canceling action or response to such + * request. + */ +typedef enum { + CYNARA_MSG_TYPE_ACTION, + CYNARA_MSG_TYPE_CANCEL +} cynara_agent_msg_type; + +/** + * \par Description: + * Initialize cynara-agent structure. + * Create structure used in following API calls. + * + * \par Purpose: + * This API must be used prior to calling other agent API functions. + * + * \par Typical use case: + * Once before other agent API functions are called. + * + * \par Method of function operation: + * This API initializes inner library structures and in case of success returns cynara_agent + * structure. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * Structure cynara_agent created by this function should be released with cynara_agent_finish(). + * + * \param[out] pp_cynara_agent Place holder for created cynara_agent structure. + * \param[in] p_agent_type Type (name) of agent used by cynara for communication agent<->plugin. + * + * \return CYNARA_API_SUCCESS on success, or error code on error. + */ +int cynara_agent_initialize(cynara_agent **pp_cynara_agent, const char *p_agent_type); + +/** + * \par Description: + * Destroy structure created with cynara_agent_initialize(). + * + * \par Purpose: + * This API should be used to clean up after usage of cynara-agent library. + * + * \par Typical use case: + * Once after connection to cynara is not needed. + * + * \par Method of function operation: + * This API releases inner library structure and destroys cynara_agent structure. Connection to + * cynara service is closed. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * No other call to cynara-agent library should be made after call to cynara_agent_finish() except + * cynara_agent_initialize(). + * + * \param[in] p_cynara_agent cynara_agent structure. If NULL, then the call has no effect. + */ +int cynara_agent_finish(cynara_agent *p_cynara_agent); + +/** + * \par Description: + * Get request from cynara service. + * + * \par Purpose: + * This API should be used to get request from cynara service. Request is generated by corresponding + * plugin loaded into cynara service. + * + * \par Typical use case: + * Agent waits for request from cynara service. Request may be either ask for performing agent + * specific action or ask for canceling such action. Agent calls this function when is ready to + * perform or cancel an action. + * + * \par Method of function operation: + * \parblock + * Function reads data incoming from cynara service and if at least one complete request is ready + * then returns with CYNARA_API_SUCCESS code. Request type, request id and specific + * plugin data are stored in given arguments. Function returns exactly one request. If there are + * more then one requests ready to get then one must call this function multiple times. + * + * This function is blocking which means that if there is no request from cynara service it will not + * return. On success, buffer for plugin specific data is allocated and size is set. Developer is + * responsible for freeing this memory using free() function. + * \endparblock + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * \parblock + * Call to cynara_agent_get_request() needs cynara_agent structure to be created first. + * Use cynara_agent_initialize() before calling this function. + * + * After CYNARA_API_ACCESS_DENIED error is returned agent should be terminated or at least should + * not invoke neither cynara_agent_get_request() nor cynara_agent_put_response() functions. + * \endparblock + * + * \param[in] p_cynara_agent cynara_agent structure. + * \param[out] req_type Request type, demand an action or cancel this action. + * \param[out] req_id Request identifier used to pair with answer #cynara_agent_put_response() and + * cancel request. + * \param[out] data Plugin specific data. Buffer is allocated in this function and developer is + * responsible for freeing it using free() function. Buffer is filled with data + * from corresponding plugin. If there is no enough memory for data + * CYNARA_API_OUT_OF_MEMORY is returned and all arguments remain untouched. + * \param[out] data_size Size of plugin data (bytes count). In case of out of memory this value + * stays untouched. + * + * \return CYNARA_API_SUCCESS on successfully read request, + * CYNARA_API_INTERRUPTED when cynara_agent_cancel_waiting() is called during waiting, + * or negative error code otherwise. + */ +int cynara_agent_get_request(cynara_agent *p_cynara_agent, cynara_agent_msg_type *req_type, + cynara_agent_req_id *req_id, void **data, size_t *data_size); + +/** + * \par Description: + * Send response to cynara service. + * + * \par Purpose: + * This API should be used to send response to cynara service. + * + * \par Typical use case: + * Agent calls this function when is ready to answer request for action or cancel request. + * + * \par Method of function operation: + * Function sends data to cynara service. Data contains answer for previously got question. + * Answer may be of type CYNARA_MSG_TYPE_ACTION or CYNARA_MSG_TYPE_CANCEL. Type is + * CYNARA_MSG_TYPE_ACTION when request for an action was processed and answer is ready, or + * CYNARA_MSG_TYPE_CANCEL when processing request for an action was interrupted by cancel request. + * Agent must send exactly one response per one request and cancel. If request is processed before + * cancel message arrives the agent sends action response. If cancel arrives before action request + * is processed then agent sends cancel response and drops processing related action. + * Request id in response must be the same as request id in corresponding request. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * Call to cynara_agent_get_request() needs cynara_agent structure to be created first. + * Use cynara_agent_initialize() before calling this function. Also successful call to + * cynara_agent_get_request() is needed before calling this function. + * + * \param[in] p_cynara_agent cynara_agent structure. + * \param[in] resp_type Response type - see Method of operation for details. + * \param[in] req_id Request identifier obtained from request. + * \param[in] data Plugin specific data. If necessary agent should fill this buffer with data + * directed to plugin. + * \param[in] data_size Size of plugin data (bytes count). + * + * \return CYNARA_API_SUCCESS on successfully read request, or negative error code otherwise. + */ +int cynara_agent_put_response(cynara_agent *p_cynara_agent, const cynara_agent_msg_type resp_type, + const cynara_agent_req_id req_id, const void *data, + const size_t data_size); + +/** + * \par Description: + * Break from waiting for cynara service request using cynara_agent_get_request(). + * + * \par Purpose: + * This API should be used when cynara_agent_get_request() is blocked and before calling + * cynara_agent_finish(). + * + * \par Typical use case: + * Agent calls this API, when it wants to gracefully quit. + * + * \par Method of function operation: + * Function notifies cynara_agent_get_request() to stop waiting for request from cynara. + * Then cynara_agent_get_request() returns CYNARA_API_INTERRUPTED and no request is fetched. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function can be used only together with cynara_agent_get_request(), otherwise should + * be treaded as NOT thread safe. + * + * \par Important notes: + * Call to cynara_agent_cancel_waiting() needs cynara_agent structure to be created first and + * cynara_agent_get_request() running. + * Use cynara_agent_initialize() before calling this function. + * + * \param[in] p_cynara_agent cynara_agent structure. + * \return CYNARA_API_SUCCESS on successful waiting cancel, or negative error code otherwise. + */ +int cynara_agent_cancel_waiting(cynara_agent *p_cynara_agent); + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_AGENT_H */ diff --git a/include/cynara/cynara-client-async.h b/include/cynara/cynara-client-async.h new file mode 100644 index 0000000..78a1313 --- /dev/null +++ b/include/cynara/cynara-client-async.h @@ -0,0 +1,645 @@ +/* + * Copyright (c) 2014-2015 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * @file src/include/cynara-client-async.h + * @author Zofia Abramowska <z.abramowska@samsung.com> + * @author Marcin Niesluchowski <m.niesluchow@samsung.com> + * @author Oskar Switalski <o.switalski@samsung.com> + * @version 1.0 + * @brief This file contains asynchronous client APIs of Cynara available + * with libcynara-client-asynchronous. + * @example cynara-client-async.example + */ + +#ifndef CYNARA_CLIENT_ASYNC_H +#define CYNARA_CLIENT_ASYNC_H + +#include <stddef.h> +#include <stdint.h> + +#include <cynara/cynara-error.h> +#include <cynara/cynara-limits.h> + +#ifdef __cplusplus +extern "C" { +#endif + +typedef uint16_t cynara_check_id; +typedef struct cynara_async cynara_async; +typedef struct cynara_async_configuration cynara_async_configuration; + +/** + * \enum cynara_async_status + * Values indicating the status of connected cynara socket. + * + * \var cynara_async_status::CYNARA_STATUS_FOR_READ + * Wait for read events on socket. + * + * \var cynara_async_status::CYNARA_STATUS_FOR_RW + * Wait for both read and write events on socket. + */ +typedef enum { + CYNARA_STATUS_FOR_READ, + CYNARA_STATUS_FOR_RW +} cynara_async_status; + +/** + * \enum cynara_async_call_cause + * Values indicating the reason of cynara_response_callback call. + * + * \var cynara_async_call_cause::CYNARA_CALL_CAUSE_ANSWER + * Callback was called due to response to previous cynara_async_create_request() or + * cynara_async_create_simple_request() call. + * + * \var cynara_async_call_cause::CYNARA_CALL_CAUSE_CANCEL + * Callback was called due to request cancellation with cynara_async_cancel_request() call. + * + * \var cynara_async_call_cause::CYNARA_CALL_CAUSE_FINISH + * Callback was called due to cynara_async_finish() call. + * + * \var cynara_async_call_cause::CYNARA_CALL_CAUSE_SERVICE_NOT_AVAILABLE + * Callback was called due to service not available. + */ +typedef enum { + CYNARA_CALL_CAUSE_ANSWER, + CYNARA_CALL_CAUSE_CANCEL, + CYNARA_CALL_CAUSE_FINISH, + CYNARA_CALL_CAUSE_SERVICE_NOT_AVAILABLE +} cynara_async_call_cause; + +/** + * \brief Response_callback is registered once in cynara_async_create_request() or + * cynara_async_create_simple_request() and will be triggered exactly once in 4 kinds of situations: + * + * -# after response is received from cynara service (CYNARA_CALL_CAUSE_ANSWER) + * -# when request is canceled with cynara_async_cancel_request() (CYNARA_CALL_CAUSE_CANCEL) + * -# when request was pending for response, but cynara_async_finish() was called + * (CYNARA_CALL_CAUSE_FINISH) + * -# when connection to cynara service was broken and cannot be established again - probably cynara + * is unoperational (CYNARA_CALL_CAUSE_SERVICE_NOT_AVAILABLE) + * + * API functions called during this callback with CYNARA_CALL_CAUSE_SERVICE_NOT_AVAILABLE + * or CYNARA_CALL_CAUSE_FINISH cause will return CYNARA_API_OPERATION_NOT_ALLOWED. + * cynara_async_finish() will be ignored if called from within this callback. + * + * \param[in] check_id Number identifying check request. Number is generated in + * cynara_async_create_request() or cynara_async_create_simple_request() + * and returned to user. It can be used to match response with sent request. + * Number is valid since cynara_async_create_request() call or + * cynara_async_create_simple_request() call till callback call. + * After that the number can be reused by cynara to run new request. + * \param[in] cause Cause of triggering this callback. + * \param[in] response Response for created request. Should be ignored if cause is not + * an answer to request (cause != CYNARA_CALL_CAUSE_ANSWER). + * \param[in] user_response_data User specific data - passed to cynara library in + * cynara_async_cancel_request() is being only remembered by library. + * Cynara library does not take any actions on this pointer, + * except for giving it back to user in cynara_response_callback. + * After that cynara forgets this data. + */ +typedef void (*cynara_response_callback) (cynara_check_id check_id, cynara_async_call_cause cause, + int response, void *user_response_data); + +/** + * \brief Callback used by cynara async API when status of cynara socket is changed in + * cynara_async_initialize(), cynara_async_check_cache(), cynara_async_create_request(), + * cynara_async_create_simple_request(), cynara_async_process(), cynara_async_cancel_request() + * or cynara_async_finish(). + * + * File descriptor changes every time cynara library connects or disconnects cynara service. + * Status change is triggered when check_request or cancel needs to be send to + * cynara service or sending data has finished and there is nothing more to send to cynara + * service. + * + * Note, that provided file descriptor is used internally by libcynara-client-async + * so user should not use it in other way than waiting on it in event loop. + * In particular user should not write to, read from or close this fd. + * CYNARA_API_OPERATION_NOT_ALLOWED will be returned for every api function called in this callback. + * cynara_async_finish() will be ignored if called from within this callback. + * + * \param[in] old_fd Old descriptor which should be unregistered from event loop, + * Special value -1 is used when callback is called after first + * successful connect. + * \param[in] new_fd New descriptor which should be registered in event loop, + * Special value -1 is used when cynara_async_finish() is called and + * cynara is disconnected. In this case status should be ignored. + * \param[in] status Status indicating which events should be awaited on socket + * \param[in] user_status_data User specific data - passed to cynara library in + * cynara_async_initialize() is being only remembered by library. + * Cynara library does not take any actions on this pointer, + * except for giving it back to user in cynara_status_callback. + * Data should be valid at least until cynara_async_finish() is called. + */ +typedef void (*cynara_status_callback) (int old_fd, int new_fd, cynara_async_status status, + void *user_status_data); + +/** + * \par Description: + * Initialize cynara_async_configuration. Create structure used in following configuration + * API calls. + * + * \par Purpose: + * For configuration parameter to be used in cynara async initialization function, this API must be + * called before any other cynara async configuration API function. + * It will create cynara_async_configuration structure, an optional parameter of cynara async + * initialization. + * + * \par Typical use case: + * Once before setting parameters of cynara async configuration and passing to + * cynara_async_initialize(). + * + * \par Method of function operation: + * This API initializes inner library structures and in case of success returns pointer + * to created cynara_async_configuration structure. + * + * \par Sync (or) Async: + * This as a synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * Structure cynara_async_configuration created by cynara_async_configuration_create() call + * should be released with cynara_async_configuration_destroy(). + * Structure cynara_async_configuration should be destroyed after passing it to + * cynara_async_initialize(). + * + * \param[out] pp_conf Placeholder for created cynara_async_configuration structure. + * + * \return CYNARA_API_SUCCESS on success + * \return negative error code on error + */ +int cynara_async_configuration_create(cynara_async_configuration **pp_conf); + +/** + * \par Description: + * Release cynara_async_configuration structure created with cynara_async_configuration_create(). + * + * \par Purpose: + * This API should be used to clean up after usage of cynara_async_configuration. + * + * \par Typical use case: + * Once cynara_async_configuration is not needed. + * + * \par Method of function operation: + * This API releases inner library structure and destroys cynara_async_configuration structure. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \param[in] p_conf cynara_async_configuration structure. If NULL, the call has no effect. + */ +void cynara_async_configuration_destroy(cynara_async_configuration *p_conf); + +/** + * \par Description: + * Set client cache size. + * + * \par Purpose: + * This API is used to change default number of cached responses returned from cynara. + * + * \par Typical use case: + * Once before setting parameters of cynara async configuration and passing to + * cynara_async_initialize(). + * + * \par Method of function operation: + * This API initializes cache with given capacity. + * + * \par Sync (or) Async: + * This as a synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * After passing cynara_async_configuration to cynara_async_initialize() calling this API will have + * no effect. + * + * \param[in] p_conf cynara_async_configuration structure pointer. + * \param[in] cache_size Cache size to be set. + * + * \return CYNARA_API_SUCCESS on success + * \return negative error code on error + */ +int cynara_async_configuration_set_cache_size(cynara_async_configuration *p_conf, + size_t cache_size); + +/** + * \par Description: + * Initialize cynara-async-client library with given configuration. Create structure used in + * following API calls and register callback and user_status_data for + * further cynara async API calls. + * + * \par Purpose: + * This API must be used prior to calling any other cynara async API function. + * It will create cynara_async structure required for any other cynara async API calls. + * + * \par Typical use case: + * Once before entering event loop and before any other cynara async API is called. + * + * \par Method of function operation: + * This API initializes inner library structures and in case of success + * returns cynara_async structure. + * + * \par Sync (or) Async: + * This is an synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * Structure cynara_async created by cynara_async_initialize() call should be released + * with cynara_async_finish(). + * + * \param[out] pp_cynara Placeholder for created cynara_async structure. + * \param[in] p_conf Configuration for cynara-async-client library. + * NULL should be used for default configuration. + * Configuration management functions will be added later. + * Configuration will be able to specify e.g. size of cache used by library + * for holding checks results. + * \param[in] callback Function called when connection is started. + * If NULL, no callback will be called, when status changes. + * \param[in] user_status_data User specific data, passed to callback is being only remembered + * by library. Cynara library does not take any actions on this pointer, + * except for giving it back to user in cynara_status_callback. + * Data should be valid at least until cynara_async_finish() is called. + * Can be NULL. + * + * \return CYNARA_API_SUCCESS on success + * \return negative error code on error + */ +int cynara_async_initialize(cynara_async **pp_cynara, const cynara_async_configuration *p_conf, + cynara_status_callback callback, void *user_status_data); + +/** + * \par Description: + * Release cynara-async-client library and destroy structure created with cynara_async_initialize(). + * + * \par Purpose: + * This API should be used to clean up after usage of cynara-async-client library. + * + * \par Typical use case: + * Once after connection to cynara is not needed. + * + * \par Method of function operation: + * This API releases inner library structure and destroys cynara_async structure. Connection to + * cynara server is closed. Upon disconnecting this will trigger cynara_status_callback callback + * with -1 as new_fd param so client can unregister file descriptor connected with cynara. It will + * also trigger cynara_response_callback callback for each created request with + * cynara_async_call_cause::CYNARA_CALL_CAUSE_FINISH as cause param. + * + * \par Sync (or) Async: + * This is an asynchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * No other call to cynara-async-client library should be made after call to cynara_async_finish(). + * cynara_async_finish() called from within cynara_response_callback or cynara_status_callback will + * be ignored. + * + * \param[in] p_cynara cynara_async structure. If NULL, then the call has no effect. + */ +void cynara_async_finish(cynara_async *p_cynara); + +/** + * \par Description: + * Check access to given privilege for specified user, client and client_session in cache. + * + * \par Purpose: + * This API should be used to check if cache holds information about access of user, + * running application identified as clients to a privilege. + * This API should be used for fast check in cache. + * + * \par Typical use case: + * A service wants to check in cache, if a client requesting access to some privilege + * has proper rights. + * + * \par Method of function operation: + * Client (a process / application) requesting access to a privilege is running as some user. + * For such triple (client, user, privilege) a cache is checked. + * If cache is invalid it is cleared and call returns same as access not found. + * Additional parameter client_session + * may be used to distinguish between client session (e.g. for allowing access only for this + * particular application launch). Empty string "" can be used, when session differentiation + * is not needed. + * + * \par Sync (or) Async: + * This is an synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * \parblock + * Call to cynara_async_check_cache() needs cynara_async structure to be created first. + * Use cynara_async_initialize() before calling this function. cynara_async_check_cache() called + * from within cynara_status_callback or cynara_response_callback with + * CYNARA_CALL_CAUSE_SERVICE_NOT_AVAILABLE or CYNARA_CALL_CAUSE_FINISH cause will return + * CYNARA_API_OPERATION_NOT_ALLOWED. + * + * Socket status may occasionally be changed to CYNARA_STATUS_FOR_RW, to ensure + * that cynara_async_process() is triggered in event loop after socket is ready to send + * monitor logs to Cynara service. + * + * String length cannot exceed CYNARA_MAX_ID_LENGTH, otherwise CYNARA_API_INVALID_PARAM will be + * returned. + * \endparblock + * + * \param[in] p_cynara cynara_async structure. + * \param[in] client Application or process identifier. + * \param[in] client_session Client defined session. + * \param[in] user User of running client. + * \param[in] privilege Privilege that is a subject of a check. + * + * \return CYNARA_API_ACCESS_ALLOWED on checked access allowed + * \return CYNARA_API_ACCESS_DENIED on checked access denied + * \return CYNARA_API_CACHE_MISS on access not in cache + * \return other negative error code on error + */ +int cynara_async_check_cache(cynara_async *p_cynara, const char *client, const char *client_session, + const char *user, const char *privilege); + +/** + * \par Description: + * Creates access check request to cynara service for client, user accessing given privilege. + * Set callback and user_response_data to be called and passed when request processing is finished. + * + * \par Purpose: + * This API should be used to create check request for client identified by a triple + * (client, user, privilege) in custom defined session. + * Response can be received with cynara_async_process(). + * Check id is returned to pair request with response for canceling purposes. + * + * \par Typical use case: + * When cynara_async_check_cache() returned CYNARA_API_CACHE_MISS, so cynara service + * has to be asked, if a client requesting access to some privilege has proper rights. + * To receive matching response client sets callback and specifies arbitrary data to be passed + * to this callback. + * + * \par Method of function operation: + * \parblock + * Client (a process / application) requesting access to a privilege is running as some user. + * For such triple (client, user, privilege) a request event is created and added to pending + * requests for cynara_async_process() to process. + * + * Socket status will be changed to CYNARA_STATUS_FOR_RW, to ensure that cynara_async_process() + * will be triggered in event loop after socket is ready to send request to cynara service. + * After request is sent and there is nothing more to send to cynara service, status will change + * back to CYNARA_STATUS_FOR_READ. Status changes are delivered with cynara_status_callback. + * When function is successfully called unique check_id is returned. It is used for matching + * generated request with response, that will be received by registered callback. + * + * Because check_id is coded as 16-bit unsigned integer, there can be only 2^16 = 65536 pending + * requests. When response callback is called either because of getting answer or because + * of cancel check_id used for that request is released and can be reused by cynara library. + * When maximum of pending requests is reached cynara_async_create_request() fails with + * CYNARA_API_MAX_PENDING_REQUESTS error code. + * \endparblock + * + * \par Sync (or) Async: + * This is an asynchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * \parblock + * Call cynara_async_create_request() needs cynara_async structure to be created first with + * cynara_async_initialize(). + * Call cynara_async_cancel_request() to cancel pending request. + * Call cynara_async_process() to receive response. + * + * It is guaranteed that if cynara_async_create_request() function succeeds (CYNARA_API_SUCCESS) + * a callback will be called exactly once and that it will receive user_response_data. + * + * If function fails (returns negative error code) request won't be generated and won't be pending, + * callback function won't be ever called and user_response_data won't be remembered by library. + * + * Also no check_id will be generated and *p_check_id value should be ignored. + * cynara_async_create_request() called from within cynara_status_callback or + * cynara_response_callback with CYNARA_CALL_CAUSE_SERVICE_NOT_AVAILABLE or CYNARA_CALL_CAUSE_FINISH + * cause will return CYNARA_API_OPERATION_NOT_ALLOWED. + * + * String length cannot exceed CYNARA_MAX_ID_LENGTH ,otherwise CYNARA_API_INVALID_PARAM will be + * returned. + * \endparblock + * + * \param[in] p_cynara cynara_async structure. + * \param[in] client Application or process identifier. + * \param[in] client_session Client defined session. + * \param[in] user User of running client. + * \param[in] privilege Privilege that is a subject of a check. + * \param[out] p_check_id Placeholder for check id. If NULL, then no check_id is returned. + * \param[in] callback Function called when matching response is received. + * If NULL then no callback will be called when response, cancel, finish + * or service not availble error happens. + * \param[in] user_response_data User specific data, passed to callback is being only remembered + * by library. Cynara library does not take any actions on this pointer, + * except for giving it back to user in cynara_response_callback. + * Can be NULL. + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_MAX_PENDING_REQUESTS on too much pending requests + * \return other negative error code on error + */ +int cynara_async_create_request(cynara_async *p_cynara, const char *client, + const char *client_session, const char *user, const char *privilege, + cynara_check_id *p_check_id, cynara_response_callback callback, + void *user_response_data); + +/** + * \par Description: + * Creates simple access check request to cynara service for (potential) permission to take some + * action or access a resource. + * Set callback and user_response_data to be called and passed when request processing is finished. + * + * \par Purpose: + * This API should be used for a quick check if a user running application identified as client + * has access to a given privilege. + * Response can be received with cynara_async_process(). + * Check id is returned to pair request with response for canceling purposes. + * + * \par Typical use case: + * An application may use this API to check if it has (potential) permission to take some action + * or access resource in future (permissions may rarely change). The typical use would be to disable + * or hide some of functionalities if they probably could not be used anyways. + * + * \par Method of function operation: + * \parblock + * This function is very similar to cynara_async_create_request() with the difference, that in case + * of answer not being one of CYNARA_API_PERMISSION_DENIED or CYNARA_API_PERMISSION_ALLOWED, + * no external application will be consulted. Instead, CYNARA_API_ACCESS_NOT_RESOLVED is returned + * by a callback, meaning, that only creating full request through cynara_async_create_request() API + * would yield eventual answer. + * + * If access permission cannot be acquired without usage of external agents, callback can be + * called with CYNARA_CALL_CAUSE_ANSWER and response value being CYNARA_API_ACCESS_NOT_RESOLVED. + * \endparblock + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * \parblock + * Call cynara_async_create_simple_request() needs cynara_async structure to be created first + * with cynara_async_initialize(). + * Call cynara_async_cancel_request() to cancel pending request. + * Call cynara_async_process() to send request and receive response. + * + * The answer will be taken from cynara's database without consulting any external applications. + * If the answer cannot be resolved in one of CYNARA_API_ACCESS_ALLOWED or + * CYNARA_API_ACCESS_DENIED without communicating with external application, response returned + * through callback will have value CYNARA_API_ACCESS_NOT_RESOLVED. + * + * String length cannot exceed CYNARA_MAX_ID_LENGTH, otherwise CYNARA_API_INVALID_PARAM will be + * returned. + * \endparblock + * + * \param[in] p_cynara cynara_async structure. + * \param[in] client Application or process identifier. + * \param[in] client_session Client defined session. + * \param[in] user User of running client. + * \param[in] privilege Privilege that is a subject of a check. + * \param[out] p_check_id Placeholder for check id. If NULL, then no check_id is returned. + * \param[in] callback Function called when matching response is received. + * If NULL then no callback will be called when response, cancel, finish + * or service not availble error happens. + * \param[in] user_response_data User specific data, passed to callback is being only stored by + * library. Cynara library does not take any actions on this pointer, except for giving + * it back to user in cynara_response_callback. + * Can be NULL. + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_MAX_PENDING_REQUESTS on too much pending requests + * \return other negative error code on error + */ +int cynara_async_create_simple_request(cynara_async *p_cynara, const char *client, + const char *client_session, const char *user, + const char *privilege, cynara_check_id *p_check_id, + cynara_response_callback callback, void *user_response_data); + +/** + * \par Description: + * Process events that appeared on cynara socket. + * + * \par Purpose: + * Process events after they appear on cynara socket. + * + * \par Typical use case: + * After request was queued with cynara_async_create_request() or + * cynara_async_create_simple_request() this API will return response. + * When event loop will return readiness on cynara socket, client should use this API. + * + * \par Method of function operation: + * \parblock + * This API sends pending requests, receives all responses and reacts when cynara + * has disconnected. If cynara has disconnected all values in cache become invalid. During these + * operations status of cynara socket may change, so cynara_status_callback callback will be + * triggered to indicate these changes. cynara_response_callback callback will be triggered with + * cynara_async_call_cause::CYNARA_CALL_CAUSE_ANSWER as cause param when response is available. + * + * If cynara has disconnected it will be triggered with + * cynara_async_call_cause::CYNARA_CALL_CAUSE_SERVICE_NOT_AVAILABLE as cause param. + * \endparblock + * + * \par Sync (or) Async: + * This is an asynchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * Call to cynara_async_process() requires initialized cynara_async structure. For this use + * cynara_async_initialize(). cynara_async_process() called from within cynara_status_callback or + * cynara_response_callback with CYNARA_CALL_CAUSE_SERVICE_NOT_AVAILABLE or CYNARA_CALL_CAUSE_FINISH + * cause will return CYNARA_API_OPERATION_NOT_ALLOWED. + * + * \param[in] p_cynara cynara_async structure. + * + * \return CYNARA_API_SUCCESS on success + * \return negative error code on error + */ +int cynara_async_process(cynara_async *p_cynara); + +/** + * \par Description: + * Cancel request created by cynara_async_create_request() or cynara_async_create_simple_request(). + * + * \par Purpose: + * This API should be used to cancel pending check request, + * created by cynara_async_create_request() or cynara_async_create_simple_request(). + * + * \par Typical use case: + * When cynara client is no longer interested in receiving an answer. + * Same check_id value should be used to identify proper request as was generated during + * request creation with cynara_async_create_request() or cynara_async_create_simple_request(). + * + * \par Method of function operation: + * \parblock + * Cancels request created by cynara_async_create_request() or cynara_async_create_simple_request() + * call. + * + * cynara_status_callback callback may be triggered to be able to send cancel to cynara. + * cynara_response_callback callback will be triggered with with + * cynara_async_call_cause::CYNARA_CALL_CAUSE_CANCEL as cause param. + * + * If given id is not valid (was not requested or response callback was already delivered) + * cynara_async_cancel_request() returns CYNARA_API_INVALID_PARAM. + * \endparblock + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * Call to cynara_async_cancel_request() needs cynara_async structure to be created first. For this + * use cynara_async_initialize(). cynara_async_cancel_request() called from within + * cynara_status_callback or cynara_response_callback with CYNARA_CALL_CAUSE_SERVICE_NOT_AVAILABLE + * or CYNARA_CALL_CAUSE_FINISH cause will return CYNARA_API_OPERATION_NOT_ALLOWED. + * + * \param[in] p_cynara cynara_async structure. + * \param[in] check_id Check id to be cancelled + * + * \return CYNARA_API_SUCCESS on success + * \return negative error code on error + */ +int cynara_async_cancel_request(cynara_async *p_cynara, cynara_check_id check_id); + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_CLIENT_ASYNC_H */ diff --git a/include/cynara/cynara-client-plugin.h b/include/cynara/cynara-client-plugin.h new file mode 100644 index 0000000..70000e6 --- /dev/null +++ b/include/cynara/cynara-client-plugin.h @@ -0,0 +1,75 @@ +/* + * Copyright (c) 2014-2015 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * @file src/include/cynara-client-plugin.h + * @author Zofia Abramowska <z.abramowska@samsung.com> + * @author Oskar Switalski <o.switalski@samsung.com> + * @version 1.0 + * @brief This file defines cynara client side of external plugin interface - + * ClientPluginInterface. + */ + +#ifndef CYNARACLIENTPLUGIN_H_ +#define CYNARACLIENTPLUGIN_H_ + +#include <memory> + +#include <plugin/ExternalPluginInterface.h> +#include <types/ClientSession.h> +#include <types/PolicyResult.h> + +namespace Cynara { + +class ClientPluginInterface; +typedef std::shared_ptr<ClientPluginInterface> ClientPluginInterfacePtr; + +/** + * A class defining external plugins interface. + * + * These plugins work inside of cynara client library. They interpret + * PolicyResult returned by cynara in terms of: + * * cacheability - tells, whether value should be cached (for e.g. policyType like + * ALLOW_ONCE should not be cached) + * * usability - whether cache entry can still be used (for e.g. policy allowing access for + * given type) + * * value - translates PolicyResult to CYNARA_API_ACCESS_ALLOWED or CYNARA_API_ACCESS_DENIED + * + * Plugin implementing ClientPluginInterface must implement ExternalPluginInterface. + * Creation/destruction functions with signatures compatible to Cynara::create_t and + * Cynara::destroy_t must be provided as factories of ClientPluginInterface. + */ +class ClientPluginInterface : public ExternalPluginInterface { +public: + /** + * Return entry cacheability + */ + virtual bool isCacheable(const ClientSession &session, const PolicyResult &result) = 0; + /** + * Return entry usability + */ + virtual bool isUsable(const ClientSession &session, const ClientSession &prevSession, + bool &updateSession, PolicyResult &result) = 0; + /** + * Translate PolicyResult to CYNARA_API_ACCESS_ALLOWED or CYNARA_API_ACCESS_DENIED + */ + virtual int toResult(const ClientSession &session, PolicyResult &result) = 0; + + virtual ~ClientPluginInterface() {}; +}; + +} + +#endif // CYNARACLIENTPLUGIN_H_ diff --git a/include/cynara/cynara-client.h b/include/cynara/cynara-client.h new file mode 100644 index 0000000..d1388ec --- /dev/null +++ b/include/cynara/cynara-client.h @@ -0,0 +1,305 @@ +/* + * Copyright (c) 2014-2016 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * @file src/include/cynara-client.h + * @author Lukasz Wojciechowski <l.wojciechow@partner.samsung.com> + * @author Zofia Abramowska <z.abramowska@samsung.com> + * @author Oskar Switalski <o.switalski@samsung.com> + * @version 1.0 + * @brief This file contains client APIs of Cynara available with libcynara-client. + * @example cynara-client.example + */ + +#ifndef CYNARA_CLIENT_H +#define CYNARA_CLIENT_H + +#include <stddef.h> + +#include <cynara/cynara-error.h> +#include <cynara/cynara-limits.h> + +#ifdef __cplusplus +extern "C" { +#endif + +typedef struct cynara cynara; +typedef struct cynara_configuration cynara_configuration; + +/** + * \par Description: + * Initialize cynara_configuration. Create structure used in following configuration + * API calls. + * + * \par Purpose: + * For configuration parameter to be used in cynara_initialize() function, this API must be + * called before any other cynara configuration API function. + * It will create cynara_configuration structure, an optional parameter of cynara initialization. + * + * \par Typical use case: + * Once before setting parameters of cynara configuration and passing to + * cynara_initialize(). + * + * \par Method of function operation: + * This API initializes inner library structures and in case of success returns pointer + * to created cynara_configuration structure. + * + * \par Sync (or) Async: + * This as a synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * Structure cynara_configuration created by cynara_configuration_create() call + * should be released with cynara_configuration_destroy(). + * Structure cynara_configuration should be destroyed after passing it to + * cynara_initialize(). + * + * \param[out] pp_conf Placeholder for created cynara_configuration structure. + * + * \return CYNARA_API_SUCCESS on success + * or negative error code on error. + */ +int cynara_configuration_create(cynara_configuration **pp_conf); + +/** + * \par Description: + * Release cynara_configuration structure created with cynara_configuration_create(). + * + * \par Purpose: + * This API should be used to clean up after usage of cynara_configuration. + * + * \par Typical use case: + * Once cynara_configuration is not needed. + * + * \par Method of function operation: + * This API releases inner library structure and destroys cynara_configuration structure. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \param[in] p_conf cynara_configuration structure. If NULL, the call has no effect. + */ +void cynara_configuration_destroy(cynara_configuration *p_conf); + +/** + * \par Description: + * Set client cache size. + * + * \par Purpose: + * This API is used to change default number of cached responses returned from cynara. + * + * \par Typical use case: + * Once after cynara_configuration is created with cynara_configuration_create() + * and before passing configuration to cynara_initialize(). + * + * \par Method of function operation: + * This API initializes cache with given capacity. + * + * \par Sync (or) Async: + * This as a synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into protected critical section. + * + * \par Important notes: + * After passing cynara_configuration to cynara_initialize() calling this API will have + * no effect. + * + * \param[in] p_conf cynara_configuration structure pointer. + * \param[in] cache_size Cache size to be set. + * + * \return CYNARA_API_SUCCESS on success + * or negative error code on error. + */ +int cynara_configuration_set_cache_size(cynara_configuration *p_conf, size_t cache_size); + +/** + * \par Description: + * Initialize cynara-client library with given configuration. + * Create structure used in following API calls. + * + * \par Purpose: + * This API must be used by prior calling cynara_check() function. + * + * \par Typical use case: + * Once before a service can call cynara_check(). + * + * \par Method of function operation: + * This API initializes inner library structures and in case of success + * creates and returns cynara structure. + * + * \par Sync (or) Async: + * This is a Synchronous API. + * + * \par Thread-safeness: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * Structure cynara created by cynara_initialize() call should be released with cynara_finish(). + * + * \param[out] pp_cynara Place holder for created cynara structure. + * \param[in] p_conf Configuration for cynara-client library. NULL for default parameters. + * [TODO define and describe functions for custom parameters]. + * + * \return CYNARA_API_SUCCESS on success, or error code on error. + */ +int cynara_initialize(cynara **pp_cynara, const cynara_configuration *p_conf); + +/** + * \par Description: + * Release cynara-client library and destroy structure created with cynara_initialize(). + * + * \par Purpose: + * This API should be used to clean up after usage of cynara-client library. + * + * \par Typical use case: + * Once after last call to cynara_check(). + * + * \par Method of function operation: + * This API releases inner library structures and destroys cynara structure. + * + * \par Sync (or) Async: + * This is a Synchronous API. + * + * \par Thread-safeness: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * No other call to libcynara-client should be made after call to cynara_finish(). + * + * \param[in] p_cynara Cynara structure. + * + * \return CYNARA_API_SUCCESS on success, or error code on error. + */ +int cynara_finish(cynara *p_cynara); + +/** + * \par Description: + * Check client, user access for given privilege. + * + * \par Purpose: + * This API should be used to check if a user running application identified as client + * has access to a privilege. + * + * \par Typical use case: + * A service want to ask trusted process (Cynara), if a client demanding access to some privilege + * has proper rights. + * + * \par Method of function operation: + * Client (a process / application) demanding access to a privilege is running as some user. + * For such triple an access to a privilege is checked by calling cynara. + * Depending on defined policy, an external application may be launched to ask user a question, + * e.g. if [s]he wants to allow client to use a privilege. Additional parameter client_session + * may be used to distinguish between client session (e.g. for allowing access only for this + * particular application launch). + * + * \par Sync (or) Async: + * This is a Synchronous API. + * + * \par Thread-safeness: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * \parblock + * An external application may be launched to allow user interaction in granting or denying access. + * + * Call to cynara_check() needs cynara structure to be created first with call to + * cynara_initialize(). + * + * String length cannot exceed CYNARA_MAX_ID_LENGTH, otherwise CYNARA_API_INVALID_PARAM will be + * returned. + * \endparblock + * + * \param[in] p_cynara Cynara structure. + * \param[in] client Application or process identifier. + * \param[in] client_session Session of client (connection, launch). + * \param[in] user User running client. + * \param[in] privilege Privilege that is a subject of a check.. + * + * \return CYNARA_API_ACCESS_ALLOWED on access allowed, CYNARA_API_ACCESS_DENIED on access denial + * or other error code on error. + */ +int cynara_check(cynara *p_cynara, const char *client, const char *client_session, const char *user, + const char *privilege); + +/** + * \par Description: + * Check for (potential) permission to take some action or access a resource. + * + * \par Purpose: + * This API should be used for a quick check if a user running application identified as client + * has access to a given privilege. + * + * \par Typical use case: + * An application may use this API to check, if it has (potential) permission to take some action + * or access resource in future (permissions may rarely change). The typical use would be to disable + * or hide some of functionalities, if they probably could not be used anyways. + * + * \par Method of function operation: + * This function is very similar to cynara_check() with the difference, that in case of answer not + * being one of CYNARA_API_ACCESS_DENIED or CYNARA_API_ACCESS_ALLOWED, no external application will + * be consulted. Instead, CYNARA_API_ACCESS_NOT_RESOLVED is returned, meaning, that only running + * full cynara_check() API would yield eventual answer. + * Similarly, like in cynara_check(), argument client_session can be used to distinguish client + * sessions and grant possibility to yield answer from cache. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * \parblock + * The answer will be taken from Cynara's database without consulting any external applications. + * If the answer cannot be resolved in one of CYNARA_API_PERMISSION_DENIED or + * CYNARA_API_PERMISSION_ALLOWED without communicating with external application the API will return + * CYNARA_API_ACCESS_NOT_RESOLVED. + * + * Call to cynara_simple_check() needs cynara structure to be created first with call to + * cynara_initialize(). String length cannot exceed CYNARA_MAX_ID_LENGTH, otherwise + * CYNARA_API_INVALID_PARAM will be returned. + * \endparblock + * + * \param[in] p_cynara Cynara structure. + * \param[in] client Application or process identifier. + * \param[in] client_session Session of client (connection, launch). + * \param[in] user User running client. + * \param[in] privilege Privilege that is a subject of a check. + * + * \return CYNARA_API_ACCESS_ALLOWED on access allowed, CYNARA_API_ACCESS_DENIED on access denial, + * CYNARA_API_ACCESS_NOT_RESOLVED when decision is not known without usage of external plugins or + * agents or negative error code on error. + */ +int cynara_simple_check(cynara *p_cynara, const char *client, const char *client_session, + const char *user, const char *privilege); + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_CLIENT_H */ diff --git a/include/cynara/cynara-creds-commons.h b/include/cynara/cynara-creds-commons.h new file mode 100644 index 0000000..81b9784 --- /dev/null +++ b/include/cynara/cynara-creds-commons.h @@ -0,0 +1,132 @@ +/* + * Copyright (c) 2014-2015 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * @file src/include/cynara-creds-commons.h + * @author Lukasz Wojciechowski <l.wojciechow@partner.samsung.com> + * @author Radoslaw Bartosiak <r.bartosiak@samsung.com> + * @author Aleksander Zdyb <a.zdyb@samsung.com> + * @author Oskar Switalski <o.switalski@samsung.com> + * @version 1.0 + * @brief This file contains common APIs for Cynara credentials helper. + */ + +#ifndef CYNARA_CREDS_COMMONS_H +#define CYNARA_CREDS_COMMONS_H + +#include <cynara/cynara-error.h> + +enum cynara_client_creds { + CLIENT_METHOD_SMACK, + CLIENT_METHOD_PID, + + CLIENT_METHOD_DEFAULT = 0xFFFF, +}; + +enum cynara_user_creds { + USER_METHOD_UID, + USER_METHOD_GID, + + USER_METHOD_DEFAULT = 0xFFFF, +}; + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \par Description: + * Gets the system default method value for client feature used in cynara-creds. + * + * \par Purpose: + * Functions cynara_creds_dbus_get_client() and cynara_creds_socket_get_client() take a method + * parameter, which determines a kind of process feature (i.e PID, SMACK label) returned by them. + * The described function provides implementation for obtaining a system default value + * for this parameter. + * + * \par Typical use case: + * The function might be called before cynara_creds_dbus_get_client() + * and cynara_creds_socket_get_client(), when functions shall be invoked with system default + * value of method parameter. + * + * \par Method of function operation: + * When this function is called for the first time it reads and returns the value of client_default + * parameter from /etc/cynara/creds.conf file. + * Returned value is cached so subsequent calls will not consult file again but use cached value. + * This also means that after the initial call any changes in the file will be ignored for the + * remaining lifetime of the process. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is thread-safe. + * + * \param[out] method Placeholder for system default client feature + * (like CLIENT_METHOD_SMACK, CLIENT_METHOD_PID) + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or + * there are errors in configuration file + * \return CYNARA_API_OUT_OF_MEMORY if there is error in memory allocation + * \return CYNARA_API_UNKNOWN_ERROR if there is other error + * + */ +int cynara_creds_get_default_client_method(enum cynara_client_creds *method); + +/** + * \par Description: + * Gets the system default method value for user feature used in cynara-creds. + * + * \par Purpose: + * Functions cynara_creds_dbus_get_user() and cynara_creds_socket_get_user() take a method + * parameter, which determines a kind of process feature (i.e UID, GID) returned by them. + * The described function provides implementation for obtaining a system default value + * for this parameter. + * + * \par Typical use case: + * The function might be called before cynara_creds_dbus_get_user() + * and cynara_creds_socket_get_user() when functions shall be invoked with system default + * value of method parameter. + * + * \par Method of function operation: + * When this function is called for the first time it reads and returns the value of user_default + * parameter from /etc/cynara/creds.conf file. + * Returned value is cached so subsequent calls will not consult file again but use cached value. + * This also means that after the initial call any changes in the file will be ignored for the + * remaining lifetime of the process. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is thread-safe. + * + * \param[out] method Placeholder for system default user feature + * (like USER_METHOD_UID, USER_METHOD_GID) + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or + * there are errors in configuration file + * \return CYNARA_API_OUT_OF_MEMORY if there is error in memory allocation + * \return CYNARA_API_UNKNOWN_ERROR if there is other error + */ +int cynara_creds_get_default_user_method(enum cynara_user_creds *method); + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_CREDS_COMMONS_H */ diff --git a/include/cynara/cynara-creds-dbus.h b/include/cynara/cynara-creds-dbus.h new file mode 100644 index 0000000..04af96f --- /dev/null +++ b/include/cynara/cynara-creds-dbus.h @@ -0,0 +1,171 @@ +/* + * Copyright (c) 2014-2015 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * @file src/include/cynara-creds-dbus.h + * @author Lukasz Wojciechowski <l.wojciechow@partner.samsung.com> + * @author Radoslaw Bartosiak <r.bartosiak@samsung.com> + * @author Oskar Switalski <o.switalski@samsung.com> + * @version 1.0 + * @brief This file contains Cynara credentials helper APIs for dbus clients. + * @example cynara-creds-dbus.example + */ + +#ifndef CYNARA_CREDS_DBUS_H +#define CYNARA_CREDS_DBUS_H + +#include <dbus/dbus.h> +#include <sys/types.h> + +#include <cynara/cynara-creds-commons.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \par Description: + * Creates a client identification string with given method. Client is a process identified by the + * unique name at the other side of the dbus connection. + * + * \par Purpose: + * Client identification string is required for cynara_check() and cynara_async_create_request() + * functions. + * + * \par Typical use case: + * The function is called before the call of cynara_check() or cynara_async_create_request() + * function. Returned string is used as client parameter in cynara_check() or + * cynara_async_create_request() function. String is released with free() function when it is no + * longer needed. + * + * \par Method of function operation: + * The function generates client string by calling a method from DBus Interface + * ("org.freedesktop.DBus") which is placed on system bus ("org.freedesktop.DBus"). + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * Memory for returned client string is obtained with malloc(), and should be freed with free(). + * Allocated string is returned only, when function succeeds. + * If method is CLIENT_METHOD_DEFAULT then it will be chosen based on Cynara configuration file. + * + * \param[in] connection DBus connection to a bus. It manages incomming and outgoing messages + * \param[in] uniqueName DBus identifier of the client + * \param[in] method Method of client identifier creation + * \param[out] client Placeholder for allocated string containing client id + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_INVALID_PARAM when client is NULL or uniqueName or client has wrong + * value (i.e NULL or non-existing) + * \return CYNARA_API_METHOD_NOT_SUPPORTED when requested method is not supported + * \return CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or + * there are errors in configuration file + * \return CYNARA_API_OUT_OF_MEMORY when there was error allocating memory + */ +int cynara_creds_dbus_get_client(DBusConnection *connection, const char *uniqueName, + enum cynara_client_creds method, char **client); + +/** + * \par Description: + * Creates a user identification string with given method. User is an executor of process + * at the other side of socket. + * + * \par Purpose: + * User identification string is required for cynara_check() and cynara_async_create_request() + * functions. + * + * \par Typical use case: + * The function is called before the call of cynara_check() or cynara_async_create_request() + * function. Returned string is used as user parameter in cynara_check() or + * cynara_async_create_request() function. String is released with free() function when it is no + * longer needed. + * + * \par Method of function operation: + * The function generates user string by calling a method from DBus Interface + * ("org.freedesktop.DBus") which is placed on system bus ("org.freedesktop.DBus"). + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * Memory for returned user string is obtained with malloc(), and should be freed with free(). + * Allocated string is returned only, when function succeeds. + * If method is USER_METHOD_DEFAULT then it will be chosen based on Cynara configuration file. + * + * \param[in] connection DBus connection to a bus. It manages incomming and outgoing messages + * \param[in] uniqueName DBus identifier of the client invoked by the user + * \param[in] method Method of client identifier creation + * \param[out] user Placeholder for allocated string containing user id + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_INVALID_PARAM when user is NULL or connection is not valid DBus connection or + * uniqueName does not represent a process conected to the DBus + * \return CYNARA_API_METHOD_NOT_SUPPORTED when requested method is not supported + * \return CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or + * there are errors in configuration file + * \return CYNARA_API_OUT_OF_MEMORY when there was error allocating memory + */ +int cynara_creds_dbus_get_user(DBusConnection *connection, const char *uniqueName, + enum cynara_user_creds method, char **user); + +/** + * \par Description: + * Return PID of a proces identified by the unique name at the other side of the dbus connection. + * + * \par Purpose: + * PID may be used for client_session creation with cynara_helper_session_from_pid() function + * from libcynara-helper-session library. Client_session is needed for cynara_check() + * and cynara_async_create_request() functions. + * + * \par Typical use case: + * The function is called before the call of cynara_helper_session_from_pid() function. + * + * \par Method of function operation: + * The function reads PID of the peer by calling a method from DBus Interface + * ("org.freedesktop.DBus") which is placed on system bus ("org.freedesktop.DBus") + * with "GetConnectionUnixProcessID" argument. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \param[in] connection DBus connection to a bus. It manages incomming and outgoing messages + * \param[in] uniqueName DBus identifier of the client invoked by the user + * \param[out] pid Placeholder for PID returned by function + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_INVALID_PARAM when socket_fd is not valid connected socket descriptor + * \return CYNARA_API_UNKNOWN_ERROR when system function fails in incredible situation + * \return CYNARA_API_OUT_OF_MEMORY when there was error allocating memory + */ +int cynara_creds_dbus_get_pid(DBusConnection *connection, const char *uniqueName, pid_t *pid); + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_CREDS_DBUS_H */ diff --git a/include/cynara/cynara-creds-gdbus.h b/include/cynara/cynara-creds-gdbus.h new file mode 100644 index 0000000..2334e45 --- /dev/null +++ b/include/cynara/cynara-creds-gdbus.h @@ -0,0 +1,167 @@ +/* + * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * @file src/include/cynara-creds-gdbus.h + * @author Jacek Bukarewicz <j.bukarewicz@samsung.com> + * @author Oskar Switalski <o.switalski@samsung.com> + * @version 1.0 + * @brief This file contains Cynara credentials helper APIs for gdbus clients. + * @example cynara-creds-gdbus.example + */ + +#ifndef CYNARA_CREDS_GDBUS_H +#define CYNARA_CREDS_GDBUS_H + +#include <gio/gio.h> +#include <sys/types.h> + +#include <cynara/cynara-creds-commons.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \par Description: + * Creates a client identification string with given method. Client is a process identified by the + * unique name at the other side of the dbus connection. + * + * \par Purpose: + * Client identification string is required for cynara_check() and cynara_async_create_request() + * functions. + * + * \par Typical use case: + * The function is called before the call of cynara_check() or cynara_async_create_request() + * function. Returned string is used as client parameter in cynara_check() or + * cynara_async_create_request() function. String is released with g_free() function when it is no + * longer needed. + * + * \par Method of function operation: + * The function generates client string by calling a method from DBus Interface + * ("org.freedesktop.DBus") which is placed on system bus ("org.freedesktop.DBus"). + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * Memory for returned user string should be freed with g_free(). + * Allocated string is returned only, when function succeeds. + * If method is CLIENT_METHOD_DEFAULT then it will be chosen based on Cynara configuration file. + * + * \param[in] connection DBus connection to a bus. It manages incomming and outgoing messages + * \param[in] uniqueName DBus identifier of the client + * \param[in] method Method of client identifier creation + * \param[out] client Placeholder for allocated string containing client id + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_INVALID_PARAM when client is NULL or uniqueName or client has wrong + * value (i.e NULL or non-existing) + * \return CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or + * there are errors in configuration file + * \return CYNARA_API_METHOD_NOT_SUPPORTED when requested method is not supported + */ +int cynara_creds_gdbus_get_client(GDBusConnection *connection, const gchar *uniqueName, + enum cynara_client_creds method, gchar **client); + +/** + * \par Description: + * Creates a user identification string with given method. User is an executor of process + * at the other side of socket. + * + * \par Purpose: + * User identification string is required for cynara_check() and cynara_async_create_request() + * functions. + * + * \par Typical use case: + * The function is called before the call of cynara_check() or cynara_async_create_request() + * function. Returned string is used as user parameter in cynara_check() or + * cynara_async_create_request() function. String is released with g_free() function when it is no + * longer needed. + * + * \par Method of function operation: + * The function generates user string by calling a method from DBus Interface + * ("org.freedesktop.DBus") which is placed on system bus ("org.freedesktop.DBus"). + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * Memory for returned user string should be freed with g_free(). + * Allocated string is returned only, when function succeeds. + * If method is USER_METHOD_DEFAULT then it will be chosen based on Cynara configuration file. + * + * \param[in] connection DBus connection to a bus. It manages incomming and outgoing messages + * \param[in] uniqueName DBus identifier of the client invoked by the user + * \param[in] method Method of client identifier creation + * \param[out] user Placeholder for allocated string containing user id + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_INVALID_PARAM when user is NULL or connection is not valid DBus connection or + * uniqueName does not represent a process conected to the DBus + * \return CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or + * there are errors in configuration file + * \return CYNARA_API_METHOD_NOT_SUPPORTED when requested method is not supported + */ +int cynara_creds_gdbus_get_user(GDBusConnection *connection, const gchar *uniqueName, + enum cynara_user_creds method, gchar **user); + +/** + * \par Description: + * Return PID of a process identified by the unique name at the other side of the dbus connection. + * + * \par Purpose: + * PID may be used for client_session creation with cynara_helper_session_from_pid() function + * from libcynara-helper-session library. Client_session is needed for cynara_check() + * and cynara_async_create_request() functions. + * + * \par Typical use case: + * The function is called before the call of cynara_helper_session_from_pid() function. + * + * \par Method of function operation: + * The function reads PID of the peer by calling a method from DBus Interface + * ("org.freedesktop.DBus") which is placed on system bus ("org.freedesktop.DBus") + * with "GetConnectionUnixProcessID" argument. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \param[in] connection DBus connection to a bus. It manages incomming and outgoing messages + * \param[in] uniqueName DBus identifier of the client invoked by the user + * \param[out] pid Placeholder for PID returned by function + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_INVALID_PARAM when one of parameters is not valid + * \return CYNARA_API_UNKNOWN_ERROR when function fails because of unknown error + */ +int cynara_creds_gdbus_get_pid(GDBusConnection *connection, const gchar *uniqueName, pid_t *pid); + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_CREDS_GDBUS_H */ diff --git a/include/cynara/cynara-creds-self.h b/include/cynara/cynara-creds-self.h new file mode 100644 index 0000000..580a19d --- /dev/null +++ b/include/cynara/cynara-creds-self.h @@ -0,0 +1,121 @@ +/* + * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * @file src/include/cynara-creds-self.h + * @author Zofia Abramowska <z.abramowska@samsung.com> + * @version 1.0 + * @brief This file contains Cynara credentials helper APIs for current process + * @example cynara-creds-self.example + */ + +#ifndef CYNARA_CREDS_SELF_H +#define CYNARA_CREDS_SELF_H + +#include <sys/types.h> + +#include <cynara/cynara-creds-commons.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \par Description: + * Creates a client identification string with given method. Client is a current process. + * + * \par Purpose: + * Client identification string is required for cynara_check() and cynara_async_create_request() + * functions. + * + * \par Typical use case: + * The function is called before the call of cynara_check() or cynara_async_create_request() + * function. Returned string is used as client parameter in cynara_check() or + * cynara_async_create_request() function. String is released with free() function when it is no + * longer needed. + * + * \par Method of function operation: + * The function generates client string using current process context. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * Memory for returned client string is obtained with malloc(), and should be freed with free(). + * Allocated string is returned only, when function succeeds. + * If method is CLIENT_METHOD_DEFAULT then it will be chosen based on Cynara configuration file. + * + * \param[in] method Method of client identifier creation + * \param[out] client Placeholder for allocated string containing client id + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_INVALID_PARAM when client is NULL + * \return CYNARA_API_METHOD_NOT_SUPPORTED when requested method is not supported + * \return CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or + * there are errors in configuration file + * \return CYNARA_API_OUT_OF_MEMORY when there was error allocating memory + */ +int cynara_creds_self_get_client(enum cynara_client_creds method, char **client); + +/** + * \par Description: + * Creates a user identification string with given method. User is current process. + * + * \par Purpose: + * User identification string is required for cynara_check() and cynara_async_create_request() + * functions. + * + * \par Typical use case: + * The function is called before the call of cynara_check() or cynara_async_create_request() + * function. Returned string is used as user parameter in cynara_check() or + * cynara_async_create_request() function. String is released with free() function when it is no + * longer needed. + * + * \par Method of function operation: + * The function generates user string using current process context. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * Memory for returned user string is obtained with malloc(), and should be freed with free(). + * Allocated string is returned only, when function succeeds. + * If method is USER_METHOD_DEFAULT then it will be chosen based on Cynara configuration file. + * + * \param[in] method Method of user identifier creation + * \param[out] user Placeholder for allocated string containing user id + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_INVALID_PARAM when user is NULL + * \return CYNARA_API_METHOD_NOT_SUPPORTED when requested method is not supported + * \return CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or + * there are errors in configuration file + * \return CYNARA_API_OUT_OF_MEMORY when there was error allocating memory + */ +int cynara_creds_self_get_user(enum cynara_user_creds method, char **user); + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_CREDS_SELF_H */ diff --git a/include/cynara/cynara-creds-socket.h b/include/cynara/cynara-creds-socket.h new file mode 100644 index 0000000..fe5cbdb --- /dev/null +++ b/include/cynara/cynara-creds-socket.h @@ -0,0 +1,161 @@ +/* + * Copyright (c) 2014-2015 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * @file src/include/cynara-creds-socket.h + * @author Radoslaw Bartosiak <r.bartosiak@samsung.com> + * @author Aleksander Zdyb <a.zdyb@samsung.com> + * @author Lukasz Wojciechowski <l.wojciechow@partner.samsung.com> + * @author Oskar Switalski <o.switalski@samsung.com> + * @version 1.0 + * @brief This file contains Cynara credentials helper APIs for socket clients. + * @example cynara-creds-socket.example + */ + +#ifndef CYNARA_CREDS_SOCKET_H +#define CYNARA_CREDS_SOCKET_H + +#include <sys/types.h> + +#include <cynara/cynara-creds-commons.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \par Description: + * Creates a client identification string with given method. Client is a process at the other + * side of socket. + * + * \par Purpose: + * Client identification string is required for cynara_check() and cynara_async_create_request() + * functions. + * + * \par Typical use case: + * The function is called before the call of cynara_check() or cynara_async_create_request() + * function. Returned string is used as client parameter in cynara_check() or + * cynara_async_create_request() function. String is released with free() function when it is no + * longer needed. + * + * \par Method of function operation: + * The function generates client string using SO_PEERCRED on socket. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * Memory for returned client string is obtained with malloc(), and should be freed with free(). + * Allocated string is returned only, when function succeeds. + * If method is CLIENT_METHOD_DEFAULT then it will be chosen based on Cynara configuration file. + * + * \param[in] socket_fd Descriptor of open connected UNIX socket + * \param[in] method Method of client identifier creation + * \param[out] client Placeholder for allocated string containing client id + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_INVALID_PARAM when client is NULL or socket_fd is not valid connected socket + * descriptor + * \return CYNARA_API_METHOD_NOT_SUPPORTED when requested method is not supported + * \return CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or + * there are errors in configuration file + * \return CYNARA_API_OUT_OF_MEMORY when there was error allocating memory + */ +int cynara_creds_socket_get_client(int socket_fd, enum cynara_client_creds method, char **client); + +/** + * \par Description: + * Creates a user identification string with given method. User is an executor of process + * at the other side of socket. + * + * \par Purpose: + * User identification string is required for cynara_check() and cynara_async_create_request() + * functions. + * + * \par Typical use case: + * The function is called before the call of cynara_check() or cynara_async_create_request() + * function. Returned string is used as user parameter in cynara_check() or + * cynara_async_create_request() function. String is released with free() function when it is no + * longer needed. + * + * \par Method of function operation: + * The function generates user string using SO_PEERCRED on socket. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \par Important notes: + * Memory for returned user string is obtained with malloc(), and should be freed with free(). + * Allocated string is returned only, when function succeeds. + * If method is USER_METHOD_DEFAULT then it will be chosen based on Cynara configuration file. + * + * \param[in] socket_fd Descriptor of open connected UNIX socket + * \param[in] method Method of user identifier creation + * \param[out] user Placeholder for allocated string containing user id + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_INVALID_PARAM when user is NULL or socket_fd is not valid connected socket + * descriptor + * \return CYNARA_API_METHOD_NOT_SUPPORTED when requested method is not supported + * \return CYNARA_API_CONFIGURATION_ERROR if the configuration file can not be opened or + * there are errors in configuration file + * \return CYNARA_API_OUT_OF_MEMORY when there was error allocating memory + */ +int cynara_creds_socket_get_user(int socket_fd, enum cynara_user_creds method, char **user); + +/** + * \par Description: + * Return PID of process at the other side of socket. + * + * \par Purpose: + * PID may be used for client_session creation with cynara_session_from_pid() function + * from libcynara-session library. Client_session is needed for cynara_check() + * and cynara_async_create_request() functions. + * + * \par Typical use case: + * The function is called before the call of cynara_session_from_pid() function. + * + * \par Method of function operation: + * The function reads PID of peer using SO_PEERCRED on socket. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is NOT thread-safe. If functions from described API are called by multithreaded + * application from different threads, they must be put into mutex protected critical section. + * + * \param[in] socket_fd Descriptor of open connected UNIX socket + * \param[out] pid Placeholder for pid + * + * \return CYNARA_API_SUCCESS on success + * \return CYNARA_API_INVALID_PARAM when socket_fd is not valid connected socket descriptor + * \return CYNARA_API_UNKNOWN_ERROR when system function fails in incredible situation + */ +int cynara_creds_socket_get_pid(int socket_fd, pid_t *pid); + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_CREDS_SOCKET_H */ diff --git a/include/cynara/cynara-error.h b/include/cynara/cynara-error.h new file mode 100644 index 0000000..8316f1d --- /dev/null +++ b/include/cynara/cynara-error.h @@ -0,0 +1,148 @@ +/* + * Copyright (c) 2014-2017 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * @file src/include/cynara-error.h + * @author Lukasz Wojciechowski <l.wojciechow@partner.samsung.com> + * @author Zofia Abramowska <z.abramowska@samsung.com> + * @author Radoslaw Bartosiak <r.bartosiak@samsung.com> + * @author Aleksander Zdyb <a.zdyb@samsung.com> + * @version 1.0 + * @brief This file contains error codes returned by APIs of Cynara. + */ + +#ifndef CYNARA_ERROR_H +#define CYNARA_ERROR_H + +#include <stddef.h> + +/** + * \name Return Codes + * Exported by the foundation API. Return codes beginning with negative codes indicate an error. + * @{ +*/ + +/*! \brief indicating that API call was interrupted by user*/ +#define CYNARA_API_INTERRUPTED 4 + +/*! \brief indicating access that cannot be resolved without further actions*/ +#define CYNARA_API_ACCESS_NOT_RESOLVED 3 + +/*! \brief indicating access that was checked is allowed */ +#define CYNARA_API_ACCESS_ALLOWED 2 + +/*! \brief indicating that access that was checked is denied */ +#define CYNARA_API_ACCESS_DENIED 1 + +/*! \brief indicating the result of the one specific API is successful */ +#define CYNARA_API_SUCCESS 0 + +/*! \brief indicating that value is not present in cache */ +#define CYNARA_API_CACHE_MISS -1 + +/*! \brief indicating that pending requests reached maximum */ +#define CYNARA_API_MAX_PENDING_REQUESTS -2 + +/*! \brief indicating system is running out of memory state */ +#define CYNARA_API_OUT_OF_MEMORY -3 + +/*! \brief indicating the API's parameter is malformed */ +#define CYNARA_API_INVALID_PARAM -4 + +/*! \brief indicating that service is not available */ +#define CYNARA_API_SERVICE_NOT_AVAILABLE -5 + +/*! \brief indicating that provided method is not supported by library */ +#define CYNARA_API_METHOD_NOT_SUPPORTED -6 + +/*! \brief cynara service does not allow to perform requested operation */ +#define CYNARA_API_OPERATION_NOT_ALLOWED -7 + +/*! \brief cynara service failed to perform requested operation */ +#define CYNARA_API_OPERATION_FAILED -8 + +/*! \brief cynara service hasn't found requested bucket */ +#define CYNARA_API_BUCKET_NOT_FOUND -9 + +/*! \brief indicating an unknown error */ +#define CYNARA_API_UNKNOWN_ERROR -10 + +/*! \brief indicating configuration error */ +#define CYNARA_API_CONFIGURATION_ERROR -11 + +/*! \brief indicating invalid parameter in command-line */ +#define CYNARA_API_INVALID_COMMANDLINE_PARAM -12 + +/*! \brief indicating that provided buffer is too short */ +#define CYNARA_API_BUFFER_TOO_SHORT -13 + +/*! \brief indicating that database is corrupted */ +#define CYNARA_API_DATABASE_CORRUPTED -14 + +/*! \brief indicating that user doesn't have enough permission to perform action */ +#define CYNARA_API_PERMISSION_DENIED -15 +/** @}*/ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \par Description: + * Returns the error string in the user-supplied buffer buf of length buflen. + * + * \par Purpose: + * This function populates passed argument buf with a string that describes the error code + * passed in the argument errnum, possibly using the LC_MESSAGES part of the current locale + * to select the appropriate language. + * + * \par Typical use case: + * Once after any of API functions returns negative value (if the error message is to be presented + * to the user). + * + * \par Method of function operation: + * This function copies error string to memory pointed by argument buf along with termination + * character ('\0'). + * + * \par Sync (or) async: + * This is a synchronous API. + * + * \par Thread-safety: + * This function is thread-safe as long as setlocale() is not invoked concurrently. + * + * \par Important notes: + * This function copies error string to memory pointed by argument buf only if the buffer is + * of sufficient size (indicated by argument buflen). User is responsible for allocating sufficient + * memory for both error string and termination character ('\0'). + * Moreover, the user must not invoke setlocale() concurrently with this function, because results + * are unspecified. + * + * \param[in] errnum error number + * \param[out] buf buffer for error message + * \param[in] buflen buffer size + * + * \return CYNARA_API_SUCCESS on success, CYNARA_API_BUFFER_TOO_SHORT, if error message couldn't fit + * into allocated buffer, or CYNARA_API_INVALID_PARAM if errnum is not a valid error number + * or argument buf is NULL. + * + * \brief Obtain error message from error number. + */ +int cynara_strerror(int errnum, char *buf, size_t buflen); + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_ERROR_H */ diff --git a/include/cynara/cynara-limits.h b/include/cynara/cynara-limits.h new file mode 100644 index 0000000..f4e98c1 --- /dev/null +++ b/include/cynara/cynara-limits.h @@ -0,0 +1,35 @@ +/* + * Copyright (c) 2015-2016 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * @file src/include/cynara-limits.h + * @author Rafal Krypa <r.krypa@samsung.com> + * @version 1.0 + * @brief This file contains limits for parameter sizes of Cynara APIs. + */ + +#ifndef CYNARA_LIMITS_H +#define CYNARA_LIMITS_H + +/*! \brief Maximum length of text identifier accepted by Cynara */ +#define CYNARA_MAX_ID_LENGTH 4096 + +/*! \brief Maximum size of vector accepted by Cynara */ +#define CYNARA_MAX_VECTOR_SIZE 4096 + +/*! \brief Maximum size of monitor entries buffer accepted by Cynara */ +#define CYNARA_MAX_MONITOR_BUFFER_SIZE 65535 + +#endif /* CYNARA_LIMITS_H */ diff --git a/include/cynara/cynara-monitor.h b/include/cynara/cynara-monitor.h new file mode 100644 index 0000000..ce7b8d0 --- /dev/null +++ b/include/cynara/cynara-monitor.h @@ -0,0 +1,421 @@ +/* + * Copyright (c) 2016 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * @file src/include/cynara-monitor.h + * @author Aleksander Zdyb <a.zdyb@samsung.com> + * @version 1.0 + * @brief This file contains client APIs of Cynara monitoring. + */ + +#ifndef CYNARA_MONITOR_H +#define CYNARA_MONITOR_H + +#include <stddef.h> +#include <time.h> + +#include <cynara/cynara-error.h> +#include <cynara/cynara-limits.h> + +#ifdef __cplusplus +extern "C" { +#endif + +typedef struct cynara_monitor_configuration cynara_monitor_configuration; +typedef struct cynara_monitor cynara_monitor; +typedef struct cynara_monitor_entry cynara_monitor_entry; + +/** + * \par Description: + * Initializes cynara_monitor_configuration. Creates structure used in following configuration + * API calls. + * + * \par Purpose: + * For configuration parameter to be used in cynara_monitor_initialize() function, this API must be + * called before any other Cynara monitor configuration API function. + * It will create cynara_monitor_configuration structure, an optional parameter + * of Cynara monitor initialization. + * + * \par Typical use case: + * Once before setting parameters of Cynara monitor configuration and passing to + * cynara_monitor_initialize(). + * + * \par Method of function operation: + * This API initializes inner library structures and in case of success returns pointer + * to created cynara_monitor_configuration structure. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safety: + * \parblock + * This function is NOT thread-safe. If this function is called simultaneously with other functions + * from described API in different threads, they must be put into protected critical section. + * + * \par Important notes: + * Structure cynara_monitor_configuration created by cynara_monitor_configuration_create() call + * should be released with cynara_monitor_configuration_destroy(). + * Structure cynara_monitor_configuration should be destroyed after passing it to + * cynara_monitor_initialize(). + * \endparblock + * + * \param[out] pp_conf Placeholder for created cynara_monitor_configuration structure. + * + * \return CYNARA_API_SUCCESS on success + * or negative error code on error. + */ +int cynara_monitor_configuration_create(cynara_monitor_configuration **pp_conf); + +/** + * \par Description: + * Releases cynara_monitor_configuration structure created + * with cynara_monitor_configuration_create(). + * + * \par Purpose: + * This API should be used to clean up after usage of cynara_monitor_configuration. + * + * \par Typical use case: + * Once cynara_monitor_configuration is not needed. + * + * \par Method of function operation: + * This API releases inner library structure and destroys cynara_monitor_configuration structure. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If this function is called simultaneously with other functions + * from described API in different threads, they must be put into protected critical section. + * + * \param[in] p_conf cynara_monitor_configuration structure. If NULL, the call has no effect. + */ +void cynara_monitor_configuration_destroy(cynara_monitor_configuration *p_conf); + +/** + * \par Description: + * Set monitor entries buffer size. + * + * \par Purpose: + * This API is used to change default number of monitor entries stored on server side + * before returning them to client of libcynara-monitor. Buffer size cannot exceed value + * of CYNARA_MAX_MONITOR_BUFFER_SIZE, otherwise CYNARA_API_INPUT_PARAM will be returned. + * + * \par Typical use case: + * Once after cynara_configuration is created with cynara_monitor_configuration_create() + * and before passing configuration to cynara_monitor_configuration(). + * + * \par Method of function operation: + * This API initializes buffer with given capacity. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safety: + * This function is NOT thread-safe. If this function is called simultaneously with other functions + * from described API in different threads, they must be put into protected critical section. + * + * \par Important notes: + * After passing cynara_configuration to cynara_monitor_initialize() calling this API will have + * no effect. + * + * If buffer size is not set with cynara_monitor_configuration_set_buffer_size(), + * a default size will be taken. + * \endparblock + * + * \param[in] p_conf cynara_monitor_configuration structure pointer. + * \param[in] buffer_size buffer size to be set. + * + * \return CYNARA_API_SUCCESS on success + * or negative error code on error. + */ +int cynara_monitor_configuration_set_buffer_size(cynara_monitor_configuration *p_conf, + size_t buffer_size); + +/** + * \par Description: + * Initializes cynara-monitor library with given configuration. + * Creates structure used in following API calls. + * + * \par Purpose: + * This API must be used by prior calling cynara_monitor_entries_get() function. + * + * \par Typical use case: + * Once before a service can call cynara_monitor_entries_get(). + * + * \par Method of function operation: + * This API initializes inner library structures and in case of success + * creates cynara_monitor structure. + * + * \par Sync (or) Async: + * This is a Synchronous API. + * + * \par Thread-safeness: + * This function is NOT thread-safe. If this function is called simultaneously with other functions + * from described API in different threads, they must be put into protected critical section. + * + * \par Important notes: + * Structure cynara_monitor created by cynara_monitor_initialize() call should be released + * with cynara_monitor_finish(). + * + * \param[out] pp_cynara_monitor Placeholder for created cynara_monitor structure. + * \param[in] p_conf Configuration for cynara-monitor library. NULL for default parameters. + * + * \return CYNARA_API_SUCCESS on success, or error code on error. + */ +int cynara_monitor_initialize(cynara_monitor **pp_cynara_monitor, + const cynara_monitor_configuration *p_conf); + +/** + * \par Description: + * Releases cynara-monitor library and destroys structure created with cynara_monitor_initialize(). + * + * \par Purpose: + * This API should be used to clean up after the usage of cynara-monitor library. + * + * \par Typical use case: + * Once after last call to cynara_monitor_entries_get(). + * + * \par Method of function operation: + * This API releases inner library structures and destroys cynara_monitor structure. + * + * \par Sync (or) Async: + * This is a Synchronous API. + * + * \par Thread-safeness: + * This function is NOT thread-safe. If this function is called simultaneously with other functions + * from described API in different threads, they must be put into protected critical section. + * + * \par Important notes: + * No other call to libcynara-monitor should be made after call to cynara_monitor_finish(). + * This function cannot be called, if cynara_monitor_entries_get() haven't returned yet. + * + * \param[in] p_cynara_monitor Cynara monitor structure. + * + * \return CYNARA_API_SUCCESS on success, or error code on error. + */ +int cynara_monitor_finish(cynara_monitor *p_cynara_monitor); + +/** + * \brief Returns monitor entries. + * + * \par Description: + * + * Returns all available monitor entries right after the size of buffer reaches set limit. + * + * \par Purpose: + * This API should be used to get available monitor entries. + * + * \par Typical use case: + * Gathering information about possible accesses checked in Cynara by individual services. + * + * \par Method of function operation: + * \parblock + * Each call to cynara_check() made by individual services are logged. The logs can be obtained + * by privileged clients with usage of libcynara-monitor (this API). + * + * In case of successful call CYNARA_API_SUCCESS is returned and *monitor_entries points + * to newly created array of pointers to cynara_monitor_entry. It is responsibility + * of the caller to release entries with cynara_monitor_entries_free(). + * + * The function blocks until the size of buffer reaches set limit or cynara_monitor_entries_flush() + * is called from another thread. + * \endparblock + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safeness: + * This function is thread-safe. + * + * \par Important notes: + * Although this function is thread-safe, no multiple calls are allowed. + * + * \param[in] p_cynara_monitor cynara_monitor structure. + * \param[out] monitor_entries placeholder for NULL terminated array of pointers to + * monitor_entries structures. + * + * \return CYNARA_API_SUCCESS on success, or error code otherwise. + */ +int cynara_monitor_entries_get(cynara_monitor *p_cynara_monitor, + cynara_monitor_entry ***monitor_entries); + +/** + * \brief Makes cynara_monitor_entries_get() return immediately. + * + * \par Description: + * + * When called from another thread, makes cynara_monitor_entries_get() return immediately. + * + * \par Purpose: + * This API should be used to make cynara_monitor_entries_get() return immediately. + * + * \par Typical use case: + * User of libcynara-monitor wants to immediately get get monitor entries and/or make + * cynara_monitor_entries_get() return without waiting for full batch of entries. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safeness: + * This function is thread-safe. + * + * \param[in] p_cynara_monitor cynara_monitor structure. + * + * \return CYNARA_API_SUCCESS on success, or error code otherwise. + */ +int cynara_monitor_entries_flush(cynara_monitor *p_cynara_monitor); + +/** + * \brief Releases monitor entries. + * + * \par Description: + * + * Releases monitor entries obtained with cynara_monitor_entries_get(). + * + * \par Purpose: + * This API should be used to release array of cynara_monitor_entry obtained + * with cynara_monitor_entries_get. + * + * \par Typical use case: + * When user obtained all needed data from the entries and won't be accessing the + * memory any more. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safeness: + * This function is thread-safe. + * + * \param[in] monitor_entries NULL terminated array of cynara_monitor_entry to be released. + */ +void cynara_monitor_entries_free(cynara_monitor_entry **monitor_entries); + +/** + * \brief Gets client from monitor_entry + * + * \par Description: + * Gives access to client field of monitor_entry given as a parameter. + * Please refer to cynara_check() in cynara-client.h for more information on client field. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safeness: + * This function is thread-safe. + * + * \par Important notes: + * The returned pointer is valid as long as given monitor_entry is. + * + * \param[in] monitor_entry cynara_monitor_entry to be accessed. + * + * \return valid const char * pointer or NULL in case of error. + */ +const char *cynara_monitor_entry_get_client(const cynara_monitor_entry *monitor_entry); + +/** + * \brief Gets user from monitor_entry + * + * \par Description: + * Gives access to user field of monitor_entry given as a parameter. + * Please refer to cynara_check() in cynara-client.h for more information on user field. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safeness: + * This function is thread-safe. + * + * \par Important notes: + * The returned pointer is valid as long as given monitor_entry is. + * + * \param[in] monitor_entry cynara_monitor_entry to be accessed. + * + * \return valid const char * pointer or NULL in case of error. + */ +const char *cynara_monitor_entry_get_user(const cynara_monitor_entry *monitor_entry); + +/** + * \brief Gets privilege from monitor_entry + * + * \par Description: + * Gives access to privilege field of monitor_entry given as a parameter. + * Please refer to cynara_check() in cynara-client.h for more information on privilege field. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safeness: + * This function is thread-safe. + * + * \par Important notes: + * The returned pointer is valid as long as given monitor_entry is. + * + * \param[in] monitor_entry cynara_monitor_entry to be accessed. + * + * \return valid const char * pointer or NULL in case of error. + */ +const char *cynara_monitor_entry_get_privilege(const cynara_monitor_entry *monitor_entry); + +/** + * \brief Gets result from monitor_entry + * + * \par Description: + * Gives access to result field of monitor_entry given as a parameter. + * In case of successful get, the result is one of CYNARA_API_ACCESS_ALLOWED + * or CYNARA_API_ACCESS_DENIED. In case of error a negative code error is returned. + * Please refer to cynara-error.h for more information. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safeness: + * This function is thread-safe. + * + * \param[in] monitor_entry cynara_monitor_entry to be accessed. + * + * \return CYNARA_API_ACCESS_ALLOWED on access allowed, CYNARA_API_ACCESS_DENIED on access denial + * or other error code on error. + */ +int cynara_monitor_entry_get_result(const cynara_monitor_entry *monitor_entry); + +/** + * \brief Gets timestamp from monitor_entry + * + * \par Description: + * Gives access to timestamp field of monitor_entry given as a parameter. + * This is the time of cynara_check() being invoked. Please refer to cynara-client.h + * for more information about cynara_check(). + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread-safeness: + * This function is thread-safe. + * + * \par Important notes: + * The returned pointer is valid as long as given monitor_entry is. + * + * \param[in] monitor_entry cynara_monitor_entry to be accessed. + * + * \return valid const istruct timspec * pointer or NULL in case of error. + */ +const struct timespec *cynara_monitor_entry_get_timestamp( + const cynara_monitor_entry *monitor_entry); + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_MONITOR_H */ diff --git a/include/cynara/cynara-plugin.h b/include/cynara/cynara-plugin.h new file mode 100644 index 0000000..747966f --- /dev/null +++ b/include/cynara/cynara-plugin.h @@ -0,0 +1,106 @@ +/* + * Copyright (c) 2014-2015 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/** + * @file src/include/cynara-plugin.h + * @author Zofia Abramowska <z.abramowska@samsung.com> + * @author Oskar Switalski <o.switalski@samsung.com> + * @version 1.0 + * @brief This file defines cynara service side of external plugin interface - + * ServicePluginInterface + */ + +#ifndef CYNARA_PLUGIN_H_ +#define CYNARA_PLUGIN_H_ + +#include <memory> +#include <string> +#include <vector> + +#include <log/log.h> +#include <plugin/ExternalPluginInterface.h> +#include <types/PolicyResult.h> +#include <types/PolicyType.h> + +namespace Cynara { + +//These typedefs will be defined in external headers +typedef std::string PluginData; +typedef std::string AgentType; + +class ServicePluginInterface; +typedef std::shared_ptr<ServicePluginInterface> ServicePluginInterfacePtr; + +/** + * A class defining external plugins interface. + * These plugins work inside of cynara and either can produce + * response through check instantly or require communication + * with given type of agent. Agent must be registered through + * cynara-agent API. + * + * Plugin implementing ServicePluginInterface must implement ExternalPluginInterface. + * Creation/destruction functions with signatures compatible to Cynara::create_t and + * Cynara::destroy_t must be provided as factories of ServicePluginInterface. + */ + +class ServicePluginInterface : public ExternalPluginInterface { +public: + /** + * Enum indicating status of calling plugin method. + */ + enum class PluginStatus { + SUCCESS, /**< update() finished successfully */ + ANSWER_READY, /**< check() returns answer immediately through argument */ + ANSWER_NOTREADY, /**< check() cannot return answer immediately, + communication with agent is required */ + ERROR /**< either check() or update() fails */ + }; + + /** + * Asks plugin, what kind of permission does client, user and privilege has. + * + * @param[in] client + * @param[in] user + * @param[in] privilege + * @param[out] result Immediate response (if available) + * @param[out] requiredAgent When ANSWER_NOTREADY, required AgentType to communicate with + * @param[out] pluginData Additional data, that will be passed to agent + * @return PluginStatus In case of success - either ANSWER_READY or ANSWER_NOTREADY, + * in case of error - ERROR + */ + virtual PluginStatus check(const std::string &client, const std::string &user, + const std::string &privilege, PolicyResult &result, + AgentType &requiredAgent, PluginData &pluginData) noexcept = 0; + + /** + * Updates response returned by agent + * @param[in] client + * @param[in] user + * @param[in] privilege + * @param[in] agentData Additional data, passed from agent + * @param[out] result Response interpreted from agent + * @return PluginStatus In case of success - SUCCESS, in case of error - ERROR + */ + virtual PluginStatus update(const std::string &client, const std::string &user, + const std::string &privilege, const PluginData &agentData, + PolicyResult &result) noexcept = 0; + + virtual ~ServicePluginInterface() {}; + +}; + +} // namespace Cynara + +#endif /* CYNARA_PLUGIN_H_ */ diff --git a/include/cynara/cynara-policy-types.h b/include/cynara/cynara-policy-types.h new file mode 100644 index 0000000..bd74b5a --- /dev/null +++ b/include/cynara/cynara-policy-types.h @@ -0,0 +1,48 @@ +/* + * Copyright (c) 2014-2015 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * \file src/include/cynara-policy-types.h + * \author Lukasz Wojciechowski <l.wojciechow@partner.samsung.com> + * \version 1.0 + * \brief This file contains policy types / operations definitions. + */ + +#ifndef CYNARA_POLICY_TYPES_H +#define CYNARA_POLICY_TYPES_H + +/** + * \name Operation Codes + * Operation codes that define action type to be taken + * @{ + */ + +/*! \brief a policy or bucket should be removed */ +#define CYNARA_ADMIN_DELETE -1 + +/*! \brief set policy result or bucket's default policy to DENY */ +#define CYNARA_ADMIN_DENY 0 + +/*! \brief set bucket's default policy to NONE */ +#define CYNARA_ADMIN_NONE 1 + +/*! \brief set policy to point into another bucket */ +#define CYNARA_ADMIN_BUCKET 0xFFFE + +/*! \brief set policy result or bucket's default policy to ALLOW */ +#define CYNARA_ADMIN_ALLOW 0xFFFF +/** @}*/ + +#endif /* CYNARA_POLICY_TYPES_H */ diff --git a/include/cynara/cynara-session.h b/include/cynara/cynara-session.h new file mode 100644 index 0000000..1c76bce --- /dev/null +++ b/include/cynara/cynara-session.h @@ -0,0 +1,73 @@ +/* + * Copyright (c) 2014-2015 Samsung Electronics Co., Ltd All Rights Reserved + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License + */ +/** + * @file src/include/cynara-session.h + * @author Aleksander Zdyb <a.zdyb@samsung.com> + * @author Radoslaw Bartosiak <r.bartosiak@samsung.com.pl> + * @author Lukasz Wojciechowski <l.wojciechow@partner.samsung.com> + * @author Oskar Switalski <o.switalski@samsung.com> + * @version 1.0 + * @brief This file contains Cynara session helper APIs. + * @example cynara-session.example + */ + +#ifndef CYNARA_SESSION_H +#define CYNARA_SESSION_H + +#include <sys/types.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \par Description: + * Creates a client session string based on pid and time of creation of client process + * + * \par Purpose: + * This function can be used to create session string identifier used in cynara_check() + * and cynara_async_create_request() functions defined in client libraries. + * + * \par Typical use case: + * The function is called before the call of cynara_check() or cynara_async_create_request() + * function. Returned string is used as client_session param in cynara_check() or + * cynara_async_create_request() function. String is released with free() function. + * + * \par Method of function operation: + * The function generates client session based on the pid and start time of the client process. + * Time is acquired from /proc/PID directory. + * + * \par Sync (or) Async: + * This is a synchronous API. + * + * \par Thread safety: + * This function is thread-safe. + * + * \par Important notes: + * Memory for returned string is obtained with malloc(), and should be freed with free(). + * + * \param[in] client_pid client application process identifier (PID). + * + * \return session string on success + * \return NULL on error + */ +char *cynara_session_from_pid(pid_t client_pid); + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_SESSION_H */ |