README

此软件包提供了一个用于SetaPDF-Signer组件的模块，允许您使用云签名联盟 API进行远程电子签名和远程电子印章，以纯PHP方式对PDF文档进行数字签名。

API文档可在云签名联盟网站上找到： https://cloudsignatureconsortium.org/resources/download-api-specifications/

在编写本文档时，该模块已与SSL.com的eSigner CSC API（v0）和Entrust的远程签名服务CSC API（v0）进行了测试。目前，它不支持其他API实现中可能出现的所有功能或差异。

对于与SSL.com一起使用，您可以遵循此集成指南以更好地了解如何设置测试环境和签名工作流程： https://www.ssl.com/guide/integration-guide-testing-remote-signing-with-esigner-csc-api/（您可以使用此模块直接进行签名，而不是使用Postman，并在本地对PDF文档进行签名）。

已知未实现的功能

目前，由于缺少测试选项，该模块不支持RSA_PSS或ECDSA作为签名算法。这两个算法都已实现，但将抛出异常以获得测试用例的机会。请通过support@setasign.com联系我们，以便我们可以一起完成最终实现。

身份验证仅支持OAuth2。尚未实现HTTP Basic或Digest身份验证。实现auth/login（11.2）端点不应需要太多努力。如果您需要此功能，请随时通过support@setasign.com联系我们，以便我们可以一起完成这项工作。

在线一次性密码（OTP）生成机制尚未实现。您必须自行触发OTP生成 - 请参阅API credentials/sendOTP（11.8）。

要求

要使用此软件包，您需要访问CSC API（v0）。

此软件包是在PHP >= 7.1上开发和测试的。SetaPDF-Signer组件的要求可以在这里找到。

我们使用PSR-17（HTTP Factories）和PSR-18（HTTP Client）进行请求。因此，您需要实现这些。我们建议使用Guzzle。

对于PHP 7.1

    "require" : {
        "guzzlehttp/guzzle": "^6.5",
        "http-interop/http-factory-guzzle": "^1.0",
        "mjelamanov/psr18-guzzle": "^1.3"
    }

对于 >= PHP 7.2

    "require" : {
        "guzzlehttp/guzzle": "^7.0",
        "http-interop/http-factory-guzzle": "^1.0"
    }

安装

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

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

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

使用

此软件包中的所有类都位于命名空间setasign\SetaPDF\Signer\Module\CSC中。

Client类

此类是一种CSC API的代理类。其构造函数需要以下参数

• $apiUri 您csc api的基本url，例如 https://cs-try.ssl.com/csc/v0
• $httpClient PSR-18 HTTP客户端实现。
• $requestFactory PSR-17 HTTP 工厂实现。
• $streamFactory PSR-17 HTTP 工厂实现。

如果您需要调用代理方法未覆盖的端点，可以使用 call(string $path, ?string $accessToken = null, array $inputData = []) 方法。

如何获取访问令牌？

访问令牌由 API 服务授权返回。

这仅通过 OAuth2 授权进行了测试。您可以使用 OAuth2 实现，如 league/oauth2-client。相关示例代码可在 "examples/generate-token.php" 中找到。

授权模式

访问用于远程签名的凭证需要拥有该凭证的用户授权，以控制与其关联的签名密钥。

CSC API 支持多种授权模式。授权模式还定义了签名过程是否必须是异步的。要获取此信息，您可以调用 Client::credentialsInfo()，然后在 "authMode" 键中找到以下授权模式之一

• implicit：授权过程由远程服务自主管理。身份验证因素由远程签名服务提供商通过直接与用户交互管理，而不是由签名应用程序管理。
• explicit：授权过程由签名应用程序管理，该应用程序收集如 PIN 或一次性密码 (OTP) 的身份验证因素。
• oauth2code：授权过程由远程服务使用基于授权码的 OAuth 2.0 机制管理。

对于 "implicit" 和 "explicit"，您可以使用同步过程（参见 examples/demo.php 和 examples/ltv-demo.php）。

对于 "oauth2code"，您必须使用异步过程（参见 examples/demo-async.php）。这将需要 OAuth2 实现，如 league/oauth2-client。

关于授权模式的更多信息，请参阅 CSC API 的 "8.2 凭据授权"。

许可协议

本软件包是开源软件，许可协议为 MIT 许可证。