Solstice Enterprise Manager 4.1 Developing C++ Applications

Chapter 12

Controlling Access to Applications and Data

Controlling access to applications and data prohibits unwanted access to critical applications and network components. Without access control, any user of your network management solution can read or modify all your network management and configuration data. The risks of this approach can be devastating when users without the proper authority or expertise modify your network management data or the configuration data of your network management solution. By controlling user access, users are allowed to access only those applications and data they need based on their network management responsibilities and other relevant criteria.

This chapter explains how to control access to applications and data.

• Section 12.1 Access Control Levels
• Section 12.2 Enforcing Predefined Access Control Rules
• Section 12.3 Modifying Access Control Information
• Section 12.4 Getting Access Control Defaults
• Section 12.5 Keeping Event Notifications Private
• Section 12.6 Making MPAs Secure

12.1 Access Control Levels

To enable you make your applications and data secure, Solstice EM provides the following levels of access control:

• Application-level access control
• Application-feature-level access control
• Managed-object-level access control
• Event notification access control
• Management protocol adapter (MPA) access control

12.1.1 Application-Level Access Control

Implement application-level access control if you want your entire application to be inaccessible to some users of the network management solution that your application is a part of. For example, if your application is used for the administration of your network management solution, make the application accessible only to system administrators and inaccessible to network operators.

If you implement application-level access control, make sure that your application gives proper feedback to a user that is denied access to your application.

Before you implement application-level access control, make sure that the application's features are defined and implemented.

Solstice EM enables you to implement application-level access control by either of the methods described in:

• Section 12.2 Enforcing Predefined Access Control Rules
• Section 12.3 Modifying Access Control Information

12.1.2 Application-Feature-Level Access Control

Implement application-feature-level access control if you want some users to be able to access some, but not all, the features of your application. For example, if your application enables users to monitor, add, modify, and delete network resources, implement application-feature-level access control to allow some users to monitor network resources, but not to add, modify, or delete network resources.

If you implement application-feature-level access control, make sure that your application gives proper feedback if a user is denied access to a feature. Where possible, make sure that your application prevents users from performing operations they do not have permission to perform. In a graphical application, make commands for performing such operations inactive and grayed out.

If you implement application-feature-level access control, make the list of application features available to your system administrator so that the system administrator can grant users access rights to perform various operations.

Before you implement application-feature-level access control, make sure that the application's features are defined and implemented.

Solstice EM enables you to implement application-feature-level access control by either of the methods described in:

• Section 12.2 Enforcing Predefined Access Control Rules
• Section 12.3 Modifying Access Control Information

12.1.3 Managed-Object-Level Access Control

Implement managed-object-level access control if you want some managed objects to be inaccessible to some users of your network management solution.

Managed-object-level access control denies users access to managed objects regardless of which application they use to try to access the managed objects. If you use application-feature-level access control to deny access to these managed objects, you do not prevent users from accessing the managed objects by using other features of other applications.

If you implement managed-object-level access control, make sure that your application gives proper feedback if a user is denied access to a managed object. In addition, make sure that your application can handle any exceptions or errors thrown if a user is denied access to a managed object.

Solstice EM enables you to implement managed-object-level access control by either of the methods described in:

• Section 12.2 Enforcing Predefined Access Control Rules
• Section 12.3 Modifying Access Control Information

12.1.4 Event Notification Access Control

Implement event notification access control if you want to ensure that a user's event logs contain only event notifications emitted by managed objects to which the user has access. By default, all events that the Solstice EM platform receives are written to a user's event logs, including event notifications from managed objects that the user is normally denied access to.

For information on how to implement event notification access control, refer to Section 12.5 Keeping Event Notifications Private.

12.1.5 Management Protocol Adapter (MPA) Access Control

Implement MPA access control if you want some managed objects that are accessed through an MPA to be inaccessible to some users of your application.

If you implement MPA access control, make sure that your application gives proper feedback if a user is denied access to a managed object accessed through an MPA.

For information on how to implement MPA access control, refer to Section 12.6 Making MPAs Secure.

12.2 Enforcing Predefined Access Control Rules

Enforce predefined access control rules if you want to control access to applications and data, but do not require your application to modify access control rules that have already been defined.

Solstice EM enables you to enforce predefined access control rules for the following levels of access control:

• Application-level
• Application-feature-level
• Managed-object-level

Enforcing predefined access control rules involves:

• Defining the access control rules
• Enforcing application-level and application-feature-level access control
• Handling denial of access to managed objects

  ---

  Note – The Solstice EM access control module enforces access control rules defined for managed objects. You do not need to add code to your applications for enforcing managed-object-level access control.

  ---

For information on source code examples that show how to enforce predefined access control rules, refer to Section A.5.3 Password Request Example and Section A.5.3 Password Request Example.

12.2.1 Defining Access Control Rules

Access control rules are the basis for denying or granting users access to applications, application features, and managed objects. Access control rules identify:

• User groups to which access controls are to be applied
• Applications, features or managed objects to which access is to be granted or denied
• The policy that determines if access is to be granted or denied

Solstice EM enables you to define access control rules in either of the following ways:

• Interactively
• From the command line

12.2.1.1 Defining Access Control Rules Interactively

Defining access control rules interactively provides immediate verification of the access control rules you define, thereby making it simple to define complex access control rules. To define access control rules interactively, use the Security tool. For information on how to use the Security tool, refer to Managing Your Network.

12.2.1.2 Defining Access Control Rules From the Command Line

Defining access control rules from the command line saves time and effort when you need to define large numbers of rules, or when you need to apply the same rules to several different systems. To define access control rules from the command line, use the em_accesscmd utility.

The em_accesscmd utility defines access control rules in accordance with information supplied in em_accesscmd commands. The em_accesscmd utility can also read em_accesscmd commands from an em_accesscmd script, which is a text file.

For information on how to use the em_accesscmd utility, refer to Managing Your Network.

An em_accesscmd script is shown in CODE EXAMPLE 12-1.

CODE EXAMPLE 12-1   em_accesscmd Script 

// // Run this script during MIS startup by using the em_accesscmd utility. // This script creates access control objects for the "Security" application. // // Create Application // createApplication "security"        "Security sample graphical application" // // Create "Security sample application" features // createFeature "security" "View only"    "View/Connect only" createFeature "security" "Delete"    "Delete objects" assignApps "Operator" "security" // Assign groups to the application features assignAppFeatures "View Only" "security" "View only"

The em_accesscmd command script shown in this example defines access control rules as follows:

• The createApplication command places an application named security under access control. The description of this application is Security sample graphical appli cation.
• The createFeature command places features of the application named security under access control as follows:
  
  
  • A feature named View only for which the description is View/Connect only
    
  • A feature named Delete for which the description is Delete objects
• The assignApps command grants members of the Operator privilege group access to the application named security.
• The assignAppFeatures command grants members of the View Only privilege group access to the feature named View only of the application named security.

12.2.2 Enforcing Application-Level and Application-Feature-Level Access Control

