Monitor Developer’s Guide - IBMpublib.boulder.ibm.com/tividd/td/ITPME/SC23-4790-00/en...The Tivoli...

IBM Tivoli Privacy Manager for e-business

Monitor Developer’s GuideVersion 1.1

SC23-4790-00

Note:Before using this information and the product it supports, read the information in “Notices” on page 39.

First Edition (July 2002)

This edition applies to version 1.1 of IBM Tivoli Privacy Manager for e-business (5724–C07) and to all subsequentreleases and modifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 2002. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Preface . . . . . . . . . . . . . . . vWho should read this guide . . . . . . . . . vPublications . . . . . . . . . . . . . . v

Tivoli Privacy Manager publications . . . . . vRelated publications . . . . . . . . . . vi

IBM Tivoli Access Manager for e-business . . viIBM Universal DB2® Enterprise Edition . . . viIBM WebSphere Application Server . . . . viIBM HTTP Server . . . . . . . . . . vi

Accessing publications online . . . . . . . viOrdering publications . . . . . . . . . . viProviding feedback about publications . . . . vi

Accessibility . . . . . . . . . . . . . . viiContacting customer support . . . . . . . . viiTypeface conventions . . . . . . . . . . . viiOperating system-dependent variables and paths vii

Chapter 1. Getting Started . . . . . . . 1What is a toolkit? . . . . . . . . . . . . . 1

Monitor SDK Java APIs. . . . . . . . . . 1Tivoli Privacy Manager overview . . . . . . . 1

Key concepts . . . . . . . . . . . . . 2Defining and deploying policies . . . . . . . 4

Introduction to monitors . . . . . . . . . . 5Monitor handling of user keys . . . . . . . 6Monitor handling of PII usage conditions. . . . 7

Environment requirements. . . . . . . . . . 8Installation requirements . . . . . . . . . . 8

Chapter 2. Designing a monitor . . . . 9Monitor architecture . . . . . . . . . . . . 9Monitor responsibilities . . . . . . . . . . 10

Learn the storage system . . . . . . . . . 11Identify storage system relationships . . . . 11Assign monitor-specific storage locationattributes . . . . . . . . . . . . . 11

Register monitors . . . . . . . . . . . 12Register storage locations . . . . . . . . . 13Retrieve monitor and storage locationinformation . . . . . . . . . . . . . 13Poll the server for updates . . . . . . . . 13Report submission and access activity . . . . 14Enforce privacy policy statements . . . . . . 14

Monitor placement . . . . . . . . . . . . 15Multiple part monitors . . . . . . . . . . 16

Chapter 3. Introduction to the MonitorSDK Java APIs . . . . . . . . . . . 17Objects . . . . . . . . . . . . . . . . 17

MonitorInfo . . . . . . . . . . . . . 17SLocInfo . . . . . . . . . . . . . . 17EvalRuleInfo . . . . . . . . . . . . . 18EvalResultInfo . . . . . . . . . . . . 18SKey . . . . . . . . . . . . . . . 18

Methods for communicating with the server . . . 18Helper methods . . . . . . . . . . . . . 20Exceptions. . . . . . . . . . . . . . . 20

Chapter 4. Monitor Development andTesting. . . . . . . . . . . . . . . 23Programming considerations . . . . . . . . 23

Setting up the monitor development environment 23Blueprint for monitor implementations . . . . 23

Monitor startup and initialization . . . . . 24Monitor polling . . . . . . . . . . . 25Monitoring PII submission . . . . . . . 26Monitoring PII access . . . . . . . . . 27Real-time enforcement of PII access . . . . 28Monitor shutdown and termination . . . . 29

Strategies for exception handling . . . . . . 29Support for debugging monitors . . . . . . 30

Performance considerations . . . . . . . . . 31Background execution . . . . . . . . . . 31Gathering additional information from thestorage system . . . . . . . . . . . . 32Tuning controls . . . . . . . . . . . . 32Multiple part monitors . . . . . . . . . 33

Setting up the run-time environment . . . . . . 33WebSphere J2EE Application Client setup . . . 34WebSphere Application Thin Client setup . . . 35WebSphere Application Server setup . . . . . 35

Internationalization considerations. . . . . . . 36

Appendix. Notices . . . . . . . . . . 39Trademarks . . . . . . . . . . . . . . 40

Glossary . . . . . . . . . . . . . . 43

Index . . . . . . . . . . . . . . . 47

© Copyright IBM Corp. 2002 iii

iv IBM Tivoli Privacy Manager for e-business: Monitor Developer’s Guide

Preface

The IBM® Tivoli® Privacy Manager for e-business Monitor Developer’s Guide providesinformation about developing monitors for IBM Tivoli Privacy Manager fore-business (Tivoli Privacy Manager, upon subsequent mention).

Who should read this guideThis document is written for the following:v Systems administrators who want to learn about the purpose and design of

Tivoli Privacy Manager monitors.v Systems programmers, systems integrators and independent software vendors

who want to design and implement a Tivoli Privacy Manager monitor for aspecific storage system or application.

Users need a working knowledge of the following products:v IBM Tivoli Privacy Manager for e-businessv IBM WebSphere Application Server

PublicationsThe following publications are related to the Tivoli Privacy Manager product.

Tivoli Privacy Manager publicationsMost of the product information for using Tivoli Privacy Manager, with theexception of the integrated online help is found on the following location:

http://www.tivoli.com/support/documents/

The publications for this product include the following:v IBM Tivoli Privacy Manager for e-business Release Notes.

Provides information on obtaining required fixes and APARs, and describesupdates, corrections, amendments, and workarounds for tasks and topicsdescribed in the Tivoli Privacy Manager library.

v IBM Tivoli Privacy Manager for e-business Planning Guide, SC23–4789.Provides information on planning for the installation, operation, andadministration of Tivoli Privacy Manager.

v IBM Tivoli Privacy Manager for e-business Installation Guide, SC23–4791.Provides information on installing and configuring Tivoli Privacy Manager.

v IBM Tivoli Privacy Manager for e-business Monitor Developer’s Guide, SC32–4790.Provides information about the application programming interface (API) systemprogrammers can use to create a storage system monitor.

v IBM Tivoli Privacy Manager for e-business Problem Determination Guide, SC32–4792.Provides information on diagnosing and solving problems with Tivoli PrivacyManager. Product messages are also included.

v Online user assistance for Tivoli Privacy Manager (Tivoli Assistant)Provides integrated online help topics for all Tivoli Privacy Manageradministrative tasks.

© Copyright IBM Corp. 2002 v


The Tivoli Glossary includes definitions for many of the technical terms related toTivoli software. The Tivoli Glossary is available, in English only, at the followingWeb site:

http://www.tivoli.com/support/documents/glossary/termsm03.htm

Related publicationsThe following documents also provide useful information:

IBM Tivoli Access Manager for e-businessThe documents required to support IBM Tivoli Access Manager for e-business areavailable at:


IBM Universal DB2® Enterprise EditionThe documents required to support DB2 are available at:

http://www.ibm.com/software/data/db2/library

IBM WebSphere Application ServerAccess publications for this product at:

http://www.ibm.com/software/webservers/appserv/library.html

IBM HTTP ServerAccess publications for this product at:

http://www-3.ibm.com/software/webservers/httpservers/library.html

Accessing publications onlineYou can access updated publications in the Tivoli Information Center from thefollowing Customer Support Web site:


These publications are available in PDF or HTML format, or both. Translateddocuments are also available for some products.

Note: If you print PDF documents on other than letter-sized paper, select the Fit topage check box in the Adobe Acrobat Print dialog (which is available whenyou click File --> Print ) to ensure that the full dimensions of a letter-sizedpage are printed on the paper that you are using.

Ordering publicationsYou can order publications at:http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

Providing feedback about publicationsWe are very interested in hearing about your experience with Tivoli products anddocumentation, and we welcome your suggestions for improvements. If you havecomments or suggestions about Tivoli products and documentation, send an e-mailto [email protected] or complete the customer feedback survey at the followingWeb site:

vi IBM Tivoli Privacy Manager for e-business: Monitor Developer’s Guide

http://www.tivoli.com/support/documents/glossary/termsm03.htm


http://www.ibm.com/software/data/db2

http://www.ibm.com/software/webservers/appserv/library.html

http://www-3.ibm.com/software/webservers/httpservers/library.html


http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

http://www.tivoli.com/support/survey

AccessibilityThe product documentation has been modified to include features to aidaccessibility:v Documentation is available in both HTML and convertible PDF formats to give

the maximum opportunity for users to apply screen-reader software.v All images in the documentation are provided with alternative text so that users

with vision impairments can understand the contents of the images.

Contacting customer supportIf you have a problem with any Tivoli product, you can contact IBM CustomerSupport for Tivoli products. See the Tivoli Customer Support Handbook at thefollowing Web site:

http://www.tivoli.com/support/handbook

The handbook provides information about how to contact Customer Support,depending on the severity of your problem, as well as the following information:v Registration and eligibilityv Telephone numbers and e-mail addresses, depending on the country in which

you are locatedv The information you should gather before contacting support

Typeface conventionsThe following typeface conventions are used in this book:

Bold Lowercase and mixed-case commands, command options, andflags that appear within text appear like this, in bold type.

Graphical user interface elements (except for titles of windows anddialogs) and names of keys also appear like this, in bold type.

Italic Variables, values you must provide, new terms, and words andphrases that are emphasized appear like this, in italic type.

Monospace Commands, command options, and flags that appear on a separateline, code examples, output, and message text appear like this, inmonospace type.

Names of files and directories, text strings you must type, whenthey appear within text, names of Java™ methods and classes, andHTML and XML tags also appear like this, in monospace type.

Operating system-dependent variables and pathsThis book uses the UNIX® convention for specifying environment variables and fordirectory notation.

When using the Windows® command line, replace $variable with %variable% forenvironment variables and replace each forward slash (/) with a backslash (\) indirectory paths.

Preface vii

http://www.tivoli.com/support/survey

http://www.tivoli.com/support/handbook

Note: If you are using the bash shell on a Windows system, you can use the UNIXconventions.

viii IBM Tivoli Privacy Manager for e-business: Monitor Developer’s Guide

Chapter 1. Getting Started

Tivoli Privacy Manager is used to define privacy policies and to monitor access toinformation governed by those policies. The IBM Tivoli Privacy Manager fore-business Monitor Developer’s Guide describes the fundamental design principles ofTivoli Privacy Manager monitors, defines the Java application programminginterfaces (APIs) used by those monitors to communicate with the Tivoli PrivacyManager server, and introduces the tools and resources that are available to assistsoftware developers in the development of monitors.

This chapter contains the following sections:v “What is a toolkit?”v “Tivoli Privacy Manager overview”v “Introduction to monitors” on page 5v “Environment requirements” on page 8v “Installation requirements” on page 8

What is a toolkit?A developers toolkit is a set of software routines and utilities used to helpprogrammers write an application. The Tivoli Privacy Manager Monitor SoftwareDeveloper’s Toolkit (Monitor SDK, upon subsequent mention) contains:v The IBM Tivoli Privacy Manager for e-business Monitor Developer’s Guide

v The Monitor SDK Java APIs needed to develop and compile a new monitorimplementation, packaged in a Java Archive (JAR) file

v The Javadoc, which contains detailed information about the Monitor SDK JavaAPIs

v A WebSphere Enterprise Archive (EAR) file, which contains the Monitor SDKruntime support

Monitor SDK Java APIsThe Monitor SDK Java APIs consist of a set of classes used by monitors to interactwith the Tivoli Privacy Manager server. A software developer can use these classesto implement new monitors without having to understand the protocols tocommunicate with the Tivoli Privacy Manager server.

The Java APIs provide methods that are used to register a monitor with the TivoliPrivacy Manager server, to retrieve storage location classification information fromthe Tivoli Privacy Manager server, and to send notifications to the Tivoli PrivacyManager server when personally identifiable information (PII) is accessed or changedwithin a monitored storage system.

For additional information about the Monitor SDK Java APIs, see Chapter 3,“Introduction to the Monitor SDK Java APIs” on page 17.

Tivoli Privacy Manager overviewThe Tivoli Privacy Manager environment consists of the Tivoli Privacy Managerserver and one or more monitors.

© Copyright IBM Corp. 2002 1

The Tivoli Privacy Manager server is an enterprise application built fromEnterprise Java Beans™ (EJBs), Java Server Pages (JSPs), and servlets. The TivoliPrivacy Manager server runs inside an IBM WebSphere Application Server (WAS)Java 2 Enterprise Edition (J2EE) container. The server maintains a DB2 databasethat contains information related to privacy policies, monitors and their storagelocations, and audit logs that record the submission and access of PII in themonitored storage systems.

Tivoli Privacy Manager monitors run inside WebSphere Application Client J2EEcontainers. They monitor the submission and access of PII and report this activityto the Tivoli Privacy Manager server for auditing and conformance checkingpurposes. The monitors use the Monitor SDK Java APIs to interact with the TivoliPrivacy Manager server. Figure 1 illustrates the relationship between the TivoliPrivacy Manager server, a Tivoli Privacy Manager monitor, and a monitoredstorage system.

