Download the PHP package pedroac/nonce without Composer

pedroac/nonce for PHP

A nonce manager PHP library useful for preventing CSRF and replay attacks.

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

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.

pedroac/nonce tries to solve those issues.

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).

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

Prerequisites

• PHP 7.1 or later: http://php.net/downloads.php
• Composer: https://getcomposer.org
• At least one PSR-16 implementation. Examples:
  • symfony/cache
  • matthiasmullie/scrapbook

Installing

Run the command:

composer require pedroac/nonce

Usage

Examples

• Using Symfony ArrayCache
• CLI test
• HTML form using a session
• HTML form using an auto generated nonce name
• HTML form using a helper

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

Use the URL http://localhost:8000/ in a browser.

HTML form with a token

1) Create a nonce form helper:

2) Check if a valid token was submitted:

3) Check if an invalid token was submitted:

4) Implement the HTML form:

The nonce is expired automatically when the token is verified with the NonceForm class.

General usage

1) Instantiate a nonce manager:

2) When a request is submitted, validate the submitted token and remove the nonce:

3) Generate a nonce when appropriate:

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

Options

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

It's also possible to create a nonce with a specified name:

NonceForm default input source is $_POST, but it accepts any array input:

Running the tests

Run from the library root folder:

php/vendor/bin/phpunit php/tests/ -c php/tests/configuration.xml

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

Generating the HTML documentation

Run from the library root folder:

sh scripts/generate-docs.sh

The generated documentation should be inside the folder docs.

Versioning

It should be used SemVer for versioning.

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.

Acknowledgments

The library was developed as a private request response made by a Stackoverflow user.