Enforcing application-level and application-feature-level access control enables your application to verify if the user that started the application has the privileges to use the application and its features. These privileges are granted or denied based on access control rules defined for the application as explained in Section 12.2.1 Defining Access Control Rules.

12.2.2.1 Enforcing Application-Level Access Control

Enforcing application-level access control involves:

• Ensuring that the access rules defined for the application deny access to all features of the application
• Verifying that no features are granted to the user who is running the application
• Disabling the application

Verifying that no features are granted to the user who is running the application involves:

• Creating and initializing an instance of the AuthFeatures class
• Passing this instance in a call to the get_authorized_features function of the Platform class
• Verifying that the call to get_authorized_features returns an empty list

How to enable or disable an application depends on the application.

12.2.2.2 Enforcing Application-Feature-Level Access Control

Enforcing application-feature-level access control involves:

• Getting a list of features granted to the user who is running the application
• For each feature in the list:
  
  
  • Verifying if the user is granted access to the feature
    
  • Enabling or disabling the feature depending on whether the user is granted access to it

Getting a list of features granted to the user who is running the application involves:

• Creating and initializing an instance of the AuthFeatures class
• Passing this instance in a call to the get_authorized_features function of the Platform class

To verify if a user is granted access to a feature, call the is_authorized function of the AuthFeatures class. In the call to is_authorized, specify the name of the feature.

How to enable or disable a of an application feature depends on the application.

12.2.2.3 Example of Enforcing Application-Level and Application-Feature-Level Access Control

CODE EXAMPLE 12-2 shows code for enforcing application-level and application-feature-level access control.

CODE EXAMPLE 12-2   Controlling Application- and Application-Feature-Level Access 

... #include <pmi/hi.hh>           // High Level PMI ... AuthFeatures feature_list;     if (!em_mis.get_authorized_features(feature_list)) {         cout << "Not authorized to run this program!" << endl;         return 0;     } ...     if (!feature_list.is_authorized("Delete"))         XtSetSensitive(main_window->delete_btn, 0);     else         XtSetSensitive(main_window->delete_btn, 1); ...

In this example, if the call to get_authorized_features returns an empty list, a message warning that the user is denied access to the application is printed and the application is terminated. Otherwise, the application verifies if the user is granted access to the Delete feature of the application and does one of the following:

• If the user is denied access to the Delete feature, the menu command for choosing this feature is made inactive and grayed out.
• If the user is granted access to the Delete feature, the menu command for choosing this feature is made active.

12.2.3 Handling Denial of Access to Managed Objects

If your application is likely to be used in a situation where managed-object-level access control is enforced, ensure that your application takes appropriate action if access to a managed object is denied. To do so, include error checking with every operation on a managed object to verify that access was granted before your application tries to process the result of the operation. If your application is denied access to managed objects it requires to function, make sure that your application provides proper feedback to the user and is terminated gracefully.

If the enforcement action for a managed object is deny without response, your application will receive no indication that it has been denied access to a managed object. In this situation, your application will become blocked indefinitely if it waits for a response. To prevent a denial without response from blocking your application indefinitely, specify a timeout period for all operations on managed objects.

12.3 Modifying Access Control Information

Enable an application to modify access control information if:

• You want the access control applied to applications and data to change while the application is running.
• You want to write a custom security tool.

Solstice EM enables you to modify access control information for the following levels of access control:

• Application-level
• Application-feature-level
• Managed-object-level

To enable an application to modify access control information, you use the access control API. Enabling an application to modify access control information involves:

• Activating access control for the Solstice EM platform
• Adding a user to a privilege group
• Listing all application features under access control
• Adding applications and application features to a privilege group
• Defining a target
• Defining a security rule
• Handling access control errors

For information on source code examples that show how to modify access control information, refer to Section A.5.1 Access Control API Examples.

12.3.1 Activating Access Control for the Solstice EM Platform

Access control the Solstice EM platform is set active or inactive during installation. If you want to enforce access control in your application, you must ensure that access control is active for the Solstice EM platform.

To determine if access control is active, call the get_access_control_switch function of the ACAccessControlRules class.

To activate access control, call the set_access_control_switch function of the ACAccessControlRules class. In the call to set_access_control_switch, specify the access control switch status as emAccessControlOn.

To deactivate access control, call the set_access_control_switch function of the ACAccessControlRules class, specifying the access control switch status as emAccessControlOff.

---

Note – Any user who runs a program that activates or deactivates access control must have full access privileges, such as those of a system administrator.

---

CODE EXAMPLE 12-3 shows code for activating access control for the Solstice EM platform.

CODE EXAMPLE 12-3   Activating Access Control for the Solstice EM Platform 

... #include <acapi/accesscontrolrules.hh>        // AC rules ... ACAccessControlRules access_control_defaults; ACAccessControlSwitch access_switch =     access_control_defaults.get_acce ss_control_switch(); if (access_switch == emAccessControlOff) {     access_switch = emAccessControlOn;     access_control_defaults.set_access_control_switch(access_switch); } ...

In this example, if access control is not active for the Solstice EM platform, the function set_access_control_switch is called to activate access control.

12.3.2 Adding a User to a Privilege Group

Access control rules are not set for individual users, but for a group of users called a privilege group. Any user that requires access to secure applications, application features, or managed objects must belong to a privilege group. All users in a privilege group have the same access control privileges. The access control model of Solstice EM allows individual users to belong to more than one group.

Solstice EM provides predefined privilege groups as given in TABLE 12-1.

TABLE 12-1   Predefined Privilege Groups 

Privilege Group	Description
Full Access	Provided they are enabled to grant all privileges, users belonging to the Full Access group are permitted to create, modify, and remove access to all Solstice EM tools and managed objects according to any existing rules or settings of the default rule. Without the ability to grant all privileges, users will be able to connect to a remote management information server (MIS), but will not be able to update the security controls. This group is not the same as turning off access control. When access control is turned off, no existing rules limit a user's access to applications and managed objects.
Operators	Users belonging to the Operators group can access specific tools but cannot modify managed data.
View Only	Users belonging to the View Only group can view a restricted set of controlled object data, but they cannot modify the data. Users in this group have access to a restricted set of tools to use for viewing data to which they have access.

Adding a user to a privilege group involves:

• Creating the privilege group
• Creating the user
• Making the user known to the management information server (MIS)
• Adding the user to the privilege group and storing the group

12.3.2.1 Creating a Privilege Group

Before you assign a user to a privilege group, make sure that the privilege group exists.

Creating a privilege group involves:

• Creating and initializing an instance of the ACGroup class
• Verifying that the privilege group does not exist in the MIS
• Adding the privilege group to the MIS

Creating and Initializing an Instance of the ACGroup Class

Create and initialize an instance of the ACGroup class to represent the privilege group. In the call to the constructor of the ACGroup class, specify the privilege group name. The privilege group name is one of those listed in TABLE 12-1 or the name of a custom privilege group you want to define yourself.

If you create a predefined privilege group, you only need to add users to it.

Verifying That a Privilege Group Does Not Exist in the MIS

