diff options
Diffstat (limited to 'src/sss_client/sudo/sss_sudo.h')
| -rw-r--r-- | src/sss_client/sudo/sss_sudo.h | 120 |
1 files changed, 120 insertions, 0 deletions
diff --git a/src/sss_client/sudo/sss_sudo.h b/src/sss_client/sudo/sss_sudo.h index 082c8015a..12d8eb2b4 100644 --- a/src/sss_client/sudo/sss_sudo.h +++ b/src/sss_client/sudo/sss_sudo.h @@ -21,42 +21,162 @@ #ifndef SSS_SUDO_H_ #define SSS_SUDO_H_ +/** + * @defgroup libsss_sudo A library for communication between SUDO and SSSD + * libsss_sudo provides a mechanism to for a SUDO plugin + * to communicate with the sudo responder of SSSD. + * + * @{ + */ + #include <stdint.h> +/** The sss_sudo* functions in general return EOK on success */ #ifndef EOK #define EOK 0 #endif +/** The value returned when the communication with SUDO is successful and + * the user was found in one of the domains + */ #define SSS_SUDO_ERROR_OK 0 +/** + * Component of a sss_rule structure. The component + * has exactly one name and one or more values. + * + */ struct sss_attr { + /** The attribute name */ char *name; + /** A string array that contains all the attribute values */ char **values; + + /** The number of values the attribute contains. + * + * Attributes are multivalued in general. + */ unsigned int num_values; }; +/** + * One sudo rule. The rule consists of one or more + * attributes of sss_attr type + */ struct sss_rule { + /** The number of attributes in the rule */ unsigned int num_attrs; + + /** List of rule attributes */ struct sss_attr *attrs; }; +/** + * A result object returned from SSSD. + * + * The result consists of zero or more sss_rule elements. + */ struct sss_result { + /** + * The number of rules for the user + * + * In case the user exists in one of SSSD domains + * but no rules match for him, the num_rules element + * is 0. + */ unsigned int num_rules; + + /** List of rules found */ struct sss_rule *rules; }; +/** + * @brief Send a request to SSSD to retreive all SUDO rules for a given + * user. + * + * @param[in] username The username to retreive the rules for + * @param[out] _error The result of the search in SSSD's domains. If the + * user was present in the domain, the _error code is + * SSS_SUDO_ERROR_OK and the _result structure is + * returned even if it was empty (in other words + * _result->num_rules == 0). Other problems are returned + * as errno codes. Most prominently these are ENOENT + * (the user was not found with SSSD), EIO (SSSD + * encountered an internal problem) and EINVAL + * (malformed query). + * @param[out] _result Newly allocated structure sss_result that contains + * the rules for the user. If no rules were found but + * the user was valid, this structure is "empty", which + * means that the num_rules member is 0. + * + * @return The return value denotes whether communication with SSSD was + * successful. It does not tell whether the result contains any rules or + * whether SSSD knew the user at all. That information is transferred in the + * _error parameter. + */ int sss_sudo_send_recv(const char *username, uint32_t *_error, struct sss_result **_result); +/** + * @brief Send a request to SSSD to retrieve the default options, commonly + * stored in the "cn=defaults" record, + * + * @param[out] _error The result of the search in SSSD's domains. If the + * options were present in the domain, the _error code + * is SSS_SUDO_ERROR_OK and the _result structure is + * returned even if it was empty (in other words + * _result->num_rules == 0). Other problems are returned + * as errno codes. + * + * @param[out] _result Newly allocated structure sss_result that contains + * the options. If no options were found this structure + * is "empty", which means that the num_rules member + * is 0. + * + * @return The return value denotes whether communication with SSSD was + * successful. It does not tell whether the result contains any options, + * That information is transferred in the _error parameter. + */ int sss_sudo_send_recv_defaults(uint32_t *_error, struct sss_result **_result); +/** + * @brief Free the sss_result structure returned by sss_sudo_send_recv + * + * @param[in] result The sss_result structure to free. The structure was + * previously returned by sss_sudo_get_values(). + */ void sss_sudo_free_result(struct sss_result *result); +/** + * @brief Get all values for a given attribute in a sss_rule + * + * @param[in] e The sss_rule to get values from + * @param[in] attrname The name of the attribute to query from the rule + * @param[out] values A newly allocated list of values the attribute has in + * rule. On success, this parameter is an array of + * NULL-terminated strings, the last element is a NULL + * pointer. On failure (including when the attribute is + * not found), the pointer address is not changed. + * + * @return EOK on success, ENOENT in case the attribute is not found and other + * errno values on failure. + * + * @note the returned values should be freed using sss_sudo_free_values() + */ int sss_sudo_get_values(struct sss_rule *e, const char *attrname, char ***values); +/** + * @brief Free the values returned by sss_sudo_get_values + * + * @param[in] values The list of values to free. The values were previously + * returned by sss_sudo_get_values() + */ void sss_sudo_free_values(char **values); +/** + * @} + */ #endif /* SSS_SUDO_H_ */ |