Key conceptsOne key goal of Tivoli Privacy Manager is to assist organizations with themonitoring and auditing of privacy sensitive information. This information can becollected from a number of persons, including customers and employees. Thefollowing key concepts should be considered before designing a monitor.

Personally identifiable informationPersonally identifiable information (PII) refers to personal data that anindividual provides to an organization for some business purpose. Data isconsidered PII if it is specifically associated with an individual, if it wasdisclosed by the individual to the organization and persistently stored forfuture use, and if the individual who submitted the data has an interest,either directly expressed or by legal right, in limiting the propagation ofthe data within the organization or to other organizations or individuals.

Figure 1. Interaction between the Tivoli Privacy Manager server and the monitor.

2 IBM Tivoli Privacy Manager for e-business: Monitor Developer’s Guide

Storage systemA storage system is a data repository that collects and stores PII for futureuse. Storage systems can either be physical repositories, such as a databaseor directory, or they can be abstract, such as an application that controlsaccess to collected data. A storage system typically maintains differenttypes of data in a logical arrangement. For example, directories keepinformation in attributes of directory object classes and databases arrangeinformation in tables of rows and columns.

Storage locationA storage location is a named place within a storage system that can holda piece of information. For example, a storage location for a directorymight represent one attribute of an object class, and a storage location for adatabase might represent one column of a table. Sometimes a storagelocation can represent information that is not stored the same way as otherinformation in the storage system. For example, a storage location mightrepresent the distinguished name (DN) of a directory object, even thoughno attribute of an object class exists that holds the DN of the directoryentry.

Storage keyInformation is considered privacy sensitive only if it can be associated withan individual, so when PII is accessed, it is necessary to know who ownsthe PII. If PII is accessed and the owner of the PII cannot be determined,the access is considered de-identified and is not privacy sensitive. Storagekeys are storage locations used by Tivoli Privacy Manager to makeassociations between other storage locations in the storage system. Forexample, the primary key of a database table identifies a row in the tableand acts as the association between all of the storage locations in that rowof the table. A user key is a storage key that identifies the owner of PII inthe storage system; that is, it associates specific instances of PII in thestorage system with the owner of the PII. Some user keys are known to theorganization collecting the information (such as a customer or patientnumber), while other user keys are known to the specific person who ownsthe information. User keys that are known to the PII owner are called useridentifiers (user IDs). All user IDs are user keys and all user keys arestorage keys.

Privacy Manager defines one other type of storage key called a master key.The master key is a user key that can be mapped to any other user key orto the value of any storage location associated with an individual. Foradditional information about the purpose and use of the master key, see“Monitor handling of user keys” on page 6.

PII Submission and accessMonitors notify the Tivoli Privacy Manager server when they detectactivity in the monitored storage system that might be privacy sensitive. APII submission notification is sent when PII is submitted or changed in thestorage system to enable the Tivoli Privacy Manager server to determinethe privacy policies that are currently in effect. If a person submits PII, thisimplies that the person consents to the privacy policy that currentlygoverns the usage of the PII. A PII access notification is sent to the TivoliPrivacy Manager server when PII is accessed so the server can keep anaudit trail of PII usage. In addition, monitors that support real-timeenforcement of privacy policies can request a PII conformance check from theTivoli Privacy Manager server to determine if a particular PII accessattempt is compliant with the governing privacy policies.

Chapter 1. Getting Started 3

When a monitor sends PII submission and access notifications or performsa real-time policy conformance check, it sends the Tivoli Privacy Managerserver a list of the PII storage locations that were involved along with oneor more user keys that identify the owner of the PII. Tivoli PrivacyManager assumes that the person submitting PII is the PII owner, but theperson accessing PII might not be the PII owner. The accessor is an entity,either a person or an application, that requests access to PII. For example,an accessor might be a physician requesting access to a patient’s medicalhistory or an application designed to send mass e-mail messages to usersthat have subscribed to an internet news service.

Monitors provide the Tivoli Privacy Manager with a list of accessorattributes to identify who is accessing PII and for what purpose. Eachaccessor attribute is a key/value pair, and the list of supported attributekeys is defined by the monitor implementation. The list of supportedattribute keys is based on the type of accessor information that is availableto the monitor when the PII is accessed. For example, a database monitorcan define the attribute key DataBaseUser, because it knows the databaseuser who is requesting information from the database.

ConditionsSometimes an organization must restrict PII usage by certain accessors andfor certain purposes, either because a privacy policy does not allow accessto the information or because the law prohibits access to the information.For example, an organization can decide that an individual’s e-mailaddress only be used for marketing purposes if the individual requests(opts in) marketing materials.

Conditions are defined at the Tivoli Privacy Manager server during privacypolicy creation, and monitors obtain instructions for evaluating theconditions during privacy policy deployment. Monitor implementations arerequired to evaluate the conditions defined for PII storage locations and toprovide the results of these evaluations on PII submission notifications, PIIaccess notifications and real-time conformance check requests. Foradditional information about evaluating conditions, see “Monitor handlingof PII usage conditions” on page 7.

Defining and deploying policiesAfter an administrator installs Tivoli Privacy Manager, the administrator uses aWeb-based graphical user interface (GUI) to define privacy policies that reflect anorganization’s PII usage practices. Each policy must contain at least one statement,and each statement contains PII types, groups, and purposes. A statement canoptionally contain conditional information that limits the use of PII. Refer to“Monitor handling of PII usage conditions” on page 7 for additional information.

When a policy is being defined, it is considered to be in draft state. After theadministrator defines the policy, the policy must be changed to published state.Publishing a policy implies that the information contained in the policy is finalizedand the policy is ready to be deployed.

Before you can deploy the policy, Tivoli Privacy Manager must know whichstorage locations exist for the storage system. When a monitor first starts up, themonitor should query the monitored storage system and build a list of storagelocations from the information contained in the system.

After the monitor builds a list of storage locations, the monitor must register itselfand the list of storage locations with the Tivoli Privacy Manager server. When a


monitor and its storage locations are registered with the Tivoli Privacy Managerserver, the administrator can begin deploying the policy.

To deploy a policy, the administrator must identify which storage locations in thestorage system contain PII and which storage locations are user keys and user IDs.This process is called storage location classification. Storage location classificationinformation enables a monitor to determine which storage locations contain PIIand therefore are subject to monitoring.

If a storage location is classified as a PII storage location, the administrator canassign PII types from a privacy policy to the storage location. When theadministrator assigns a PII type to the storage location, the information containedin the storage location is governed by the privacy policy statement that containsthe PII type. For privacy policy statements that have conditional information,evaluation rules must be defined. The evaluation rules are used to evaluateconditions to ensure adherence to a policy.

The the length of time needed to deploy a policy to a monitored storage systemcan vary depending on the complexity of the system and the privacy policy. Whilea policy is being deployed, the monitor remains in Not deployed state and pollsthe server for updates to its status.

After the administrator completes the policy deployment process, which includeschanging the state of the policy from published to deployed, the monitor state canbe changed from Not deployed to In test or Deployed (depending on whether themonitor is being tested or deployed). On the next polling operation, the monitordetects that its status has been changed and retrieves the complete set of storagelocation classification information from the Tivoli Privacy Manager server.

The monitor is ready to begin monitoring the storage system for submissions andaccesses of PII. When PII submission or PII access activity is detected, the monitormust send submission and access notifications to the Tivoli Privacy Managerserver.

The process for defining privacy policies, deploying the policies, and monitoringaccess to data governed by the policies is a cooperative effort that requiresinformation from both the monitor (list of storage locations) and the Tivoli PrivacyManager administrator (storage location classification and conditional information).

Introduction to monitorsAlthough storage systems (such as databases, directories, or applications withproprietary data repositories) are designed with different operating characteristics,they all perform the same function: they store data that must be retrieved andupdated. When the stored data being retrieved or updated is privacy sensitive,monitors can be used to observe submission and access activity and to report thisactivity.

Tivoli Privacy Manager monitors observe data going into and out of a monitoredstorage system. They act as a bridge between the monitored storage system andthe Tivoli Privacy Manager server. The Tivoli Privacy Manager server defines acommon model for the monitors and provides a set of Java APIs that are used bythe monitors to interact with the Tivoli Privacy Manager server. Thus, the TivoliPrivacy Manager server can support different monitor implementations for a widevariety of storage systems.


While monitor implementations can vary, there are certain responsibilities thatmust be carried out by all monitors regardless of the implementation. In general,monitors are responsible for registering with the Tivoli Privacy Manager server, forregistering all storage locations with the Tivoli Privacy Manager server, and fornotifying the Tivoli Privacy Manager server when storage locations that contain PIIare accessed or changed in the storage system. For detailed information about theresponsibilities of a monitor, see “Monitor responsibilities” on page 10.

Monitor handling of user keysWhen PII is accessed or changed, the monitor sends a list of the storage locationsaccessed to the Tivoli Privacy Manager server along with one or more user keys.User keys are used to identify the person whose PII is involved in the activitybeing monitored. Monitors are required to supply one or more user keys for everyPII submission notification, PII access notification, or PII conformance checkrequest.

A storage system is likely to contain many user keys for an individual, and any ofthe user keys can be used to identify the individual. However, not all PIIsubmissions or accesses use the same user key. For example, one database querymight return an individual’s salary and full name, while another query mightreturn the individual’s home address and telephone number. In this case, differenttypes of PII (salary and home address) are accessed with different user keys (fullname and telephone number, respectively). If only the user keys associated withthe activity are recorded in the Tivoli Privacy Manager audit logs, it is difficult toget a complete report of all PII access. The person requesting the report wouldneed to know the values of all user keys associated with the individual to find allof the audit records for that individual.

Ideally, a monitor’s interaction with its storage system should allow the monitor tomap user keys for an individual to other user keys for that same individual. Forexample, a monitor should be able to query its storage system to obtain anindividual’s telephone number given the individual’s full name. But mapping anyuser key to any other user key might be difficult to implement in some storagesystems.

To simplify user key mapping, Tivoli Privacy Manager uses the concept of a masterkey. A master key is a user key that can be used to obtain any other user key (orthe value of any other storage location) for an individual. It should be possible toobtain an individual’s master key given any other user key for that individual.With a master key, a monitor does not need to map all user keys for an individualto each other. Instead, the monitor can map a user key to the master key and thenmap the master key to any other user key.

Tivoli Privacy Manager does not require monitors to support a master key, becauseall monitors or storage systems might not be able to implement a master key. If amonitor does not support master keys, the monitor should send all user keys thatwere involved in the submission or access operation to the Tivoli Privacy Managerserver when it reports submission and access activity. If a monitor supports masterkeys, the monitor must send the master key and all other user keys involved in thesubmission or access, which might require the monitor to request the master keyfrom the storage system using one of the other user keys involved in the operation.

The advantage of supporting a master key is evident when individual accessreports are generated. If an administrator wants to generate a report that shows allthe times an individual’s PII was accessed, the administrator must first know one


or more user keys for the individual. For monitors that do not support a masterkey, the administrator must know every user key for the individual to include allPII accesses in the report. However, if the monitor supports a master key, theadministrator needs to know a single user key for the individual. Theadministrator can map the user key to the individual’s master key and run thereport using the master key to find all accesses for the individual.

The drawback to supporting a master key is that the monitor might need toperform additional queries against the storage system for every data submission oraccess to obtain the master key. This might have an impact on performance.

Some monitor implementations might require that a specific storage location beclassified as the master key, whereas other monitor implementations might allowthe Tivoli Privacy Manager administrator to select the storage location that acts asthe master key. A monitor cannot programmatically define which storage locationis the master key. If a monitor implementation requires that a specific storagelocation be identified as the master key, the documentation for the monitor mustidentify which storage location must be the master key.

Monitor handling of PII usage conditionsPII usage can be limited based on conditions that are either defined by law or bythe organization collecting the PII. For example, if a law states that an individual’semployer information cannot be used to determine loan eligibility if the individuallives in a certain state or country, a policy that governs the employer informationmight contain a condition that prohibits use of the information for that purpose.Use of PII can also be limited based on a person’s choice to opt in or opt out withregard to use of the PII. For example, an organization can allow its customers toopt out with regard to use of their PII for telemarketing purposes. If the customerdoes not choose to opt out, PII can be used for telemarketing, but if the customerchooses to opt out, the PII cannot be used for telemarketing.

The conditions for data usage are part of the contract between the individual andthe organization regarding use of the individual’s PII. As a result, the conditionsmust be considered during privacy policy conformance checks. Using theinformation maintained in the storage system, administrators can use the TivoliPrivacy Manager GUI to define the conditions for various types of PII and todefine how these conditions are evaluated by monitors.

A storage location assigned to a certain PII type can be subject to one or moreconditions, and to evaluate those conditions, it might be necessary to accessinformation in other storage locations, such as the individual’s opt in or opt outchoice or the individual’s state or country of residence. (Retrieving the values ofother storage locations is similar to retrieving the master key for an individual, asdescribed in “Monitor handling of user keys” on page 6.) Monitors must evaluateconditions each time information is submitted or accessed for a PII storage locationso the conditions defined for the storage location are known and recorded with thePII submission or access.

