Solstice Enterprise Manager 4.1 C++ API Reference

Chapter 6

Access Control Engine API

The Access Control Engine (ACE) API functions enable you to invoke Access Control Decision Function (ADF) and Access Control Enforcement Function (AEF) operations. The ADF and AEF are implemented in the ACE module, which is in turn implemented as a shared library.

The ACE API is designed using the low-level PMI and is independent of the MIS architecture. This allows the API to be plugged into different Auxiliary Servers (such as MIS and MPA), making it possible for the Auxiliary Servers to impose access control on the objects they manage.

This chapter comprises the following topics:

• Section 6.1 Symbolic Constants
• Section 6.2 ACE API Classes
• Section 6.3 ACE Class

6.1 Symbolic Constants

6.1.1 ACEOperationType

enum ACEOperationType { ACEAction, ACECreate, ACEDelete, ACEGet, ACESet, ACEReplace = 4, ACEAddMember = 4, ACERemoveMember = 4, ACEReplaceWithDefault = 4, ACEMultipleObjectSelection = 8, ACEFilter, ACEEventReport, ACEMaxNumOperations }

The ACEMaxNumOperations element is a count of ACEOperationTypes and not an ACEOperationType.

6.1.2 ACEEnforcementAction

enum ACEEnforcementAction { DenyWithResponse, DenyWithoutResponse, AbortAssociation, DenyWithFalseResponse, Allow, Unknown, MaxNumEnforcementActions }

The MaxNumEnforcementActions element is a count of the ACEEnforcementActions and not an ACEEnforcementAction.

6.2 ACE API Classes

This section describes the following ACE API classes:

• ACE
• ACEContext
• ACEDecision
• ACEDomain
• ACEGlobals
• ACEReqData
• AuxServerUtils

6.3 ACE Class

Inheritance: None

#include <ace/ace.hh>

Data members: No public data members are declared in this class.

This class abstracts the concept of ACE initialization and acts as a single point of access to the services provided by the ACE library. There can only be one object instance of this class for each security domain. This restriction helps in the management of and clear separation between an auxiliary server (such as MIS or MPA) and the Access Control Servers (ACS) to which it connects.

6.3.1 Constructor

ACE(const ACEDomain& domain, AuxServerUtils& aux_server_utils)

This constructor initializes the ACE library. It sets the security domain for which access control is to be provided to domain. It also takes a reference to the class derived from AuxServerUtils, which needs to be implemented as part of using ACE API.

---

Note – You should either create the ACE object on the heap or make sure it does not go out of scope.

---

6.3.2 Destructor

~ACE()

6.3.3 ACE Member Functions

get_ace_instance

ACE& get_ace_instance()

This function is a static method. It returns the currently instantiated ACE object instance.

check_access

ACEDecision check_access( const ACEReqData& ace_req_data) const throw(ACEException)

ACEDecision check_access( const Message* msg, const void* user_data = 0, const RWTValSlist<Asn1Value>& in_oc_component_list = ACEGlobals::null_oc_component_list, const ACEContext& context =ACEGlobals::null_ace_context, Boolean x740_supported = TRUE ) const throw(ACEException)

Checks access for the user found in the msg's access field and returns the ACEDecision object from which the enforcement action can be obtained. TABLE 6-1 describes this function's parameters.

TABLE 6-1   check_access() Parameters 

Parameter	Description
ace_req_data	Reference to a ACEReqData object.
msg	Message for which access control needs to be applied.
user_data	User data to be passed to AuxServerUtils methods. This is analogous to the user_data parameter passed for typical callbacks.
in_oc_component_list	List of all possible object classes starting from the root of the above oi. This list contains the following: Object class root for / Object class system for /systemId=name:"netareno Object class log for /systemId=name:"netareno"/logId=string:"Alarmlog" You can pass the default value ACEGlobals::null_oc_component_list ao, while applying the access control decisions, the ACE API calls AuxServerUtils::determine_class() to get the object class information for the message.
context	A reference to an ACEContext object.

---

Note – The Message class is the base class used for messages passed between SAPs and the PMI.

---

hi_process_ace_event

void hi_process_ace_event(Ptr user_data, Ptr call_data)

The ACE API callback that processes all access control-related events once the application/auxiliary server is up and running. This method can be registered using the Platform::when() method. While registering with Platform::when(), the pointer to the ACE object should be passed in the userdata of the Platform::when() method, so that the hi_process_ace_event() receives a pointer to the ACE object in its user_data parameter.