Before trying to add a privilege group to the MIS, verify that the group does not already exist in the MIS. To verify that a privilege group does not exist in the MIS, call the exists function that the ACGroup class inherits from the ACObject class.

Adding a Privilege Group to the MIS

Adding a privilege group to the MIS enables the MIS to apply access control to the privilege group. To add a privilege group to the MIS, call the create function that the ACGroup class inherits from the ACObject class.

---

Note – When you add a privilege group to the MIS, the privilege group is stored only in memory, not persistently. To store the privilege group persistently, store it as described in Section 12.3.2.4 Adding a User to a Privilege Group and Storing the Group.

---

Example of Creating a Privilege Group

Code for creating a privilege group is shown in CODE EXAMPLE&nb sp;12-4.

CODE EXAMPLE 12-4   Creating a Privilege Group 

... #include <acapi/acgroup.hh>            // ACGroup class ...     RWCString group_name("Operator"); // default group name     ACGroup group(group_name);     if (!group.exists())         group.create(); ...

In this example, an instance of the ACGroup class is created and initialized to represent the Operator privilege group. The overloaded NOT (!) operator acts on the call to exists to verify that the privilege group does not exist. If the privilege group does not exist, the create function is called to add the privilege group to the MIS.

12.3.2.2 Creating a User

Before you assign a user to a privilege group, create the user. To create a user, create and initialize an instance of the ACUser class. The ACUser class represents a user in a privilege group. In the call to the constructor of the ACUser class, specify the login name of the user and, optionally, the full name of the user.

Code for creating a user is shown in CODE EXAMPLE 12-5.

CODE EXAMPLE 12-5   Creating a User 

... #include <acapi/acaccessuserlist.hh>            // ACUser class ... ACUser user(user_name) ; ...

In this example, a user whose login name is specified by the user_name variable is created. The initialization of the user_name variable is not shown in this example.

12.3.2.3 Making a User Known to the MIS

Each user in your network management environment must be made known to the MIS to be granted privileges to access applications, application features or managed objects.

Making a user known to the MIS involves:

• Creating an access control list
• Adding a user to the access control list and storing the list

Creating an Access Control List

An access control list contains all users in your network management environment.

To create an access control list, call the get_access_user_list function of the ACInterface class. The get_access_user_list function returns an instance of the ACAccessUserList class. The ACAccessUserList class represents an access control list.

Code for creating an access control list is shown in CODE EXAMPLE 12-6

CODE EXAMPLE 12-6   Creating an Access Control List 

... #include <acapi/acinterface.hh           // ACInterface class #include <acapi/acaccessuserlist.hh>     // ACAccessUserList class ... ACInterface ac_interface; ... ACAccessUserList user_list = ac_interface.get_access_user_list(); ...

Adding a User to an Access Control List and Storing the List

After you have created an access control list, add to the list each user in the network management environment. To add a user to the access control list, call the add_user function of the ACAccessUserList class. In the call to add_user, specify the instance of ACUser that represents the user you want to add.

Each time you add a user to an access control list, store the list in the MIS. To store the list in the MIS, call the store function that the ACAccessUserList class inherits from the ACObject class.

Code for adding a user to an access control list and storing the list is shown in CODE EXAMPLE 12-7.

CODE EXAMPLE 12-7   Adding a User and Storing an Access Control List 

if (user_list.add_user(user) == TRUE)   // Add the user to the user_list     user_list.store();                  // Store user_list in the MIS // Error checking and reporting     if (user_list.get_error_type() == ACC_OK)     {         Return(OK);     }     if (user_list.get_error_type() == ACC_USER_EXISTS)     {         cout << user_name << " already exists, will continue ..."              << endl;         Return(OK);     }     else     {         cout << "Error: " << user_list.get_error_string() << endl;         Return(NOT_OK);     } ...

In this example, if the attempt to add the user represented by user_name succeeds, the access control list is stored in the MIS. If the user already exists in the access control list, the list is not stored, and a message that states that the user exists is printed. If the attempt to add the user fails for another reason, the list is not stored in the MIS. The reason for the failure is printed.

The initialization of the user_list object is shown in CODE EXAMPLE 12-6.

The initialization of the user_name variable is not shown in this example.

12.3.2.4 Adding a User to a Privilege Group and Storing the Group

Each user that you want to grant access privileges to must belong to a privilege group. Add a user to a privilege group after you have made the user known to the MIS. To add a user to a privilege group, call the add_group_member function on the instance of ACGroup that represents the group.

Each time you add a user to a privilege group, store the privilege group persistently in the MIS. To store a privilege group persistently in the MIS, call the store function that the ACGroup class inherits from the ACObject class.

Code for adding a user to a privilege group and storing the group is shown in CODE EXAMPLE 12-8.

CODE EXAMPLE 12-8   Adding a User to a Privilege Group 

... #include <acapi/acgroup.hh>            // ACGroup class ...     if (group.add_group_member(user_name) == TRUE)         group.store(); // Error checking and reporting     if (group.get_error_type() == ACC_OK)     {         Return(OK);     }     if (group.get_error_type() == ACC_USER_EXISTS)     {         cout << user_name << " already exists, will continue ..."             << endl;         Return(OK);     }     else     {         cout << "Error: " << group.get_error_string() << endl;         Return(NOT_OK);     } }

In this example, if the attempt to add the user represented by user_name succeeds, the privilege group is stored in the MIS. If the user is already a member of the privilege group, the privilege group is not stored, and a message that states that the user is a member is printed. If the attempt to add the user fails for another reason, the privilege group is not stored in the MIS. The reason for the failure is printed.

The initialization of the user_name variable is not shown in this example.

The initialization of the group object is shown in CODE EXAMPLE&nb sp;12-4.

12.3.3 Listing All Application Features Under Access Control

To determine whether all the features you want to restrict access to are under access control, list all application features under application-feature-level access control.

Listing all application features under application-feature-level access control involves:

• Listing all applications under application-feature-level access control
• For each application listed, listing the features of the application that are under access control

12.3.3.1 Listing All Applications Under Application-Feature-Level Access Control

Listing all applications under application-feature-level access control involves:

• Creating and initializing an instance of the ACInterface class
• Calling the get_application_container function of the ACInterface class to get an instance of the ACApplicationContainer class
• Calling the get_all_applications function on the instance of ACApplicationContainer that the call to get_application_container returned

If you want to get a description of each application, call the get_application_description function on each application in the list returned by the call to get_all_applications.

Code for listing all applications under application-feature-level access control and getting a description of each application is shown in CODE EXAMPLE 12-9.

CODE EXAMPLE 12-9   Listing Applications Under Application-Feature-Level Access Control 

... #include <acapi/acapplication.hh> #include <acapi/acapplicationfeature.hh> #include <acapi/acinterface.hh> ...     ACInterface ac_interface;     ACApplicationContainer app_container =         ac_interface.get_application_container(); ACApplicationList app_list =     app_container.get_all_applicatio ns(); ...     for (int k=0; k < app_list.entries(); k++)     {         ACApplication app(app_list[k].data());         cout << app_list[k].data();         cout << app.get_application_description() << endl;     } ...

