Rev 2 | Show entire file | Regard whitespace | Details | Blame | Last modification | View Log | RSS feed
Rev 2 | Rev 12 | ||
---|---|---|---|
Line -... | Line 1... | ||
- | 1 | ||
- | 2 | ||
1 | # Server requests using client challenges |
3 | # Server requests using client challenges |
2 | 4 | ||
3 | ### What is it? |
5 | ### What is it? |
4 | This PHP/JavaScript package can be used to add client challenges on top of your |
6 | This PHP/JavaScript package can be used to add client challenges on top of your |
5 | AJAX requests to protect your scripts against brute-force or DoS attacks. |
7 | AJAX requests to protect your scripts against brute-force or DoS attacks. |
Line 8... | Line 10... | ||
8 | 10 | ||
9 | ### Usage example |
11 | ### Usage example |
10 | A usage example is located in the directory example/ |
12 | A usage example is located in the directory example/ |
11 | 13 | ||
12 | ### System requirements |
14 | ### System requirements |
13 | - PHP compatible web-server (tested with Apache 2, nginx, and Microsoft IIS) |
15 | - PHP-compatible web server (tested with Apache 2, nginx, and Microsoft IIS) |
14 | - PHP 7.0 or higher (also tested with PHP 8.0) |
16 | - PHP 7.0 or higher (also tested with PHP 8.0) |
15 | - Independent of operating system (tested with Windows, Linux, and macOS X) |
17 | - Independent of operating system (tested with Windows, Linux, and macOS X) |
16 | 18 | ||
- | 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 | ||
17 | ### Reporting a bug |
63 | ### Reporting a bug |
18 | You can file a bug report here: |
64 | You can file a bug report here: |
19 | - https://www.viathinksoft.com/thinkbug/thinkbug.php?id=119 |
65 | - https://www.viathinksoft.com/thinkbug/thinkbug.php?id=119 |
20 | - https://www.viathinksoft.com/contact/daniel-marschall |
66 | - https://www.viathinksoft.com/contact/daniel-marschall |
21 | - https://github.com/danielmarschall/php_clientchallenge/issues |
67 | - https://github.com/danielmarschall/php_clientchallenge/issues |