Skip to content

Commit d541c86

Browse files
martinspielmannmartinspielmann
committed
add javadoc
1 parent 4428f8b commit d541c86

File tree

4 files changed

+52
-23
lines changed

4 files changed

+52
-23
lines changed

‎pom.xml‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,17 +15,15 @@
1515
See the License for the specific language governing permissions and
1616
limitations under the License.
1717
-->
18-
<project xmlns="http://maven.apache.org/POM/4.0.0"
19-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
20-
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
18+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
2119

2220
<modelVersion>4.0.0</modelVersion>
2321
<groupId>de.martinspielmann.wicket</groupId>
2422
<artifactId>wicket-pwnedpasswords-validator</artifactId>
2523
<packaging>jar</packaging>
2624
<version>1.0.0-SNAPSHOT</version>
2725
<name>wicket-pwnedpasswords-validator</name>
28-
<description></description>
26+
<description />
2927
<licenses>
3028
<license>
3129
<name>The Apache Software License, Version 2.0</name>
@@ -47,7 +45,8 @@
4745
<connection>scm:git:[email protected]:pingunaut/wicket-pwnedpasswords-validator.git</connection>
4846
<developerConnection>scm:git:[email protected]:pingunaut/wicket-pwnedpasswords-validator.git</developerConnection>
4947
<url>[email protected]:pingunaut/wicket-pwnedpasswords-validator.git</url>
50-
</scm>
48+
<tag>wicket-pwnedpasswords-validator-1.0.0</tag>
49+
</scm>
5150

5251
<developers>
5352
<developer>

‎src/main/java/de/martinspielmann/wicket/pwnedpasswordsvalidator/PwnedPasswordsValidator.java‎