12.3.3.2 Listing the Features of an Application That Are Under Access Control

After you have listed all applications under application-feature-level access control, get for each application a list of the features that are under access control.

Listing the features of an application that are under access control involves:

• Creating and initializing an instance of the ACAppFeatureContainer class
• Calling the get_all_features function of the ACAppFeatureContainer class to get an instance of the ACApplicationFeatureList class

If you want to get a description of each application, call the get_feature_description function on each feature in the list returned by the call to get_all_features.

Code for listing the features of an application that are under access control and getting a description of each feature is shown in CODE EXAMPLE 12-10.

CODE EXAMPLE 12-10   Listing Application Features Under Access Control 

... #include <acapi/acapplication.hh> #include <acapi/acapplicationfeature.hh> ...     ACAppFeatureContainer app_features(application_name);     ACApplicationFeatureList feature_list =         app_features.get_all_features(); ...     for (int j=0; j < feature_list.entries(); j++)     {         ACApplicationFeature feature(application_name,             feature_list[j].data());         cout << feature_list[j].data();         cout << feature.get_feature_description() << endl;     } ...

12.3.4 Adding Applications and Application Features to a Privilege Group

Adding applications and application features to a privilege group defines which applications and application features are accessible to the users in the privilege group.

To add an application to a privilege group, call the add_application function on the instance of ACGroup that represents the group. In the call to add_application, specify the name of the application you want to add.

To add an application feature to a privilege group, call the add_application_feature function on the instance of ACGroup that represents the group. In the call to add_application_feature, specify:

• The name of the application that provides the feature you want to add
• The name of the feature you want to add

  ---

  Note – For information on how to enable your application to enforce application level and application-feature-level access control, refer to Section 12.2.2 Enforcing Application-Level and Application-Feature-Level Access Control.

  ---

12.3.5 Defining a Target

A target is a collection of management information that is subject to access control. Define a target for each collection of management information that you want to be subject to the same set of security rules for the same user group.

Solstice EM provides predefined targets as given in TABLE 12-2.

TABLE 12-2   Predefined Targets 

Name of Target	Description
DenyAccessControlObjectsChange	Pointer to the object /em-name="accessControlContainer"
Connection	Pointer for the instance of the object subsuystemid='EM-MIS" which is of type emApplicationinstance
View Only	Pointer to the root of the management information tree (MIT)

Defining a target involves:

• Creating a target
• Defining the list of operations for the target
• Defining the membership of the target
• Storing the target persistently in the MIS

12.3.5.1 Creating a Target

Before you define the membership of a target, make sure that the target exists.

Creating a target involves:

• Creating and initializing an instance of the ACTargets class
• Verifying that the target does not exist in the MIS
• Adding the target to the MIS
• Checking for errors

Creating and Initializing an Instance of the ACTargets Class

Create and initialize an instance of the ACTargets class to represent the target. In the call to the constructor of the ACTargets class, specify:

• The target name. The target name is one of those listed in TABLE 12-2 or the name of a custom target you want to define yourself. If you create a predefined target, you do not need to define its membership.
• Optionally, the target type. The target type specifies the managed object class that defines the target. The target type is one of the following:
  
  
  • X741_TARGETS, which specifies the targets managed object class defined in ITU-T X.741 Objects and Attributes for Access Control
    
  • EM_TARGETS, which specifies the emTargets managed object class defined in Solstice EM access control module

The default target type is X741_TARGETS.

Verifying That a Target Does Not Exist in the MIS

Before trying to add a target to the MIS, verify that the target does not already exist in the MIS. To verify that a target does not exist in the MIS, call the exists function that the ACTargets class inherits from the ACObject class.

Adding a Target to the MIS

Adding a target to the MIS enables the MIS to apply access control to the target. To add a target to the MIS, call the create function that the ACTargets class inherits from the ACObject class.

---

Note – When you add a target to the MIS, the target is stored only in memory, not persistently. To store the target persistently, store it as described in Section 12.3.5.4 Storing the Target Persistently in the MIS.

---

Checking for Errors

After you have added a target to the MIS, check for errors. You have to explicitly check for errors because no errors are returned when you verify if the target exists or when you add a target to the MIS. To check for errors, call the get_error_type function that the ACTargets class inherits from the ACObject class. To get the reason for an error, call the get_error_string function that the ACTargets class inherits from the ACObject class.

Example of Creating a Target

Code for creating a target is shown in CODE EXAMPLE 12-11.

CODE EXAMPLE 12-11   Creating a Target 

... #include <acapi/actargets.hh> //ACTargets class ...     ACTargets target(target_name);     if (!target.exists())     target.create(); // Error checking and reporting     if (target.get_error_type() != ACC_OK)     {     cerr << "Error: " << target.get_error_string() << endl;     exit(3); ...

In this example, an instance of the ACTargets class is created and initialized to represent the target identified by target_name. The overloaded NOT (!) operator acts on the call to exists to verify that the target does not exist. If the target does not exist, the create function is called to add the target to the MIS. If an error occurs, a message explaining the reason for the error is printed.

The initialization of the target_name variable is not shown in this example.

12.3.5.2 Defining the List of Operations for a Target

The list of operations for a target specifies which management operations on the target are subject to any security rule applied to the target. The operations are permitted or disallowed, depending on the security rule applied to the target. For information on how to define a security rule, see Section 12.3.6 Defining a Security Rule.

Defining the list of operations for a target involves:

• Creating the list of operations for a target
• Adding each operation to the list
• Adding the list of operations to the target

To create a list of operations for a target, create an instance of the defined type ACOperationsList to represent the list.

To add an operation to a list of operations, call the insert function of the defined type ACOperationsList. In the call to insert, specify the operation. The operation must be one of the operations defined in TABLE 12-3.

TABLE 12-3   Operations for a Target 

Operation	Definition
create	Creates a managed object
delete	Deletes a managed object
get	Obtains attribute values from a managed object
replace	Replaces the existing value with a specified value
addMember	Adds a value to the current value of a multi-valued attribute
removeMember	Removes a value from the current value of a multi-valued attribute
replacewithDefault	Replaces the existing value with the default value defined in the property list in the ATTRIBUTES construct of the attribute's GDMO specification
action	Performs an action on a managed object
multipleObjectSelection	Selects multiple objects in the MIT to be the subject of a management operation
filter	Applies a filter to a subtree of the MIT

To add a list of operations to a target, call the set_operations_list function of the ACTargets class.

Code for defining the list of operations for a target is shown in CODE EXAMPLE 12-12.

CODE EXAMPLE 12-12   Defining the List of Operations for a Target 

... #include <acapi/actargets.hh> // ACTargets class and                               // ACOperationsList typedef ...     ACOperationsList oper_list;     RWCString operation1("get");     oper_list.insert(operation1);     RWCString operation2("replace");     oper_list.insert(operation2); ...     target.set_operations_list(oper_ list); ...

