Guide to Passay

1. Introduction

Nowadays, most web applications have their password policy – which is, simply put, created to force users to create difficult to break passwords.

To generate such passwords or validate them we can make use of Passay library.

2. Maven Dependency

If we want to use Passay library in our project, it’s necessary to add the following dependency to our pom.xml:

<dependency>
    <groupId>org.passay</groupId>
    <artifactId>passay</artifactId>
    <version>1.3.1</version>
</dependency>

We can find it here.

3. Password Validation

Password validation is one of two main functionalities provided by Passay library. It’s effortless and intuitive. Let’s discover it.

3.1. PasswordData

To validate our password, we should use PasswordData. It’s a container for information that is necessary for validation. It can store such data as:

• password
• username
• list of password references
• origin

Password and username properties explain themselves. Passay library gives us HistoricalReference and SourceReference which we can add to the list of password references.

We can use the origin field to hold information about whether the password was generated or defined by a user.

3.2. PasswordValidator

We should know that we need PasswordData and PasswordValidator objects to start validating passwords. We’ve already discussed PasswordData. Let’s create PasswordValidator now.

Firstly, we should define a set of rules for password validation. We have to pass them to constructor while creating a PasswordValidator object:

PasswordValidator passwordValidator = new PasswordValidator(new LengthRule(5));

There are two ways of passing our password to a PasswordData object. We pass it to either the constructor or the setter method:

PasswordData passwordData = new PasswordData("1234");

PasswordData passwordData2 = new PasswordData();
passwordData.setPassword("1234");

We can validate our password by calling validate() method on PasswordValidator:

RuleResult validate = passwordValidator.validate(passwordData);

As a result, we’ll get a RuleResult object.

3.3. RuleResult

RuleResult holds interesting information about a validation process. It comes as a result of the validate() method.

First of all, it can tell us whether the password is valid:

Assert.assertEquals(false, validate.isValid());

Moreover, we can learn what errors are returned when the password is invalid. Error codes and validation descriptions are kept in RuleResultDetail:

RuleResultDetail ruleResultDetail = validate.getDetails().get(0);
Assert.assertEquals("TOO_SHORT", ruleResultDetail.getErrorCode());
Assert.assertEquals(5, ruleResultDetail.getParameters().get("minimumLength"));
Assert.assertEquals(5, ruleResultDetail.getParameters().get("maximumLength"));

Finally, we can explore the password validation’s metadata with RuleResultMetadata:

Integer lengthCount = validate
  .getMetadata()
  .getCounts()
  .get(RuleResultMetadata.CountCategory.Length);
Assert.assertEquals(Integer.valueOf(4), lengthCount);

4. Password Generation

In addition to validation, the Passay library enables us to generate passwords. We can provide rules which the generator should use.

To generate a password, we need to have a PasswordGenerator object. Once we have it, we call the generatePassword() method and pass list of CharacterRules. Here is a sample code:

CharacterRule digits = new CharacterRule(EnglishCharacterData.Digit);

PasswordGenerator passwordGenerator = new PasswordGenerator();
String password = passwordGenerator.generatePassword(10, digits);

Assert.assertTrue(password.length() == 10);
Assert.assertTrue(containsOnlyCharactersFromSet(password, "0123456789"));

We should know that we need an object of CharacterData to create CharacterRule. Another interesting fact is that the library provides us with EnglishCharacterData. It is an enum of five sets of characters:

• digits
• lowercase English alphabet
• uppercase English alphabet
• combination of lowercase and uppercase sets
• special characters

However, nothing can stop us from defining our set of characters. It’s as straightforward as implementing the CharacterData interface. Let’s see how we can do it:

CharacterRule specialCharacterRule = new CharacterRule(new CharacterData() {
    @Override
    public String getErrorCode() {
        return "SAMPLE_ERROR_CODE";
    }

    @Override
    public String getCharacters() {
        return "ABCxyz123!@#";
    }
});

