Subversion Repositories php_clientchallenge

Rev

Rev 2 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
12 daniel-mar 1 
 
2 
 
2 daniel-mar 3 
# Server requests using client challenges
4 
 
5 
### What is it?
6 
This PHP/JavaScript package can be used to add client challenges on top of your
7 
AJAX requests to protect your scripts against brute-force or DoS attacks.
8 
It can also protect your server against resource starvation attacks, for example,
9 
if you have a login script that uses a complex hash algorithm like BCrypt.
10 
 
11 
### Usage example
12 
A usage example is located in the directory example/
13 
 
14 
### System requirements
12 daniel-mar 15 
- PHP-compatible web server (tested with Apache 2, nginx, and Microsoft IIS)
2 daniel-mar 16 
- PHP 7.0 or higher (also tested with PHP 8.0)
17 
- Independent of operating system (tested with Windows, Linux, and macOS X)
18 
 
12 daniel-mar 19 
 
20 
### Program flow
21 
 
22 
#### 1. Request from Client to Server (Get Challenge)
23 
Request parameters:
24 
- None
25 
 
26 
The server will generate a secret random number between Min and Max.
27 
The difference between Min and Max is the complexity constant.
28 
 
29 
Response:
30 
- Current time ("Start time")
31 
- IP address of the client
32 
- Challenge = `Hash(StartTime + IP address + Random number)`
33 
- Min value
34 
- Max value
35 
- Challenge integrity = `Hash_HMAC(Challenge, ServerSecret)`
36 
 
37 
Additionally, the server will create a "transaction file" (which prevents a replay attack). The filename is `Hash_HMAC(IP+Random, ServerSecret)`.
38 
 
39 
The client will now brute-force all values to find the random value between Min and Max.
40 
 
41 
#### 2. Request from Client to Server (Solve Challenge and request the resource)
42 
 
43 
Request parameters:
44 
- StartTime (as received previously from the server)
45 
- IP address of the client (as received previously from the server)
46 
- Challenge (as received previously from server)
47 
- Answer (the random number found)
48 
- Challenge Integrity (as received previously from the server)
49 
 
50 
The server will do:
51 
- Check if parameters exist and have the correct data type
52 
- Verify that the IP address is the same, otherwise return the error "IP address changed"
53 
- Verify StartTime is not older than "X" minutes*, otherwise return the error "Challenge expired"
54 
- Verify that the challenge integrity fits the HMAC of the Challenge
55 
- Check if the challenge was solved, i.e. Original Challenge matches `Hash(StartTime + IP + Answer)`
56 
- Check if the transaction file exists, otherwise return the error "Challenge submitted twice"
57 
- If all is OK, delete the transaction file (to prevent the answer is sent again) and grant access to the resource
58 
 
59 
Note: Depending on when you solve the challenge, you should decide on a fitting timeout value, e.g.
60 
- When the challenge is solved once the login/contact/... form is shown -> choose a timeout value of 10 minutes. The usage of a "transaction file" is important, because the same challenge can be submitted within 10 minutes.
61 
- When the challenge is solved during the pressing of the "log in/send/..." button -> choose a timeout value of 10-30 seconds (depending on what your complexity constant is and how fast the client CPU is). Usage of "transaction file" is still recommended, but not as important.
62 
 
2 daniel-mar 63 
### Reporting a bug
64 
You can file a bug report here:
65 
- https://www.viathinksoft.com/thinkbug/thinkbug.php?id=119
66 
- https://www.viathinksoft.com/contact/daniel-marschall
67 
- https://github.com/danielmarschall/php_clientchallenge/issues
68 
 
69 
### Support
70 
If you have any questions or need help, please contact us:
71 
https://www.viathinksoft.com/contact/daniel-marschall