The results of the evaluations must be sent to the Tivoli Privacy Manager serverwith each PII submission and access notification. Because the storage locationsthemselves can be privacy sensitive, the results of the evaluations are sent to theTivoli Privacy Manager server instead of the actual values of the storage locationsused in the evaluation process.


Because the evaluation of conditions might involve any storage location in themonitored storage system, the monitor must be able to retrieve the value of anystorage location for a particular individual, given one or more user keys for thatindividual. While this is a simple task for some monitors, it is more complex forother monitors, such as database monitors that have storage locations spreadacross several interrelated tables. For monitors that support a master key, this taskcan be simplified by assuming that the master key is always used to retrieveconditional information, as opposed to an arbitrary user key.

Environment requirementsTivoli Privacy Manager monitors use the Monitor SDK Java APIs to communicatewith the Tivoli Privacy Manager server. Therefore, monitor source code must becompiled against the Monitor SDK Java API classes during the development of anew monitor implementation. The classes needed at compile time are packaged ina JAR file. The JAR file can be installed on the development machine using theTivoli Privacy Manager installation procedure. Monitor development requires Java1.3 or a later version.

Testing a new monitor implementation requires a fully functional Tivoli PrivacyManager server environment and the setup of the monitor runtime environment.The monitor run-time environment requires the installation of either theWebSphere Application Server or a WebSphere client environment, depending onthe design and implementation of the monitor. Several different runtimeconfigurations are supported, and the setup requirements for each configurationare different. For detailed information about the monitor runtime environment, see“Setting up the run-time environment” on page 33.

Installation requirementsThe Monitor SDK can be installed on the same machine as the Tivoli PrivacyManager server or on a different machine. For information about the Tivoli PrivacyManager installation procedure for the Monitor SDK, see the IBM Tivoli PrivacyManager for e-business Installation Guide.


Chapter 2. Designing a monitor

Each monitor is designed specifically for the storage system being monitored. Thestorage system might be a database, a directory, or an application that controlsaccess to its own proprietary data repository. A monitor acts as the bridge betweenthe storage system and the Tivoli Privacy Manager server.

This chapter describes how to design a new monitor implementation and focuseson the architecture and responsibilities of monitors. The chapter contains thefollowing sections:v “Monitor architecture”v “Monitor responsibilities” on page 10v “Monitor placement” on page 15v “Multiple part monitors” on page 16

Monitor architectureA monitor can be conceptually divided into three components: storage systemadapter, monitor implementation, and privacy server adapter.

The first component of the monitor is the storage system adapter. The storage systemadapter is specific to the storage system being monitored, and it detects when datais submitted or accessed in the storage system. The storage system adapter acts asa bridge between the storage system and the monitor implementation.

The second component of the monitor is the monitor implementation. The monitorimplementation uses information maintained on the Tivoli Privacy Manager serverand information from the storage system to perform privacy monitoring functions.

The interface between the storage system adapter and the monitor implementationis called the storage system interface. The storage system interface is bi-directional;that is, it defines the ways the storage system adapter conveys information to themonitor implementation and also defines the way the monitor implementationrequests information from the storage system adapter. This interface might only bea logical interface because some monitor designs can blur the line between thestorage system adapter and the monitor implementation.

TivoliPrivacy Manager

server

Monitor statusStorage location classificationStorage key definitions

Privacyserver

adapter

Storagesystemadapter

Monitor implementation

Monitoredstoragesystem

Privacy serverinterface

Storage systeminterface

Figure 2. Monitor component architecture


The storage system adapter uses the storage system interface to notify the monitorimplementation when data in the storage system is accessed or updated. For eachnotification, the storage system adapter provides information about the affecteddata to the monitor implementation. The monitor maps this information to its listof storage locations to determine if any of the data is PII and therefore subject tomonitoring. The storage system adapter must provide the monitor implementationwith the values of the affected data items in order for the monitor to use thevalues of storage key locations to identify the individual whose PII was accessedor updated. The storage system adapter does not contain logic that requiresinformation about storage location classification; it is simply a thin layer thatcommunicates storage system activity to the monitor implementation.

The monitor implementation receives notifications from the storage system adapter,determines whether or not PII was accessed or updated, and then notifies theTivoli Privacy Manager server. The monitor implementation might requireadditional information from the storage system when it builds the notificationmessages. For example, the monitor might need the value of the master keystorage location for the individual, or the monitor might need to obtain the valuesof other storage locations to evaluate conditions for one or more of the affected PIIstorage locations. In either case, the monitor implementation uses the storagesystem interface to request additional information, and must provide the value ofone or more user keys to identify the individual whose information is beingaccessed or updated. The monitor implementation also uses the storage systeminterface during monitor startup to retrieve the list of data fields in the storagesystem that are used to build the list of storage locations.

The third component of the monitor is the privacy server adapter. The privacy serveradapter implements the protocols and flows used by the monitor to communicatewith the Tivoli Privacy Manager server. The interface between the privacy serveradapter and the monitor implementation is the privacy server interface. The monitorimplementation uses the privacy server interface in all communications with theTivoli Privacy Manager server, including monitor and storage location registration,polling, submission and access notifications, and real-time conformance checking.(The privacy server interface is abstracted from the underlying EJB protocols, sothat monitors do not have to handle the complexities of using EJBs.) The TivoliPrivacy Manager Monitor SDK Java APIs provide the implementation of theprivacy server adapter and define the privacy server interface.

Monitor responsibilitiesEach monitor implementation is specific to a particular storage system. A monitoris written based on the design and operational characteristics of the storage systemand presents a view of the storage system to the Tivoli Privacy Manager server.The monitor performs the following functions:v “Learn the storage system” on page 11v “Register monitors” on page 12v “Register storage locations” on page 13v “Retrieve monitor and storage location information” on page 13v “Poll the server for updates” on page 13v “Report submission and access activity” on page 14v “Enforce privacy policy statements” on page 14


Learn the storage systemEach monitor must identify the list of storage locations within the storage system.A storage location is a location within the storage system where data can be stored,such as a column in a database table or an attribute of a directory object, or astorage location can be abstract. For example, an abstract storage location might bedefined to represent the parent-child relationship between two directory objectswhen no explicit object attribute is defined for this purpose.

A monitor derives a list of storage locations in various ways depending on thestorage system. The monitor should be able to create a list of storage locationsfrom the storage system definition information (database schema or directoryschema). If not, the monitor implementation might require that a list of storagelocations be built manually and that this list be made available to the monitor atrun time.

A monitor must provide a unique name for each storage location. The namingconvention should reflect the logical arrangement of the storage locations withinthe storage system. Below are two examples of naming conventions for storagelocations.v A database monitor can use the form Database.Schema.Table.Column to name

storage locations based on the organization of the data in the database.v A directory monitor can use the form ObjectClass.Attribute to name storage

locations based on the arrangement of attributes in directory objects.

The monitor must be able to detect changes in the storage system that result in achange in the list of storage locations, such as when storage locations are added orremoved. The monitor is responsible for notifying the Tivoli Privacy Managerserver when changes occur. The following sections contain information to considerwhen creating a list of storage locations.

Identify storage system relationshipsA monitor must be able to determine the relationship between storage locations tofind related information in a storage system. For example, a database monitorshould be able to determine which storage locations are primary keys, indexedfields that maintain the primary sequence of the table, and which storage locationsare foreign keys, fields in one table that are indexed in another table. A directorymonitor should be implemented to detect the parent-child relationship betweendirectory objects and might need to determine which attributes of directory objectsare DN pointers to other directory objects. If the implementation of a monitorrequires knowledge of these relationships, the monitor must be able to derive themfrom the storage system definition information (schema), or the information mustbe provided to the monitor using an alternate method.

Assign monitor-specific storage location attributesAttributes are assigned to storage locations to assist the monitor with managingthem. Each attribute consists of a key/value pair. The set of attributes assigned tostorage locations by monitors is based on each individual monitor implementation.Attributes are assigned to storage locations when they are registered with theTivoli Privacy Manager server. The registered attributes are then provided to themonitor when it subsequently retrieves the storage locations from the TivoliPrivacy Manager server.

The following examples indicate how attributes can play a significant role in thedesign of a monitor:

Chapter 2. Designing a monitor 11

Storage location descriptionMonitors that have access to text descriptions of storage locations (forexample, from the storage system schema) should set the DESCRIPTIONattribute of the storage location to the text description. The Tivoli PrivacyManager server uses the value of this attribute, if it exists, as a hint for thestorage location, and can display this hint in the GUIs.

Storage location aliasesIn some storage systems, the same information can be accessed in differentways. For example, database information can be accessed by table/column.If specialized views are constructed, the same information can be accessedby view/column, as well as by stored procedures, which hide the actualdatabase schema implementation. LDAP directories permit access toattributes based on the attribute name such as organizationUnit or anabbreviation, such as OU. Storage location attributes can be used to list allof the aliases that refer to a particular storage location.

Primary key indicatorA monitor can use an attribute to indicate which storage locations areprimary keys.

Foreign key informationA monitor can use an attribute to indicate which storage locations areforeign keys and to indicate the storage location of the foreign keyreferences.

Storage location record namesMonitors might need to understand the arrangement of storage locationswithin the storage system, such as storage locations in the same databasetable or storage locations that are attributes of the same directory object.While the monitor’s storage location naming scheme might reflect thisarrangement of storage locations, using a storage location attribute, such asRECORD_NAME, could prevent the monitor from having to performrepeated parsing of storage location names.

Sharing information among monitor partsIf a monitor is designed with multiple parts, as described in “Multiple partmonitors” on page 16, storage location attributes can be used to shareinformation among the monitor parts. That is, the monitor part thatregisters the storage locations with the Tivoli Privacy Manager server canrecord the storage location attributes for the storage locations to make theattributes available to the other monitor parts when those monitor partsretrieve updated storage location information from the server. In this way,the multiple part monitor can use the Tivoli Privacy Manager server as adata store for storage location information so that all monitor parts areusing consistent storage location information.

Register monitorsAll monitors must register with the Tivoli Privacy Manager server. When amonitor registers with the server, it must:v Provide a unique name for the monitor.v Define the type of information the monitor can provide to identify the PII

accessor in the monitored storage system. This accessor information is providedas a list of one or more attribute names. For example, a database monitor mightdefine DataBaseUser, because an individual accessing information in thedatabase is required to provide a database user ID. Accessor attribute names are


specific to the monitor that registers them. Each monitor must register the set ofattribute names to be used by that monitor.

v Specify whether or not the monitor supports real-time policy enforcement.v Provide monitor attributes in the form of key/value pairs. These attributes are

for the sole use of the monitor.

Register storage locationsAfter a monitor registers with the Tivoli Privacy Manager server, it must alsoregister the list of storage locations in the storage system with the server. Themonitor must provide the following information for each storage location itregisters:v A unique name for the storage locationv A set of zero or more monitor-specific storage location attributes

Retrieve monitor and storage location informationAfter a monitor registers itself and its storage locations with the Tivoli PrivacyManager server, an administrator uses the Tivoli Privacy Manager server GUIs toadd information to the monitor and storage location definitions. For example, theadministrator performs the following tasks:v Defines the polling interval for the monitorv Identifies which storage locations contain PII and the type of PII contained in

the storage locationv Identifies which storage locations contain user keys and user IDs.v Defines the conditional information associated with storage locations and how to

evaluate it (for example, opt in or opt out choices)v Changes the monitor’s deployment status (for example, to activate a monitor)v Enables or disables real-time enforcement checking

In other words, the information provided by the monitor during the registrationprocess is only a subset of the total information maintained for the monitor and itsstorage locations. The monitor does not supply any policy-related information. Thisinformation is provided by the administrator after the initial registration process,and some of this information is required by the monitor. Therefore, a monitor mustbe able to retrieve monitor and storage location information from the TivoliPrivacy Manager server. This information should be retrieved during monitorstartup and might need to be updated while the monitor is running based on theresult of the monitor polling function.

Poll the server for updatesThe monitor and storage location information retrieved from the Tivoli PrivacyManager server should be refreshed continuously. Monitors are responsible forpolling the Tivoli Privacy Manager server for changes to this information.

The polling interval used by the monitor is configured by the Tivoli PrivacyManager server administrator. The Tivoli Privacy Manager graphical user interfaceallows an administrator to define monitor properties, such as the polling interval,for each monitor. The interval is stored along with other monitor properties, suchas name, description, and deployment status.


Report submission and access activityThe main purpose of monitors is to detect the submission of new or updated PII tothe storage system and the access to PII in the storage system and to report theseactivities to the Tivoli Privacy Manager server for recording.

For submission activity, the monitor detects the storage locations that aresubmitted and determines which ones contain PII. If any of the submitted storagelocations contain PII, the monitor notifies the Tivoli Privacy Manager server of thesubmission (typically on a different thread of execution, so as to not cause asignificant delay in the submission request), passing it:v A list of all the PII storage locations submittedv A list of user keys. The list must include all of the user keys available with the

submitted storage locations, and might also include additional user keysobtained by the monitor.

v A list of the evaluation results for the conditional information associated witheach storage location to assist the Tivoli Privacy Manager server in determiningthe context states at the time the PII was submitted.