In this example, a list that consists of the operations get and replace is defined for a target. The set_operations_list function is called to add the list to the target. The initialization of the target object is shown in CODE EXAMPLE&nb sp;12-11.

12.3.5.3 Defining the Membership of a Target

Defining the membership of a target identifies a collection of management information that is subject to access control. In the Solstice EM environment, this collection of management information is an object set that consists of one or more of the following:

• One or more managed objects
• A subtree of the MIT
• All instances of one or more managed object classes

Selecting One or More Managed Objects

If the managed objects you want to be members of a target are distributed throughout the MIT, select them individually.

To select one managed object, call the add_moi function of the ACTargets class. In the call to add_moi, specify the fully distinguished name (FDN), local distinguished name (LDN), or nickname of the managed object.

Selecting more than one managed object involves:

• Creating an instance of the defined type ACMOIList to represent the list of managed objects you want to select
• Calling the insert function once for each managed object you want to add to the list
• Passing the list in a call to the set_moi_list function of the ACTargets class

Selecting a Subtree of the MIT

If the managed objects you want to be members of a target are in a subtree of the MIT, select the subtree. To select a subtree, specify:

• The base managed object
• A scope
• A filter

The base managed object is the root object of the subtree you want to select. To specify the base managed object, call the add_moi function of the ACTargets class. In the call to add_moi, specify the FDN, LDN, or nickname of the base managed object.

The scope selects one or more managed objects in the subtree rooted at the base managed object. The scope is defined with reference to the base managed object.

To specify a scope, call the set_scope function of the ACTargets class. In the call to set_scope, create and initialize an instance of the ACScope class to represent the scope. In the call to the constructor of the ACScope class, specify one of the scope values given in TABLE 12-4.

TABLE 12-4   Scope Values in the Constructor of ACScope 

Value	Selects
BASE_OBJECT	The base managed object only
ALL_LEVELS	The base managed object and its entire subtree
ALL_LEVELS_EXCEPT_BASE	The entire subtree of the base managed object excluding the base managed object itself
NTH_LEVEL, n	Only level n subordinates of the base managed object, where n is an integer
BASE_TO_NTH_LEVEL, n	The base managed object and all its subordinates to level n, where n is an integer

The filter selects or rejects objects based on the presence and values of specific attributes. The filter is a boolean expression, which may be a single test or a combination of multiple tests. The filter is optional. If you omit it, all managed objects identified by the base managed object and scope are selected.

To specify a filter, call the set_filter function of the ACTargets class. In the call to set_filter, specify an instance of the defined type ACFilter to represent the filter. This defined type corresponds to a string. The required format of this string is identical to a filter in a derivation string as defined in Section 6.3.2.3 Filter.

Selecting All Instances of One or More Managed Object Classes

To select all instances of a managed object class, call the add_moc function of the ACTargets class. In the call to add_moc, specify the name of the managed object class.

If a managed object class with the same name is defined in more than one of the GDMO documents loaded into the MIS, you must specify in which document the managed object class you are interested in is defined.

To specify the document, prefix the managed object class name with the document name specified in the MODULE construct of the managed object's GDMO specification, for example: "My Document":reusedMOC.

Specifying all instances of more than one managed object class involves:

• Creating an instance of the defined type ACMOCList to represent the list of managed object classes you want to specify
• Calling the insert function once for each managed object class you want to add to the list
• Passing the list in a call to the set_moc_list function of the ACTargets class

12.3.5.4 Storing the Target Persistently in the MIS

After you have defined the list of operations for a target and the membership of a target, store the target persistently in the MIS.To store a target persistently in the MIS, call the store function that the ACTargets class inherits from the ACObject class.

Code for storing a target persistently in the MIS is shown in CODE EXAMPLE 12-13.

CODE EXAMPLE 12-13   Storing a Target Persistently in the MIS 

... #include <acapi/actargets.hh> // ACTargets class and ...     if (target.add_moc(moc) && target.set_operations_list(oper_list))     {         target.store();     } ...

In this example, if the managed object class and list of operations are added to the target, the target is stored persistently in the MIS. The initialization of the target object is shown in CODE EXAMPLE 12-11.

12.3.6 Defining a Security Rule

A security rule grants or denies a privilege group access to the management information in a target. Solstice EM provides predefined security rules as given in TABLE 12-5.

TABLE 12-5   Predefined Security Rules 

Rule Name	Description
Full Access	Grants the users of "Operators" and "Full Access" groups access to all managed objects
DenyAccesscontrolObjectsChange	Denies the users of the "Operator" group access to change object attributes
View Only	Grants the users of the "View Only" group access to the following objects named: "View Only" which allows the users to view data but not change it "Connection" which allows them to connect to an MIS to view data

Defining a security rule involves:

• Creating the security rule
• Adding a privilege group to the security rule
• Adding a target to the security rule
• Defining the enforcement action of the security rule
• Storing the security rule persistently in the MIS

12.3.6.1 Creating a Security Rule

Before you add a target or a privilege group to a security rule, create the security rule.

Creating a security rule involves:

• Creating and initializing an instance of the ACRule class
• Verifying that the security rule does not exist in the MIS
• Adding the security rule to the MIS
• Checking for errors

Creating and Initializing an Instance of the ACRule Class

Create and initialize an instance of the ACRule class to represent the security rule. In the call to the constructor of the ACRule class, specify the name of the security rule. The security rule name is one of those listed in TABLE 12-5 or the name of a custom security rule you want to define yourself. If you create a predefined security rule, you do not need to add a target or a privilege group nor define the enforcement action, unless you want to extend the rule.

Verifying That a Security Rule Does Not Exist in the MIS

Before trying to add a security rule to the MIS, verify that the security rule does not already exist in the MIS. To verify that a security rule does not exist in the MIS, call the exists function that the ACRule class inherits from the ACObject class.

Adding a Security Rule to the MIS

Adding a security rule to the MIS enables the MIS to enforce the security rule. To add a security rule to the MIS, call the create function that the ACRule class inherits from the ACObject class.

---

Note – When you add a security rule to the MIS, the security rule is stored only in memory, not persistently. To store the security rule persistently, store it as described in Section 12.3.6.5 Storing the Security Rule Persistently in the MIS.

---

Checking for Errors

After you have added a security rule to the MIS, check for errors. You have to explicitly check for errors because no errors are returned when you verify if a security rule exists or when you add a security rule to the MIS. To check for errors, call the get_error_type function that the ACRule class inherits from the ACObject class. To get the reason for an error, call the get_error_string function that the ACRule class inherits from the ACObject class.

Example of Creating a Security Rule

Code for creating a security rule is shown in CODE EXAMPLE 12-14.

CODE EXAMPLE 12-14   Creating a Security Rule 

... #include <acapi/acrule.hh>        // ACRule class ...     ACRule rule(rule_name);          if (!rule.exists())     rule.create(); // Error checking and reporting     if (rule.get_error_type() != ACC_OK)     {     cerr << "Error: " << rule.get_error_string() << endl;     exit(4);     } ...

