README

一个PHP库，用于防止nonce尝试防止的漏洞，如CSRF和重放攻击。

我们可能会找到一些文章和视频解释nonce尝试防止的漏洞。

然而，许多PHP nonce库过于限制性，与某些框架结合使用时难以使用或难以理解它们的工作方式。

pedroac/nonce试图解决这些问题。

它允许选择任何PSR-16实现来存储nonce，nonce值生成器，过期间隔，甚至一个DateTime提供者来覆盖时钟系统（此功能用于单元测试）。

它还提供了管理输入，生成随机nonce名称和值，验证提交的令牌与nonce，以及生成HTML元素的辅助程序。

先决条件

PHP 7.1或更高版本：https://php.ac.cn/downloads.php
Composer：https://getcomposer.org.cn
至少一个PSR-16实现。例如
- symfony/cache
- matthiasmullie/scrapbook

安装

运行以下命令

composer require pedroac/nonce

用法

示例

可以使用PHP内置的Web服务器测试HTML表单。
从php/examples文件夹中运行以下命令

php -S localhost:8000

在浏览器中使用URL https://:8000/

带令牌的HTML表单

创建nonce表单辅助程序

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

use Symfony\Component\Cache\Simple\FilesystemCache;
use \pedroac\nonce\NoncesManager;
use \pedroac\nonce\Form\HtmlNonceField;
use \pedroac\nonce\Form\NonceForm;

// this handles automatically the input and nonce management
$form = new NonceForm(
    'token', // the HTML input name
    new NoncesManager(
      new FilesystemCache // a \Psr\SimpleCache\CacheInterface implementation
    )
);
// this will be used to generate a HTML input element
$htmlField = new HtmlNonceField($form);

检查是否提交了有效令牌

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

检查是否提交了无效令牌

if ($form->isSubmittedInvalid()) {
  /**
   * handle failure:
   * - don't show the form again;
   * - show an error message;
   */
}

实现HTML表单

<form method="POST">
    <?= $htmlField ?>
    <!-- more HTML -->
    <input type="submit" name="myform" value="Submit" />
</form>

当使用NonceForm类验证令牌时，nonce会自动过期。

通用用法

实例化nonce管理器

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

use Symfony\Component\Cache\Simple\FilesystemCache;
use \pedroac\nonce\NoncesManager;

$manager = new NoncesManager(new FilesystemCache);

当请求提交时，验证提交的令牌并删除nonce

$isValidToken = false;
$isValidForm = false;
$wasSubmitted = filter_has_var(INPUT_POST, 'myform');
$tokenName = filter_input(INPUT_POST, 'token_name');
$tokenValue = filter_input(INPUT_POST, 'token_value') ?? '';

if ($tokenName) {
    $isValidToken = $manager->verifyAndExpire($tokenName, $tokenValue);
}
if ($wasSubmitted && $isValidToken) {
    // validate input
}

在适当的时候生成nonce

if (!$wasSubmitted || (!$isValidForm && $isValidToken)) {
  $nonce = $manager->create();
}

使用nonce名称和值构建，例如，HTML表单

<?php if ($nonce) : ?>
  <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; >

选项

除了nonce缓存存储之外，还可以选择随机nonce值生成器和过期间隔

<?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')
);

还可以创建具有指定名称的nonce

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

NonceForm默认输入来源是$_POST，但它接受任何数组输入

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

运行测试

从库根目录运行

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

如果测试成功，php/tests/coverage-html 应该有代码覆盖率报告。

生成HTML文档

从库根目录运行

sh scripts/generate-docs.sh

生成的文档应该在 docs 文件夹中。

版本控制

应该使用 SemVer 进行版本控制。

作者

佩德罗·阿马拉尔·库托 - 初步工作 - https://github.com/pedroac

许可协议

pedroac/nonce 以MIT公共许可证发布。
有关详细信息，请参阅所附的 LICENSE。

致谢

该库是根据Stackoverflow用户提出的私人请求而开发的。

pedroac / nonce

维护者

详细信息