This is a static method that processes high-level events. call_data must be a CurrentEvent object pointer. For more information about the CurrentEvent class.

lo_process_ace_event

void lo_process_ace_event(Ptr user_data, Ptr call_data)

The ACE API callback that processes all access control-related events once the application or auxiliary server is up and running. This method is typically called when there is an existing callback on the Platform. When the Platform callback is called, you can call this method with user_data containing a pointer to the ACE object and call_data containing the message from CurrentEvent.

This method is a static method that processes low-level events. call_data must be a Message object pointer.

6.4 ACEContext Class

#include <ace/ace_context.hh>

The ACEContext class stores the context of an access check on a scoped and filtered CMIP request that cannot be resolved deterministically.

6.4.1 Constructor

ACEContext(const Message* p_orig_user_req = 0)

This constructor creates an ACEContext object with the original user request set to p_orig_user_req. If p_orig_user_req is not provided, the original user request is set to 0.

6.4.2 Destructor

~ACEContext()

6.4.3 ACEContext Operator Overloading

operator void*() const

int operator !() const

6.4.4 ACEContext Member Functions

get_orig_user_req

Message* get_orig_user_req() const

Returns the original user request message that the instantiated ACEContext object contains.

get_scope

MessScope& get_scope() const

Returns the scope that the instantiated ACEContext object contains.

get_filter

Asn1Value& get_filter() const

Returns the filter information that the instantiated ACEContext object contains.

set_scope

void set_scope(const MessScope& scope)

Sets the scope of the instantiated ACEContext object to scope.

set_filter

void set_filter(const Asn1Value& filter)

Set the filter of the instantiated ACEContext object to filter.

6.5 ACEDecision Class

#include <ace/ace_decision.hh>

The ACEDecision class abstracts the concept of ADF decision in response to an access check request to ACE.

6.5.1 Constructor

ACEDecision()

The preceding constructor creates an ACEDecision object.

ACEDecision(const ACEDecision& rhs)

The preceding constructor is a copy constructor.

ACEDecision( const Asn1Value& oc, const Asn1Value& oi, const ACEEnforcementAction& enforcement_action, const Message* p_msg = 0 )

This constructor creates an ACEDecision object and initializes its "proposed response" data member as follows:

• If enforcement_action is DenyWithResponse, the proposed response is set to ACCESS_DENIED.
• If enforcement_action is DenyWithoutResponse or AbortAssociation, the proposed response is set to PROCESS_FAILURE.

6.5.2 Destructor

~ACEDecision()

6.5.3 ACEDecision Member Functions

get_enforcement_action

ACEEnforcementAction get_enforcement_action() const

Returns the enforcement action for the ACE decision. Refer to Section6.1 Symbolic Constants," for return values.

get_proposed_response

ObjResMess* get_proposed_response() const

Returns the proposed response of the ACEDecision object. The return value is an ObjResMess pointer to an ACCESS_DENIED or PROCESS_FAILURE message.

get_proposed_response returns NULL if the decision was not denied.

get_original_request

Message* get_original_request() const

Returns the original message given to ACE by the ACE client for which access control is to be applied.

6.6 ACEDomain Class

#include <ace/ace_domain.hh>

The ACEDomain class abstracts the concept of a security domain and information that is needed to identify and access the domain server ACS.

6.6.1 Constructor

ACEDomain(const DataUnit& domain_name, MessageSAP* p_sap)

The preceding constructor creates an ACEDomain object with the domain name set to domain_name and the message SAP set to p_sap.

ACEDomain(const ACEDomain& that)

The preceding constructor is a copy constructor.

6.6.2 Destructor

~ACEDomain()

6.6.3 ACEDomain Member Function

get_sap

MessageSAP* get_sap() const

Returns the message SAP of the ACEDomain object.

6.7 ACEReqData Class

#include <ace/ace_req_data.hh>

The ACEReqData class stores operation request data.

6.7.1 Constructor

ACEReqData( const Asn1Value& user_id =ACEGlobals::null_asn1_value, const Asn1Value& oc = ACEGlobals::null_asn1_value, const Asn1Value& oi = ACEGlobals::null_asn1_value, const ACEOperationType& operation = ACEGlobals::null_operation_type, const MessScope& scope = ACEGlobals::null_scope, const Asn1Value& filter = ACEGlobals::null_asn1_value, const void* user_data = 0, const RWTValSlist<Asn1Value>& in_oc_component_list = ACEGlobals::null_oc_component_list, const Message* opt_original_msg = 0, ACEContext context = ACEGlobals::null_ace_context, Boolean x740_supported = TRUE )

