README

本包为 SetaPDF-Signer 组件提供了一个模块，允许您使用存储在 PKCS11 兼容设备（例如 HSM、USB Token）上的密钥，使用纯 PHP 对 PDF 文档进行数字签名。

需求

此模块需要安装 PKCS11 PHP 扩展。

您还需要提供设备 PKCS11 模块的路径。

本包在 PHP >= 7.4 上开发和测试。SetaPDF-Signer 组件的要求可以在此处找到。

安装

将以下内容添加到 composer.json 中

{
    "require": {
        "setasign/setapdf-signer-addon-pkcs11": "^1.0"
    },
    "repositories": [
        {
            "type": "composer",
            "url": "https://www.setasign.com/downloads/"
        }
    ]
}

并执行 composer update。您需要定义 repository 以评估对 SetaPDF-Signer 组件的依赖（有关更多详细信息，请参阅此处）。

用法

本包中所有类都位于命名空间 setasign\SetaPDF\Signer\Module\Pkcs11 中。

Module 类

这是主要的签名模块，可以与 SetaPDF-Signer 组件一起使用。内部它持有一个 PAdES 签名模块 的实例，并提供所有相关的代理方法。

传递给 Module 实例的唯一参数是私钥的 \Pkcs11\Key 实例和相关 X509 证书。

使用 RSA 密钥进行签名的默认填充方案是 RSASSA-PKCS1-v1_5。要使用 RSASSA-PSS，只需调用 $module->setPssPadding();。

一个简单的完整签名过程如下所示

$pin = '123456';

$modulePath = '/usr/lib/softhsm/libsofthsm2.so';
$pkcs11 = new Pkcs11\Module($modulePath);

$slotList = $pkcs11->getSlotList();
$slotId = $slotList[0];

$session = $pkcs11->openSession($slotId, Pkcs11\CKF_RW_SESSION);
$session->login(Pkcs11\CKU_USER, $pin);

$skey = $session->findObjects([
    Pkcs11\CKA_PRIVATE => true,
    Pkcs11\CKA_LABEL => "SetaPDF-Demo"
])[0];

$module = new setasign\SetaPDF\Signer\Module\Pkcs11\Module($skey);
$module->setCertificate('path/to/setapdf.pem');
$module->setPssPadding();
$module->setDigest(SetaPDF_Signer_Digest::SHA_512);

$fileToSign = 'path/to/Laboratory-Report.pdf';

// create a writer instance
$writer = new SetaPDF_Core_Writer_Http('signed.pdf');
// create the document instance
$document = SetaPDF_Core_Document::loadByFilename($fileToSign, $writer);

// create the signer instance
$signer = new SetaPDF_Signer($document);
$signer->sign($module);

$session->logout();

测试

出于测试目的，我们使用了 SoftHSM2，并使用以下命令将现有的测试证书和密钥导入其中

softhsm2-util --import <PATH-TO-CERTIFICATE> --token "<THE-TOKEN-NAME>" --label "<THE-LABEL>" --id <UNIQUE-ID-IN-HEX-NOTATION>

CSR 生成和密钥证明不是本插件的一部分。