In this example, an instance of the ACRule class is created and initialized to represent the security rule identified by rule_name. The overloaded NOT (!) operator acts on the call to exists to verify that the security rule does not exist. If the security rule does not exist, the create function is called to add the security rule to the MIS. If an error occurs, a message explaining the reason for the error is printed.

The initialization of the rule_name variable is not shown in this example.

12.3.6.2 Adding a Privilege Group to a Security Rule

Adding a privilege group to a security rule specifies the users that the security rule applies to. To add a privilege group to a security rule, call the add_group function of the ACRule class. In the call to add_group, specify the name of the privilege group you want to add.

CODE EXAMPLE 12-15 shows code for adding a privilege group to a security rule.

CODE EXAMPLE 12-15   Adding a Privilege Group to a Security Rule 

... #include <acapi/acrule.hh>        // ACRule class ...     ACRule rule(rule_name); ...     RWCString group("Operator");     rule.add_group(group); ...

In this example, a privilege group named Operator is added to a security rule. The initialization of the rule_name variable is not shown in this example.

12.3.6.3 Adding a Target to a Security Rule

Adding a target to a security rule specifies the collection of management information that the security rule applies to. To add a target to a security rule, call the add_targets function of the ACRule class. In the call to add_targets, specify the name of the target you want to add.

CODE EXAMPLE 12-16 shows code for adding a target to a security rule.

CODE EXAMPLE 12-16   Adding a Target to a Security Rule 

... #include <acapi/acrule.hh>        // ACRule class ...     ACRule rule(rule_name); ...     RWCString target("View Only");     rule.add_targets(target); ...

In this example, a target named View Only is added to a security rule. The initialization of the rule_name variable is not shown in this example.

12.3.6.4 Defining the Enforcement Action of a Security Rule

Defining the enforcement action of a security rule specifies the result of an attempt by a member of the security rule's privilege group to perform a management operation on a member of the security rule's target.

To define the enforcement action of a security rule, call the set_enforcement_action function of the ACRule class. In the call to set_enforcement_action, specify the enforcement action. The enforcement action must be one of the enforcement actions defined in TABLE 12-6.

TABLE 12-6   Enforcement Actions 

Enforcement Action	Meaning
allow	Allows the requested management operation to be performed
denyWithResponse	Denies the requested management operation and returns the access denied response
denyWithoutResponse	Denies the requested management operation without giving a response
denyWithFalseResponse	Gives a false response and, if the management operation was performed in confirmed mode, returns incorrect management information
abortAssociation	Aborts the association between the manager and the managed entity

CODE EXAMPLE 12-17 shows code for defining the enforcement action of a security rule.

CODE EXAMPLE 12-17   Defining the Enforcement Action of a Security Rule 

... #include <acapi/acrule.hh>        // ACRule class ...     ACRule rule(rule_name); ...     EnforcementAction enforcement_action = denyWithResponse;     rule.set_enforcement_action(enforcement_action); ...

In this example, the enforcement action of a security rule is set to denyWithResponse. The initialization of the rule_name variable is not shown in this example.

12.3.6.5 Storing the Security Rule Persistently in the MIS

After you have defined the enforcement action, store the security rule persistently in the MIS. To store a security rule persistently in the MIS, call the store function that the ACRule class inherits from the ACObject class.

CODE EXAMPLE 12-18 shows code for storing a security rule persistently in the MIS.

CODE EXAMPLE 12-18   Storing a Security Rule 

... #include <acapi/acrule.hh>        // ACRule class ... ACRule rule(rule_name); ... RWCString group("Operator"); RWCString target("View Only"); EnforcementAction enforcement_action = denyWithResponse; if (rule.add_group(group) && rule.add_targets(target) &&             rule.set_enforcement_action(enforcement_action)) {     rule.store(); } ...

In this example, if the privilege group and target are added to the security rule, and if the enforcement action is defined, the security rule is stored persistently in the MIS.

12.3.7 Handling Access Control Errors

Users need to know when an attempted access control operation has failed. By providing accurate information on why the operation failed, your applications can ease a user's work by indicating the corrective action required when problems occur. To provide accurate diagnostic information, test for the success of any function call that may, in some circumstances, fail to return the desired result.

To test for the success of a function call, call the get_error_type function. When you test for the success of a function call, call the get_error_string function to get information on the error and present that information to the user.

---

Note – The get_error_type and get_error_string functions of the access control API are similar to the corresponding functions of the Error class described in Chapter 4.

---

If you need to ignore an error and carry on, call the reset_error function. Call this function should before any valid call is made on an object.

CODE EXAMPLE 12-19 shows code for testing the success of a function call and for providing information on the reason for the failure if the function call fails.

CODE EXAMPLE 12-19   Error Handling Example 

... #include <acapi/acgroup.hh>            // ACGroup class ...     RWCString group_name("Operator"); // default group name     ACGroup group(group_name);     if (!group.exists())         group.create(); ... // Error checking and reporting if (group.get_error_type() != ACC_OK) {     cout << "Error: " << group.get_error_string() << endl;     exit(3); } ...

12.4 Getting Access Control Defaults

Getting access control defaults enables you to determine if you need to modify any of the predefined security rules provided with the Solstice EM platform. Solstice EM enables you to get the following access control defaults:

• Default enforcement action for all management operations
• Default enforcement action for all events
• List of trusted hosts
• Access control denial granularity
• Access control domain

12.4.1 Getting the Default Enforcement Action for All Management Operations

The enforcement action for a management operation specifies the result of an attempt to perform the management operation.

The management operations to which an enforcement action can be applied are listed in TABLE 12-3. The possible enforcement actions are listed in TABLE 12-6.

To get the default enforcement action for all management operations, call the get_default_access function of the ACAccessControlRules class. The get_default_access function returns a list of value pairs. There is one item in the list for each management operation. Each item in the list consists of the management operation and its enforcement action separated by a space.

CODE EXAMPLE 12-20 shows code for getting the default enforcement action for all management operations.

CODE EXAMPLE 12-20   Getting Default Access Control for All Operations 

... #include <acapi/accesscontrolrules.hh        // AC rules ...     ACAccessControlRules access_control_defaults; ...     ACDefaultAccess access =             access_control_defaults.get_default_access(); ...

12.4.2 Getting the Default Enforcement Action for All Events

The enforcement action for an event specifies the result of an attempt to view the information contained in an event. By default, Solstice EM applies the same enforcement action to all events, regardless of event type.

To get the default enforcement action for all events, call the get_default_event_access function of the ACAccessControlRules class. The get_default_event_access function returns one of the enforcement actions listed in TABLE 12-6.

CODE EXAMPLE 12-21 shows code for getting the default enforcement action for all events.

CODE EXAMPLE 12-21   Getting the Default Enforcement Action for All Events 

... #include <acapi/accesscontrolrules.hh        // AC rules ...     ACAccessControlRules access_control_defaults; ...     ACDefaultEventAccess event_access =         access_control_defaults.get_default_event_access(); ...

12.4.3 Getting a List of Trusted Hosts

A trusted host provides its root user with full access permission to the MIS of the current host whenever that user is running a Solstice EM application or tool.