v A timestamp representing the date and time of the submission. The timestampmust be expressed in coordinated universal time (UTC).

For access activity, the monitor detects the storage locations that were accessed anddetermines which of the storage locations contain PII. If any of the accessedstorage locations contain PII, the monitor notifies the Tivoli Privacy Managerserver of the access (typically on a different thread of execution, so as to not causea significant delay in the access request), passing it the same information that isprovided for submission activity. The monitor also provides information to helpidentify the PII accessor. This PII accessor information is in the form of a list ofattribute name/value pairs, where the attribute names are the accessor attributesdefined by the monitor during monitor registration.

Enforce privacy policy statementsThe Tivoli Privacy Manager server is designed to support two modes ofmonitoring storage systems: audit and enforcement. For the audit mode, monitorsnotify the server each time PII is accessed or changed in the storage system, whichallows the server to maintain an audit trail of PII activity and to track whether ornot each PII access is in conformance with the governing privacy policies. For theenforcement mode, monitors use the server to enforce privacy policies byrequesting real-time conformance checks each time PII is accessed and by denyingaccess to PII that is not in conformance with governing privacy policies.

All monitor implementations are required to support the audit mode ofmonitoring, but Tivoli Privacy Manager does not require monitor implementationsto support the enforcement mode. The enforcement mode requires a more complexmonitor implementation and might have a significant impact on the performanceof applications using the storage system because each access to PII causes themonitor to request a policy conformance check from the Tivoli Privacy Managerserver before information is returned to the application. Because of the potentialperformance impact associated with the enforcement mode of monitoring, TivoliPrivacy Manager allows an administrator to turn off real-time enforcement for anymonitor. Therefore, if a monitor implementation supports real-time enforcementmode, the monitor must be able to run in audit mode if it is configured to do soby the administrator of the Tivoli Privacy Manager server.


When a monitor runs in real-time enforcement mode, it detects when storagelocations are accessed in the storage system and determines which ones containPII. If any of the accessed storage locations contain PII, the monitor suspends theaccess request while it consults with the Tivoli Privacy Manager server todetermine if the access is in conformance with the organization’s privacy policy.The information passed to the Tivoli Privacy Manager server on this conformancecheck request is the same as that provided for PII access activity, but the resultreturned from the server indicates whether or not the access conforms with theprivacy policy. If the access request conforms with the policy, the monitor allowsthe access request to complete. If the access request is not in conformance with thepolicy, the monitor must either deny the access request or it must change theinformation returned as a result of the access request to omit information thatshould not be accessed.

Monitor placementDifferent storage systems can require different monitor implementations. Duringthe initial design phase of a new monitor implementation, careful considerationshould be given to the placement of the monitor with respect to its monitoredstorage system and to the applications accessing the storage system. There areseveral different monitoring strategies that can be used, and each one hasadvantages and drawbacks.

The first strategy is to perform monitoring near the storage system, where themonitor cooperates with or acts as an extension of the monitored storage system,as opposed to acting as an extension of the application that accesses the storagesystem. Monitors that use this strategy can be divided into two categories: thosethat are between the application and the storage system and those that are behindthe storage system. For example, a monitor designed as a proxy server to monitortraffic should be between the applications and the storage system, but a monitordesigned as a database extension should be behind the database and is notified bythe database each time information is accessed or changed. Monitors that are nearthe storage system can be completely transparent to the applications that are usingthe storage system, which is an advantage because the applications do not requiremodification to be enabled for privacy monitoring. The drawback is that closeintegration between the monitor and the storage system might be limiting to themonitor. For example, the only information that can be used by the monitor toidentify a PII accessor is probably the credentials used for access, which can bestorage system specific.

The second strategy is to perform monitoring near the application. Monitors thatfollow this design might require that the application be changed to enable privacymonitoring. For example, a monitor implemented as a JDBC driver implementationmight require the application to be configured to use the monitor JDBC driver butdoes not require additional application changes. This approach is similar to thefirst strategy, in which the monitor resides on the data access path between theapplication and the storage system. On the other hand, a monitor designed as anapplication add-on might require that the application be changed to call out to themonitor when it accesses privacy-sensitive information. Although this might seeminvasive to the application, there are significant advantages to this approach.Because the application maintains the most information about who is accessing PIIand why PII is being accessed, it can provide the monitor with comprehensiveaccessor information.

The third strategy is to perform monitoring at the business process layer. Thisstrategy requires a company to have a well-defined business process model, and to


implement a monitor that resides within or between the business process steps.Because the business process usually defines the type of information that flowsbetween the steps of the business process, it can be simple for a monitor todetermine what information is being accessed. The business processes themselvescan define the intended use of the information.The drawback to this approach isthat monitors of this design most likely require changes to the business processinfrastructure and work flow tools.

Multiple part monitorsA monitor can be developed to function as a single process that performs allmonitor tasks on one machine or it can be developed in parts with the monitorresponsibilities performed on different machines in the environment. For example,one monitor part can run near the storage system itself and monitor thesubmission of new information, while another monitor part runs near theapplication using the storage system and monitors information accessed by theapplication. The monitor parts are two distinct parts of the same monitor, witheach monitor part providing a portion of the overall monitor functionality.

Multiple part monitors are implemented by configuring all monitor parts to usethe same name monitor name. When a monitor is comprised of multiple monitorparts, some monitor responsibilities must be implemented by each part and somecan be divided among the different parts.

The following monitor responsibilities must be implemented by each monitor part:v Retrieving information from the Tivoli Privacy Manager serverv Polling the Tivoli Privacy Manager server for updates to monitor and storage

location information

The following monitor responsibilities must be implemented by the same monitorpart:v Enumerating and naming the storage locationsv Identifying the relationships between the storage locationsv Assigning monitor-specific attributes to storage locationsv Registering the monitor and its storage locations with the Tivoli Privacy

Manager server

The following monitor responsibilities can be divided among the different monitorparts:v Reporting submission information to the Tivoli Privacy Manager serverv Reporting access information to the Tivoli Privacy Manager server

For detailed information about monitor responsibilities, see “Monitorresponsibilities” on page 10.


Chapter 3. Introduction to the Monitor SDK Java APIs

The Monitor SDK Java APIs are a set of Java classes used by monitorimplementations to communicate with the Tivoli Privacy Manager server. Thischapter contains a brief introduction to the Java APIs. For detailed informationabout using the Java APIs, see the Javadoc located in the sdk_install/javadocdirectory, where sdk_install is the directory where the Monitor SDK is installed.

The Monitor SDK Java APIs consist of the following:v Objects used as parameters that are passed between the monitor and the Tivoli

Privacy Manager serverv Methods invoked by the monitor to perform basic operations on the Tivoli

Privacy Manager serverv Helper methods that assist in the creation of the parameter objectsv Exception classes used to reflect error conditions to the monitor

ObjectsThe following Monitor SDK objects are used as parameters between the monitorand the Tivoli Privacy Manager server. The methods defined on each of theseobjects allow the monitor to get or set the information maintained in the objects.v “MonitorInfo”v “SLocInfo”v “EvalRuleInfo” on page 18v “EvalResultInfo” on page 18v “SKey” on page 18

MonitorInfoThe MonitorInfo object contains information about a monitor registered on theTivoli Privacy Manager server. Monitors retrieve this object from the Tivoli PrivacyManager server to obtain the latest monitor property information. The monitorinformation maintained in this object consists of the following:v Monitor namev Deployment statusv Polling intervalv List of attribute key/value pairs registered with the monitorv List of accessor information attribute names registered for the monitorv Indication of whether or not real-time enforcement is enabledv Indication of the last time updates were made to monitor or storage location

information on the Tivoli Privacy Manager server

SLocInfoThe SLocInfo object contains information about a single storage location for amonitor. Monitors use this object to register storage locations with the TivoliPrivacy Manager server and to report submission and access activity for storagelocations. Monitors also retrieve a list of SLocInfo objects from the Tivoli PrivacyManager server to obtain the most current storage location classificationinformation. The information maintained in this object consists of the following:


v Storage location namev Name of the monitor that owns the storage locationv List of monitor-assigned attribute key/value pairs for the storage locationv Storage location classification informationv Evaluation rules (EvalRuleInfo objects) that define the conditions for the storage

location, if anyv Evaluation results (EvalResultInfo objects) that reflect the results of the

evaluation

EvalRuleInfoThe EvalRuleInfo object represents a condition that applies to a storage locationand defines how the condition is evaluated using storage locations in themonitored storage system. Each evaluation rule describes how to make acomparison between two pieces of data: the left side and the right side of thecomparison operator. The information maintained in this object consists of thefollowing:v Storage location for the left side of the comparisonv Storage location, literal value, or set of literal values for the right side of the

comparisonv Comparison operator to use for the evaluation

EvalResultInfoThe EvalResultInfo object represents the result of the evaluation of a condition. AnEvalResultInfo object is created for a specific EvalRuleInfo object. The informationmaintained in this object consists of the evaluation result. The result is True if thecomparison passed, False if the comparison failed, or Unknown if the comparisoncould not be performed.

SKeyThe SKey object represents a user key. The monitor uses this object to pass a list ofone or more user keys to the Tivoli Privacy Manager server on each submissionand access notification. The list of user keys are used to identify the owner of thePII that was submitted or accessed. The information maintained in this objectconsists of the following:v SLocInfo object that represents the user key storage locationv Hashed value of the user key (a user key can be privacy sensitive, therefore the

value of the user key is stored in a hashed form to prevent the actual value frombeing sent to the Tivoli Privacy Manager server and stored in the submissionand access log)

Methods for communicating with the serverThe MonitorSupport class provides a set of static methods that perform basicoperations on the Tivoli Privacy Manager server.v getRegisteredMonitor retrieves the MonitorInfo object for a specific monitor

from the Tivoli Privacy Manager server. The returned object has the most recentmonitor properties information. If the monitor is not registered with the TivoliPrivacy Manager server, the method returns a null value. The MonitorInfo objectis obtained by a monitor during start up and during the polling operations todetermine if monitor or storage location information has been updated since thelast poll.


v registerMonitor is used to register a new monitor with the Tivoli PrivacyManager server or to update monitor information if a monitor is alreadyregistered.

v registerSLocList is used to register a list of storage locations (SLocInfo objects)for a monitor or to update the list of storage locations already registered.

v removeFromSLocList is used to remove one or more registered storage locations(SLocInfo objects) for a monitor. A monitor implementation might remove aregistered storage location from the list of storage locations if the monitordetects that the storage location has been removed from the monitored storagesystem. Removing a registered storage location from Tivoli Privacy Managerserver also removes the storage location classification information.

v getSLocList retrieves the latest classification information for the registeredstorage locations. This method is used during monitor start up and when amonitor’s deployment status is changed from Not Deployed to either In Test orDeployed to ensure that the monitor has the most recent storage locationclassifications.

v getSLocListUpdates retrieves the most recent storage location classificationssince a particular date and time. The monitor polling function uses the time inthe last modified field of the MonitorInfo object to determine when changeswere made to the monitor or its storage locations, and then calls this method toretrieve the most recent storage location classifications for any storage locationsupdated since the last polling operation.

v submitPII is used to report the submission of PII storage locations to the TivoliPrivacy Manager server. Each submission notification includes the list of storagelocations (SLocInfo objects) submitted and one or more user keys (SKey objects)that identify the owner of the PII. Monitors must use this method when data issubmitted or changed in the storage system if the submission includes one ormore PII storage locations.

v accessPII is used to report access to PII storage locations to the Tivoli PrivacyManager server. Each access notification includes the list of storage locations(SLocInfo objects) accessed, one more user keys (SKey objects) that identify theowner of the PII that was accessed, and one or more access information attributekey/value pairs that indicate the entity (person or application) that accessed thePII. Monitors must use this method when data is accessed in the storage systemif the access includes one or more PII storage locations.

v realTimeConfCheck is used to request a real-time privacy policy conformancecheck from the Tivoli Privacy Manager server. Only monitors that supportreal-time enforcement use this method. Each real-time conformance checkrequest includes the same information provided on accessPII method calls. Thereturn value for this method is a list of conformance check results, one for eachstorage location in the request, that indicate whether or not access conformswith the governing privacy policies.Monitors that support real-time enforcement should use this method only whenthe MonitorInfo object indicates that real-time enforcement is enabled. When thismethod is used by a monitor, the accessed storage locations should not bereturned to the requesting application until the conformance check is completed.If any of the conformance check results indicate access that is not inconformance with the policy, the monitor should either filtering thenon-conforming information from the results returned to the requestingapplication or deny the access request. If the monitor returns PII to therequesting application, it must call the accessPII method to notify the TivoliPrivacy Manager server of the PII storage locations that were returned.

Chapter 3. Introduction to the Monitor SDK Java APIs 19

Helper methodsThe MonitorSupport class also contains static helper methods to assist the monitorin creating parameter objects for various method calls.v createSLocForRegistration is used to construct an SLocInfo object with the

information needed for storage location registration.v copySLocForReporting is used to make a copy of an SLocInfo object. It copies

