Panduan untuk Passay

Pengaturcaraan

1. Pengenalan

Pada masa kini, kebanyakan aplikasi web mempunyai dasar kata laluan mereka - yang secara sederhana dibuat untuk memaksa pengguna membuat kata laluan yang sukar dipecahkan.

Untuk menghasilkan kata laluan tersebut atau mengesahkannya, kita dapat menggunakan perpustakaan Passay.

2. Ketergantungan Maven

Sekiranya kami ingin menggunakan perpustakaan Passay dalam projek kami, perlu menambahkan kebergantungan berikut ke pom.xml kami :

 org.passay passay 1.3.1

Kita boleh menemuinya di sini.

3. Pengesahan Kata Laluan

Pengesahan kata laluan adalah salah satu daripada dua fungsi utama yang disediakan oleh perpustakaan Passay. Ia mudah dan intuitif. Mari temui.

3.1. Kata LaluanData

Untuk mengesahkan kata laluan kami, kami harus menggunakan PasswordData. Ini adalah wadah untuk maklumat yang diperlukan untuk pengesahan. Ia dapat menyimpan data seperti:

  • kata laluan
  • nama pengguna
  • senarai rujukan kata laluan
  • asal

Sifat kata laluan dan nama pengguna menjelaskannya. Perpustakaan Passay memberi kami HistoricalReference dan SourceReference yang dapat kami tambahkan ke senarai rujukan kata laluan.

Kita boleh menggunakan bidang asal untuk menyimpan maklumat mengenai sama ada kata laluan dihasilkan atau ditentukan oleh pengguna.

3.2. Kata Laluan Pengesah

Kita perlu tahu bahawa kita perlu PasswordData dan PasswordValidator objek untuk mula mengesahkan kata laluan. Kami telah membincangkan PasswordData . Mari buat PasswordValidator sekarang.

Pertama, kita harus menentukan satu set peraturan untuk pengesahan kata laluan. Kita harus menyerahkannya ke konstruktor semasa membuat objek PasswordValidator :

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

Terdapat dua cara untuk menyampaikan kata laluan kami ke objek PasswordData . Kami menyebarkannya kepada kaedah konstruktor atau setter:

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

Kami boleh mengesahkan kata laluan kami dengan memanggil kaedah validate () pada PasswordValidator :

RuleResult validate = passwordValidator.validate(passwordData);

Hasilnya, kita akan mendapat objek RuleResult .

3.3. Keputusan Peraturan

RuleResult menyimpan maklumat menarik mengenai proses pengesahan. Ia datang sebagai hasil kaedah validate () .

Pertama sekali, ini dapat memberitahu kita sama ada kata laluan itu sah:

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

Selain itu, kita dapat mengetahui kesalahan apa yang dikembalikan apabila kata laluan tidak sah. Kod ralat dan perihalan pengesahan disimpan dalam 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"));

Akhirnya, kita dapat meneroka metadata pengesahan kata laluan dengan RuleResultMetadata :

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

4. Penjanaan Kata Laluan

Selain pengesahan, perpustakaan Passay membolehkan kami menghasilkan kata laluan. Kami boleh memberikan peraturan yang harus digunakan oleh penjana.

Untuk menghasilkan kata laluan, kita perlu mempunyai objek PasswordGenerator . Setelah memilikinya, kami memanggil kaedah createPassword () dan senarai lulus dari CharacterRules . Berikut adalah contoh kod:

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 bahawa kita memerlukan objek CharacterData untuk membuat CharacterRule . Fakta menarik yang lain adalah bahawa perpustakaan memberi kita EnglishCharacterData. Ini adalah jumlah lima set watak:

  • digit
  • huruf kecil Inggeris
  • huruf besar Inggeris
  • gabungan set huruf kecil dan huruf besar
  • watak khas

Namun, tidak ada yang dapat menghalang kita untuk menentukan kumpulan watak kita. Ia semudah melaksanakan antara muka CharacterData . Mari lihat bagaimana kita dapat 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. Peraturan Pencocokan Positif

Kami sudah belajar bagaimana kami dapat menghasilkan dan mengesahkan kata laluan. Untuk melakukan itu, kita perlu menentukan satu set peraturan. Untuk itu, kita harus tahu bahawa ada dua jenis peraturan yang ada di Passay : peraturan pencocokan positif dan peraturan pencocokan negatif.

Pertama, mari kita ketahui apakah peraturan positif dan bagaimana kita boleh menggunakannya.

Peraturan pencocokan positif menerima kata laluan yang mengandungi watak yang disediakan, ungkapan biasa atau sesuai dengan beberapa batasan.

Terdapat enam peraturan pemadanan 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 bahawa perpustakaan Passay itu sendiri tidak menjadikan kata laluan kita selamat. Pertama, kita harus belajar apa peraturan umum dan kemudian menggunakan perpustakaan untuk melaksanakannya.

Semua contoh, seperti biasa, terdapat di GitHub.