Lines changed: 45 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,9 @@
2222
* using API of <a href="https://haveibeenpwned.com/">https://haveibeenpwned.com/</a>
2323
* More details at <a href="https://haveibeenpwned.com/API/v2#PwnedPasswords">https://haveibeenpwned.com/API/v2#PwnedPasswords</a>
2424
*
25-
*
26-
*
2725
* @author Martin Spielmann
2826
*/
29-
public class PwnedPasswordsValidator implements IValidator<String>{
27+
public class PwnedPasswordsValidator implements IValidator<String> {
3028

3129
private static final Logger LOG = LoggerFactory.getLogger(PwnedPasswordsValidator.class);
3230

@@ -36,15 +34,43 @@ public class PwnedPasswordsValidator implements IValidator<String>{
3634
private final RateLimitExceededBehavior rateLimitExceededBehavior;
3735
private final Proxy proxy;
3836

39-
public PwnedPasswordsValidator(){
37+
/**
38+
* Creates a new PwnedPasswordsValidator with default configuration.
39+
* If an error occurs during validation, the validated password will be treated as invalid.
40+
* If the rate limit of the <a href="https://haveibeenpwned.com/API/v2#PwnedPasswords">have i been pwned? API</a> is reached,
41+
* the current Thread will sleep for two seconds before another validation will be triggered.
42+
* <strong>Warning:</strong> this might have negative impact on your application responsiveness depending on your app design.
43+
*/
44+
public PwnedPasswordsValidator() {
4045
this(true, RateLimitExceededBehavior.RETRY);
4146
}
4247

43-
public PwnedPasswordsValidator(boolean failOnUnknownError, RateLimitExceededBehavior rateLimitExceededBehavior){
48+
49+
/**
50+
* Creates a new PwnedPasswordsValidator
51+
*
52+
* @param failOnUnknownError If {@code true}, if an error occurs during validation, the validated password will be treated as invalid.
53+
* Else errors will be ignored and the password will be treated as valid.
54+
* @param rateLimitExceededBehavior If set to {@link RateLimitExceededBehavior#IGNORE}, if rate limit is exceeded during validation, the validated password will be treated as valid.
55+
* If set to {@link RateLimitExceededBehavior#RETRY}, if rate limit is exceeded during validation, the {@code Thread} will sleep for two seconds and validation will be retried afterwards.
56+
* If set to {@link RateLimitExceededBehavior#FAIL}, if rate limit is exceeded during validation, the validated password will be treated as invalid.
57+
*/
58+
public PwnedPasswordsValidator(boolean failOnUnknownError, RateLimitExceededBehavior rateLimitExceededBehavior) {
4459
this(failOnUnknownError, rateLimitExceededBehavior, null);
4560
}
4661

47-
public PwnedPasswordsValidator(boolean failOnUnknownError, RateLimitExceededBehavior rateLimitExceededBehavior, Proxy proxy){
62+
63+
/**
64+
* Creates a new PwnedPasswordsValidator
65+
*
66+
* @param failOnUnknownError If {@code true}, if an error occurs during validation, the validated password will be treated as invalid.
67+
* Else errors will be ignored and the password will be treated as valid.
68+
* @param rateLimitExceededBehavior If set to {@link RateLimitExceededBehavior#IGNORE}, if rate limit is exceeded during validation, the validated password will be treated as valid.
69+
* If set to {@link RateLimitExceededBehavior#RETRY}, if rate limit is exceeded during validation, the {@code Thread} will sleep for two seconds and validation will be retried afterwards.
70+
* If set to {@link RateLimitExceededBehavior#FAIL}, if rate limit is exceeded during validation, the validated password will be treated as invalid.
71+
* @param proxy the proxy server
72+
*/
73+
public PwnedPasswordsValidator(boolean failOnUnknownError, RateLimitExceededBehavior rateLimitExceededBehavior, Proxy proxy) {
4874
this.failOnUnknownError = failOnUnknownError;
4975
this.rateLimitExceededBehavior = rateLimitExceededBehavior;
5076
this.proxy = proxy;
@@ -57,7 +83,7 @@ public void validate(IValidatable<String> validatable) {
5783

5884
switch (status) {
5985
case UNKNOWN_API_ERROR:
60-
if (shouldFailOnUnknownError()){
86+
if (shouldFailOnUnknownError()) {
6187
validatable.error(decorate(new ValidationError(this, "unknownError"), validatable));
6288
}
6389
break;
@@ -91,15 +117,16 @@ protected void handleToManyRequests(IValidatable<String> validatable) {
91117
}
92118
}
93119

94-
protected Status getResponseStatus(String pw){
120+
protected Status getResponseStatus(String pw) {
95121
try {
96122
HttpURLConnection c;
97-
if (getProxy() != null){
123+
if (getProxy() != null) {
98124
c = (HttpURLConnection) getApiUrl(pw).openConnection(getProxy());
99-
}else{
125+
} else {
100126
c = (HttpURLConnection) getApiUrl(pw).openConnection();
101127
}
102128
c.setRequestMethod("GET");
129+
// for some reason, we don't get a response without setting a user agent
103130
c.setRequestProperty("User-Agent", "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.4; en-US; rv:1.9.2.2) Gecko/20100316 Firefox/3.6.2");
104131
c.connect();
105132
return Status.of(c.getResponseCode());
@@ -113,26 +140,28 @@ protected Proxy getProxy() {
113140
return proxy;
114141
}
115142

116-
protected boolean shouldFailOnUnknownError(){
143+
protected boolean shouldFailOnUnknownError() {
117144
return failOnUnknownError;
118145
}
119146

120-
protected RateLimitExceededBehavior getRateLimitExceededBehavior(){
147+
protected RateLimitExceededBehavior getRateLimitExceededBehavior() {
121148
return rateLimitExceededBehavior;
122149
}
123150

124151
protected URL getApiUrl(String pw) throws MalformedURLException, NoSuchAlgorithmException {
125152
return new URL(String.format(API_URL, sha1(pw)));
126153
}
127154

155+
128156
/**
129157
* The API allows to check passwords directly. To avoid url encoding issues with complicated passwords,
130158
* we use the possibility to check sha1 hashes
131159
*
132160
* @param pw the password
133-
* @return sha1 hash of the given passwird
161+
* @return sha1 hash of the given password
162+
* @throws NoSuchAlgorithmException if SHA-1 digest not available
134163
*/
135-
protected String sha1(String pw) throws NoSuchAlgorithmException{
164+
protected String sha1(String pw) throws NoSuchAlgorithmException {
136165
MessageDigest digest = MessageDigest.getInstance("SHA-1");
137166
byte[] encodedhash = digest.digest(pw.getBytes(StandardCharsets.UTF_8));
138167
return Strings.toHexString(encodedhash);
@@ -141,8 +170,8 @@ protected String sha1(String pw) throws NoSuchAlgorithmException{
141170
/**
142171
* Allows subclasses to decorate reported errors
143172
*
144-
* @param error
145-
* @param validatable
173+
* @param error the error
174+
* @param validatable the validatable
146175
* @return decorated error
147176
*/
148177
protected IValidationError decorate(IValidationError error, IValidatable<String> validatable) {

‎src/main/java/de/martinspielmann/wicket/pwnedpasswordsvalidator/RateLimitExceededBehavior.java‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
package de.martinspielmann.wicket.pwnedpasswordsvalidator;
22

3+
34
/**
45
* Requests to the breaches and pastes APIs are limited to one per every 1500 milliseconds each
56
* from any given IP address (an address may request both APIs within this period).
67
* Any request that exceeds the limit will receive an HTTP 429 "Too many requests" response.
78
*
8-
* @return
9+
* @author Martin Spielmann
910
*/
1011
public enum RateLimitExceededBehavior {
1112
FAIL, RETRY, IGNORE

‎src/main/java/de/martinspielmann/wicket/pwnedpasswordsvalidator/Status.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
import java.util.Map;
55

66
/**
7-
* Represents the status of haveibeenpwned API response.
7+
* Represents the status of have i been pwned? API response.
88
*
99
* @author Martin Spielmann
1010
*/

0 commit comments

Comments
 (0)