only the fields that are needed for submission and access reporting and forreal-time conformance checking. Monitors use this method to copy SLocInfoobjects to minimize the size of the parameters sent to the Tivoli Privacy Managerserver for these requests.

v createEvalResult is used to create an EvalResultInfo object for a specificEvalRuleInfo object.

ExceptionsThe following classes define the exceptions thrown by the Monitor SDK Java APIsto report error conditions:v MonitorException is the superclass for all Monitor SDK exception classes. The

information maintained in this object, and all other Monitor SDK exceptionclasses, includes the exception message string and the nested exception, if any.

exception message stringThe exception message string is a keyword string that presents thenature of the exception. Each subclass of MonitorException defines thekeyword strings, as public static fields, that are used as messageexception strings. Monitors can use the keyword strings to determine thecause of an exception and issue an error message, if necessary.

nested exceptionThe Monitor SDK Java APIs might throw an exception if some otherkind of exception occurred during processing. When this happens, theMonitor SDK Java APIs throw a MonitorException, or one of itssubclasses, to the monitor implementation, and keep a reference to theunderlying exception. The monitor implementation can retrieve thisnested exception from the MonitorException to learn more about theunderlying cause of the failure. If a nested exception does not exist, anull value is returned.

v MonitorParameterException is a subclass of MonitorException that is used toindicate an error in the parameters passed to one of the Monitor SDK Java APImethods. When this exception is thrown, it indicates an error in the monitorimplementation. In other words, the monitor implementation is passing incorrector invalid parameters to the Monitor SDK Java API methods. This exceptionclass defines a number of keywords for the exception message to indicate thekind of error that occurred, such as NULL_POINTER, NOT_SERIALIZABLE,SLOC_NOT_PII, EMPTY_LIST. (See the Javadoc for a complete list of the exceptionmessage keywords for MonitorParameterException).

v MonitorRemoteException is a subclass of MonitorException that is used toindicate that an error occurred while communicating with the Tivoli PrivacyManager server. When this exception is thrown, the problem is not with themonitor implementation, but with the communication path between the monitorand the Tivoli Privacy Manager server. When the Monitor SDK Java APImethods detect such an error, they perform at least one retry. This exception isreturned to the monitor implementation when at least two consecutive attemptshave failed. This exception class defines a number of keywords for the exception


message to indicate the kind of error that occurred, such asMONITOR_DOES_NOT_EXIST, REMOTE_ERROR. (See the Javadoc for a complete list ofthe exception message keywords for MonitorRemoteException)

Chapter 3. Introduction to the Monitor SDK Java APIs 21

Chapter 4. Monitor Development and Testing

This chapter contains information related to the development and testing of a newmonitor implementation. The chapter contains the following sections:v “Programming considerations”v “Performance considerations” on page 31v “Setting up the run-time environment” on page 33v “Internationalization considerations” on page 36

Programming considerationsThis section provides information about the programming aspects of developing anew monitor. The following subsections are included in this section:v “Setting up the monitor development environment”v “Blueprint for monitor implementations”v “Strategies for exception handling” on page 29v “Support for debugging monitors” on page 30

Setting up the monitor development environmentDuring the development of a monitor implementation, the monitor source codemust be compiled against the Monitor SDK Java API classes. The classes needed atcompile time are packaged in the monitor_support.jar file. The JAR file can beinstalled on the development machine using the standard Tivoli Privacy Managerinstallation procedure by selecting the Tivoli Privacy Manager SDK installationcomponent. After this component is installed, locate the JAR file in thesdk_install/lib directory, where sdk_install is the directory where the MonitorSDK is installed. This JAR file should be added to the javac classpath when themonitor source code is compiled. Monitor development requires Java 1.3 or a laterversion.

Blueprint for monitor implementations“Monitor architecture” on page 9 conceptually divides a monitor into threecomponents: storage system adapter, privacy server adapter, and monitorimplementation. The storage system adapter for a monitor is specific to the storagesystem being monitored and is likely to be different from other monitors. Theprivacy server adapter is provided by Tivoli Privacy Manager in the form of theMonitor SDK Java API classes. Although each monitor implementation can differslightly in how the functions are performed, the monitor implementation performsthe same high-level functions in all monitors. For example, every monitor mustregister itself and its storage locations with the Tivoli Privacy Manager server, butthe attributes registered with the monitor and storage locations might be differentfor each monitor implementation.

This section describes how a monitor should function under various conditions, forexample, during monitor startup or polling. The section provides a blueprint as thestarting point for new monitors that defines how a monitor implementation shouldact under various conditions. References are made to methods in the Monitor SDKJava APIs, and the methods are in the MonitorSupport class, unless otherwisenoted. The Javadoc contains detailed information for using these methods as wellas other objects and methods of the Monitor SDK Java APIs.


Monitor startup and initializationMonitors should be designed to read a set of configuration properties duringstartup. How the properties are read varies based on the monitor implementation.For example, they can be read from a Java properties file. The set of propertiesneeded for a given monitor is monitor specific, but the monitor name shouldalways be a configured property that is read during startup. This design allows theinstaller of the monitor to choose a name that does not conflict with othermonitors, rather than defining the monitor name in the monitor source code.

During initialization, the monitor must first determine whether or not it isregistered with the Tivoli Privacy Manager server. To do this, the monitor mustrequest the MonitorInfo object for its monitor name using thegetRegisteredMonitor method. If the monitor is not registered, a null value isreturned. If the monitor is registered, a MonitorInfo object is returned that containsthe monitor configuration information. The configuration information includes, butis not limited to, monitor attributes, the polling interval, the monitor’s deploymentstatus, and an indicator of the last time updates were made to the monitorinformation on the Tivoli Privacy Manager server.

If the monitor is already registered, the monitor can check the information in theMonitorInfo object to ensure it is accurate and complete. For example, a monitorcan verify that the accessor attributes and the required monitor attributes areregistered. If the MonitorInfo object contains inaccurate information, the monitorcan update any information except the monitor name by calling theregisterMonitor method.

If the monitor is not registered, the monitor implementation must complete thefollowing tasks to register the monitor with the Tivoli Privacy Manager server:v Build a list of accessor attribute names that the monitor will use to identify the

entity (a person or an application) accessing PII. This list of accessor attributenames are different for each monitor, but monitor implementations shouldprovide attributes that the administrator can use to identify the recipient of thePII as well as the purpose for using the PII.

v Build a list of the attributes to be registered with the monitor. This list ofattributes is for the sole use of the monitor implementation, so the contents ofthese attributes are monitor dependent. Some monitor implementations mightnot require monitor attributes.

v Register the monitor using the registerMonitor method. This method requiresthe monitor to provide its name, an indication of whether the monitor supportsreal-time enforcement, the list of accessor attributes, and the list of monitorattributes. This method call returns the MonitorInfo object for the newlyregistered monitor.

After the monitor has its configuration information in the form of a MonitorInfoobject, it can verify that its storage locations are registered with the Tivoli PrivacyManager server. The monitor should consult the monitored storage system, using astorage system dependent mechanism, to build a list of storage locations. Thestorage locations should be named using a convention that is meaningful to themonitor or its storage system. The monitor should then retrieve the list ofregistered storage locations using the getSLocList method and compare thereturned list of storage locations to the list built from the information in thestorage system. If any of the storage locations in the storage system are notregistered with the Tivoli Privacy Manager server, or if information associated withthe registered storage locations is not accurate, the monitor should register thestorage locations or update their information using the registerSLocList method.


If a monitor detects registered storage locations that are not in the storage system,perhaps the storage locations were deleted from the storage system. In this case,the monitor can deregister the storage locations from the Tivoli Privacy Managerserver using the removeSLocList method. This method should be used with cautionbecause deregistering storage locations from the Tivoli Privacy Manager serverremoves all classification information for the storage locations.

After the monitor verifies that all storage locations are registered and theinformation for each storage location is accurate, the monitor should start abackground thread that is responsible for periodically polling the Tivoli PrivacyManager server for changes to information. This polling thread should use thepolling interval specified in the MonitorInfo object to determine the frequency ofpolling operations.

Finally, the monitor should obtain its deployment status from the MonitorInfoobject. If the deployment status is either In Test or Deployed, the monitor shouldbegin monitoring for PII submissions and accesses. To monitor PII submission andaccess efficiently, the monitor should maintain the MonitorInfo object and the listof storage locations and their classifications (the SLocInfo objects returned from thegetSLocList method) in memory for quick reference.

Monitor pollingMonitors should poll the Tivoli Privacy Manager server for updated status andconfiguration information. Monitor polling should be performed in the backgroundon a separate thread of execution to minimize the impact on other monitor activity.The polling thread should use the polling interval defined in the MonitorInfoobject to determine the frequency of polling operations.

For each polling operation, the monitor should first request a new MonitorInfoobject from the Tivoli Privacy Manager server using the getRegisteredMonitormethod, and then compare the new MonitorInfo object with the previous onemaintained by the monitor. If information has changed, the last modified field ofthe MonitorInfo object will be updated. If the last modified field has changed, themonitor should update its monitor and storage location information. The lastmodified field contains a number that represents the UTC time. Between two UTCtimes, the larger number is the most recent time.

The monitor should begin using the status information in the new MonitorInfoobject, namely the monitor deployment status, polling interface, and real-timeenforcement enabled state. If the monitor is the Not Deployed state, no furtheraction is needed. Otherwise, the monitor should check to see if the monitordeployment state has changed by comparing the deployment state in the oldMonitorInfo object with the one in the new MonitorInfo object. If the deploymentstate changed from Not Deployed to either In Test or Deployed, the monitorshould begin monitoring storage system activity. For this deployment state change,the monitor should ensure it has the most recent storage location classificationinformation by requesting the complete list of storage locations from the TivoliPrivacy Manager server using the getSLocList method. The returned list of storagelocations (SLocInfo objects) should be maintained locally and used for allsubsequent monitoring activity. For other monitor changes (deployment status orotherwise), the monitor should check to see if storage location information on theTivoli Privacy Manager server has been updated by calling the getSLocListUpdatesmethod using the last modified time in the old MonitorInfo object; this method callretrieves only the SLocInfo objects for storage locations that have been changed

Chapter 4. Monitor Development and Testing 25

since the last time the monitor requested them from the Tivoli Privacy Managerserver. The monitor should use the returned SLocInfo objects to update its locallymaintained list of storage locations.

As the polling thread updates monitor and storage location classificationinformation, care should be taken to ensure that the updates do not adverselyaffect routine monitor activities. For example, if the monitor is currentlymonitoring PII accesses when the polling thread is updating storage locationinformation, the monitor should not be able to use the old and new storagelocation information at different stages in the process of monitoring a single PIIaccess.

If errors are detected that prevent a monitor from completing a polling operation,monitors should not wait for another polling interval to elapse before retrying thepolling operation. Instead, the monitor can enter a loop that waits a short time,such as 30 seconds, and then retry the failed operation to complete the pollingoperation as soon as possible.

In addition to polling the Tivoli Privacy Manager server for changes, monitorimplementations can use this polling thread to check for changes in the storagesystem. Polling the storage system enables a monitor to detect when new storagelocations are created in the storage system or when storage locations are removedfrom the storage system. When such activity is detected, the monitor can updatestorage locations registered on the Tivoli Privacy Manager server using theregisterSLocList and the removeSLocList methods, respectively.

When monitor polling is complete, the polling thread should allow another pollinginterval to elapse before starting the next polling operation. That is, the pollinginterval is the time between the completion of one poll and the start of the nextone. If the polling interval has changed, the polling interval in the newMonitorInfo object should be used.

Monitoring PII submissionWhen a monitor is in either In Test or Deployed state, it must notify the TivoliPrivacy Manager server when PII is changed in the monitored storage system. Themethod used by the storage system adapter to detect PII submission activity isspecific to the monitor and its storage system. Each time the storage systemadapter detects data being changed or submitted, it must notify the monitorimplementation of the fields that were changed and the new values for thosefields.

The monitor implementation uses this information from the storage system adapterin conjunction with its locally maintained list of storage location classifications(SLocInfo objects) to determine if any of the updated fields are privacy sensitive. Ifthe updated information involves PII storage locations and at least one user keystorage location, the monitor must report the activity to the Tivoli Privacy Managerserver as a PII submission. If the fields are not PII storage locations or if no userkey storage locations are involved in the operation, the activity is ignored becauseprivacy sensitive information is not involved or the updated information isde-identified (that is, the information cannot be associated with an individual).

To report a PII submission, the monitor should record the current time of day inUTC (using the Java method System.currentTimeMillis) as the time when thesubmission occurred. Then it should collect any additional information neededfrom the storage system, such as the value of the master key storage location andthe values of any storage locations that are needed to evaluate the conditions


(EvalRuleInfo objects) associated with the submitted PII. The information gatheredmust be for the person whose PII was submitted, so the monitor must use thevalue of a user key storage location provided by the storage system adapter toensure that the correct information is gathered. Monitors should be efficient ingathering this additional information to minimize the amount of additional workimposed on the storage system.

After the monitor has gathered the necessary information, the monitor shouldbuild a list of the storage keys (SKey objects) involved in the submission. Themaster key storage location should be first in the list. The list should contain anystorage locations that are classified as user keys that were involved in thesubmission.