PasswordGenerator passwordGenerator = new PasswordGenerator();
String password = passwordGenerator.generatePassword(10, specialCharacterRule);

Assert.assertTrue(containsOnlyCharactersFromSet(password, "ABCxyz123!@#"));

5. Positive Matching Rules

We’ve already learned how we can generate and validate passwords. To do that, we need to define a set of rules. For that reason, we should know that there are two types of rules available in Passay: positive matching rules and negative matching rules.

Firstly, let’s find out what are the positive rules and how we can use them.

Positive matching rules accept passwords which contain provided characters, regular expressions or fits in some limitations.

There are six positive matching rules:

• AllowedCharacterRule – defines all characters that the password must include
• AllowedRegexRule – defines a regular expression which the password must match
• CharacterRule – defines a character set and a minimal number of characters that should be included in the password
• LengthRule – defines a minimal length of the password
• CharacterCharacteristicsRule – checks whether the password fulfills N of defined rules.
• LengthComplexityRule – allows us to define different rules for different password lengths

5.1. Simple Positive Matching Rules

Now, we’ll cover all the rules that have a simple configuration. They define a set of legal characters or patterns or an acceptable password’s length.

Here’s a short example of the discussed rules:

PasswordValidator passwordValidator = new PasswordValidator(
  new AllowedCharacterRule(new char[] { 'a', 'b', 'c' }), 
  new CharacterRule(EnglishCharacterData.LowerCase, 5), 
  new LengthRule(8, 10)
);

RuleResult validate = passwordValidator.validate(new PasswordData("12abc"));

assertFalse(validate.isValid());
assertEquals(
  "ALLOWED_CHAR:{illegalCharacter=1, matchBehavior=contains}", 
  getDetail(validate, 0));
assertEquals(
  "ALLOWED_CHAR:{illegalCharacter=2, matchBehavior=contains}", 
  getDetail(validate, 1));
assertEquals(
  "TOO_SHORT:{minimumLength=8, maximumLength=10}", 
  getDetail(validate, 4));

We can see that each rule gives us a clear explanation if the password is not valid. There are notifications that the password is too short and has two illegal characters. We can also notice that the password doesn’t match the provided regular expression.

What’s more, we’re informed that it contains insufficient lowercase letters.

5.2. CharacterCharacterisitcsRule

CharcterCharacterisitcsRule is more complex than rules presented before. To create a CharcterCharacterisitcsRule object, we need to provide a list of CharacterRules. What’s more, we have to set how many of them the password must match. We can do it this way:

CharacterCharacteristicsRule characterCharacteristicsRule = new CharacterCharacteristicsRule(
  3, 
  new CharacterRule(EnglishCharacterData.LowerCase, 5), 
  new CharacterRule(EnglishCharacterData.UpperCase, 5), 
  new CharacterRule(EnglishCharacterData.Digit),
  new CharacterRule(EnglishCharacterData.Special)
);

Presented CharacterCharacteristicsRule requires a password to contain three of four provided rules.

5.3. LengthComplexityRule

On the other hand, Passay library provides us with LengthComplexityRule. It allows us to define which rules should be applied to the password of which length. In contrast to CharacterCharacteristicsRule, they allow us to use all kind of rules – not only CharacterRule.

Let’s analyze the example:

LengthComplexityRule lengthComplexityRule = new LengthComplexityRule();
lengthComplexityRule.addRules("[1,5]", new CharacterRule(EnglishCharacterData.LowerCase, 5));
lengthComplexityRule.addRules("[6,10]", 
  new AllowedCharacterRule(new char[] { 'a', 'b', 'c', 'd' }));

As we can see for password having one to five characters, we apply CharacterRule. But for a password containing six to ten characters, we want the password to match AllowedCharacterRule.

6. Negative Matching Rules

Unlike positive matching rules, negative matching rules reject passwords that contain provided characters, regular expressions, entries, etc.

Let’s find out what are the negative matching rules:

• IllegalCharacterRule – defines all characters that a password mustn’t contain
• IllegalRegexRule – defines a regular expression which mustn’t match
• IllegalSequenceRule – checks whether a password has an illegal sequence of characters
• NumberRangeRule – defines a range of numbers which a password mustn’t contain
• WhitespaceRule – checks whether a password contains whitespaces
• DictionaryRule – checks whether a password is equal to any dictionary record
• DictionarySubstringRule – checks whether a password contain any dictionary record
• HistoryRule – checks whether a password contains any historical password reference
• DigestHistoryRule – checks whether a password contains any digested historical password reference
• SourceRule – checks whether a password contains any source password reference
• DigestSourceRule – checks whether a password contains any digest source password reference
• UsernameRule – checks whether a password contains a username
• RepeatCharacterRegexRule – checks whether a password contains repeated ASCII characters

6.1. Simple Negative Matching Rules

Firstly, we’re going to see how we can use simple rules such as IllegalCharacterRule, IllegalRegexRule, etc. Here is a short example:

PasswordValidator passwordValidator = new PasswordValidator(
  new IllegalCharacterRule(new char[] { 'a' }), 
  new NumberRangeRule(1, 10), 
  new WhitespaceRule()
);

RuleResult validate = passwordValidator.validate(new PasswordData("abcd22 "));

assertFalse(validate.isValid());
assertEquals(
  "ILLEGAL_CHAR:{illegalCharacter=a, matchBehavior=contains}", 
  getDetail(validate, 0));
assertEquals(
  "ILLEGAL_NUMBER_RANGE:{number=2, matchBehavior=contains}", 
  getDetail(validate, 4));
assertEquals(
  "ILLEGAL_WHITESPACE:{whitespaceCharacter= , matchBehavior=contains}", 
  getDetail(validate, 5));

The example shows us how the described rules work. Similarly to positive matching rules, they give us full feedback about validation.

6.2. Dictionary Rules

What if we want to check whether a password is not equal to provided words.

For that reason, the Passay library gives us excellent tools for that. Let’s discover DictionaryRule and DictionarySubstringRule:

WordListDictionary wordListDictionary = new WordListDictionary(
  new ArrayWordList(new String[] { "bar", "foobar" }));

DictionaryRule dictionaryRule = new DictionaryRule(wordListDictionary);
DictionarySubstringRule dictionarySubstringRule = new DictionarySubstringRule(wordListDictionary);

We can see dictionary rules enable us to provide a list of banned words. It’s beneficial when we have a list of the most common or the easiest to break passwords. Therefore, it’s reasonable to prohibit users from using them.

In real life, we would certainly load a list of words from a text file or a database. In that case, we can use WordLists. It has three overloaded methods that take an array of Readers and create ArrayWordList.

6.3. HistoryRule and SourceRule

Furthermore, the Passay library gives us HistoryRule and SourceRule. They can validate passwords against historical passwords or text content from various sources.

Let’s take a look at the example:

SourceRule sourceRule = new SourceRule();
HistoryRule historyRule = new HistoryRule();

PasswordData passwordData = new PasswordData("123");
passwordData.setPasswordReferences(
  new PasswordData.SourceReference("source", "password"), 
  new PasswordData.HistoricalReference("12345")
);

PasswordValidator passwordValidator = new PasswordValidator(
  historyRule, sourceRule);

HistoryRules help us checking whether a password has been used before. Because such practices are insecure, we don’t want users to use old passwords.

On the other hand, SourceRule allows us to check whether the password is different than those provided in SourceReferences. We can avoid the risk of having the same passwords in different systems or applications.

It’s worth mentioning that there are such rules as DigestSourceRule and DigestHistoryRule. We’ll cover them in the next paragraph.

6.4. Digest Rules

There are two digest rules in the Passay library: DigestHistoryRule and DigestSourceRule. Digest rules are intended to work with passwords stored as digest or hash. Hence, to define them we need to provide an EncodingHashBean object.

Let’s see how it’s done:

List<PasswordData.Reference> historicalReferences = Arrays.asList(
  new PasswordData.HistoricalReference(
    "SHA256",
    "2e4551de804e27aacf20f9df5be3e8cd384ed64488b21ab079fb58e8c90068ab"
));

EncodingHashBean encodingHashBean = new EncodingHashBean(
  new CodecSpec("Base64"), 
  new DigestSpec("SHA256"), 
  1, 
  false
);

This time we create HistoricalReference by a label and the encoded password to the constructor. After that, we’ve instantiated EncodingHashBean with the proper Codec and digest algorithm.

Additionally, we can specify the number of iterations and whether the algorithm is salted.

Once, we have an encoding bean, we can validate our digest password:

PasswordData passwordData = new PasswordData("example!");
passwordData.setPasswordReferences(historicalReferences);

PasswordValidator passwordValidator = new PasswordValidator(new DigestHistoryRule(encodingHashBean));

RuleResult validate = passwordValidator.validate(passwordData);

Assert.assertTrue(validate.isValid());

We can learn more about EncodingHashinBean at Cryptacular library webpage.

6.5. RepeatCharacterRegexRule

Another interesting validation rule is RepeatCharacterRegexRule. We can use it to check whether password contains repeating ASCII characters.

Here’s a sample code:

PasswordValidator passwordValidator = new PasswordValidator(new RepeatCharacterRegexRule(3));

RuleResult validate = passwordValidator.validate(new PasswordData("aaabbb"));

assertFalse(validate.isValid());
assertEquals("ILLEGAL_MATCH:{match=aaa, pattern=([^\\x00-\\x1F])\\1{2}}", getDetail(validate, 0));

6.6. UsernameRule

The last rule we’re going to discuss in this chapter is UsernameRule. It enables us to prohibit using the user’s name in the password. 

As we’ve learned before, we should store the username in PasswordData:

PasswordValidator passwordValidator = new PasswordValidator(new UsernameRule());

PasswordData passwordData = new PasswordData("testuser1234");
passwordData.setUsername("testuser");

RuleResult validate = passwordValidator.validate(passwordData);

assertFalse(validate.isValid());
assertEquals("ILLEGAL_USERNAME:{username=testuser, matchBehavior=contains}", getDetail(validate, 0));

7. Customized Messages

Passay library enables us to customize messages returned by validation rules. Firstly, we should define the messages and assign them to error codes.

We can put them into a simple file. Let’s see how easy it is:

TOO_LONG=Password must not have more characters than %2$s.
TOO_SHORT=Password must not contain less characters than %2$s.

Once we have messages, we have to load that file. Finally, we can pass it into PasswordValidator object.

Here is a sample code:

URL resource = this.getClass().getClassLoader().getResource("messages.properties");
Properties props = new Properties();
props.load(new FileInputStream(resource.getPath()));

MessageResolver resolver = new PropertiesMessageResolver(props);

As we can see, we’ve loaded the message.properties file and passed it into Properties object. Then, we can use the Properties object to create PropertiesMessageResolver.

Let’s take a look at the example how to use the message resolver:

PasswordValidator validator = new PasswordValidator(
  resolver, 
  new LengthRule(8, 16), 
  new WhitespaceRule()
);

RuleResult tooShort = validator.validate(new PasswordData("XXXX"));
RuleResult tooLong = validator.validate(new PasswordData("ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ"));

Assert.assertEquals(
  "Password must not contain less characters than 16.", 
  validator.getMessages(tooShort).get(0));
Assert.assertEquals(
  "Password must not have more characters than 16.", 
  validator.getMessages(tooLong).get(0));

The example clearly shows that we can translate all error codes with the validator equipped with a message resolver.

8. Conclusion

In this tutorial, we’ve learned how to use Passay library. We have analyzed several examples of how the library can be easily used for password validation. Provided rules cover most of the common ways of assuring that a password is safe.

But we should remember that Passay library itself doesn’t make our password secure. Firstly, we should learn what are general rules and then use the library to implement them.

All examples, as always, can be found over on GitHub.