To get a list of trusted hosts for a Solstice EM system, call the get_trusted_host_list function of the ACAccessControlRules class.

CODE EXAMPLE 12-22 shows code for getting a list of trusted hosts.

CODE EXAMPLE 12-22   Getting a List of Trusted Hosts 

... #include <acapi/accesscontrolrules.hh        // AC rules ...     ACAccessControlRules access_control_defaults; ...     ACTrustedHostList trusted_hosts =         access_control_defaults.get_trusted_host_list(); ...

12.4.4 Getting the Access Control Denial Granularity

The access control denial granularity defines the level at which access is denied. The possible values of access control denial granularity are given in TABLE 12-7.

TABLE 12-7   Access Control Denial Granularity Levels 

Granularity Value	Meaning
request	Access is denied at the request level. An entire request to access one or more managed objects in the MIS is denied if access to one of the managed objects in the request is denied. The request is allowed only when all managed objects in the request are accessible.
object	Access is denied at the managed object level. Access is denied only to managed objects in the request that are not accessible. Access to the remaining managed objects in the request is allowed.
attribute	Access is denied at the attribute level. A request to access a managed object is denied if access to one or more of its attributes is denied. Access to the managed object is allowed only when all the attributes of the managed object are accessible.

To get the access control denial granularity, call the get_denial_granularity function of the ACAccessControlRules class. The get_denial_granularity function returns one of the granularity values given inTABLE 12-7.

CODE EXAMPLE 12-23 shows code for getting the access control denial granularity.

CODE EXAMPLE 12-23   Getting the Access Control Denial Granularity

... #include <acapi/accesscontrolrules.hh        // AC rules ...     ACAccessControlRules access_control_defaults; ...     ACDenialGranularity denial_gran =         access_control_defaults.get_denial_granularity(); ...

12.4.5 Getting the Access Control Domain

To get the domain that your access control rules govern, call the get_domain_identity function of the ACAccessControlRules class.

CODE EXAMPLE 12-24 shows code for getting the access control domain.

CODE EXAMPLE 12-24   Getting the Access Control Domain

... #include <acapi/accesscontrolrules.hh        // AC rules ... ACAccessControlRules access_control_defaults; ...     cout << "Access control domain is";     adjust_indentation("Access control domain is");     cout << access_control_defaults.get_domain_identity() << endl; ...

12.5 Keeping Event Notifications Private

Keeping event notifications private ensures that a user's logs contain only event notifications emitted by managed objects to which the user has access. By default, all event notifications that the Solstice EM platform receives are written to a user's logs, including event notifications from managed objects that the user is normally denied access to.

Keeping event notifications private involves:

• Assigning an owner to a log
• Enabling access control for the log server

12.5.1 Assigning an Owner to a Log

The owner of a log is the user who will read the log. Assigning an owner to a log associates the log with the managed objects to which the owner of the log has access. This association enables the log server to perform access control on event notifications. When the log server receives an event notification, the log server verifies if the owner of the log is granted access to the managed object that emitted the event notification. If the owner is granted access to the managed object, the event is logged. Otherwise, the event is not logged.

Assigning an owner to a log involves:

• Creating an auxiliary object for the log
• Verifying that the auxiliary object does not exist in the MIS
• Adding the auxiliary object to the MIS
• (Optional) Changing the owner of the log
• Storing the auxiliary object persistently in the MIS

12.5.1.1 Creating an Auxiliary Object for a Log

In the Solstice EM environment, a log is represented by an instance of the log class as defined in ITU-T X.735/ISO 10164-6 Log Control Function. This class provides no mechanism for assigning an owner to a log. Consequently, to assign an owner to a log, you must create an auxiliary object for the log. An auxiliary object contains an identifier for a log and an identifier for the owner of the log.

To create an auxiliary object for a log, create and initialize an instance of the ACDbObject class. The ACDbObject class represents a database object, such as a log, on which access control can be enforced. In the call to the constructor of ACDbObject, specify the FDN, LDN or nickname of the log.

12.5.1.2 Verifying That an Auxiliary Object Does Not Exist in the MIS

Before trying to add an auxiliary object to the MIS, verify that the auxiliary object does not already exist in the MIS. To verify that an auxiliary object does not exist in the MIS, call the exists function that the ACDbObject class inherits from the ACObject class.

12.5.1.3 Adding an Auxiliary Object to the MIS

Adding an auxiliary object for a log to the MIS enables the log server to use the auxiliary object for performing access control on event notifications. To add an auxiliary object to the MIS, call the create function that the ACDbObject class inherits from the ACObject class.

---

Note – When you add an auxiliary object to the MIS, the auxiliary object is stored only in memory, not persistently. To store the auxiliary object persistently, store it as described in Storing the Auxiliary Object Persistently in the MIS.

---

12.5.1.4 (Optional) Changing the Owner of a Log

When you create an auxiliary object for a log, the log server sets the owner of the log to the user name of the user who created the log. To change the owner of a log, call the set_auxobject_owner function of the ACDbObject class.

In the call to set_auxobject_owner, specify:

• The type of the new owner, which must be USER
• The user name of the new owner

  ---

  Note – Any user who runs a program that changes the owner of a log must have full access privileges, such as those of a system administrator.

  ---

12.5.1.5 Storing the Auxiliary Object Persistently in the MIS

After you have added an auxiliary object to the MIS, store the auxiliary object persistently in the MIS. To store an auxiliary object persistently in the MIS, call the store_auxobject function of the ACDbObject class.

12.5.1.6 Example of Assigning an Owner to a Log

CODE EXAMPLE 12-25 shows code for assigning an owner to a log.

CODE EXAMPLE 12-25   Assigning an Owner to a Log 

... #include <pmi/sched.hh>  // Scheduler for applications with no GUI #include <acapi/acdbobject.hh>  // ACDbObject class ... ACDbObject *acdbobj_ptr = new ACDbObject(logname, FALSE); if (!acdbobj_ptr->exists()) { {     if (!acdbobj_ptr->create()) {         cout<<"The auxiliary object has not been created."<<endl;         exit(1);     }     else{         cout<<"The auxiliary object has not been created."<<endl;         exit(1);     } } //Send and receive the messages. dispatch_recursive(FALSE); cout<<"Resetting the auxiliary object."<<endl; if(!acdbobj_ptr->set_auxobject_owner(USER, owner_id)) {     cout<<"Failed to reset the auxiliary object."<<endl;     exit(3); } if(!acdbobj_ptr->store_auxobject()) {     cout<<"Failed to reset the auxiliary object."<<endl;     exit(3); }

In this example, an auxiliary object for the log identified by log_name is created. The overloaded NOT (!) operator acts on the call to exists to verify that the auxiliary object does not exist. If the auxiliary object does not exist, the create function is called to add the auxiliary object to the MIS. The set_auxobject_owner is then called to change the owner of the log to the user identified by owner_id. After the owner of the log has been changed, the store_auxobject function is called to store the auxiliary object persistently in the MIS.

The initialization of the log_name and owner_id variables is not shown in this example.

