Solstice Enterprise Manager 4.1 C++ API Reference Doc Set ContentsPreviousNextIndex


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:

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:

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:

    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.


    Sun Microsystems, Inc.
    Copyright information. All rights reserved.
    Doc Set  |   Contents   |   Previous   |   Next   |   Index