TABLE 6-2 describes the parameters of the preceding constructor.

TABLE 6-2   ACEReqData() Constructor Parameters 

Parameter	Description
user_id	An encoded GraphicString whose access needs to be checked against a request.
oc	Object class of the message.
oi	Object instance of the message.
operation	Type of the message. Values are obtained from ACEOperationType.
scope	Scope of the message.
filter	Filter of the message.
user_data	User data to be passed to AuxServerUtils methods. This is analogous to the user_data parameter passed for typical callbacks.
in_oc_component_list	List of all possible object classes for the message that is being passed to check_access. For example, if the message being passed is a get request whose oi = /systemId=name:"netareno"/logId=string:"Alarmlog", in_oc_component_list contains all possible object classes starting from the root of the above oi. The list contains the following: Object class root for / Object class system for /systemId=name:"netareno Object class log for /systemId=name:"netareno"/ logId=string:"Alarmlog" The default value for this parameter is ACEGlobals::null_oc_component_list. If the default value is used, ACE API calls the AuxServerUtils::determine_class() to get the object class information for the message.
opt_original_msg	Message for which access control needs to be applied.
context	A reference to an ACEContext object.

6.7.2 Destructor

~ACEReqData();

6.8 AuxServerUtils Class

Inheritance: None

#include <ace/ace_aux_server_utils.hh>

Data members: No public data members are declared in this class.

The C++ class, AuxServerUtils, is an abstract base class that provides auxiliary services to ACE objects.

6.8.1 Constructor

AuxServerUtils()

The AuxServerUtils class is an abstract base class, and cannot be instantiated.

6.8.2 Destructor

~AuxServerUtils()

6.8.3 AuxServerUtils Virtual Functions

check_filter

FilterResult check_filter( const Asn1Value& oi, const Asn1Value& filter, const void* userdata = 0)

This method is a hook into the application or auxiliary server's code called by the ACE. This method is called whenever the ACE is evaluating a target that has a filter specified in it. This method is expected to check whether oi satisfies the filter. userdata has a valid pointer if ACE::check_access() was called with userdata in it.

The possible return values are NO_MATCH, MATCH, INVALID, RESOURCELIM, and PROCESSFAIL as defined in pmi/filter.hh. If the filter field of the targets is not being used, this method returns MATCH.

determine_class

Asn1Value determine_class( const Asn1Value& oi, const void* userdata = 0)

This method is a hook into the application or auxiliary server's code called by the ACE. This method is called whenever the ACE does not find the managed object class of the request in the target's object classes list. This method evaluates the object class of the given oi and returns it. userdata has a valid pointer if ACE::check_access() was called with userdata in it.

aux_get_req

Result aux_get_req( MessageSAP* sap, const Asn1Value& oi, const MessScope& scope, const Callback& cb, const Asn1Value& oc = ACEGlobals::actual_class_oc const Asn1Value& attrs = ACEGlobals:: null_asn1_value, const Asn1Value& filter = ACEGlobals::null_asn1_value, const Asn1Value& access = ACEGlobals::null_asn1_value, const MessSync& sync = BEST_EFFORT, MessId& op_id = ACEGlobals::null_msg_id, const U32 flags = 0, const Boolean& sub_trans = FALSE)

This method is called by ACE internals to send a GET_REQ to the MIS to load access control information inside the ACE.

extract_message

Message* extract_message(Ptr call_data)

This method is called by ACE internals to receive the response to a GET_REQ sent in by aux_get_req.

aux_check_create_filter

FilterResult aux_check_create_filter( const Message* msg, const Asn1Value& filter)

This method is a hook into the application or auxiliary server's code called by the ACE. This method is called whenever the ACE is evaluating a create request against a target that has a filter specified in it. This method checks whether msg satisfies the filter. The possible return values are NO_MATCH, MATCH, INVALID, RESOURCELIM, and PROCESSFAIL as defined in pmi/filter.hh.

aux_check_event_filter

FilterResult aux_check_event_filter( const Message* msg, const Asn1Value& filter)

This method is a hook into the application or auxiliary server's code called by the ACE. This method is called whenever the ACE is evaluating an event request. This method checks whether the event msg satisfies filter. The possible return values are NO_MATCH, MATCH, INVALID, RESOURCELIM, and PROCESSFAIL as defined in pmi/filter.hh.