Provides a framework and an application programming interface to generate and validate passwords.


Interface Summary
PasswordGenerator Interface which needs to be implemented by all custom password generators.
Rule This interface needs to be implemented by all standard and custom password rule classes.
ValidationInfo Interface for classes providing contextual information used to validate passwords.

Class Summary
BehavioralRule Abstract base class for Rule implementations that provide validation of password's behavior.
LexicalRule Abstract base class for Rule implementations that provide validation of password's lexical content.

Exception Summary
IncompatibleRulesException IncompatibleRulesException is thrown when given two rules cannot be joined because they are not compatible.
InvalidPasswordException Objects of this class are thrown when a password violates one of the rules.
IterationsExceededException Class represents an exception, which is thrown if the allowed number of iterations was exceeded while generating a random password satisfying all associated password rules.

Package Description

Provides a framework and an application programming interface to generate and validate passwords.


The Password Rules API has been developed to provide the developers a means for adding custom rules to the password validation engine of Identity Manager or for overriding the default password generation algorithm that Identity Manager uses. The Identity Manager password engine will invoke custom logic for both of these purposes if the steps outlined below are taken.

The Password Rules API is organized at two levels of abstraction. The base level of abstraction only addresses a generic password environment. The only context of the password engine is a single generic object with a password and other general attributes. The second level of abstraction is specific to provisioning. At this level, the context of the password engine is assumed to be an account, whereby the attributes of the account are available, as well as the attributes of the identity that owns the account and the service that hosts the account. The engine being extended will determine the abstraction, or the context, being used when executing rules. In other words, if the client is customizing the password engine of a simple identity password management application the base context will be available, whereas if the client is customizing the Identity Manager provisioning product the provisioning context will be available. A better explanation of this will be provided below.

API Description

The Password Rules API consists of a set of classes that provide interfaces that clients can implement so that their custom algorithms can participate in the password validation and password generation frameworks. The UML class diagram in Figure 1 below illustrates the primary objects in these frameworks and their relationships.

Figure 1 - Password Rules Class Diagram

Rule is an interface that defines the requirements of one specific password rule. The client will provide an implementation to these requirements and this interface in order for their custom rule algorithm to be integrated into the rules framework. A Rule gets its context, id of password protected object, password history, and other attributes of the password protected object, from an implementation of the ValidationInfo interface. The password rules engine generates the context and provides it to the Rule implementation at the time of evaluation.

The password rules framework supports the merging, or joining, of multiple rule sets with overlapping rules when validating a single password. For example, the framework can evaluate to two rule sets, each defining a minimum length rule. The engine will attempt to validate the single password against both rules. In this example, this appears simple, the engine could simply evaluate the password against the rules one at a time. However, it is not so easy to relay to a client what the password rule requirements are without listing them one at a time, which could become overwhelming if there are many rules and many rule sets that are configured. For this reason, any class implementing Rule interface is expected to provide logic in a join() method, which would allow joining parameters of two rules of the same type and returning that one rule definition. So, in our example of two rule sets with a minimum length rule, if one rule defined a minimum length of 6 and the other defined 8, the join() method on the Rule implementation would return 8. This is the resulting requirement for the minimum length of a password.

A Rule is also involved in the password generation process. The PasswordGenerator interface defines the requirements of the password generation engine. To override the generation algorithm of the platform, the client can provide an alternative implementation of this interface. At the time of password generation, the PasswordGenerator will be passed to each Rule instance in the framework as a visitor where the Rule can provide information to the PasswordGenerator to constrain the construction of the password being generated. For example, if a Rule defines a minimum of 6 characters is required for a password; this information is provided to the PasswordGenerator so that it does not generate a password with under 6 characters.

As an extension to the base password rules framework, the Identity Manager provisioning product provides additional provisioning specific context information, such as owner and service related attributes, to the Rules in the framework through the ProvisioningValidationInfo interface. This interface extends the ValidationInfo interface. Rule implementations that are built specifically for provisioning can make use of this information by down-casting the ValidationInfo object passed to the Rule at validation time. This, however, makes the Rule implementation provisioning specific and can not be used in a more general purpose password management rules engine. The ProvisioningValidationInfo interface can be found in the package.

The package provides a set of standard password rules and a standard password generator. This package is available by default in a password rules engine utilizing this framework. Clients of this API can extend these classes if they wish to add logic to the existing algorithms.

API Example

For a working code example of the Password Rules API usage, please see the tim_home/extensions/examples/passwordrules directory.

Rule Registration

After a custom password rule has been developed that implements the Rule interface, that rule must be compiled and placed in the Identity Manager classpath. At this point the class can be instantiated within the Identity Manager process, however the password rules framework does not know that this class should be used within the engine. The class must then be registered with the engine by placing the full class name of the new rule in the file. The class is listed as a key in the properties file. The prefix for the password rule key is "password.rule". The format of the line in the properties file is:


The line below illustrates registering an "illegal pattern" rule implemented by the class.

‘=true' in this example indicates, that the rule requires an input parameter.

A custom password rule may be one of two types:

  1. Password rule requires input parameter:
    This can be configured in the file by specifying boolean value 'true', after '='. Following additional callback methods are called by ITIM server to set and get the parameters;
    1. void setParameter(java.lang.String parameter),
    2. String getParameter()

  2. Password rule does not require input parameter:
    This can be configured in the file by specifying a boolean value 'false', after '='. In this case, following callback methods will NOT be called by ITIM server.
    1. void setParameter(java.lang.String parameter),
    2. String getParameter()

For example, the built-in minimum length rule requires a numeric parameter indicating what the minimum length is. However, the check dictionary rule does not need a parameter. It just needs to be toggled on or off by the administrator. If a rule requires a parameter, the Identity Manager password rules user interface will display a text field in which the administrator can provide a value. It is up to the administrator to format the contents of the parameter text in the way expected by the custom rule implementation. The password rules engine will pass unprocessed contents of the text field to the custom rule implementation class.

Finally, in order to provide an intuitive queue to the password rules administrator in the user interface, a label can be associated with the rule. This label, as are all labels in Identity Manager, can be localized. The label is defined in the with other labels, using a key=label property format. The key will be the same full class name of the Rule implementation and the label can be any text. To complete our example of the illegal pattern rule, the following line would be added to Pattern:

Generator Registration

Just as custom password rules must be registered with the Identity Manager engine, so must custom password generators. The custom password generator class must first be compiled and placed in the Identity Manager classpath. Then the class must be specified in the file. The prefix of the generator property is "generator." The full class name of the custom generator class is appended to that prefix. The line below illustrates registering a custom password generator implemented by the class.

If initialization context information s required for the custom generator implementation, they can be specified in the file as a value to the generator class key shown above. The format is:

generator.classname=context information

This information will be passed to the custom class’s initialize() method. In our CustomGenerator example, we will add two parameters that indicate we are using the generator in a provisioning system and that we’re deployed in a government environment. Since the property key-value pair format does not support multiple values out-of-the-box, we have delimited our value data. This is only an example as the engine will pass everything after the ‘=’ as one string to the initialize() call anyway.

The value of the string passed to CustomGenerator’s initialize() method will be "provisioning?government".

IBM Tivoli Identity Manager 4.6
© Copyright International Business Machines Corporation 2005. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.