diff --git a/README.md b/README.md index d119cd9..044d4fb 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,26 @@ # Automatic protection from Cross-Site Request Forgery for PHP 7 projects. +This library handles [CSRF](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)) protection automatically for you, including generating tokens, injecting them into all forms in the page and then verifying that a valid token is present whenever a POST request is received. + *** - - Gitter chat + + Gitter chat - - Build status + + Build status - - Code quality + + Code quality - - Code coverage + + Code coverage - - Current version + + Current version - - -This library handles [CSRF](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)) protection automatically for you — including generating tokens, injecting them into all forms in the page and then verifying that a valid token is present whenever a POST request is received. - - - - - -## Protection in Three Steps +## Usage: Protection in Three Steps The CSRF library does two things: @@ -94,9 +88,11 @@ $htmlOut = $page->getHTMLDocument()->saveHTML(); By default, 32 character tokens are generated. They use characters from the set \[a-zA-Z0-9\], meaning a 64-bit token which would take a brute-force attacker making 100,000 requests per second around 2.93 million years to guess. If this seems either excessive or inadequate you can change the token length using `TokenStore::setTokenLength()`. - #### Special Note About AJAX Clients Note that if several of the forms on your page could be submitted without reloading the page (which is uncommon, but could happen if you're using AJAX and not reloading the page using on the server response), you will want to call `$page->protectAndInject(HTMLDocumentProtector::TOKEN_PER_FORM);`, to have a unique token injected into each form. This uses more server resources, and means there are far more unused tokens that could be guessed, but is unavoidable. (Remember, if you'll still need to parse the new token for that form out of the page response and update the client-side form, otherwise a second submit would fail as the original token will have been spent.) - + +## Alternatives to Storing Tokens on the Session + +The package includes an `ArrayTokenStore`, which can be stored on the session. You can implement alternative token stores such as a RDBMS or Mongo by subclassing `TokenStore` and implementing the abstract methods.