Panduan untuk Passay

1. Perkenalan

Saat ini, sebagian besar aplikasi web memiliki kebijakan kata sandi mereka - yang, sederhananya, dibuat untuk memaksa pengguna membuat kata sandi yang sulit dibobol.

Untuk menghasilkan kata sandi tersebut atau memvalidasinya, kita dapat menggunakan perpustakaan Passay.

2. Ketergantungan Maven

Jika kita ingin menggunakan pustaka Passay dalam proyek kita, itu perlu untuk menambahkan ketergantungan berikut ke pom.xml kita :

 org.passay passay 1.3.1 

Kita bisa menemukannya disini.

3. Validasi Kata Sandi

Validasi kata sandi adalah salah satu dari dua fungsi utama yang disediakan oleh perpustakaan Passay. Mudah dan intuitif. Mari kita temukan.

3.1. PasswordData

Untuk memvalidasi kata sandi kami, kami harus menggunakan PasswordData. Ini adalah wadah untuk informasi yang diperlukan untuk validasi. Itu dapat menyimpan data seperti:

  • kata sandi
  • nama pengguna
  • daftar referensi kata sandi
  • asal

Properti kata sandi dan nama pengguna menjelaskan sendiri. Perpustakaan Passay memberi kita HistoricalReference dan SourceReference yang dapat kita tambahkan ke daftar referensi kata sandi.

Kita dapat menggunakan bidang asal untuk menyimpan informasi tentang apakah kata sandi dibuat atau ditentukan oleh pengguna.

3.2. PasswordValidator

Kita harus tahu bahwa kita memerlukan objek PasswordData dan PasswordValidator untuk mulai memvalidasi kata sandi. Kami sudah membahas PasswordData . Mari buat PasswordValidator sekarang.

Pertama, kita harus menetapkan seperangkat aturan untuk validasi kata sandi. Kita harus meneruskannya ke konstruktor saat membuat objek PasswordValidator :

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

Ada dua cara untuk meneruskan kata sandi kami ke objek PasswordData . Kami meneruskannya ke konstruktor atau metode penyetel:

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

Kami dapat memvalidasi kata sandi kami dengan memanggil metode validate () di PasswordValidator :

RuleResult validate = passwordValidator.validate(passwordData);

Hasilnya, kita akan mendapatkan objek RuleResult .

3.3. RuleResult

RuleResult menyimpan informasi menarik tentang proses validasi. Itu datang sebagai hasil dari metode validate () .

Pertama-tama, ini dapat memberi tahu kami apakah kata sandi itu valid:

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

Selain itu, kita dapat mempelajari kesalahan apa yang dikembalikan ketika kata sandi tidak valid. Kode kesalahan dan deskripsi validasi disimpan di 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"));

Terakhir, kita bisa menjelajahi metadata validasi kata sandi dengan RuleResultMetadata :

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

4. Pembuatan Kata Sandi

Selain validasi, pustaka Passay memungkinkan kami membuat kata sandi. Kami dapat memberikan aturan yang harus digunakan generator.

Untuk membuat kata sandi, kita perlu memiliki objek PasswordGenerator . Setelah kita memilikinya, kita memanggil metode generatePassword () dan mengirimkan daftar CharacterRules . Berikut ini contoh kode:

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

Kita harus tahu bahwa kita membutuhkan objek CharacterData untuk membuat CharacterRule . Fakta menarik lainnya adalah bahwa perpustakaan memberi kita EnglishCharacterData. Ini adalah enum dari lima set karakter:

  • digit
  • huruf kecil alfabet Inggris
  • huruf besar alfabet Inggris
  • kombinasi set huruf kecil dan huruf besar
  • karakter spesial

Namun, tidak ada yang dapat menghentikan kami untuk menentukan kumpulan karakter kami. Ini semudah mengimplementasikan antarmuka CharacterData . Mari kita lihat bagaimana kita bisa melakukannya:

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. Aturan Pencocokan Positif

Kami telah mempelajari bagaimana kami dapat menghasilkan dan memvalidasi kata sandi. Untuk melakukan itu, kita perlu mendefinisikan seperangkat aturan. Oleh karena itu, kita harus mengetahui bahwa ada dua jenis aturan yang tersedia di Passay : aturan pencocokan positif dan aturan pencocokan negatif.

Pertama, mari kita cari tahu apa saja aturan positifnya dan bagaimana kita bisa menggunakannya.

Aturan pencocokan positif menerima sandi yang berisi karakter yang disediakan, ekspresi reguler, atau cocok dalam beberapa batasan.

Ada enam aturan pencocokan positif:

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

Tetapi kita harus ingat bahwa pustaka Passay itu sendiri tidak membuat kata sandi kita aman. Pertama, kita harus mempelajari apa itu aturan umum dan kemudian menggunakan perpustakaan untuk mengimplementasikannya.

Semua contoh, seperti biasa, dapat ditemukan di GitHub.