Next the monitor should build a list of the PII storage locations that were involvedin the submission. Only the storage locations classified as PII should be included inthis list, not the entire list reported by the storage system adapter. For each of thePII storage locations being reported, the monitor must evaluate the correspondingconditions. The conditions are described in the EvalRuleInfo objects, which can beobtained using the getEvalRules method of the SLocInfo object.

Each EvalRuleInfo object specifies a storage location to compare to another storagelocation, a literal value, or a set of literal values to determine the result. Theoperator used for the comparison is either Equals or Not Equals for scalarcomparisons and In or Not In for set comparisons. The monitor should perform allcomparisons as case-insensitive string comparisons.

Monitors should treat a null or missing value for a storage location as a distinctvalue that only matches another null value. For example, if a storage location witha null value is compared to a storage location that does not have a null value, themonitor must be designed to evaluate an Equals comparison as False and a NotEquals comparison as True. Similarly, if a storage location with a null value iscompared to a list of literal values, the monitor must be designed to evaluate anIN comparison as False and a Not In comparison as True.

The result of a comparison can be True, False, or Unknown. The result is stored inan EvalResultInfo object using the createEvalResult method. Unknown is usedwhen the result could not be determined, such as when the monitor is not able toretrieve the necessary information from the storage system. The monitor shouldmake a copy of the corresponding PII storage location using thecopySLocforReporting method and store the list of EvalResultInfo objects in thecopy using the setEvalResults method of the SLocInfo object.

Finally, the monitor should report the PII submission to the Tivoli Privacy Managerserver using the submitPII method, passing all of the information gathered on thecall.

Monitoring PII accessWhen a monitor is in the In Test or Deployed state, it must notify the TivoliPrivacy Manager server when PII is accessed in the monitored storage system. Themethod used by the storage system adapter to detect PII access activity is specificto the monitor and its storage system. But each time the storage system adapterdetects data being accessed, it must notify the monitor implementation of the fieldsthat were accessed and the new values for those fields.

The monitor implementation uses this information from the storage system adapterin conjunction with its locally maintained list of storage location classifications


(SLocInfo objects) to determine if any of the accessed fields are privacy sensitive. Ifthe accessed information involves PII storage locations and at least one user keystorage location, the monitor must report the activity to the Tivoli Privacy Managerserver as a PII access. If the fields are not PII storage locations or if no user keystorage locations are involved in the operation, the access is ignored becauseprivacy sensitive information is not involved or the accessed information isde-identified (that is, the information cannot be associated with an individual).

Note: If the monitor supports real-time enforcement and if real-time enforcementis enabled (as indicated in the MonitorInfo object), the PII access might notbe reported, based on the results of the conformance check. Refer to“Real-time enforcement of PII access” for more information.

To report a PII access, the monitor must collect the same information needed whenreporting PII submissions, including the current time in UTC, the storage key list,and the PII storage location list (with the results of the evaluations of all associatedconditions). Refer to “Monitoring PII submission” on page 26 for details aboutcollecting this information. In addition, the monitor must build a list of one ormore accessor attribute key/value pairs. The attribute key/value pairs describe theentity (person or application) that is accessing the PII. The attribute keys should becomprised of the accessor attribute names registered with the monitor, and theattribute values should reflect the entity accessing the PII.

Finally, the monitor reports the access to the Tivoli Privacy Manager server usingthe accessPII method, passing all of the information gathered on the call. The lastparameter of the accessPII method (confResults) should be specified as a nullvalue because no prior real-time conformance checks were performed by themonitor for this PII access.

Real-time enforcement of PII accessTivoli Privacy Manager does not require a monitor implementation to supportreal-time enforcement of privacy policy statements. If a monitor supports real-timeenforcement and if real-time enforcement is enabled (as indicated in theMonitorInfo object), when the monitor is in the In Test or Deployed state, it mustperform a real-time conformance check for every PII access and must block accessto PII that does not conform with the governing privacy policy. There are manyways to prevent PII that does not conform with a policy from being returned tothe requesting application. For example, a monitor might filter the PII storagelocations (for PII that is non-conforming) from the returned results or simply denythe request.

To perform a real-time conformance check, the monitor must collect the sameinformation needed when reporting PII accesses, including the current time, thestorage key list, the PII storage location list (with the results of the evaluations ofall associated conditions), and the accessor attribute key/pair list. Refer to“Monitoring PII access” on page 27 for details about collecting this information.

After the information is gathered, the monitor performs a real-time conformancecheck using the realTimeConfCheck method. The value returned from this methodcall is a list of Boolean objects that reflect the results of the conformance check.One object is returned for each PII storage location passed on therealTimeConfCheck method. For each Boolean object in the result list, a value ofTrue indicates that access to the corresponding PII storage location conforms withthe governing privacy policy. A value of False indicates that access does notconform with the governing privacy policy.


Using the list of conformance check results, the monitor can determine exactlywhich PII storage locations can be returned to the requesting application. Themonitor implementation can either filter the PII storage locations that do notconform with the policy from the results returned or deny the entire request. Ineither case, the monitor implementation must notify the Tivoli Privacy Managerserver if any PII storage locations are returned to the requesting application, sothat the PII access can be recorded in the audit log. The monitor performs thisnotification using the accessPII method. The list of PII storage locations sent onthis accessPII call must include those that were returned to the requestingapplication, not the ones filtered by the monitor. In addition, the last parameter ofthe accessPII call should not be a null value in this case because the monitor hasalready performed a conformance check for these PII storage locations. Instead, themonitor should provide a list of Boolean objects (one for each PII storage location)with values of True to inform the Tivoli Privacy Manager server of the results ofthe prior conformance check. This way, the monitor can improve the efficiency ofthe Tivoli Privacy Manager server by preventing a second conformance check frombeing performed on the subsequent accessPII method call.

Monitor shutdown and terminationThe method for instructing a monitor to shutdown can vary depending on themonitor implementation. When a monitor is instructed to shut down, it shouldstop monitoring new PII submissions and accesses, but it should finish processingPII submission and access notifications and real-time conformance checks that arein progress before the monitor shuts down. After the work in progress iscompleted, the monitor should signal the polling thread to terminate, release itslocally maintained MonitorInfo object and storage location list, and performadditional cleanup, as required.

Strategies for exception handlingThe Monitor SDK Java API throws subclasses of MonitorException to reflectvarious error conditions to the monitor. These exceptions must be caught by themonitor implementation (otherwise the monitor code will not compile properly)and handled appropriately. The following guidelines are for handling Monitor SDKexceptions:v All of the methods of the MonitorSupport class may throw a

MonitorParameterException if a problem is found with the parameters passed bythe monitor implementation. This exception indicates an error with the monitorsource code itself; that is, the monitor is passing incorrect or invalid parametersto a method. When handling this exception, the monitor should display or log amessage that indicates an error occurred. The displayed error helps the monitordeveloper to diagnose and fix the problem in the monitor code. The displayed orlogged message should include the exception message (keyword) from theMonitorParameterException as well as the nested exception, if any. Because theerror is a monitor source code error, there is no need to retry the operation. Aretry is likely to produce the same MonitorParameterException. These types oferrors will occur primarily during the development and testing of the monitorimplementation because debugging is not completed. The errors should occurless frequently when monitor development is complete.

v The methods of the MonitorSupport class that perform operations on the TivoliPrivacy Manager server might also throw a MonitorRemoteException if an erroroccurs while trying to communicate with the Tivoli Privacy Manager server.Exceptions of this type do not indicate problems with the monitorimplementation, but with the communication path between the monitor and theTivoli Privacy Manager server. The following errors might cause this exception:


– A network problem that prevents the monitor from accessing the TivoliPrivacy Manager server

– The Tivoli Privacy Manager server application is not running– The credentials used by the monitor do not have the required permissions to

invoke the necessary remote methods on the Tivoli Privacy Manager server– The Monitor SDK was unable to locate the necessary EJB references because

of an incorrect hostname, port, or EJB name

In some cases the error could be intermittent, while in other cases the error couldbe unrecoverable. It’s difficult for the monitor implementation to determinewhether or not the error is intermittent or unrecoverable based solely on theMonitorRemoteException and the nested exception. The way a monitor handlesthese remote exceptions can vary, but the following points should be considered:v If the error occurs during monitor startup and initialization, an error should

probably be displayed or logged, and the monitor should stop to give themonitor installer a chance to investigate and resolve the problem.

v If the monitor successfully completed startup and initialization, which shouldinvolve making several requests to the Tivoli Privacy Manager server, theproblem is more likely to be transient in nature (network failure or server down)rather than a permanent failure (bad credentials or bad EJB lookup information).

v If the error occurs while the monitor is trying to obtain information from theTivoli Privacy Manager server (getRegisteredMonitor, getSLocList), it might notbe a critical error. That is, the monitor might be able to continue functioningwith existing, though slightly out of date, information until the problem iscorrected. The monitor should display or log the error, if possible, but it shouldcontinue running because the problem might go away. For errors that occurduring polling operations, the monitor can enter a loop that waits a short time(for example, 30 seconds) and retry the failed operation, in an effort to completethe polling operation as soon as possible.

v If the error occurs while the monitor is trying to send information to the TivoliPrivacy Manager server, this might be a critical error if the monitor cannotproceed until the operation is completed. For example, if the error occurs duringa submission or access notification or during a real-time conformance check, theerror must be detected and the operation must be retried; otherwise, the audittrail on the Tivoli Privacy Manager server is incomplete. If possible, the monitorshould continue retrying the operation until it completes successfully, or save thesubmission and access information so it can be sent to the Tivoli PrivacyManager server when the problem is corrected. For real-time conformancechecks, the monitor might retry twice; if the problem persists, it can return anerror (access denied) to the requesting application instead of returning therequested PII information.

Regardless of how a monitor handles exceptions, it should display or log errors sothat there is a record of the failure. For persistent errors, the monitor should notcreate so many error messages that it depletes system resources, such as filling upa disk with log messages.

Support for debugging monitorsThe Monitor SDK Java APIs include tracing support, which can be useful indebugging new monitor implementations. By default, the tracing support isdisabled, but it can be enabled by using the Java -D parameter to define thefollowing Java system property for the monitor JVM:com.ibm.btb.monitor.sdk.trace


This system property does not require a value. When Monitor SDK tracing isenabled, calls to methods of the MonitorSupport class cause trace messages to bewritten to STDOUT of the monitor JVM. Typically, STDOUT is directed to the console,but in certain environments, like the WebSphere Application Server JVM, STDOUT isdirected to a file.

Each trace message displays the calling thread ID and the class name and methodname that generated the trace message, as well as trace information. The tracemessages help developers follow the flow of control through the Monitor SDK JavaAPIs.

Note: If the monitor implementation uses the WebSphere Application Clientrun-time environment and is launched through the Tivoli Privacy ManagerEAR file, the trace support of the Monitor SDK Java APIs can also beenabled by specifying -MonitorSDKTrace as the first parameter on thelaunchClient utility (that is, before the fully qualified name of the monitorimplementation main class).

Performance considerationsMonitoring a storage system for privacy introduces a significant amount ofadditional processing. A great deal of this processing is performed on the TivoliPrivacy Manager server, but some of it is performed by the monitor, which may berunning in the same process as (or as an extension to) the storage system. Monitordesigns should minimize the performance impact on the storage system and theapplications that use it whenever possible. The following sections provideinformation about performance issues to consider when implementing a monitor.

Background executionAll of the methods of the Monitor SDK Java APIs are synchronous. That is, when amonitor invokes a method to perform an operation on the Tivoli Privacy Managerserver, control does not return from the method call until the operation iscomplete. This means the thread of execution in the monitor is suspended whilethe operation is performed and resumed when the operation is completed. Inmany situations, this synchronous execution simplifies the monitor function by notrequiring the monitor to explicitly wait for the operation to complete. For example,monitor startup and initialization is normally performed on a single thread ofexecution. When the monitor requests its MonitorInfo object using thegetRegisteredMonitor method, it wants to suspend the thread until the operationcompletes because startup processing cannot continue until the MonitorInfo objectis obtained.

But there are some cases when monitors might not want to suspend the currentthread of execution for the duration of a Monitor SDK method call, especially ifdoing so would unnecessarily delay the monitor from returning information to arequesting application. In this case, the monitor should be designed to perform asmuch processing as possible on a different background thread of execution so thecurrent thread does not experience the delay.

The polling thread is an example of background execution. This thread performsperiodic polling of the Tivoli Privacy Manager server in the background, so it doesnot cause a direct impact to basic monitoring activity.

There are other situations in which background execution can improve theperformance of the monitor, at least as seen by the storage system or the


applications that use the storage system. Specifically, the sending of PII submissionand PII access notifications to the Tivoli Privacy Manager server can be performedin the background. Because the purpose of the notifications is to generate an auditlog of PII submission and access, there is no need for the storage system orapplications to wait for the audit record to be recorded before the submission oraccess is allowed to occur. When the monitor implementation is notified of asubmission or access, if real-time enforcement is either not supported or disabled,the monitor should collect the information it needs and pass the information toanother background thread so the current thread can return without delay. Thebackground thread can then perform the bulk of the work, such as collectingadditional information, building the list of storage keys and storage locations, andcalling the Monitor SDK APIs to send the notifications, without impacting theoriginal thread. This approach might add complexity to the monitorimplementation (for example, thread management and request queuing andprocessing), but the performance benefits are significant.