12.5.2 Enabling Access Control for the Log Server

By default, the log server does not perform access control on event notifications. To enable the log server to perform access control on event notifications, set the EM_LOG_MPA_EVENT_ACCESS environment variable to TRUE. To disable access control on event notifications, set the EM_LOG_MPA_EVENT_ACCESS environment variable to FALSE. To set environment variables for Solstice EM, edit the /opt/SUNWconn/em/build/acct/EM-config configuration file.

12.6 Making MPAs Secure

Making MPAs secure protects objects that are accessed through a management protocol adapter (MPA) from unauthorized access. An MPA performs protocol translation required for communication between the Solstice EM MIS and an external entity, such as an agent. Making an MPA secure enables the MPA to enforce access control on the objects it manages.

To make an MPA secure, you use the access control engine API. Making an MPA secure involves:

• Subscribing to access control events
• Creating and initializing an instance of the ACE class
• Handling access control events
• Implementing a class derived from AuxServerUtils
• Calling access control decision and enforcement functions

For information on source code examples that show how to make an MPA secure, refer to Section A.5.2 Access Control Engine API Examples.

12.6.1 Subscribing to Access Control Events

To be able to enforce current access control policies on the objects it manages, a secure MPA must be updated with changes to access control information that is stored in the MIS. Changes to access control information in the MIS are communicated by access control events.

A secure MPA needs to receive access control events to be updated with changes to access control information. A secure MPA receives access control events only if it has subscribed to them.

Subscribing to access control events involves:

• Selecting the managed object that represents the MPA's connection to the MIS
• Setting the emSpecialEvents attribute of the managed object to accessControlEvent

For information on how to select a managed object, refer to Section 5.3 Selecting a Managed Object. To obtain the FDN of the managed object that represents an MPA's connection to the MIS, call the get_prop function of the Platform class. In the call to get_prop, specify the APPLICATION_OBJNAME property.

For information on how to set an attribute of a managed object, refer to Section 5.7 Setting Attribute Values of an Object. You have to set the emSpecialEvents attribute to the text string accessControlEvent. Therefore, call the set_str function of the Image class to set this attribute in the Image instance.

Code for subscribing to access control events is shown in CODE EXAMPLE 12-26.

CODE EXAMPLE 12-26   Subscribing to Access Control Events 

.... #include <pmi/hi.hh>                    // High Level PMI ... Platform emPlatform(duEM); ... extern Debug pdm_test_error; ... /* * Set the special events on the testmpa's application instance */ DU appl_obj = emPlatform.get_prop(duAPPLICATION_OBJNAME); Image appl_inst(appl_obj); if (!appl_inst.set_str("emSpecialEvents",             "{accessControlEvent}")) { pdm_test_error.print(         "Error in setting special events on the testmpa's                             application instance\n");     pdm_test_error.print("Reason: %s\n",                         emPlatform.get_error_string()); exit (-1); } // Store the changes if (!appl_inst.store()) {     pdm_test_error.print(         "Error in setting special events on the topo server's                             application instance\n");     pdm_test_error.print("Reason: %s\n",                             emPlatform.get_error_string()); exit (-1); }

12.6.2 Creating and Initializing an Instance of the ACE Class

Creating and initializing an instance of the ACE class provides an MPA with the services it requires to enforce access control on the objects it manages. An MPA uses an instance of the ACE class to call access control decision and enforcement functions.

An instance of the ACE class loads access control information that is stored in the MIS into an MPA. The loading of this information is done by internal callbacks. Consequently, the loading of this information is complete only when dispatch_recursive is called. If functions of any classes in the access control engine (ACE) API are called before dispatch_recursive is called, the default behavior is provided.

Create and initialize an instance of the ACE class in the main function of the MPA after the MPA has established a connection to the MIS. In the constructor of the ACE class, specify:

• The domain for which access control is to be provided
• A reference to the class that implements the AuxServerUtils class (see Section 12.6.4 Implementing a Class Derived From AuxServerUtils)

To specify the access controldomain, create and initialize an instance of the ACEDomain class and pass this instance to the constructor of the ACE class. In the constructor of ACEDomain, specify:

• The name of the security domain
• The message service access point (SAP) of the security domain

Code for creating and initializing an instance of the ACE class is shown in CODE EXAMPLE 12-27.

CODE EXAMPLE 12-27   Creating and Initializing an Instance of the ACE Class 

... #include <ace/ace.hh>        // ACE API #include "mpapdm_ace.hh"    // AuxServerUtils implementation ... ACEDomain ace_domain ("AccessControl", ev_sap); mpapdm_aux_server = new MpapdmAuxServer(); ace_ptr = new ACE(ace_domain, *mpapdm_aux_server); ...

In this example, an instance of the ACEDomain class is initialized with the domain AccessControl and the message SAP identified by ev_sap. This instance and a reference to the MpapdmAuxServer class are passed to the constructor of the ACE class. The MpapdmAuxServer class is an implementation of the AuxServerUtils class.

The initialization of the ev_sap variable is not shown in this example.

12.6.3 Processing Information in Access Control Events

Changes to access control information in the MIS are communicated to an MPA by access control events. An MPA needs to be able to process information in these events to ensure that its access control information is current.

To enable an MPA to process information in access control events, register a callback for these events. The callback is called when the MPA receives an access control event.

To register a callback for access control events, call the when function of the Platform class. In the call to when, you must:

• Specify the event type
• Initialize an instance of the Callback class to represent the callback function you want to register

The event type must be RAW_EVENT.

To initialize an instance of the Callback class, call its constructor in the call to the when function. In the call to the constructor of the Callback class, specify:

• The name of the callback function. The callback must be one of the following functions of the ACE class:
  
  
  • hi_process_ace_event to process high-level events
    
  • lo_process_ace_event to process low-level events
• A pointer to the data to be passed as an argument to the callback function. You can specify a null pointer if you do not want to pass any data to the callback function.

Code for registering a callback for access control events is shown in CODE EXAMPLE 12-28.

CODE EXAMPLE 12-28   Registering a Callback for Access Control Events 

... #include <pmi/hi.hh>                          //High Level PMI ... emPlatform.when("RAW_EVENT", Callback(ACE::hi_process_ace_event, ace_ptr)); ...

In this example, the callback function hi_process_ace_event of the ACE class is registered so that it is called when the MPA receives an event of type RAW_EVENT. The pointer ace_ptr specifies data that is passed to the function.

12.6.4 Implementing a Class Derived From AuxServerUtils

The AuxServerUtils class is an abstract that contains all of the functions that must be implemented for MPA access control. Before creating a secure MPA, you must implement a class derived from the abstract class AuxServerUtils.

An example implementation of a class derived from the AuxServerUtils class is shown in the source code example file /opt/SUNWconn/em/src/mpa_pdm/src/mpapdm_ace.cc .

12.6.5 Calling Access Control Decision and Enforcement Functions

Access control decision and enforcement functions check the access control rules. Include calls to these functions in a secure MPA whenever a managed object is accessed through the MPA.