Путівник по Passay

1. Вступ

На сьогоднішній день у більшості веб-додатків існує своя політика щодо паролів - яка, простіше кажучи, створена для того, щоб змусити користувачів створювати важкі для злому паролі.

Щоб створити такі паролі або перевірити їх, ми можемо використовувати бібліотеку Passay.

2. Залежність Мавена

Якщо ми хочемо використовувати бібліотеку Passay у нашому проекті, необхідно додати наступну залежність до нашого pom.xml :

 org.passay passay 1.3.1 

Ми можемо знайти його тут.

3. Перевірка пароля

Перевірка пароля - одна з двох основних функціональних можливостей бібліотеки Passay. Це невимушено та інтуїтивно зрозуміло. Давайте відкриємо це.

3.1. PasswordData

Щоб перевірити наш пароль, ми повинні використовувати PasswordData. Це контейнер для інформації, необхідної для перевірки. Він може зберігати такі дані, як:

  • пароль
  • ім'я користувача
  • список посилань на паролі
  • походження

Властивості пароля та імені користувача пояснюють себе. Passay бібліотека дає нам HistoricalReference і SourceReference , які ми можемо додати до списку посилань пароля.

Ми можемо використовувати поле джерела для зберігання інформації про те, чи генерував пароль користувач або визначив його.

3.2. PasswordValidator

Ми повинні знати, що нам потрібні об’єкти PasswordData та PasswordValidator, щоб розпочати перевірку паролів. Ми вже обговорювали PasswordData . Давайте створимо PasswordValidator зараз.

По-перше, слід визначити набір правил перевірки пароля. Ми повинні передати їх конструктору під час створення об'єкта PasswordValidator :

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

Існує два способи передачі нашого пароля об’єкту PasswordData . Ми передаємо його або конструктору, або методу сеттера:

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

Ми можемо перевірити наш пароль, викликавши метод validate () на PasswordValidator :

RuleResult validate = passwordValidator.validate(passwordData);

В результаті ми отримаємо об'єкт RuleResult .

3.3. RuleResult

RuleResult містить цікаву інформацію про процес перевірки. Це відбувається в результаті методу validate () .

Перш за все, це може сказати нам, чи дійсний пароль:

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

Більше того, ми можемо дізнатися, які помилки повертаються, коли пароль недійсний. Коди помилок та описи перевірки зберігаються в 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"));

Нарешті, ми можемо дослідити метадані перевірки пароля за допомогою RuleResultMetadata :

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

4. Генерація пароля

На додаток до перевірки, бібліотека Passay дозволяє нам генерувати паролі. Ми можемо надати правила, якими повинен користуватися генератор.

Для генерації пароля нам потрібно мати об’єкт PasswordGenerator . Після того, як він у нас є, ми викликаємо метод createPassword () і передаємо список CharacterRules . Ось зразок коду:

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"));

Ми повинні знати, що нам потрібен об’єкт CharacterData для створення CharacterRule . Ще одним цікавим фактом є те, що бібліотека надає нам EnglishCharacterData. Це перелік з п’яти наборів символів:

  • цифри
  • мала літера англійського алфавіту
  • великий англійський алфавіт
  • поєднання набору з малої та великої літер
  • спеціальні символи

Однак ніщо не може завадити нам визначити наш набір символів. Це так само просто, як реалізація інтерфейсу CharacterData . Давайте подивимося, як ми можемо це зробити:

CharacterRule specialCharacterRule = new CharacterRule(new CharacterData() { @Override public String getErrorCode() { return "SAMPLE_ERROR_CODE"; } @Override public String getCharacters() { return "[email protected]#"; } }); PasswordGenerator passwordGenerator = new PasswordGenerator(); String password = passwordGenerator.generatePassword(10, specialCharacterRule); Assert.assertTrue(containsOnlyCharactersFromSet(password, "[email protected]#"));

5. Позитивні правила відповідності

Ми вже дізналися, як ми можемо створювати та перевіряти паролі. Для цього нам потрібно визначити набір правил. З цієї причини ми повинні знати, що у Passay є два типи правил : правила позитивного збігу та правила збігу негативних.

По-перше, давайте з’ясуємо, які є позитивні правила та як ми можемо ними користуватися.

Правила позитивного збігу приймають паролі, що містять надані символи, регулярні вирази або вміщують деякі обмеження.

Існує шість правил позитивного збігу:

  • 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 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.

Але слід пам’ятати, що сама бібліотека Passay не робить наш пароль надійним. По-перше, ми повинні вивчити загальні правила, а потім використовувати бібліотеку для їх реалізації.

Усі приклади, як завжди, можна знайти на GitHub.