2017 © Pedro Peláez
 

library nonce

A nonces manager usefull for preventing CSRF and replay attacks.

image

pedroac/nonce

A nonces manager usefull for preventing CSRF and replay attacks.

  • Friday, April 13, 2018
  • by pedroac
  • Repository
  • 1 Watchers
  • 0 Stars
  • 6 Installations
  • PHP
  • 0 Dependents
  • 0 Suggesters
  • 0 Forks
  • 0 Open issues
  • 5 Versions
  • 200 % Grown

The README.md

pedroac/nonce for PHP

Build Status Codacy Badge Support via PayPal, (*1)

A nonce manager PHP library useful for preventing CSRF and replay attacks., (*2)

We may find several articles and videos explaining the vulnerabilities that nonces try to prevent: - YouTube - Jmaxxz - CSRF Explained - YouTube - Professor Messer - Cross-site Request Forgery - YouTube - Professor Messer - Replay Attacks - YouTube - Hak5 - How to Hack Wireless Remotes with Radio Replay Attacks - Coding Horror - Preventing CSRF and XSRF Attacks - acunetix - CSRF Attacks, XSRF or Sea-Surf - SitePoint - How to Prevent Replay Attacks on Your Website, (*3)

It seems, though, that many PHP nonces libraries are too restrictive, coupled with some framework, hard to use or hard to understand how they work., (*4)

pedroac/nonce tries to solve those issues., (*5)

It allows choosing any PSR-16 implementation to store temporarily the nonces, nonces values generators, expiration intervals and even a DateTime provider to override the clock system (this feature is used for unit tests)., (*6)

It also provides helpers to manage input, generate random nonces names and values, verify submitted tokens against the nonce and generate HTML elements., (*7)

Prerequisites

Installing

Run the command:, (*8)

composer require pedroac/nonce, (*9)

Usage

Examples

The HTML forms can be tested using a PHP built-in web server.
From the php/examples folder run the command:, (*10)

php -S localhost:8000

Use the URL http://localhost:8000/ in a browser., (*11)

HTML form with a token

1) Create a nonce form helper:, (*12)

isSubmittedValid()) {
  /**
   * handle the success:
   * - if all form input is valid, show success page;
   * - otherwise, show an error page and the form again;
   */
}
```

3) Check if an invalid token was submitted:
```php
if ($form->isSubmittedInvalid()) {
  /**
   * handle failure:
   * - don't show the form again;
   * - show an error message;
   */
}
```

4) Implement the HTML form:
```php
= $htmlField ?> <!-- more HTML --> <input type="submit" name="myform" value="Submit" /> </form>

The nonce is expired automatically when the token is verified with the NonceForm class., (*13)

General usage

1) Instantiate a nonce manager:, (*14)

verifyAndExpire($tokenName, $tokenValue);
}
if ($wasSubmitted && $isValidToken) {
    // validate input
}
```

3) Generate a nonce when appropriate:
```php
if (!$wasSubmitted || (!$isValidForm && $isValidToken)) {
  $nonce = $manager->create();
}
```

4) Use the nonce name and value to build, for instance, a HTML form:
```php

  <input type="hidden"
        name="token_name"
        value="<?= htmlspecialchars($nonce->getName()) ?>" />
  <input type="hidden"
        name="token_value"
        value="<?= htmlspecialchars($nonce->getValue()) ?>" />
  <input type="submit" name="myform" value="Submit" />
<?php endif; >

Options

Besides the nonces cache storage, it's possible to select the random nonce value generator and the expiration interval:, (*15)

<?php
require __DIR__ . '/../vendor/autoload.php';

use Symfony\Component\Cache\Simple\ArrayCache;
use \pedroac\nonce\NoncesManager;
use \pedroac\nonce\Random\HexRandomizer;

$manager = new NoncesManager(
    new ArrayCache(60),
    new HexRandomizer(32), // a \pedroac\nonce\Random implementation
    new \DateInterval('PT3H')
);

It's also possible to create a nonce with a specified name:, (*16)

$user_id = $_SESSION['user_id'];
$tokenName = "{$user_id}_form";
$nonce = $manager->create($tokenName);

NonceForm default input source is $_POST, but it accepts any array input:, (*17)

$form = new NonceForm(
    'token',
    new NoncesManager(
      new FilesystemCache
    ),
    filter_input_array(INPUT_GET) // use $_GET
);

Running the tests

Run from the library root folder:, (*18)

php/vendor/bin/phpunit php/tests/ -c php/tests/configuration.xml, (*19)

If the tests were successful, php/tests/coverage-html should have the code coverage report., (*20)

Generating the HTML documentation

Run from the library root folder:, (*21)

sh scripts/generate-docs.sh, (*22)

The generated documentation should be inside the folder docs., (*23)

Versioning

It should be used SemVer for versioning., (*24)

Authors

  • Pedro Amaral Couto - Initial work - https://github.com/pedroac

License

pedroac/nonce is released under the MIT public license.
See the enclosed LICENSE for details., (*25)

Acknowledgments

The library was developed as a private request response made by a Stackoverflow user., (*26)

The Versions

13/04 2018

dev-master

9999999-dev https://github.com/pedroac/nonce4php

A nonces manager usefull for preventing CSRF and replay attacks.

  Sources   Download

MIT

The Requires

 

The Development Requires

by Pedro Amaral Couto

security token csrf nonce replay-attack

11/04 2018

1.1.0

1.1.0.0 https://github.com/pedroac/nonce4php

A nonces manager usefull for preventing CSRF attacks.

  Sources   Download

MIT

The Requires

 

The Development Requires

by Pedro Amaral Couto

security token csrf nonce

10/04 2018

1.0.0

1.0.0.0 https://github.com/pedroac/nonce4php

A nonces manager usefull for preventing CSRF attacks.

  Sources   Download

MIT

The Requires

 

The Development Requires

by Pedro Amaral Couto

security token csrf nonce

31/03 2018

0.1.2

0.1.2.0 https://github.com/pedroac/nonce4php

A nonces manager usefull for preventing CSRF attacks.

  Sources   Download

The Requires

  • php >=7.1

 

The Development Requires

by Pedro Amaral Couto

security token csrf nonce

31/03 2018

0.1.1

0.1.1.0

A nonces manager usefull for preventing CSRF attacks.

  Sources   Download

The Requires

  • php >=7.1

 

The Development Requires

by Pedro Amaral Couto

security token nounce