From: Krystian Kisielak Date: Mon, 29 Aug 2016 13:13:46 +0000 (+0200) Subject: Added doxygen documentation. X-Git-Tag: accepted/tizen/3.0/ivi/20161011.044356^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=3cbf2cfa8d17e5f63fa1091f5e7fda67646e0dea;p=platform%2Fcore%2Fsystem%2Flibdbuspolicy.git Added doxygen documentation. Change-Id: I097ff1090998637d5c51ffbfa6023bfd0c04e405 Signed-off-by: Krystian Kisielak --- diff --git a/doc/main_page.dox b/doc/main_page.dox new file mode 100644 index 0000000..299c4d3 --- /dev/null +++ b/doc/main_page.dox @@ -0,0 +1,63 @@ +/** + \mainpage Libdbuspolicy documentation + +\section intro_sec Introduction + +Dbuspolicy is library which allows to check policies for ownership, send and receive rules. + +\section Implementation + +\subsection step1 Step 1: Init + +Policy is parsed from xml file/files and added to policy databases. In send/receive policy rules are stored in vector, in ownership policy as a prefix tree. +Handle to policy db is created. + +\subsection step2 Step 2: Looking for rule + +Depending on the type of query(ownership/send/receive) distinct functions are called to check policy. First policies of each types (MANDATORY, user, group, DEFAULT) are accesed by checker.\n +Then each of them is searched for given item. At the end returned decision is parsed. In case of decision CHECK Cynara is run. + + +\section desc_sec Description + +Libdbuspolicy uses dbus-daemon logics. Policies are created from policy section from dbus .conf files. +Config file syntax is precisely described in section "CONFIGURATION FILE" at: +dbus-daemon documentation. \n + An example of syntax is shown below: + +\code{.xml} + + + + + + + + + + + + + + + + + + + + + + + + + + + +\endcode + + + */ diff --git a/doxygen.cfg b/doxygen.cfg index ff1c452..0b1c67d 100644 --- a/doxygen.cfg +++ b/doxygen.cfg @@ -4,14 +4,20 @@ GENERATE_LATEX = NO GENERATE_MAN = NO GENERATE_RTF = NO CASE_SENSE_NAMES = NO -INPUT = src/dbuspolicy1/libdbuspolicy1.h +INPUT = doc/main_page.dox src/internal/ src/dbuspolicy1 src/libdbuspolicy1.c +EXCLUDE = src/internal/xml_policy.hpp JAVADOC_AUTOBRIEF = YES EXTRACT_PRIVATE = YES EXTRACT_STATIC = YES TYPEDEF_HIDES_STRUCT = YES -INLINE_SOURCES = YES -REFERENCED_BY_RELATION = YES -REFERENCES_RELATION = YES -SEARCHENGINE = NO -COMPACT_LATEX = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +SEARCHENGINE = YES +COMPACT_LATEX = YES LATEX_HIDE_INDICES = YES +HAVE_DOT = NO +EXTRACT_ALL = YES +RECURSIVE = NO +QUIET = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO diff --git a/src/dbuspolicy1/libdbuspolicy1.h b/src/dbuspolicy1/libdbuspolicy1.h index b6ffdae..d923a94 100644 --- a/src/dbuspolicy1/libdbuspolicy1.h +++ b/src/dbuspolicy1/libdbuspolicy1.h @@ -13,9 +13,8 @@ * See the License for the specific language governing permissions and * limitations under the License. */ - -/** - * \file libdbuspolicy1.h +/** API usually used in libdbus/libglib. + \defgroup API API */ #ifndef _LIBDBUSPOLICY1_H_ #define _LIBDBUSPOLICY1_H_ @@ -50,38 +49,42 @@ extern "C" { struct udesc; -/*! - Initialize libdbuspolicy configuration context - \param bus_path path to the kdbus bus (system or session) +/** + * Initialize libdbuspolicy configuration context + * \param[in] bus_path path to the kdbus bus (system or session) - \note This function should be called only on well known kdbus buses - - the system bus (/sys/fs/kdbus/0-system/bus) and session bus - (/sys/fs/kdbus/getuid()-user/bus). If any other bus is specified - function will not succeed. + * \note This function should be called only on well known kdbus buses + * - the system bus (/sys/fs/kdbus/0-system/bus) and session bus + * (/sys/fs/kdbus/getuid()-user/bus). If any other bus is specified + * function will not succeed. - \return On success pointer to configuration context is returned. On - error NULL is returned. + * \return On success pointer to configuration context is returned. On + * error NULL is returned. + * \ingroup API */ void* dbuspolicy1_init(const char *bus_path); -/*! - Free libdbuspolicy configuration context - \param configuration pointer with policy configuration acquired using dbuspolicy1_init +/** + * Free libdbuspolicy configuration context + * \ingroup API + * \param[in] configuration Pointer with policy configuration acquired using dbuspolicy1_init */ void dbuspolicy1_free(void* configuration); -/*! - Check policy for outgoing message - \param configuration pointer with policy configuration - \param destination list of message destinations - \param sender list of message sender names - \param path path - \param interface interface name - \param member member name - \param message_type message type - \param error_name (future implementation) - \param reply_serial (future implementation) - \param requested_reply (future implementation) +/** + * Check policy for outgoing message + * \ingroup API + * \param[in] configuration Pointer with policy configuration + * \param[in] destination List of message destinations + * \param[in] sender List of message sender names + * \param[in] path Path + * \param[in] interface Interface name + * \param[in] member Member name + * \param[in] message_type Message type + * \param[in] error_name (future implementation) + * \param[in] reply_serial (future implementation) + * \param[in] requested_reply (future implementation) + * \return Allow/deny or negative error code */ int dbuspolicy1_check_out(void* configuration, const char *destination, @@ -94,21 +97,22 @@ int dbuspolicy1_check_out(void* configuration, int reply_serial, int requested_reply); -/*! - Check policy for incoming message - \param configuration pointer with policy configuration - \param destination list of message destinations - \param sender list of message sender names - \param sender_label sender label (should be manually extracted from incomming message) - \param sender_uid sender uid (should be manually extracted from incomming message) - \param sender_gid sender gid (should be manually extracted from incomming message) - \param path path - \param interface interface name - \param member member name - \param message_type message type - \param error_name (future implementation) - \param reply_serial (future implementation) - \param requested_reply (future implementation) +/** Check policy for incoming message + * \ingroup API + * \param[in] configuration Pointer with policy configuration + * \param[in] destination List of message destinations + * \param[in] sender List of message sender names + * \param[in] sender_label Sender label (should be manually extracted from incoming message) + * \param[in] sender_uid Sender uid (should be manually extracted from incoming message) + * \param[in] sender_gid Sender gid (should be manually extracted from incoming message) + * \param[in] path Path + * \param[in] interface Interface name + * \param[in] member Member name + * \param[in] message_type Message type + * \param[in] error_name (future implementation) + * \param[in] reply_serial (future implementation) + * \param[in] requested_reply (future implementation) + * \returns Allow/deny or negative error code */ int dbuspolicy1_check_in(void* configuration, const char *destination, @@ -124,10 +128,12 @@ int dbuspolicy1_check_in(void* configuration, int reply_serial, int requested_reply); -/*! - Check policy for service ownership - \param configuration pointer with policy configuration - \param service service name +/** + * Check policy for service ownership + * \ingroup API + * \param[in] configuration Pointer with policy configuration + * \param[in] service Service name + * \returns Allow/deny or negative error code */ int dbuspolicy1_can_own(void* configuration, const char* const service); diff --git a/src/internal/internal.cpp b/src/internal/internal.cpp index 2849ea0..1445f7b 100644 --- a/src/internal/internal.cpp +++ b/src/internal/internal.cpp @@ -13,6 +13,10 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +/** + * \file + * \ingroup Implementation + */ #include #include diff --git a/src/internal/internal.h b/src/internal/internal.h index 270b13a..787b380 100644 --- a/src/internal/internal.h +++ b/src/internal/internal.h @@ -14,6 +14,15 @@ * limitations under the License. */ + +/** + \defgroup Implementation Implementation + Internal implementation of policy. + */ +/** + * \file + * \ingroup Implementation + */ #ifndef _LIBDBUSPOLICY1_INTERNAL_H_ #define _LIBDBUSPOLICY1_INTERNAL_H_ @@ -23,13 +32,38 @@ extern "C" { #define KDBUS_CONN_MAX_NAMES 256 +/** Initializes policies from given policy configuration file name + * \param[in] bus_type Bus type (system/session) + * \param[in] config_name Configuration file name + */ int __internal_init(bool bus_type, const char* const config_name); + +/** Inits tslog. */ void __internal_init_once(void); + extern pthread_mutex_t g_mutex; + +/** Flushes logs. */ void __internal_init_flush_logs(void); + +/** Enables logger mutex */ void __internal_enter(void); + +/** Disables logger mutex */ void __internal_exit(void); +/** Checks if user can send message to given location. + * \param[in] bus_type Bus type (system/session) + * \param[in] user User id + * \param[in] group User group id + * \param[in] label Sender label + * \param[in] destination Message destination + * \param[in] path Path + * \param[in] interface Interface name + * \param[in] member Member name + * \param[in] type Message type + * \return 1 on allow, 0 on deny, negative error code otherwise + */ int __internal_can_send(bool bus_type, const uid_t user, const gid_t group, @@ -40,6 +74,18 @@ int __internal_can_send(bool bus_type, const char* const member, int type); +/** Checks if user can send messages (multiple destinations). + * \param[in] bus_type Bus type (system/session) + * \param[in] user User id + * \param[in] group User group id + * \param[in] label Sender label + * \param[in] destination Message destination + * \param[in] path Path + * \param[in] interface Interface name + * \param[in] member Member name + * \param[in] type Message type + * \return 1 on allow, 0 on deny, negative error code otherwise + */ int __internal_can_send_multi_dest(bool bus_type, const uid_t user, const gid_t group, @@ -50,6 +96,18 @@ int __internal_can_send_multi_dest(bool bus_type, const char* const member, int type); +/** Check if user can receive messages. + * \param[in] bus_type Bus type (system/session) + * \param[in] user User id + * \param[in] group User group id + * \param[in] label User label + * \param[in] sender Sender of received message + * \param[in] path Path + * \param[in] interface Interface name + * \param[in] member Member name + * \param[in] type Message type + * \return 1 on allow, 0 on deny, negative error code otherwise + */ int __internal_can_recv(bool bus_type, uid_t user, gid_t group, @@ -60,6 +118,14 @@ int __internal_can_recv(bool bus_type, const char* const member, int type); +/** Checks if given user can own interface with given label + * \param[in] bus_type Bus type (system/session) + * \param[in] user User id + * \param[in] group User group id + * \param[in] label Label given to Cynara + * \param[in] service Name to own + * \return 1 on allow, 0 on deny, negative error code otherwise + */ int __internal_can_own(bool bus_type, uid_t user, gid_t group, diff --git a/src/internal/libdbuspolicy1-private.hpp b/src/internal/libdbuspolicy1-private.hpp index 83bd79c..14b9d09 100644 --- a/src/internal/libdbuspolicy1-private.hpp +++ b/src/internal/libdbuspolicy1-private.hpp @@ -26,6 +26,7 @@ namespace arraySizeDetail { #define TABSIZE(...) (::arraySizeDetail::size(__VA_ARGS__)) namespace { + /** Contains error code and string corresponding to it */ class ErrCode { int m_err; std::string m_err_str; diff --git a/src/internal/naive_policy_checker.cpp b/src/internal/naive_policy_checker.cpp index 39702e5..71ab8c1 100644 --- a/src/internal/naive_policy_checker.cpp +++ b/src/internal/naive_policy_checker.cpp @@ -2,6 +2,11 @@ #include "cynara.hpp" #include "tslog.hpp" +/** + * \file + * \ingroup Implementation + */ + using namespace ldp_xml_parser; static void __log_item(const MatchItemSR& item) @@ -65,6 +70,10 @@ NaivePolicyChecker::~NaivePolicyChecker() { + + + + DecisionResult NaivePolicyChecker::check(bool bus_type, uid_t uid, gid_t gid, @@ -112,10 +121,12 @@ Decision NaivePolicyChecker::checkPolicySR(const NaivePolicyDb::PolicySR& policy return Decision::ANY; } -Decision NaivePolicyChecker::checkPolicyOwn(const NaivePolicyDb::PolicyOwn& policy, const ItemOwn& item, const char*& privilege) { +Decision NaivePolicyChecker::checkPolicyOwn(const NaivePolicyDb::PolicyOwn& policy, const ItemOwn& item, const char*& privilege) +{ if (tslog::verbose()) { - __log_item(item); + std::cout << "Checking policy for name: " << std::string(!(item.getName()) ? item.getName() : "NULL") << std::endl; } + const char *name = item.getName(); const struct TreeNode *node = policy.getTreeRoot(); int childIndex = 0; @@ -125,6 +136,9 @@ Decision NaivePolicyChecker::checkPolicyOwn(const NaivePolicyDb::PolicyOwn& poli childIndex = char_map[*name]; if (childIndex > 64) { /* name contains forbidden char */ + if (tslog::verbose()) { + std::cout << "Name: " << std::string(!(item.getName()) ? (item.getName()) : "NULL") << " contains forbidden character!" << std::endl; + } privilege = NULL; return Decision::DENY; } @@ -146,6 +160,7 @@ Decision NaivePolicyChecker::checkPolicyOwn(const NaivePolicyDb::PolicyOwn& poli } name++; } + return node->__decisionItem.getDecision(); } diff --git a/src/internal/naive_policy_checker.hpp b/src/internal/naive_policy_checker.hpp index a54302d..b80c23f 100644 --- a/src/internal/naive_policy_checker.hpp +++ b/src/internal/naive_policy_checker.hpp @@ -13,6 +13,13 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + +/** + * \file + * \ingroup Implementation + */ + + #ifndef _NAIVE_DECISIONER_H #define _NAIVE_DECISIONER_H @@ -21,25 +28,71 @@ namespace ldp_xml_parser { + /* Class which checks rights in policies retrieved from policy db + * \ingroup Implementation + */ class NaivePolicyChecker { private: + + /** Policy databases for system and session bus */ NaivePolicyDb m_bus_db[2]; + + /** Adapter to policies database */ DbAdapter* m_adapter; + + /** Retrieves policy db + * \param[in] type Type of database (system/session bus) + * \return Returns reference to chosen bus policy db + * \ingroup Implementation + */ NaivePolicyDb& getPolicyDb(bool type); + /** Checks send/receive policy for given item + * \param[in] policy Policy to check + * \param[in] item Item to check + * \param[in] privilege Privilege string + * \return Returns decision retrieved from policy + * \ingroup Implementation + * \callgraph + */ Decision checkPolicySR(const NaivePolicyDb::PolicySR& policy, const MatchItemSR& item, const char*& privilege); + /** Checks ownership policy for given item + * \param[in] policy Policy to check + * \param[in] item Item to check + * \param[in] privilege Privilege string + * \return Returns decision retrieved from policy + * \ingroup Implementation + */ Decision checkPolicyOwn(const NaivePolicyDb::PolicyOwn& policy, const ItemOwn& item, const char*& privilege); + /** Parses delivered decision. In case of Decision::CHECK calls cynara. + * \param[in] decision Decision from checkers + * \param[in] uid User id + * \param[in] label User label + * \param[in] privilege Privilege string + * \return Returns deny=0, allow=1 or cynara error + * \ingroup Implementation + */ DecisionResult parseDecision(Decision decision, uid_t uid, const char* label, const char* privilege); + /** Checks send/receive policy for given item + * \param[in] bus_type Bus type (system/session) + * \param[in] uid User id + * \param[in] gid User group id + * \param[in] label User label + * \param[in] item Item to check + * \param[in] type Item type + * \return Returns deny=0, allow=1 or cynara error + * \ingroup Implementation + */ DecisionResult checkItemSR(bool bus_type, uid_t uid, gid_t gid, @@ -47,6 +100,16 @@ namespace ldp_xml_parser const MatchItemSR& item, const ItemType type); + /** Checks send/receive policy for given item + * \param[in] bus_type Bus type (system/session) + * \param[in] uid User id + * \param[in] gid User group id + * \param[in] label User label + * \param[in] item Item to check + * \param[in] type Item type + * \return Returns deny=0, allow=1 or cynara error + * \ingroup Implementation + */ DecisionResult checkItemOwn(bool bus_type, uid_t uid, gid_t gid, @@ -55,12 +118,37 @@ namespace ldp_xml_parser const ItemType type); public: ~NaivePolicyChecker(); + + /** Generates adapter for db with policies + * \ingroup Implementation + */ DbAdapter& generateAdapter(); + + /** Checks ownership policy for given item + * \param[in] bus_type Bus type (system/session) + * \param[in] uid User id + * \param[in] gid User group id + * \param[in] label User label + * \param[in] name Name to own + * \return Returns deny=0, allow=1 or cynara error + * \ingroup Implementation + */ DecisionResult check(bool bus_type, uid_t uid, gid_t gid, const char* const label, const char* const name); + + /** Checks send/receive policy for given item + * \param[in] bus_type Bus type (system/session) + * \param[in] uid User id + * \param[in] gid User group id + * \param[in] label User label + * \param[in] matcher Structure with multiple names to check + * \param[in] type Item type + * \return Returns deny=0, allow=1 or cynara error + * \ingroup Implementation + */ DecisionResult check(bool bus_type, uid_t uid, gid_t gid, diff --git a/src/internal/naive_policy_db.cpp b/src/internal/naive_policy_db.cpp index a82cced..a796660 100644 --- a/src/internal/naive_policy_db.cpp +++ b/src/internal/naive_policy_db.cpp @@ -2,6 +2,11 @@ #include "cynara.hpp" #include "tslog.hpp" +/** + * \file + * \ingroup Implementation + */ + using namespace ldp_xml_parser; @@ -166,9 +171,15 @@ const struct TreeNode* NaivePolicyDb::PolicyOwn::getTreeRoot() const{ assert(treeRootPtr); return treeRootPtr; } + void NaivePolicyDb::PolicyOwn::addItem(ItemOwn* item) { const char *name = item->getName(); - + if (tslog::enabled()){ + if(name) + std::cout << "Adding item: " << name << " with decision: " << (int) item->getDecision().getDecision() << std::endl; + else + std::cout << "Adding item: NULL with decision: " << (int) item->getDecision().getDecision() << std::endl; + } if (!name) { /* For '*' name*/ if(item->getDecision().getDecision() != Decision::ANY){ @@ -216,7 +227,6 @@ void NaivePolicyDb::PolicyOwn::addItem(ItemOwn* item) { node->__is_prefix = item->isPrefix(); } - bool NaivePolicyDb::getPolicySR(const NaivePolicyDb::PolicyTypeSetSR& set, const PolicyType policy_type, const PolicyTypeValue policy_type_value, diff --git a/src/internal/naive_policy_db.hpp b/src/internal/naive_policy_db.hpp index 3b8a655..5efd301 100644 --- a/src/internal/naive_policy_db.hpp +++ b/src/internal/naive_policy_db.hpp @@ -20,28 +20,43 @@ #include #include "policy.hpp" + +/** + * \file + * \ingroup Implementation + */ + namespace ldp_xml_parser { + /** Database class, contains policies for ownership and send/receive */ class NaivePolicyDb { public: + /** Class containing policy with send/receive rules */ class PolicySR { private: + /** Vector with policy items */ std::vector m_items; public: + /** Iterator used to get access to policy items */ class PolicyConstIterator { private: + /** Vector with policy items */ const std::vector& m_items; + /** Assistant iterator */ int m_index; public: + /** Public method allowing access to policy items */ PolicyConstIterator(const std::vector& items, int position); ItemSendReceive* const& operator*() const; PolicyConstIterator& operator++(); bool operator!=(const PolicyConstIterator& it) const; }; - + /** Iterator used to get access to policy items */ class PolicyIterator { private: + /** Vector with policy items */ std::vector& m_items; + /** Assistant iterator */ int m_index; public: PolicyIterator(std::vector& items, int position); @@ -54,74 +69,150 @@ namespace ldp_xml_parser PolicyIterator end(); PolicyConstIterator begin() const; PolicyConstIterator end() const; + + /** Adds given item to policy. + * \param[in] item Item to add to policy + */ void addItem(ItemSendReceive* item); }; - + /** Class containing policy with ownership rules */ class PolicyOwn { private: + /** Pointer to policy tree root */ struct TreeNode *treeRootPtr = NULL; + + /** Removes given node and its descendants + * \param[in] node Node to remove from tree + */ void nodeRemove(TreeNode **node); public: PolicyOwn(); ~PolicyOwn(); + /** Adds given item to tree by retrieving its name, decision and checking is it prefix. + * \param[in] item Item to add to policy + */ void addItem(ItemOwn* item); + + /** Retrieves policy tree root + * \return Pointer to tree root + */ const TreeNode* getTreeRoot() const; }; ~NaivePolicyDb(); + /** Gets policy with ownership rules from DB + * \param[in] item_type Item Type + * \param[in] policy_type Policy type + * \param[in] policy_type_value Policy type value + * \param[out] policy Received policy + * \return True if there is such policy, false elsewhere + */ bool getPolicy(const ItemType item_type, const PolicyType policy_type, const PolicyTypeValue policy_type_value, const PolicyOwn*& policy) const; + /** Gets policy with send/receive rules from DB + * \param[in] item_type Item Type + * \param[in] policy_type Policy type + * \param[in] policy_type_value Policy type value + * \param[out] policy Received policy + * \return True if there is such policy, false elsewhere + */ bool getPolicy(const ItemType item_type, const PolicyType policy_type, const PolicyTypeValue policy_type_value, const PolicySR*& policy) const; + /** Adds item to ownership policy + * \param[in] policy_type Policy type + * \param[in] policy_type_value Policy type value + * \param[in] item Item to add + */ void addItem(const PolicyType policy_type, const PolicyTypeValue policy_type_value, ItemOwn* const item); + /** Adds item to send/receive policy + * \param[in] policy_type Policy type + * \param[in] policy_type_value Policy type value + * \param[in] item Item to add + */ void addItem(const PolicyType policy_type, const PolicyTypeValue policy_type_value, ItemSendReceive* const item); private: - + /** Contains maps for different ownership policy types (uid, gid, DEFAULT, MANDATORY) */ struct PolicyTypeSetOwn { + /** Policies for all contexts */ PolicyOwn context[static_cast(ContextType::MAX)]; + /** Map with policies for different users */ std::map user; + /** Map with policies for different groups */ std::map group; }; + /** Contains maps for different send/receive policy types (uid, gid, DEFAULT, MANDATORY) */ struct PolicyTypeSetSR { + /** Policies for all contexts */ PolicySR context[static_cast(ContextType::MAX)]; + /** Map with policies for different users */ std::map user; + /** Map with policies for different groups */ std::map group; }; + /** Set of ownership policies */ PolicyTypeSetOwn m_own_set; + /** Set of send policies */ PolicyTypeSetSR m_send_set; + /** Set of receive policies */ PolicyTypeSetSR m_receive_set; + /** Adds given item to send/receive policy + * \param[in] set Set to add item to + * \param[in] policy_type Policy type + * \param[in] policy_type_value Policy type value + * \param[in] item Item to add + */ void addItem(PolicyTypeSetSR& set, const PolicyType policy_type, const PolicyTypeValue policy_type_value, ItemSendReceive* const item); + /** Gets requested policy from send/receive policies + * \param[in] set Set to add item to + * \param[in] policy_type Policy type + * \param[in] policy_type_value Policy type value + * \param[out] policy Received policy + * \return False if there is no such policy, true elsewhere + */ bool getPolicySR(const PolicyTypeSetSR& set, const PolicyType policy_type, const PolicyTypeValue policy_type_value, const PolicySR*& policy) const; + /** Adds given item to ownership policy + * \param[in] set Set to add item to + * \param[in] policy_type Policy type + * \param[in] policy_type_value Policy type value + * \param[in] item Item to add + */ void addItem(PolicyTypeSetOwn& set, const PolicyType policy_type, const PolicyTypeValue policy_type_value, ItemOwn* const item); + /** Gets requested policy from ownership policies + * \param[in] set Set to add item to + * \param[in] policy_type Policy type + * \param[in] policy_type_value Policy type value + * \param[out] policy Received policy + * \return False if there is no such policy, true elsewhere + */ bool getPolicyOwn(const PolicyTypeSetOwn& set, const PolicyType policy_type, const PolicyTypeValue policy_type_value, diff --git a/src/internal/policy.cpp b/src/internal/policy.cpp index bed844a..2497a63 100644 --- a/src/internal/policy.cpp +++ b/src/internal/policy.cpp @@ -1,3 +1,8 @@ +/** + * \file + * \ingroup Implementation + */ + #include "policy.hpp" #include "naive_policy_db.hpp" #include "tslog.hpp" diff --git a/src/internal/policy.hpp b/src/internal/policy.hpp index 55834cc..4e17722 100644 --- a/src/internal/policy.hpp +++ b/src/internal/policy.hpp @@ -13,6 +13,13 @@ * See the License for the specific language governing permissions and * limitations under the License. */ + + +/** + * \file + * \ingroup Implementation + */ + #ifndef _POLICY_H #define _POLICY_H @@ -20,12 +27,14 @@ #include #include #include + #define MAX_LOG_LINE 1024 +/** Maximum tree node children. It is connected with proper characters which can be used in name.*/ #define MAX_CHILDREN 65 namespace ldp_xml_parser { - + /** Char map used in ownership policy. Single character from given name is mapped to index of tree node child*/ const char char_map[128] {65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 65, 10, 12, 65, @@ -34,7 +43,7 @@ namespace ldp_xml_parser 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 65, 65, 65, 11, 65, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 65, 65, 65, 65, 65}; - + /** Type of sent message*/ enum class MessageType : uint8_t { ANY = 0, METHOD_CALL, @@ -43,12 +52,14 @@ namespace ldp_xml_parser SIGNAL }; + /** Sent message direction */ enum class MessageDirection : uint8_t { ANY, SEND, RECEIVE }; + /** Item type. (different items have different content of class */ enum class ItemType : uint8_t { GENERIC, OWN, @@ -56,18 +67,21 @@ namespace ldp_xml_parser RECEIVE }; + /** Policy type, either context, user or group */ enum class PolicyType : uint8_t { CONTEXT, USER, GROUP }; + /** Context type for context policy type */ enum class ContextType : uint8_t { DEFAULT, MANDATORY, MAX }; + /** Decision returned by policy checkers. Is parsed later */ enum class Decision : uint8_t { ANY, ALLOW, @@ -75,12 +89,14 @@ namespace ldp_xml_parser CHECK }; + /** Final decision of libdbus policy. Either allow, deny or error code */ enum class DecisionResult : int8_t { CYNARA_ERROR = -3, DENY = 0, ALLOW }; + /** Contains value corresponding to each of policy types */ union PolicyTypeValue { PolicyTypeValue(); PolicyTypeValue(ContextType type); @@ -92,6 +108,7 @@ namespace ldp_xml_parser class ItemBuilder; + /** Class contains decision and privilege string */ class DecisionItem { private: Decision __decision; @@ -106,6 +123,7 @@ namespace ldp_xml_parser const char* toString(char* str) const; }; + /** Class contains info about ownership policy item */ class ItemOwn { private: DecisionItem __decision; @@ -124,6 +142,7 @@ namespace ldp_xml_parser bool isPrefix() const; }; + /** Node of tree used in ownership policy. */ struct TreeNode{ DecisionItem __decisionItem; char __nameChar; @@ -131,12 +150,14 @@ namespace ldp_xml_parser struct TreeNode *children[MAX_CHILDREN]; }; + /** Name structure for send/receive policy */ struct NameSR { const char* name; int len; NameSR(const char* m = NULL, int l = 0); }; + /** Struct which allows to contain multiple connection names then compared in s/r policy checker */ struct MatchItemSR { int names_num; NameSR names[KDBUS_CONN_MAX_NAMES+1]; @@ -152,6 +173,7 @@ namespace ldp_xml_parser const char* toString(char* str) const; }; + /** Class contains info about item send/receive */ class ItemSendReceive { private: DecisionItem __decision; @@ -180,6 +202,8 @@ namespace ldp_xml_parser }; class NaivePolicyDb; + + /** Allows to create items from given name, decision etc. */ class ItemBuilder { private: DecisionItem __decision; @@ -208,6 +232,7 @@ namespace ldp_xml_parser void setPrefix(bool value); }; + /** Adapter which allows to access policy db. Contains references to system and session db. */ class DbAdapter { private: enum state { diff --git a/src/internal/tslog.cpp b/src/internal/tslog.cpp index fa5b579..cd6d18e 100644 --- a/src/internal/tslog.cpp +++ b/src/internal/tslog.cpp @@ -1,3 +1,8 @@ +/** + * \file + * \ingroup Implementation + */ + #include "tslog.hpp" namespace tslog { diff --git a/src/internal/tslog.hpp b/src/internal/tslog.hpp index 07fc383..62aea11 100644 --- a/src/internal/tslog.hpp +++ b/src/internal/tslog.hpp @@ -13,6 +13,10 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +/** + * \file + * \ingroup Implementation + */ #ifndef _TSLOG_HPP #define _TSLOG_HPP @@ -26,12 +30,16 @@ typedef std::ostream& (*t_ManFun)(std::ostream&); namespace tslog { - + /** Checks value of environmental variable with given name */ bool get_log_env(char const *name); + /** Checks environmental variables and sets global variable defining if logs are enabled */ void init(); + /** Checks if logs are enabled */ bool enabled(); + + /** Checks if verbosity is enabled */ bool verbose(); } diff --git a/src/internal/xml_parser.cpp b/src/internal/xml_parser.cpp index 5606a33..afd14ca 100644 --- a/src/internal/xml_parser.cpp +++ b/src/internal/xml_parser.cpp @@ -1,3 +1,7 @@ +/** + * \file + * \ingroup Implementation + */ #include "xml_parser.hpp" std::set ldp_xml_parser::XmlParser::__parsed; diff --git a/src/internal/xml_parser.hpp b/src/internal/xml_parser.hpp index ff1a723..4e417b1 100644 --- a/src/internal/xml_parser.hpp +++ b/src/internal/xml_parser.hpp @@ -13,6 +13,10 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +/** + * \file + * \ingroup Implementation + */ #ifndef _XML_PARSER_HPP #define _XML_PARSER_HPP @@ -29,26 +33,29 @@ namespace ldp_xml_parser { + /** Class which have methods parsing policy rules contained in xml files */ class XmlParser : boost::noncopyable { public: + /** Parses given config file for declared bus type */ ErrCode parsePolicy(bool bus, std::string const &fname) { ErrCode err = parse(bus, fname); return err; } - + /** Registers DBAdapter */ void registerAdapter(DbAdapter& adapter) { __adapter = &adapter; } private: - //IO operation + /** Vector containing parsed policy */ static std::set __parsed; + /** Adapter which allows to acces parsed policies */ DbAdapter* __adapter; - //Data obtained from XML + /** Parses config file and all files included in it */ ErrCode parse(bool bus, std::string const &filename) { ErrCode err; std::vector incl_files; @@ -61,7 +68,7 @@ namespace ldp_xml_parser } return err; } - + /** Parses given xml file and files included in it */ ErrCode parse(bool bus, bool first, const std::string& filename, std::vector& included_files) { std::pair errparam; std::vector incl_dirs; @@ -81,7 +88,7 @@ namespace ldp_xml_parser return errparam.first; } - //Get all the .conf files within included subdirectory, POSIX style as boost::filesystem is not header-only + /** Get all the .conf files within included subdirectory, POSIX style as boost::filesystem is not header-only */ void getIncludedFiles(const std::string& filename, const std::string& incldir, std::vector& files) { DIR *dir; struct dirent *ent; @@ -109,7 +116,7 @@ namespace ldp_xml_parser std::cout << "could not open directory " << dname << '\n'; } } - + /** Acceses given configuration file/files */ std::pair parseXml(bool bus, const std::string& filename, std::vector& incl_dirs) { std::pair ret; diff --git a/src/libdbuspolicy1.c b/src/libdbuspolicy1.c index 79b858b..431827a 100644 --- a/src/libdbuspolicy1.c +++ b/src/libdbuspolicy1.c @@ -271,13 +271,6 @@ DBUSPOLICY1_EXPORT void __dbuspolicy1_change_creds(void* configuration, uid_t ui static bool configuration_bus_type(struct kconn const *configuration) { return configuration != g_conn; } -/** - * dbuspolicy1_can_send - * @param: <> - * @return: <> - * - * Description. - **/ DBUSPOLICY1_EXPORT int dbuspolicy1_check_out(void* configuration, const char *destination, const char *sender, @@ -388,13 +381,6 @@ end: return r; } -/** - * dbuspolicy1_can_send - * @param: <> - * @return: <> - * - * Description. - **/ DBUSPOLICY1_EXPORT int dbuspolicy1_check_in(void* configuration, const char *destination, const char *sender, @@ -428,13 +414,6 @@ end: return r; } -/** - * dbuspolicy1_can_send - * @param: <> - * @return: <> - * - * Description. - **/ DBUSPOLICY1_EXPORT int dbuspolicy1_can_own(void* configuration, const char* const service) { int r;