From: Marcin Niesluchowski Date: Thu, 31 Jul 2014 15:55:36 +0000 (+0200) Subject: Add asynchronous client api X-Git-Tag: accepted/tizen/common/20140905.175100~38 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=ab73c19c44d7f4e6f4a25ba1243ce08af11c84c0;p=platform%2Fcore%2Fsecurity%2Fcynara.git Add asynchronous client api Change-Id: I76f4374a96a09f53dd4154a8049c42683fb39bf7 --- diff --git a/CMakeLists.txt b/CMakeLists.txt index 354d39b..eadba21 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -55,6 +55,7 @@ ENDIF (CMAKE_BUILD_TYPE MATCHES "DEBUG") SET(TARGET_CYNARA "cynara") SET(TARGET_LIB_CYNARA "cynara-client") +SET(TARGET_LIB_CYNARA_ASYNC "cynara-client-async") SET(TARGET_LIB_CYNARA_ADMIN "cynara-admin") SET(TARGET_CYNARA_COMMON "cynara-commons") SET(TARGET_CYNARA_TESTS "cynara-tests") diff --git a/build/CMakeLists.txt b/build/CMakeLists.txt index 269b258..ff93082 100644 --- a/build/CMakeLists.txt +++ b/build/CMakeLists.txt @@ -17,4 +17,5 @@ # ADD_SUBDIRECTORY(cynara-client) +ADD_SUBDIRECTORY(cynara-client-async) ADD_SUBDIRECTORY(cynara-admin) diff --git a/build/cynara-client-async/CMakeLists.txt b/build/cynara-client-async/CMakeLists.txt new file mode 100644 index 0000000..c24b331 --- /dev/null +++ b/build/cynara-client-async/CMakeLists.txt @@ -0,0 +1,25 @@ +# Copyright (c) 2014 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 CMakeLists.txt +# @author Marcin Niesluchowski +# + +CONFIGURE_FILE(cynara-client-async.pc.in cynara-client-async.pc @ONLY) + +INSTALL(FILES + ${CMAKE_BINARY_DIR}/build/cynara-client-async/cynara-client-async.pc + DESTINATION + ${LIB_INSTALL_DIR}/pkgconfig + ) diff --git a/build/cynara-client-async/cynara-client-async.pc.in b/build/cynara-client-async/cynara-client-async.pc.in new file mode 100644 index 0000000..c3f1be5 --- /dev/null +++ b/build/cynara-client-async/cynara-client-async.pc.in @@ -0,0 +1,11 @@ +prefix=@CMAKE_INSTALL_PREFIX@ +exec_prefix=${prefix} +libdir=@LIB_INSTALL_DIR@ +includedir=${prefix}/include + +Name: cynara-client-async +Description: cynara-client-async package +Version: 0.0.1 +Requires: +Libs: -L${libdir} -lcynara-client-async +Cflags: -I${includedir}/cynara diff --git a/packaging/cynara.spec b/packaging/cynara.spec index 5524b9d..a75ed92 100644 --- a/packaging/cynara.spec +++ b/packaging/cynara.spec @@ -7,8 +7,9 @@ License: Apache-2.0 Source0: %{name}-%{version}.tar.gz Source1001: cynara.manifest Source1002: libcynara-client.manifest -Source1003: libcynara-admin.manifest -Source1004: cynara-tests.manifest +Source1003: libcynara-client-async.manifest +Source1004: libcynara-admin.manifest +Source1005: cynara-tests.manifest Requires: default-ac-domains BuildRequires: cmake BuildRequires: zip @@ -30,7 +31,7 @@ BuildRequires: pkgconfig(libunwind) %endif %description -service, client libraries (libcynara-client, libcynara-admin) +service and client libraries (libcynara-client, libcynara-client-async, libcynara-admin) and tests (cynara-tests) ####################################################### @@ -51,6 +52,23 @@ Requires: libcynara-client = %{version}-%{release} client library (devel) for checking policies ####################################################### +%package -n libcynara-client-async +Summary: Cynara - asynchronous client library +Requires: cynara = %{version}-%{release} +Requires(post): /sbin/ldconfig +Requires(postun): /sbin/ldconfig + +%description -n libcynara-client-async +asynchronous client library for checking policies + +%package -n libcynara-client-async-devel +Summary: Cynara - asynchronous client library (devel) +Requires: libcynara-client-async = %{version}-%{release} + +%description -n libcynara-client-async-devel +asynchronous client library (devel) for checking policies + +####################################################### %package -n libcynara-admin Summary: Cynara - admin client library Requires: cynara = %{version}-%{release} @@ -90,6 +108,7 @@ cp -a %{SOURCE1001} . cp -a %{SOURCE1002} . cp -a %{SOURCE1003} . cp -a %{SOURCE1004} . +cp -a %{SOURCE1005} . %build %if 0%{?sec_build_binary_debug_enable} @@ -163,6 +182,10 @@ fi %postun -n libcynara-client -p /sbin/ldconfig +%post -n libcynara-client-async -p /sbin/ldconfig + +%postun -n libcynara-client-async -p /sbin/ldconfig + %post -n libcynara-admin -p /sbin/ldconfig %postun -n libcynara-admin -p /sbin/ldconfig @@ -171,6 +194,10 @@ fi %postun -n libcynara-client-devel -p /sbin/ldconfig +%post -n libcynara-client-async-devel -p /sbin/ldconfig + +%postun -n libcynara-client-async-devel -p /sbin/ldconfig + %post -n libcynara-admin-devel -p /sbin/ldconfig %postun -n libcynara-admin-devel -p /sbin/ldconfig @@ -200,6 +227,18 @@ fi %{_libdir}/pkgconfig/cynara-client.pc %{_libdir}/libcynara-client.so +%files -n libcynara-client-async +%manifest libcynara-client-async.manifest +%license LICENSE +%defattr(-,root,root,-) +%{_libdir}/libcynara-client-async.so.* + +%files -n libcynara-client-async-devel +%defattr(-,root,root,-) +%{_includedir}/cynara/cynara-client-async.h +%{_libdir}/pkgconfig/cynara-client-async.pc +%{_libdir}/libcynara-client-async.so + %files -n libcynara-admin %manifest libcynara-admin.manifest %license LICENSE diff --git a/packaging/libcynara-client-async.manifest b/packaging/libcynara-client-async.manifest new file mode 100644 index 0000000..a76fdba --- /dev/null +++ b/packaging/libcynara-client-async.manifest @@ -0,0 +1,5 @@ + + + + + diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 852e0a5..385e440 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -47,5 +47,6 @@ INCLUDE_DIRECTORIES( ADD_SUBDIRECTORY(include) ADD_SUBDIRECTORY(common) ADD_SUBDIRECTORY(client) +ADD_SUBDIRECTORY(client-async) ADD_SUBDIRECTORY(admin) ADD_SUBDIRECTORY(service) diff --git a/src/client-async/CMakeLists.txt b/src/client-async/CMakeLists.txt new file mode 100644 index 0000000..98f5ad6 --- /dev/null +++ b/src/client-async/CMakeLists.txt @@ -0,0 +1,48 @@ +# Copyright (c) 2014 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 CMakeLists.txt +# @author Marcin Niesluchowski +# + +SET(LIB_CYNARA_ASYNC_VERSION_MAJOR 0) +SET(LIB_CYNARA_ASYNC_VERSION ${LIB_CYNARA_ASYNC_VERSION_MAJOR}.0.2) + +SET(CYNARA_LIB_CYNARA_ASYNC_PATH ${CYNARA_PATH}/client-async) + +SET(LIB_CYNARA_ASYNC_SOURCES + ${CYNARA_LIB_CYNARA_ASYNC_PATH}/api/client-async-api.cpp + ${CYNARA_LIB_CYNARA_ASYNC_PATH}/logic/Logic.cpp + ) + +INCLUDE_DIRECTORIES( + ${CYNARA_LIB_CYNARA_ASYNC_PATH} + ) + +ADD_LIBRARY(${TARGET_LIB_CYNARA_ASYNC} SHARED ${LIB_CYNARA_ASYNC_SOURCES}) + +SET_TARGET_PROPERTIES( + ${TARGET_LIB_CYNARA_ASYNC} + PROPERTIES + COMPILE_FLAGS "-D_GNU_SOURCE -fPIC -fvisibility=hidden" + SOVERSION ${LIB_CYNARA_ASYNC_VERSION_MAJOR} + VERSION ${LIB_CYNARA_ASYNC_VERSION} + ) + +TARGET_LINK_LIBRARIES(${TARGET_LIB_CYNARA_ASYNC} + ${CYNARA_DEP_LIBRARIES} + ${TARGET_CYNARA_COMMON} + ) + +INSTALL(TARGETS ${TARGET_LIB_CYNARA_ASYNC} DESTINATION ${LIB_INSTALL_DIR}) diff --git a/src/client-async/api/ApiInterface.h b/src/client-async/api/ApiInterface.h new file mode 100644 index 0000000..216713a --- /dev/null +++ b/src/client-async/api/ApiInterface.h @@ -0,0 +1,47 @@ +/* + * Copyright (c) 2014 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 ApiInterface.h + * @author Marcin Niesluchowski + * @version 1.0 + * @brief This file contains libcynara-client-async API interface definition. + */ + +#ifndef SRC_CLIENT_ASYNC_API_APIINTERFACE_H_ +#define SRC_CLIENT_ASYNC_API_APIINTERFACE_H_ + +#include + +#include + +namespace Cynara { + +class ApiInterface { +public: + ApiInterface() = default; + virtual ~ApiInterface() {}; + + virtual int connect(int &sockFd) = 0; + virtual int check(const std::string &client, const std::string &session, + const std::string &user, const std::string &privilege, + cynara_check_id &checkId) = 0; + virtual int receive(cynara_check_id &checkId) = 0; + virtual int cancel(const cynara_check_id checkId) = 0; +}; + +} // namespace Cynara + +#endif /* SRC_CLIENT_ASYNC_API_APIINTERFACE_H_ */ diff --git a/src/client-async/api/client-async-api.cpp b/src/client-async/api/client-async-api.cpp new file mode 100644 index 0000000..34111f6 --- /dev/null +++ b/src/client-async/api/client-async-api.cpp @@ -0,0 +1,118 @@ +/* + * Copyright (c) 2014 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 client-async-api.cpp + * @author Marcin Niesluchowski + * @version 1.0 + * @brief Implementation of external libcynara-client-async API + */ + +#include + +#include +#include + +#include +#include +#include + +struct cynara_async { + Cynara::ApiInterface *impl; + + cynara_async(Cynara::ApiInterface *_impl) : impl(_impl) { + } + + ~cynara_async() { + delete impl; + } +}; + +CYNARA_API +int cynara_async_initialize(cynara_async **pp_cynara, + const cynara_async_configuration *p_conf UNUSED) +{ + if (!pp_cynara) + return CYNARA_ASYNC_API_INVALID_PARAM; + + try { + *pp_cynara = new cynara_async(new Cynara::Logic); + } catch (const std::bad_alloc &ex) { + return CYNARA_ASYNC_API_OUT_OF_MEMORY; + } + + init_log(); + + LOGD("Cynara client async initialized"); + + return CYNARA_ASYNC_API_SUCCESS; +} + +CYNARA_API +int cynara_async_finish(cynara_async *p_cynara) +{ + delete p_cynara; + + return CYNARA_ASYNC_API_SUCCESS; +} + +CYNARA_API +int cynara_async_connect(cynara_async *p_cynara, int *p_sock_fd) +{ + if (!p_cynara || !p_cynara->impl) + return CYNARA_ASYNC_API_INVALID_PARAM; + if (!p_sock_fd) + return CYNARA_ASYNC_API_INVALID_PARAM; + + return p_cynara->impl->connect(*p_sock_fd); +} + +CYNARA_API +int cynara_async_check(cynara_async *p_cynara, + const char *client, const char *client_session, + const char *user, const char *privilege, + cynara_check_id *p_check_id) +{ + if (!p_cynara || !p_cynara->impl) + return CYNARA_ASYNC_API_INVALID_PARAM; + if (!client || !client_session || !user || !privilege) + return CYNARA_ASYNC_API_INVALID_PARAM; + if (!p_check_id) + return CYNARA_ASYNC_API_INVALID_PARAM; + + return p_cynara->impl->check(client, client_session, + user, privilege, + *p_check_id); +} + +CYNARA_API +int cynara_async_receive(cynara_async *p_cynara, cynara_check_id *p_check_id) +{ + if (!p_cynara || !p_cynara->impl) + return CYNARA_ASYNC_API_INVALID_PARAM; + if (!p_check_id) + return CYNARA_ASYNC_API_INVALID_PARAM; + + return p_cynara->impl->receive(*p_check_id); +} + +CYNARA_API +int cynara_async_cancel(cynara_async *p_cynara, const cynara_check_id check_id) +{ + if (!p_cynara || !p_cynara->impl) + return CYNARA_ASYNC_API_INVALID_PARAM; + + return p_cynara->impl->cancel(check_id); +} diff --git a/src/client-async/logic/Logic.cpp b/src/client-async/logic/Logic.cpp new file mode 100644 index 0000000..c6e7860 --- /dev/null +++ b/src/client-async/logic/Logic.cpp @@ -0,0 +1,52 @@ +/* + * Copyright (c) 2014 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 Logic.cpp + * @author Marcin Niesluchowski + * @version 1.0 + * @brief This file contains implementation of Logic class - main + * libcynara-client-async class + */ + +#include + +#include "Logic.h" + +namespace Cynara { + +int Logic::connect(int &sockFd UNUSED) noexcept +{ + return CYNARA_ASYNC_API_SUCCESS; +} + +int Logic::check(const std::string &client UNUSED, const std::string &session UNUSED, + const std::string &user UNUSED, const std::string &privilege UNUSED, + cynara_check_id &checkId UNUSED) noexcept +{ + return CYNARA_ASYNC_API_SUCCESS; +} + +int Logic::receive(cynara_check_id &checkId UNUSED) noexcept +{ + return CYNARA_ASYNC_API_SUCCESS; +} + +int Logic::cancel(const cynara_check_id checkId UNUSED) noexcept +{ + return CYNARA_ASYNC_API_SUCCESS; +} + +} // namespace Cynara diff --git a/src/client-async/logic/Logic.h b/src/client-async/logic/Logic.h new file mode 100644 index 0000000..e63ce68 --- /dev/null +++ b/src/client-async/logic/Logic.h @@ -0,0 +1,47 @@ +/* + * Copyright (c) 2014 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 Logic.h + * @author Marcin Niesluchowski + * @version 1.0 + * @brief This file contains declaration of Logic class - main + * libcynara-client-async class + */ + +#ifndef SRC_CLIENT_ASYNC_LOGIC_LOGIC_H_ +#define SRC_CLIENT_ASYNC_LOGIC_LOGIC_H_ + +#include +#include + +namespace Cynara { + +class Logic : public ApiInterface { +public: + Logic() = default; + virtual ~Logic() {}; + + virtual int connect(int &sockFd) noexcept; + virtual int check(const std::string &client, const std::string &session, + const std::string &user, const std::string &privilege, + cynara_check_id &checkId) noexcept; + virtual int receive(cynara_check_id &checkId) noexcept; + virtual int cancel(const cynara_check_id checkId) noexcept; +}; + +} // namespace Cynara + +#endif /* SRC_CLIENT_ASYNC_LOGIC_LOGIC_H_ */ diff --git a/src/include/CMakeLists.txt b/src/include/CMakeLists.txt index 5d8ed5a..edf2938 100644 --- a/src/include/CMakeLists.txt +++ b/src/include/CMakeLists.txt @@ -22,6 +22,11 @@ INSTALL(FILES ) INSTALL(FILES + ${CYNARA_PATH}/include/cynara-client-async.h + DESTINATION ${INCLUDE_INSTALL_DIR}/cynara + ) + +INSTALL(FILES ${CYNARA_PATH}/include/cynara-admin.h DESTINATION ${INCLUDE_INSTALL_DIR}/cynara ) diff --git a/src/include/cynara-client-async.h b/src/include/cynara-client-async.h new file mode 100644 index 0000000..c04d0b5 --- /dev/null +++ b/src/include/cynara-client-async.h @@ -0,0 +1,294 @@ +/* + * Copyright (c) 2014 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 cynara-client-async.h + * @author Marcin Niesluchowski + * @version 1.0 + * @brief This file contains asynchronous client APIs of Cynara available + * with libcynara-client-asynchronous. + */ + + +#ifndef CYNARA_CLIENT_ASYNC_H +#define CYNARA_CLIENT_ASYNC_H + +#include + +/** + * \name Return Codes + * exported by the foundation API. + * result codes begin with the start error code and extend into negative direction. + * @{ +*/ + +/*! \brief indicating the result of the one specific API is successful or access is allowed */ +#define CYNARA_ASYNC_API_SUCCESS 0 + +/*! \brief indicating that access that was checked is denied */ +#define CYNARA_ASYNC_API_ACCESS_DENIED -1 + +/*! \brief indicating that answer was not yet received */ +#define CYNARA_ASYNC_API_ANSWER_NOT_READY -2 + +/*! \brief indicating that client is already connected */ +#define CYNARA_ASYNC_API_ALREADY_CONNECTED -3 + +/*! \brief indicating system is running out of memory state */ +#define CYNARA_ASYNC_API_OUT_OF_MEMORY -4 + +/*! \brief indicating the API's parameter is malformed */ +#define CYNARA_ASYNC_API_INVALID_PARAM -5 + +/*! \brief service not available */ +#define CYNARA_ASYNC_API_SERVICE_NOT_AVAILABLE -6 + +/** @}*/ + +#ifdef __cplusplus +extern "C" { +#endif + +typedef struct cynara_async cynara_async; +typedef struct cynara_async_configuration cynara_async_configuration; +typedef uint16_t cynara_check_id; + +/** + * \par Description: + * Initialize cynara-async-client library with given configuration. + * Create structure used in following API calls. + * + * \par Purpose: + * This API must be used prior to calling cynara_async_connect function. + * + * \par Typical use case: + * Once before a service can call cynara_async_connect. + * + * \par Method of function operation: + * This API initializes inner library structures and in case of success creates + * and returns cynara_async 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_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 for default parameters. + * + * \return CYNARA_ASYNC_API_SUCCESS on success, or error code on error. + */ + +int cynara_async_initialize(cynara_async **pp_cynara, + const cynara_async_configuration *p_conf); + +/** + * \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 all checks have been answered. + * + * \par Method of function operation: + * This API releases inner library structure and destroys cynara_async structure. All pending + * requests are cancelled. + * + * \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-async-client library should be made after call to cynara_async_finish. + * + * \param[in] p_cynara cynara_async structure. + * + * \return CYNARA_ASYNC_API_SUCCESS on success, or error code on error. + */ +int cynara_async_finish(cynara_async *p_cynara); + +/** + * \par Description: + * Connect with cynara server. + * + * \par Purpose: + * This API must be used prior to calling cynara_async_check and cynara_async_receive. + * + * \par Typical use case: + * After initiating cynara_async structure and after connection with cynara server has been lost. + * + * \par Method of function operation: + * This API connects to cynara server and provides socket descriptor of this connection. + * + * \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_check needs cynara_async structure to be created first by + * cynara_async_initialize. + * + * \param[in] p_cynara cynara_async structure. + * \param[out] p_sock_fd Placeholder for connection socket descriptor. + * + * \return CYNARA_ASYNC_API_SUCCESS on success, CYNARA_ASYNC_API_ALREADY_CONNECTED when client is + * already connected or error code on error. + */ +int cynara_async_connect(cynara_async *p_cynara, int *p_sock_fd); + +/** + * \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 wants to ask Cynara daemon, if a client demanding access to some privilege + * has proper rights. Despite the fact that the final response has been received, if there are + * still some pending checks, cynara_async_receive MUST be called after this call until not ready + * answer is returned. If service does not get answer after this sequence, it may get it + * asynchronously by calling cynara_async_receive. + * + * \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). If final answer is not returned, id of current check should + * be received. + * + * \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: + * An external application may be launched to allow user interaction in granting or denying access. + * Call cynara_async_cancel to cancel pending request. Call to cynara_async_check needs + * cynara_async structure to be created first and connected with cynara daemon. To do that call + * cynara_async_initialize and cynara_async_connect. + * + * \param[in] p_cynara cynara_async 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. + * \param[out] p_check_id Placeholder for check id. + * + * \return CYNARA_ASYNC_API_SUCCESS on success (access granted), CYNARA_API_ACCESS_DENIED + * on access denial, CYNARA_ASYNC_API_ANSWER_NOT_READY on asynchronous request sent + * or other error code on error. + */ +int cynara_async_check(cynara_async *p_cynara, + const char *client, const char *client_session, + const char *user, const char *privilege, + cynara_check_id *p_check_id); + +/** + * \par Description: + * Receive answer of cynara_async_check call from cynara daemon. + * + * \par Purpose: + * This API should be used to receive answer on single check not answered by cynara_async_check. + * + * \par Typical use case: + * After calling cynara_async_check, if there are still pending checks, this function MUST be + * called until not ready answer is returned. After that, answer can be received by this call + * if a read event occurs on socket received by cynara_async_connect. It MUST be called then + * the same way as after cynara_async_check. + * + * \par Method of function operation: + * Receives answer sent by cynara daemon in response to cynara_async_check call. + * + * \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: + * An external application may be launched to allow user interaction in granting or denying access. + * Call cynara_async_cancel to cancel pending request. Call to cynara_async_receive needs + * cynara_async structure to be created first and connected with cynara daemon. To do that call + * cynara_async_initialize and cynara_async_connect. As multiple answers can be available at once, + * cynara_async_receive MUST be called until not ready answer is returned. + * + * \param[in] p_cynara cynara_async structure. + * \param[out] p_check_id Placeholder for check id. + * + * \return CYNARA_ASYNC_API_SUCCESS on success (access granted), CYNARA_API_ACCESS_DENIED + * on access denial, CYNARA_ASYNC_API_ANSWER_NOT_READY on answer not yet fully received + * or other error code on error. + */ +int cynara_async_receive(cynara_async *p_cynara, cynara_check_id *p_check_id); + +/** + * \par Description: + * Cancel check request created by cynara_async_check. + * + * \par Purpose: + * This API should be used to cancel check request created by cynara_async_check. + * + * \par Typical use case: + * A service did not get final answer in cynara_async_check call and answer did not come yet + * due to check hanging on user decision to allow or deny privilege. + * + * \par Method of function operation: + * Cancels check request created by cynara_async_check call. + * + * \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_cancel needs cynara_async structure to be created first and connected + * with cynara daemon. To do that call cynara_async_initialize and cynara_async_connect. + * + * \param[in] p_cynara cynara_async structure. + * \param[in] check_id Check id to be cancelled + * + * \return CYNARA_ASYNC_API_SUCCESS on success or other error code on error. + */ +int cynara_async_cancel(cynara_async *p_cynara, cynara_check_id check_id); + + +#ifdef __cplusplus +} +#endif + +#endif /* CYNARA_CLIENT_ASYNC_H */