diff options
Diffstat (limited to 'src/providers/ipa/ipa_hbac.h')
| -rw-r--r-- | src/providers/ipa/ipa_hbac.h | 180 |
1 files changed, 159 insertions, 21 deletions
diff --git a/src/providers/ipa/ipa_hbac.h b/src/providers/ipa/ipa_hbac.h index 7de49d1ff..02077e37e 100644 --- a/src/providers/ipa/ipa_hbac.h +++ b/src/providers/ipa/ipa_hbac.h @@ -26,107 +26,216 @@ #ifndef IPA_HBAC_H_ #define IPA_HBAC_H_ +/** + * @defgroup ipa_hbac Host-Based Access Control Resolver + * Libipa_hbac provides a mechanism to validate FreeIPA + * HBAC rules as well as evaluate whether they apply to + * a particular user login attempt. + * + * Libipa_hbac is case-insensitive and compatible with + * UTF-8. + * @{ + */ + #include <stdint.h> #include <stdbool.h> +/** Result of HBAC evaluation */ enum hbac_eval_result { + /** An error occurred + * See the #hbac_info for more details + */ HBAC_EVAL_ERROR = -1, + + /** Evaluation grants access */ HBAC_EVAL_ALLOW, + + /** Evaluation denies access */ HBAC_EVAL_DENY, + + /** Evaluation failed due to lack of memory + * #hbac_info is not available + */ HBAC_EVAL_OOM }; -#define HBAC_CATEGORY_NULL 0x0000 /* No service category specified */ -#define HBAC_CATEGORY_ALL 0x0001 /* Rule should apply to all */ +/** + * No service category specified + */ +#define HBAC_CATEGORY_NULL 0x0000 -/* Opaque type contained in hbac_evaluator.c */ +/** + * Rule should apply to all + */ +#define HBAC_CATEGORY_ALL 0x0001 + +/** + * Opaque type contained in hbac_evaluator.c + */ struct hbac_time_rules; +/** + * Component of an HBAC rule + * + * Components can be one of users, target hosts, + * source hosts, or services. + */ struct hbac_rule_element { + /** + * Category for this element + * + * This value is a bitmask. + * See #HBAC_CATEGORY_NULL and + * #HBAC_CATEGORY_ALL + */ uint32_t category; + + /** + * List of explicit members of this rule component + * + * - Users: usernames + * - Hosts: hostnames + * - Services: PAM service names + */ const char **names; + + /** + * List of group members of this rule component + * + * - Users: user groups (POSIX or non-POSIX) + * - Hosts: hostgroups + * - Services: PAM service groups. + */ const char **groups; }; +/** + * HBAC rule object for evaluation + */ struct hbac_rule { const char *name; bool enabled; - /* Services and service groups + /** + * Services and service groups * for which this rule applies */ struct hbac_rule_element *services; - /* Users and groups for which this + /** + * Users and groups for which this * rule applies */ struct hbac_rule_element *users; - /* Target hosts for which this rule apples */ + /** + * Target hosts for which this rule apples + */ struct hbac_rule_element *targethosts; - /* Source hosts for which this rule applies */ + /** + * Source hosts for which this rule applies + */ struct hbac_rule_element *srchosts; - /* For future use */ + /** + * For future use + */ struct hbac_time_rules *timerules; }; +/** + * Component of an HBAC request + */ struct hbac_request_element { + /** + * List of explicit members of this request component + * + * - Users: usernames + * - Hosts: hostnames + * - Services: PAM service names + */ const char *name; + + /** + * List of group members of this request component + * + * - Users: user groups (POSIX or non-POSIX) + * - Hosts: hostgroups + * - Services: PAM service groups. + */ const char **groups; }; +/** + * Request object for an HBAC rule evaluation + * + * + */ struct hbac_eval_req { - /* This is a list of service DNs to check, + /** This is a list of service DNs to check, * it must consist of the actual service * requested, as well as all parent groups * containing that service. */ struct hbac_request_element *service; - /* This is a list of user DNs to check, + /** This is a list of user DNs to check, * it must consist of the actual user * requested, as well as all parent groups * containing that user. */ struct hbac_request_element *user; - /* This is a list of target hosts to check, + /** This is a list of target hosts to check, * it must consist of the actual target host * requested, as well as all parent groups * containing that target host. */ struct hbac_request_element *targethost; - /* This is a list of source hosts to check, + /** This is a list of source hosts to check, * it must consist of the actual source host * requested, as well as all parent groups * containing that source host. */ struct hbac_request_element *srchost; - /* For future use */ + /** For future use */ time_t request_time; }; +/** + * Error code returned by the evaluator + */ enum hbac_error_code { + /** Unexpected error */ HBAC_ERROR_UNKNOWN = -1, + + /** Succesful evaluation */ HBAC_SUCCESS, + + /** Function is not yet implemented */ HBAC_ERROR_NOT_IMPLEMENTED, + + /** Ran out of memory during processing */ HBAC_ERROR_OUT_OF_MEMORY, + + /** Parse error while evaluating rule */ HBAC_ERROR_UNPARSEABLE_RULE }; -/* Extended information */ +/** Extended information */ struct hbac_info { - /* If the hbac_eval_result was HBAC_EVAL_ERROR, + /** + * If the hbac_eval_result was HBAC_EVAL_ERROR, * this will be an error code. * Otherwise it will be HBAC_SUCCESS */ enum hbac_error_code code; - /* Specify the name of the rule that matched or + /** + * Specify the name of the rule that matched or * threw an error */ char *rule_name; @@ -141,20 +250,45 @@ struct hbac_info { * @param[out] info Extended information (including the name of the * rule that allowed access (or caused a parse error) * @return + * - #HBAC_EVAL_ERROR: An error occurred + * - #HBAC_EVAL_ALLOW: Access is granted + * - #HBAC_EVAL_DENY: Access is denied + * - #HBAC_EVAL_OOM: Insufficient memory to complete the evaluation */ enum hbac_eval_result hbac_evaluate(struct hbac_rule **rules, struct hbac_eval_req *hbac_req, struct hbac_info **info); +/** + * @brief Display result of hbac evaluation in human-readable form + * @param[in] result Return value of #hbac_evaluate + * @return English string describing the evaluation result + */ const char *hbac_result_string(enum hbac_eval_result result); + +/** + * @brief Display error description + * @param code Error code returned in #hbac_info + * @return English string describing the error + */ const char *hbac_error_string(enum hbac_error_code code); +/** + * @brief Function to safely free #hbac_info returned by #hbac_evaluate + * @param info #hbac_info returned by #hbac_evaluate + */ void hbac_free_info(struct hbac_info *info); - +/** User element */ #define HBAC_RULE_ELEMENT_USERS 0x01 + +/** Service element */ #define HBAC_RULE_ELEMENT_SERVICES 0x02 + +/** Target host element */ #define HBAC_RULE_ELEMENT_TARGETHOSTS 0x04 + +/** Source host element */ #define HBAC_RULE_ELEMENT_SOURCEHOSTS 0x08 /** @@ -163,10 +297,10 @@ void hbac_free_info(struct hbac_info *info); * @param[in] rule An HBAC rule to evaluate * @param[out] missing_attrs A list of attributes missing from the rule * This is a bitmask that may contain one or more - * of HBAC_RULE_ELEMENT_USERS, - * HBAC_RULE_ELEMENT_SERVICES, - * HBAC_RULE_ELEMENT_TARGETHOSTS and - * HBAC_RULE_ELEMENT_SOURCEHOSTS + * of #HBAC_RULE_ELEMENT_USERS, + * #HBAC_RULE_ELEMENT_SERVICES, + * #HBAC_RULE_ELEMENT_TARGETHOSTS and + * #HBAC_RULE_ELEMENT_SOURCEHOSTS * * @return True if the rule contains all mandatory attributes * @@ -174,4 +308,8 @@ void hbac_free_info(struct hbac_info *info); */ bool hbac_rule_is_complete(struct hbac_rule *rule, uint32_t *missing_attrs); + +/** + * @} + */ #endif /* IPA_HBAC_H_ */ |