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 |