Gathering additional information from the storage systemMonitors are often required to gather additional information from the monitoredstorage system during the handling of PII submission and access notifications. Forexample, a monitor might need to retrieve the value of the master key storagelocation or the values of storage locations needed to evaluate conditions. Becausethis involves direct interaction with the storage system, which might already havea substantial workload, monitors should consider the additional work they imposeon the storage system. If possible, the monitor should minimize the number oftrips it makes to the storage system to gather additional information.

Tuning controlsMonitor implementations must provide a way for the installer to configure andcontrol the resources that the monitor consumes and a way to allow the operationof the monitor to be tuned for a given environment. Because multiple monitors canreport to a single Tivoli Privacy Manager server, it must be possible to tune eachmonitor so that server and network resources are shared equally among themonitors. Without this tuning capability, one monitor can overuse the resources ofthe server or network and inhibit other monitors from performing theirresponsibilities.

There are several ways in which a monitor can provide tuning capability. Onemethod is to define monitor configuration properties that can be customized by theinstaller. The monitor can read these configuration properties during initializationand use them to regulate the operational characteristics of the monitor. Monitorsthat implement tuning parameters through configuration properties should bedesigned to read the properties periodically (not just during startup), so thatchanges to the properties can be detected without requiring the monitor to bestopped and restarted.

As an alternative to configuration properties, a monitor can define a method forreceiving commands or messages from the installer or administrator that providestuning instructions to the monitor, so that tuning adjustments can be madeinteractively without requiring a monitor restart. Regardless of what tuningmechanism is implemented by a monitor, the tuning controls must be describedthoroughly in the monitor documentation.

Some examples of the types of tuning controls a monitor can provide are listedbelow. Developers must determine which tuning controls are useful or necessaryduring the early design stages of the monitor.


ConcurrencyMonitors are typically designed to handle multiple tasks concurrently, suchas reporting many simultaneous storage system accesses or submissions.Without adequate controls, monitors can be overwhelmed with so muchactivity that the monitor runs out of the resources (memory, threads ornetwork bandwidth) needed to handle the workload. In such cases, amonitor must provide a method for configuring the maximum number ofrequests that it can handle concurrently, and its design must block orqueue new requests when the maximum number of requests have beenreceived.

Server communicationsWhen multiple monitors report to the same Tivoli Privacy Manager server,the administrator must ensure that no monitor can monopolize the serverand its resources. For example, if the WebSphere application serverrunning the Tivoli Privacy Manager server is configured to support 100concurrent connections, you must configure the monitors such that nosingle monitor can use all 100 connections. Monitors must provide a wayof tuning the maximum number of simultaneous requests that can be madeto the Tivoli Privacy Manager server and must queue and defer processingof additional requests when this limit is reached. With this tuningcapability, the monitor installer can configure each monitor to use a portionof the 100 connections, and thereby ensure that no monitor is without aserver connection.

Queue lengthsIf a monitor design implements queues for scheduling units of work, itshould be possible to configure the maximum lengths of the work queues.Without limits on the queue lengths, a monitor can run out of memory iftoo much work is queued. By providing a way to configure queue lengths,the monitor installer can adjust the queue length based on the amount ofmemory allocated for the monitor JVM. When the queue length limit isreached, the monitor should block new work from arriving or beingqueued until work already on the queue is processed.

Multiple part monitorsA monitor designed as multiple parts can be used to spread the workload of amonitor over several processes or machines. For example, if a monitor with twoparts is monitoring a single storage system and applications are directed to one ofthe two monitor parts when accessing the storage system, it effectively divides thework of the monitor between the two monitor parts, even though the TivoliPrivacy Manager server perceives the two monitor parts as being a single monitor.

Setting up the run-time environmentTo run or test a new monitor, there must be a fully functional Tivoli PrivacyManager server available. Tivoli Privacy Manager servers used for testing shouldbe separate from production Tivoli Privacy Manager servers, so that productionservers are not impacted by problems that might be caused while testing the newmonitor implementation.

After the test Tivoli Privacy Manager server is setup and operational, you cansetup the runtime environment for the monitor. Because monitors must use theMonitor SDK Java APIs (which use EJBs to communicate with the Tivoli PrivacyManager server), the monitor run-time must be a supported EJB clientenvironment. Tivoli Privacy Manager supports several EJB client environments for


monitors, and the setup requirements are different for each one. The followingsubsections provide information about the three runtime environment choices:v “WebSphere J2EE Application Client setup”v “WebSphere Application Thin Client setup” on page 35v “WebSphere Application Server setup” on page 35

The choice of run-time environment depends on the design of the monitorimplementation. The following are examples of possible monitor implementations:v A monitor implemented as a WebSphere server application is packaged in an

EAR file and runs in a Web container or an EJB container on a WebSphereapplication server. This implementation requires the WebSphere ApplicationServer runtime environment.

v A monitor implemented as a WebSphere client application is packaged in anEAR file and runs in a WebSphere application client container. Thisimplementation requires the WebSphere Application Client runtimeenvironment.

v A monitor implemented as a Java application that does not use EJBs can eitheruse the WebSphere Application Client or the WebSphere Thin Client runtimeenvironment. For most monitor implementations either one of theseenvironments can be used. The preferred environment is the WebSphereApplication Client environment; however, if the monitor implementationrequires its main class to be started first (for example, because it needs toestablish its own security manager or has its own class loading mechanism), theWebSphere Thin Client should be used.

The proper setup of the monitor runtime environment basically involves makingsure the monitor has access to the Monitor SDK Java API classes, and making surethe Monitor SDK classes can find the Tivoli Privacy Manager server and lookupEJBs on that server. The setup instructions for each of the above run-timeenvironments is discussed in the following sections.

WebSphere J2EE Application Client setupThe WebSphere Application Client environment requires applications to bepackaged in an EAR file; but even if the monitor implementation is not designedto run as a client application in an EAR file, it is possible to use the WebSphereApplication Client environment by launching the monitor’s main class through theTivoli Privacy Manager EAR file. In either case, this environment first requires thatthe WebSphere Application Client be installed on the monitor machine.

Note: If the monitor is going to run on the same machine as the WebSphereApplication Server, it is not necessary to install the WebSphere ApplicationClient, because the server also contains all the required client function.

If the monitor implementation is packaged in its own EAR file,1. During the application assembly process, include the Monitor SDK JAR file as

other files in the EAR file, and add theMonitor SDK JAR file to the classpath ofthe monitor application client in the EAR file.

2. Create a J2EE.properties file that defines the hostname and port of the TivoliPrivacy Manager server and the JNDI names of all the EJBs used by theMonitor SDK. In most cases, the default EJB names can be used, so that theJ2EE.properties file looks like this:BootstrapHost= privacy_manager_server_hostnameBootstrapPort=900InitialContextFactory=com.ibm.websphere.naming.WsnInitialContextFactory


MonitorConnectionEJBName=btb110/com/ibm/btb/cms/session/MonitorConnectionHomeStorageLocationManagerEJBName=btb110/com/ibm/btb/cms/session/StorageLocationManagerHomeSubmissionServerEJBName=btb110/com/ibm/btb/server/submission/submissionServerBean/SubmissionServerHome (type on same line as previous line)AccessServerEJBName=btb110/com/ibm/btb/server/access/accessServerBean/AccessServerHomeEnforcementServerEJBName=btb110/com/ibm/btb/server/enforcement/EnforcementServerHomeBeanCounterEJBName=btb110/com/ibm/btb/beancounter/BeanCounterHome

3. Modify the WebSphere launchClient utility to add the following parameter tothe Java command that starts the application:-Dcom.ibm.btb.monitor.sdk.J2EEProps=J2EE.properties

4. Use the WebSphere launchClient utility to launch the monitor EAR file,making sure the -CCclasspath parameter of the launchClient commandincludes the directory containing the J2EE.properties file.

If the monitor implementation is not packaged in its own EAR file, use theWebSphere launchClient utility to launch the sdk_install/lib/privacy.ear file(where sdk_install is the directory where the Monitor SDK is installed) and makesure:v The -CCclasspath parameter includes the directories or JAR files containing the

monitor class files.v The -CCBootstrapHost parameter specifies the hostname of the Tivoli Privacy

Manager serverv The -CCBootstrapPort parameter specifies the port number of the Tivoli Privacy

Manager server (typically, 900)v The fully qualified name of the monitor is specified after all other launchClient

command parameters. This class name can optionally be followed by anycommand parameters required by the main class of the monitor implementation.

WebSphere Application Thin Client setupTo run the monitor implementation in the WebSphere Thin Client environment,you must first install the WebSphere Thin Client support on the monitor machine,and then perform the following task:1. Create a J2EE.properties file that defines the hostname and port of the Tivoli

Privacy Manager server and the JNDI names of the EJBs used by the MonitorSDK. In most cases, the default EJB names can be used, so the J2EE.propertiesfile looks like the one shown in “WebSphere J2EE Application Client setup” onpage 34.

2. Run the setupClient utility of the WebSphere Thin Client to initialize theclasspath with the required WebSphere Thin Client JAR files.

3. Modify the classpath to include the Monitor SDK JAR file (in thesdk_install/lib directory, where sdk_install is the directory where theMonitor SDK is installed), the directory containing the J2EE.properties file,and the directories or JAR files that contain the monitor implementation classfiles.

4. Launch the main class of the monitor implementation using the Java command,making sure the following parameter is specified:-Dcom.ibm.btb.monitor.sdk.J2EEProps=J2EE.properties.

WebSphere Application Server setupIf the monitor is designed to run as a WebSphere server application, the monitor ispackaged in an EAR file and runs in a Web container or EJB container on aWebSphere Application Server. Due to the way WebSphere performs class loading,a monitor cannot run in the same WebSphere Application Server JVM as the TivoliPrivacy Manager server. You must install the monitor EAR file in a different


WebSphere Application Server. The application server can either be on the samemachine or on a different machine from the Tivoli Privacy Manager JVM.

To set up the run-time environment for a WebSphere server application performthe following task:1. During the application assembly process of the monitor EAR file, include the

Monitor SDK JAR file as other files in the EAR file, and add the Monitor SDKJAR file to the classpath of the monitor Web Module or EJB Module in the EARfile.

2. Create a J2EE.properties file that defines the hostname and port of the TivoliPrivacy Manager server and the JNDI names of all the EJBs used by theMonitor SDK. In most cases, the default EJB names can be used, so theJ2EE.properties file looks like the one shown in “WebSphere J2EE ApplicationClient setup” on page 34.

3. Add the directory containing the J2EE.properties file to the classpath of themonitor’s WAS JVM. (This can be done through the WebSphere AdministrativeConsole.)

4. Define the following system property for the monitor’s WAS JVM (using theWebSphere Administrative Console):com.ibm.btb.monitor.sdk.J2EEProps=J2EE.properties

5. Restart the monitor’s WAS JVM.6. Install the monitor EAR file onto the WebSphere application server and start it.

Internationalization considerationsInternationalization is the process of designing software that can be adapted todifferent languages without any programming changes. Tivoli Privacy Managerdoes not require monitor implementations to be enabled for internationalization orto be translated into any specific languages. A monitor can be enabled forinternationalization by the monitor development team if it is deemed necessary oradvantageous for the monitor’s target market. For example, if a monitor isdeveloped for use only by the organization developing the monitor,internationalization might not be necessary. However, if the monitor is developedfor a number of organizations in different geographies, internationalization mightbe important.

There are a few things to consider when designing internationalization support fora monitor. The Monitor SDK Java APIs do not issue any error messages orexceptions that have text that requires translation. All exceptions thrown by theAPIs return an exception string that the monitor can examine to determine thenature of the exception. If the exception condition warrants displaying atranslatable message to the monitor user, the monitor implementation isresponsible for mapping the thrown exception to a message and providing supportfor translating the message.

Exceptions thrown by the Monitor SDK Java APIs can contain nested exceptions.These nested exceptions are available to the monitor to assist in diagnosis andproblem determination but are not modified or translated by the Monitor SDK JavaAPIs.

The Monitor SDK Java APIs have tracing support, as described in “Support fordebugging monitors” on page 30. The tracing support is only for debuggingpurposes, and all trace messages are displayed in English. The trace messages werenot designed for internationalization.


Certain information generated by monitors is displayed in the Tivoli PrivacyManager console. For example, the names of registered storage locations aredisplayed during policy deployment to allow the administrator to classify thestorage locations and assign PII types to them. Although monitors should generatenames that are meaningful to the monitor and the storage system, monitors shouldalso generate names that are appropriate, in readability and length, for display inthe console.


Appendix. Notices

This information was developed for products and services offered in the U.S.A.IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.


Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this information and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurements may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

TrademarksThe following terms are trademarks or registered trademarks of InternationalBusiness Machines Corporation in the United States, other countries, or both:

AIXIBMIBM logoSecureWayTivoliTivoli logo

Microsoft, Windows, Windows NT, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.


Table 1.

Java and all Java-based trademarks andlogos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in theUnited States and other countries.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Other company, product, and service names may be trademarks or service marksof others.

Appendix. Notices 41

Glossary

Aaccess record. See PII access record.

administrator (ADMIN_STAFF). Authorization rolethat enables specified users to perform serverconfiguration tasks through the Tivoli Privacy Managerconsole.

auditor (AUDIT_STAFF). Authorization role thatenables specified users to generate reports through theTivoli Privacy Manager console. An auditor can besomeone outside the customer’s organization, such as athird-party privacy policy auditor.

authorization ID. The identifier of the application,group, or individual associated with the origination ofan access request. The Tivoli Privacy Manager consolelabels this field as the Access ID. See also PII accessor.

Cchief privacy officer (CPO). Individual responsible forensuring that an organization’s privacy policies complywith applicable privacy legislation and company policy.Defines an organization’s privacy policies.

condition rule. Boolean condition that is defined for agroup or purpose in a usage statement to furtherrestrict access to the PII defined in the usage statement.See also evaluation rule.

conformance check. Tivoli Privacy Manager processthat determines whether a PII access attempt does ordoes not conform to the governing privacy policy.

consent record. Recording of a submission of PII andthe consent to a privacy policy associated with the PII.

CPO staff (CPO_STAFF). Authorization role thatenables specified users to translate the organization’sprivacy requirements into their organization’s privacypolicies, through the Tivoli Privacy Manager console.

Ddeployment. The process of activating into fullfunctional use. Applies separately to monitors andprivacy policies. A monitor in deployed state monitorsdata accesses for privacy-sensitive operations andgenerates the appropriate submission and accessinformation. A privacy policy in deployed stateevaluates access attempts for policy conformance usinginformation supplied by monitors and generates accessand submission records.

Eenforcement. The level of PII access control that is setin a Tivoli Privacy Manager monitor. If the monitor isset to enforce PII access in real time, a failedconformance check does not allow access toPII-classified storage locations. If real-time enforcementis not set, an access attempt is recorded and the recorddenotes the access as having passed or failed theconformance check.

evaluation rule. Three-part expression (<key><operator> <value>) that represents an individual’schoice to opt in or opt out of a specified group orpurpose, or to represent another condition, such as alegal restriction on the use of PII. See also conditionrule.

explicit consent. A type of consent classificationindicating that an individual’s explicit or implicitconsent to the terms of the applicable privacy policy isrequired. If a policy is classified as explicit consent, asubmission record is used as an indication of the PIIowner’s consent to the use of the PII owner’sinformation according to the terms of the applicableprivacy policy. See also implicit consent.

Ggroup. A usage statement element that defines the setof individuals, groups of individuals, or applicationsthat can access specific PII data. See also usagestatement, PII type, and purpose.

Iimplicit consent. A type of consent classificationindicating that an individual’s explicit consent to theterms of the applicable privacy policy is not required.See also explicit consent.

IT staff (IT_STAFF). Authorization role that gives theuser the ability to deploy published policies tomonitored systems. Those assigned the IT staff roleunderstand the topography of the network, the systemsthat contain privacy-sensitive information, and whichinstances of the data in that system areprivacy-sensitive. With this role, the user can alsogenerate reports.


Mmonitor. In a privacy management environment, anentity that monitors PII-classified storage locations forattempts to submit data or retrieve data.

monitored system. Any system in an enterprise whichstores PII data that needs to be monitored forcompliance to a privacy policy. Examples of systemsthat might need to be monitored include LDAPdirectories, CRM systems, and customer profilers.

Oopt in. In a privacy policy, a representation of anindividual’s implicit or explicit choice to accept theintended use of the individual’s privacy-sensitiveinformation. See also opt out.

opt out. In a privacy policy, a representation of anindividual’s implicit or explicit choice to decline theintended use of the individual’s privacy-sensitiveinformation. See also opt in.

PP3P. See Platform for Privacy Preferences.

P3P privacy policy. Privacy policy based on the P3Pspecification. See also privacy policy.

personally identifiable information (PII). Dataelements that are associated with a specific individualand that can be accessed and used in such a way thatthe identity of the individual who submitted the PII isknown.

PII access. Request to retrieve information from aPII-classified storage location.

PII accessor. An application, group, or individual thatattempts a read or write operation on a PII-classifiedstorage location. The Tivoli Privacy Manager consolelabels this field as the Access Attribute. See alsoauthorization ID.

PII access record. Record generated by the TivoliPrivacy Manager server in response to accessinformation that a monitor has forwarded because a PIIaccess attempt has occurred.

PII-classified storage location. Storage locationidentified by the IT staff to contain privacy-sensitiveinformation subject to one or more privacy policies.

PII owner. An individual with whomprivacy-sensitive information is associated. As theowner of PII, the individual might have the legal rightto limit the propagation of the privacy-sensitiveinformation within the organization or to otherorganizations and individuals. See also PII.

PII submission. Request to update information in aPII-classified storage location.

PII submission record. Record generated by TivoliPrivacy Manager in response to a PII submissionrequest. Associates the submission information withone or more governing policies to which the owner ofthe information consents.

PII type. A category of privacy-sensitive informationfor which rules of allowable access are defined. Forexample, a privacy policy might define Home ContactInformation and Medical Records as PII types and thendefine the allowable purposes for which these typescan be used. See also group, purpose, and usagestatement.

PII user. An individual or organization, or an agentacting on behalf of an individual or organization, thatcollects privacy-sensitive information from a PII ownerand then uses that information in accordance withgoverning privacy policies. See also PII owner and PIIaccessor.

Platform for Privacy Preferences (P3P). A World WideWeb Consortium (W3C) specification that enables Websites to define their privacy practices in a standardformat. For more information, see the P3P project Website (http://www.w3.org/P3P/).

policy. See privacy policy

portfolio. The left-hand frame of the Tivoli PrivacyManager console that presents the tasks that can beperformed.

privacy policy. Organization’s stated position on howit intends to use the privacy-sensitive information itcollects. A privacy policy constitutes an agreementbetween an organization and owners of personallyidentifiable information (PII) that the organizationcollects.

privacy policy statement. See usage statement.

privacy-sensitive information. Information that isclassified for protection from general and unauthorizeduse. In the Platform for Privacy Preferences (P3P)specification, privacy-sensitive information is referredto as personally identifiable information (PII). See alsoPlatform for Privacy Preferences and personallyidentifiable information.

publish. To make a privacy policy available fordeployment. Only the CPO staff role is authorized toput a policy into a published state.

purpose. A usage statement element that defines howassociated PII types can be used. See also usagestatement, PII type, and group.


Sstate. The functional level of a privacy policy ormonitor. A privacy policy can be in draft, published, ordeployed state. A monitor can be in test, deployed, ornon-deployed state.

storage location. Data elements within a storagesystem that can be mapped to the schema of thestorage system, such as a column in a database table, orto an aggregation of data, such as a table, or to a wayof accessing data, such as a transaction identifier. Seealso storage system.

storage system. Any system in a network thatpersistently stores data that is collected for future useor that acts as a gateway to such data. See also storagelocation.

Ttask. A selection in the portfolio of the Tivoli PrivacyManager console. Which tasks are displayed iscontrolled by the authorization role of the user loggedinto the console.

type. See PII type.

Uusage statement. A logical sentence that identifieshow personally identifiable information (PII) can beused. A statement identifies PII types, the groups thatcan access the PII types, the purposes for which the PIItypes can be used, and conditions that might apply tothe use of the PII. For example a privacy policy mightinclude the following statement: ″Doctors (group) canaccess medical records (PII type) for diagnosis andtreatment (purpose).″

user identifier. User key of which a PII owner islikely to know the value, for example, name and socialsecurity number. See also user key.

user key. Storage location, with a value that might ormight not be known by the PII owner, that representsthe identity of the PII owner of other PII-classifiedstorage locations. For example, a storage location mightcontain only a reference to another storage location thatis also defined as a user key with which one or morePII-classified storage locations are associated. In thisinstance, the user key is not known by the PII owner.

Glossary 45

Index

AaccessPII 19API (application programming

interface) 1, 17architecture, monitor 9attribute

storage location 11

Bbackground execution 31

Cclass

exceptionMonitorException 20MonitorParameterException 20

helperMonitorSupport 20

commandJava 35launchClient 35setupClient 35

conditionmonitor handling of 7PII usage 4

copySLocForReporting 20createEvalResult 20createSLocForRegistration 20customer support vii

Ddatabase

monitor 11DB2 database 2debugging monitor 30directory

LDAP 9monitor 11object 11

directory names, notation viidocuments

accessing online vifeedback viprerequisite vrelated v

EEAR file 1EJB (Enterprise Java Bean) 2EJB (Enterprize Java Bean) 10environment

EJB client 34monitor

development 23requirement 8

environment (continued)run-time 33runtime 8Tivoli Privacy Manager 2variables, notation viiWebSphere Application Server,

setup 36WebSphere client 8WebSphere J2EE Application Client,

setup 34WebSphere Thin Client, setup 35

EvalResultInfo 18EvalRuleInfo 18evaluation rule 5exception

keyword 20message string 20nested 20strategies for handling 29

Ffile

EAR 1, 36JAR 1, 8, 23, 36properties 36

J2EE 34foreign key 12

GgetRegisteredMonitor 18getSLocList 19getSLocListUpdates 19

Iinitialization 24installation, requirement 8internationalization 36

JJ2EE 2

properties file 34JAR file 1Java

class 1MonitorException 20MonitorParameterException 20MonitorRemoteException 21MonitorSupport 20

exceptionmessage string 20nested 20

method 1, 18Java command 35Javadoc 1, 17, 20JDBC driver 15

Kkey

foreign 12primary 12

LlaunchClient command 35log

audit 6

Mmaster key

monitor support of 6method

accessPII 19, 29copySLocForReporting 20createEvalResult 20createSLocForRegistration 20getRegisteredMonitor 18, 31getSLocList 19getSLocListUpdates 19helper 20realTimeConfCheck 19, 28registerMonitor 19registerSLocList 19removeFromSLocList 19submitPII 19

monitorarchitecture 9database 11design

internationalizationconsideration 36

performance consideration 31programming consideration 23

development 23directory 11EAR file 36exception handling 29implementation 9

blueprint for 23initialization 24installation 8multiple part 12, 16, 33object

EvalResultInfo 18EvalRuleInfo 18MonitorInfo 17, 18SKey 18, 19SLocInfo 17, 19

PIIaccess 27submission 26

placement 15polling 25

last modified field 25programming 23register 1, 12


monitor (continued)responsibilities 10retrieve information 13shutdown 29startup 24support for debugging 30termination 29testing 23Tivoli Privacy Manager 2

MonitorException class 20MonitorInfo 17MonitorSupport class 20multiple part monitor 12, 33

Nname

storage location 12notation

environment variables viipath names viitypeface vii

Oobject

directory 11MonitorInfo 28, 31

Ppath names, notation viiperformance 31PII (personally identifiable

information) 1, 2access 3, 27

real-time enforcement of 28report 14

submission 3, 26report 14

prerequisite documents vprimary key 12privacy policy

define 4deploy 4enforce 14evaluation rule 5

privacy serveradapter 10interface 10

publicationsaccessing online vifeedback viprerequisite vrelated v

Rreal-time

conformancecheck 19

enforcement 15, 19PII access 28

realTimeConfCheck 19

registermonitor 12storage location 13

registerMonitor 19registerSLocList 19related documents vremoveFromSLocList 19

Ssetup

run-time environment 33WebSphere Application Server 36WebSphere J2EE Application

Client 34WebSphere Thin Client 35

setupClient command 35SKey 18SLocInfo 17startup 24storage

key 3location 3

alias 12attribute 11classification 5description 12name 12register 13

system 3, 9adapter 9gather information from 32identify relationships 11interface 9monitor mode, audit 14monitor mode, enforcement 14monitor, learns 11

storage locationretrieve information 13

submitPII 19

TTivoli Customer Support viiTivoli Privacy Manager

console 37environment 2installation 8key concept

condition 4PII 2PII access 3PII submission 3storage key 3storage location 3storage system 3

monitor 2, 5privacy policy 4server 9

communication 33methods for communicating

with 18polling 13

Tivoli Privacy Manager serverDB2 database 2Enterprise Java Bean 2

toolkit 1tuning control

concurrency 33queue length 33server communication 33

typeface conventions vii

Uuser

ID 3ID, monitor handling of 6key 3key, monitor handling of 6

UTC (coordinated universal time) 14

Vvariables, notation for vii

WWebSphere

application client 8, 34, 36application server 8, 36


Program Number: 5724–C07

Printed in U.S.A.

SC23-4790-00

Monitor Developer’s Guide - IBMpublib.boulder.ibm.com/tividd/td/ITPME/SC23-4790-00/en...The Tivoli...

Documents

Transcript of Monitor Developer’s Guide - IBMpublib.boulder.ibm.com/tividd/td/ITPME/SC23-4790-00/en...The Tivoli...