使用eSigner CSC API进行远程文档签名

查看所有指南

本指南将向您展示如何使用SSL.com的文档注册文档签名证书订单 电子签名者 服务并使用Cloud Signature Consortium（CSC）API对文档哈希和PDF文件进行数字签名。 您可以将本指南与 卷曲 or 邮差。 我们建议Postman用户安装 桌面应用 用于完成示例。 本指南中的示例均适用于 SSL.com 的生产和测试 eSigner 和 eSealing 环境。 以下部分解释了生产模式和测试模式之间命令的差异。

要遵循这些说明，您将需要：

  • 经过验证的文档签名证书订单。 请阅读 这个方法 有关订购和验证的完整说明。
  • A 客户ID （也称为 应用程序ID。 Please refer to请参阅 这个方法 有关生成此证书的说明）。

订购您的 SSL.com 文档签名证书

如果您已经拥有颁发的文档签名证书，则可以跳过此部分。 如果是这种情况，请继续阅读下一部分，其中讨论如何在 eSigner 中注册您的证书。

如何在生产环境中订购证书

请参阅本指南文章，了解如何订购生产文档签名证书的说明： 代码和文档签名证书的订购流程

如何在 SSL.com 的 Sandbox 上订购测试证书

SSL.com 提供专用的沙盒环境，镜像我们的实时 SSL.com 门户和 SWS API，提供无风险的实验空间。这种“实验室”设置允许用户探索和测试 SSL.com 的服务，而无需担心造成中断或产生实际成本。 

这篇文章， 使用SSL.com沙箱进行测试和集成, 将帮助您浏览建立沙盒帐户、启动测试订单以及将沙盒与 SWS API 集成的过程。

创建测试证书后，请联系 SSL.com 支持团队进行验证。您可以通过单击右下角的在线聊天按钮来完成此操作 SSL.com 网站或发送电子邮件至 support@ssl.com.

转至顶部

注册eSigner并设置两因素身份验证

在开始使用 CSC API 之前，您需要注册 SSL.com 的 eSigner 云签名服务。已验证的订单可以按照以下说明在 eSigner 中注册： 

  1. 。 导航到 订单 标签进入您的SSL.com帐户，然后找到您的订单。
    找到订单
  2. 点击订单的 详情 链接。
    详情
  3. 创建一个并确认4位PIN码，然后点击 创建PIN码 按钮。
    如果您需要重设eSigner PIN，请阅读 这个方法.
    创建PIN码
  4. 将会出现QR码。
    下次重新加载页面时，QR码将不可见。 如果您需要查看或重置您的eSigner QR码，请阅读 这个方法.
    扫码支付
  5. 将代码扫描到移动设备上的2因子身份验证应用程序中，例如 谷歌身份验证 or Authy。 该应用程序将为您提供一次性密码（OTP），供您在签名时使用。 每个OTP有效期为30秒。
    Authy中的OTP
提示： 您可以使用eSigner在队友之间共享经过组织验证（OV）的签名证书。 请阅读 eSigner文档和EV代码签名证书的团队共享 作为指示。
转至顶部

可选：将 OV 文档签名证书转换为密封证书

请注意： 此部分仅适用于想要进行密封的用户。为了自动进行文档签名并且不被一次性密码 (OTP) 提示，用户可以自行将其组织验证 (OV) 文档签名证书转换为其 SSL.com 帐户上的密封证书。 请注意，个人验证 (IV) 文档签名证书无法转换为密封。密封转换的详细说明如下：

  1. 点击 订单 在您的 SSL.com 帐户的顶部菜单上。 
  2. 找到您的证书并单击 下载/详细信息 链接。
  3. 点击 删除 2FA 按钮。
转至顶部

安装Postman和导入API集合

本节中的说明仅适用于Postman用户。 如果将cURL与CSC API结合使用，则可以进入下一部分。

  1. 下载并解压缩 CSC API邮递员收藏 和 文档签名API邮递员集合 （见 https://www.postman.com/sslcom 用于在线 SSL.com API 集合）。
    邮差收藏
  2. 下载并安装 邮递员REST客户端.
    邮递员REST客户端下载
  3. 启动Postman，然后创建一个新的Postman帐户或登录到现有的帐户。
    邮递员登录
  4. 点击 进口 按钮。
    导入按钮
  5. 点击 上传文件 按钮，导航到未压缩的API集合文件（csc-api-prod.postman_collection.json 和 document-signing-api-prod.postman_collection.json），然后打开它们。
    上传文件
  6. 点击 进口 按钮。
    点击导入按钮
  7. 您将使用的API请求现在可以在 系列 邮递员窗口左侧的标签。
    API请求
转至顶部

检索访问令牌

下一步是从SSL.com检索访问令牌。 你需要你的 客户ID 可用，以及SSL.com帐户的用户名和密码。 访问令牌在发出后一小时内有效。

使用下面的可点击标签来选择Postman或cURL的说明：

邮递员说明cURL说明
  1. 从CSC API集合中选择一个API请求。
    选择API请求
  2. 点击 授权 选项​​卡，并选择 身份验证 2.0 来自 Type 菜单。
    授权标签
  3. 在表单中输入以下信息：
    • 标头前缀： Bearer
    • 令牌名称： SSLCOM CSC （或您喜欢的其他易于记忆的名称）
    • 赠款类型： Authorization Code
    • 回调网址： https://upload.esigner.com
    • 使用浏览器授权： 选中
    • 验证网址：  https://login.ssl.com/oauth2/authorize 适用于生产环境； https://oauth-sandbox.ssl.com/oauth2/authorize 适用于沙盒环境。
    • 访问令牌URL： https://login.ssl.com/oauth2/token 适用于生产环境； https://oauth-sandbox.ssl.com/oauth2/token 适用于沙盒环境。 
    • 客户编号： [您的客户编号]
    • 客户机密： [您的客户秘密]
    • 范围： service
    • 省（自治区，直辖市，州）： [留着空白]
    • 客户端身份验证： Send as Basic Auth header

    完成后，单击 获取新的访问令牌 按钮。
    获取新的访问令牌

  4. 将出现一个登录表格。 输入您的SSL.com用户名和密码，然后单击 会员登录 按钮。
    帐号登录
  5. 您的新访问令牌应出现在Postman中。 选择访问令牌文本并将其复制到剪贴板，然后关闭 管理访问令牌 对话框。 将您的访问令牌粘贴到文本编辑器中，您可以在其中轻松访问它。 每个访问令牌将在一个小时后过期。
    您还可以保存令牌以在Postman请求中重复使用，但是我们发现将令牌直接复制并粘贴到每个请求中最可靠。
    访问令牌
  1. 使用以下命令来请求访问令牌。 用您的实际值替换ALL-CAPS中显示的值：
    curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "内容类型：application/json" \ --data-raw '{ "client_id" : "您的-CLIENT-ID", "client_secret" : "您的客户端秘密", "grant_type" : "密码", "用户名" : "您的用户名", "密码" : "您的密码" }'
  2. 您应该收到一个包含访问令牌和刷新令牌的JSON对象。 复制访问令牌值以粘贴到您的API请求中。 这些示例不需要刷新令牌。
    检索访问令牌
转至顶部

签署哈希

有了访问令牌后，就可以开始发出API请求和创建签名了。 本节将引导您完成Postman CSC集合中的五个可用请求，从而从文档哈希中创建数字签名。

应使用 SHA 256 算法来计算 PDF 文档的哈希值。 

  1. 需要一个 PDF 库来操作 PDF 进行哈希输入，然后将 PKCS#7 嵌入到 PDF 文档中。 （例如 Java 中的 ApachePDFBox）。 
  2. 一个加密库，用于根据从 eSigner API（例如 Java 中的 BouncyCastle）收到的原始签名创建 PKCS#7。

获取CSC信息（可选）

邮递员说明cURL说明
  1. 您可以使用 CSC资讯 请求获取有关SSL.com的云签名服务的信息。 请注意，与集合中的其他集合不同，此请求不需要您的访问令牌。 要发送请求，请选择 CSC资讯 来自 CSC 应用程序接口 集合，然后单击 提交 按钮。
    发送CSC信息请求
  2. 有关云签名服务的信息将显示在Postman的JSON对象中 响应 领域。
    CSC资讯
  1. 使用以下命令获取有关 SSL.com 的 CSC API 服务的信息。 如果您在沙箱环境中，请使用 https://cs-try.ssl.com/csc/v0/info 代替。 
    curl --location --request POST“ https://cs.ssl.com/csc/v0/info” \ --header“内容类型：application / json” \ --data-raw“ {}”
  2. 您将收到一个JSON对象，其中包含有关服务的详细信息：
    获取CSC信息

CSC凭证列表

 CSC凭证列表 请求将检索您将在以后的API请求中使用的凭据。

邮递员说明cURL说明
  1. 选择 CSC凭证列表 并单击 授权 标签。
    授权标签
  2. 不记名令牌 来自 Type 菜单，将您的访问令牌粘贴到 Token 字段，然后单击 提交 按钮。
    发送凭据列表请求
  3. 带有与用户相关联的凭据ID列表的JSON对象将出现在 响应 领域。 您的列表可能包含一个值。 将您的凭据ID复制并粘贴到文本编辑器中，以用于以后的请求。
    凭证ID
  1. 输入以下命令。 （将 MY-ACCESS-TOKEN 替换为您的实际访问令牌）。 如果您处于沙箱环境中，请使用 https://cs-try.ssl.com/csc/v0/credentials/list 代替：
    curl --location --request POST“ https://cs.ssl.com/csc/v0/credentials/list” \ --header“内容类型：application / json” \ --header“授权：Bearer MY- ACCESS-TOKEN“ \ --data-raw” {}“

    如果使用 eseal 证书（仅包含组织信息的文档签名证书；包含在您的免费 esigner.com 帐户中），则包括“clientData”：“DS_ESEAL”（注意：eseal 不需要 OTP 身份验证）。 “clientData”的其他选项是用于 EV 代码签名的“EVCS”和用于 IV 或 IV+OV 文档签名的“DS”（默认）：

    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY-访问令牌" \ --data-raw '{"clientData": "DS_ESEAL"}'
  2. 您应该收到一个JSON对象，其中包含与用户相关联的凭据ID列表。 您的列表可能包含一个值。 将您的凭据ID复制并粘贴到文本编辑器中，以用于以后的请求。
    凭证ID

CSC凭证信息（可选）

CSC凭证信息 请求将返回证书和与凭据ID相关的其他信息，并且不需要签名。

邮递员说明cURL说明
  1. 要使用此请求，请选择 CSC凭证信息 从集合中，然后单击 授权 标签。
    授权标签
  2. 不记名令牌 来自 Type 菜单，然后将您的访问令牌粘贴到 Token 领域。
    粘贴令牌
  3. 点击 Body 标签，然后将您的凭据ID粘贴为 credentialID.
    粘贴凭证ID
  4. 点击 提交 按钮。
    提交
  5. 带有您的签名证书链和其他信息的JSON对象将显示在 响应 领域。
    凭证信息
  1. 输入以下命令。 如果您处于沙箱环境中，请使用 https://cs-try.ssl.com/csc/v0/credentials/info  更换 MY-ACCESS-TOKEN 和 MY-CREDENTIAL-ID 使用您的实际信息：
    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": true, "authInfo": true }'
  2. 您应该收到带有签名证书链和其他信息的JSON对象：
    CSC凭证信息

凭证授权

凭证授权 请求将检索用于签名哈希的授权。

邮递员说明cURL说明
  1. 首先选择 凭证授权 从集合中，然后单击 授权 标签。
    授权标签
  2. 不记名令牌 来自 Type 菜单，然后将您的访问令牌粘贴到 Token 领域。
    粘贴令牌
  3. 点击 Body 标签。 将您的凭据ID粘贴为 credentialID 值和您希望作为文档签名的文档的哈希值 hash 值。 从身份验证应用程序检索并输入OTP，然后将其输入为 OTP，然后点击 提交 按钮。 注意：密封证书不需要 OTP。
    身体标签
  4. 带有您的签名激活数据（SAD）的JSON对象将出现在 响应 领域。 复制此值并将其粘贴到文本编辑器中，以用于哈希签名请求。
    悲伤
  1. 使用以下命令。 代替 MY-ACCESS-TOKEN, MY-CREDENTIAL-ID及 MY-HASH 与您的实际信息。 从您的2FA应用程序中获得一次性密码，并使用作为该密码的值 MY-OTP. 注意：密封证书不需要 OTP。
    curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP " }'
  2. 您应该收到带有签名激活数据（SAD）的JSON对象。 复制此值并将其粘贴到文本编辑器中，以用于哈希签名请求。
    凭证授权

签名哈希

现在您准备对文档哈希签名。

邮递员说明cURL说明
  1. 选择 签名哈希 从集合中，然后选择 授权 标签。
    授权标签
  2. 不记名令牌 来自 Type 菜单，然后将您的访问令牌粘贴到 Token 领域。
    粘贴令牌
  3. 点击 Body 标签。 将您的凭据ID粘贴为 credentialID 值，您的签名激活数据作为 SAD 值，以及您希望作为文档签名的文档的哈希值 hash 值，然后单击 提交 按钮。
    身体标签
  4. 带有您签名的JSON对象将出现在 响应 领域。
    签名
  1. 输入以下命令。 代替 MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SAD及 MY-HASH 使用您的实际信息：
    curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": ["MY-HASH"], "signAlgo": “1.2.840.113549.1.1.11”}'
  2. 您应该收到一个包含签名的JSON对象。
    签名哈希
转至顶部

签署PDF

除了签署文档哈希之外，您还可以上传和签署PDF文件。

在签署PDF时，您将处理两个POST请求：

  • 上载PDF文件
  • 签署PDF文件

文档签名API集合

您可以将上面使用的凭证重新使用 CSC凭证列表 请求。 您可能还需要检索一个新的 访问令牌.

上载PDF文件

邮递员说明cURL说明
  1. 点击 上载PDF文件 请求并单击 授权 标签。
    授权标签
  2. 不记名令牌 来自 Type 菜单，然后将您的访问令牌粘贴到 Token 领域。
    粘贴令牌
  3. 点击 头 标签，然后将您的凭据ID粘贴到 值 列。
    标题标签
  4. 点击 Body 选项卡并单击 × 旁边 hello.pdf 删除此占位符文件名。
    删除示例文件名
  5. 点击 选择文件 按钮，然后导航到您要上传的文件。
    选择文件
  6. 点击 提交 按钮。
    提交
  7. 选择并复制 id 要在下一个请求中使用的响应中的值。
    ID
  1. 使用以下命令。 代替 MY-CREDENTIAL-ID, MY-ACCESS-TOKEN及 /PATH/TO/FILE.pdf 使用您的实际信息：
    curl --location --request POST“ https://ds.ssl.com/v1/pdf/upload” \ --header“凭据ID：MY-CREDENTIAL-ID” \ --header“授权：Bearer MY- ACCESS-TOKEN“ \ --header”内容类型：application / pdf“ \ --data-binary” @ / PATH / TO / FILE.pdf“
  2. 您将收到一个JSON对象，其值为 id。 复制此值以在下一个请求中使用。
    上传PDF

注意：对于可见的签名，请参考以下 HTTP 请求标头（/v1/pdf/upload）：

请求头

产品描述

凭据 ID

分配给密钥的唯一凭据 ID – 必需

签约理由

添加签名原因以添加签名外观和签名字典 - 可选，例如我批准此文档

签约地点

在签名字典中添加签名位置 - 可选，例如德克萨斯州休斯顿

联系方式

在签名字典中添加联系信息 - 可选，例如电话号码

签名字段位置

显示视觉签名的签名字段位置。 格式是 “x，y，宽度，高度“ - 可选的

页码

页码在哪里绘制签名 - 可选

手签

手签名的 Base64 编码 PNG 图像 - 可选


签署PDF文件

现在您可以签署PDF。

使用密封文件签名证书进行签名时不需要 OTP 授权。 如果使用密封文件签名证书，请忽略以下指南中的所有 OTP 参数。
邮递员说明cURL说明
  1. 点击 上载PDF文件 请求并单击 授权 标签。
       授权
  2. 不记名令牌 来自 Type 菜单，然后将您的访问令牌粘贴到 Token 领域。
    粘贴令牌
  3. 选择“身体”标签，然后粘贴到 id 上一步中的值和身份验证应用中的OTP，然后单击 提交 按钮。
    发送请求
  4. PDF数据将显示在下方 响应 领域。 选择 保存到文件 来自 保存回复 菜单，然后为文件命名。
    将PDF保存到文件
  5. 在Acrobat中打开文件以确认文件已签名。
    有效签名
  1. 输入以下命令。 代替 MY-CREDENTIAL-ID, MY-FILE-ID及 OUTPUT-FILENAME 与您的实际信息。 从您的2FA应用中获取一次性密码（OTP）并输入为 MY-OTP. 注意：密封证书不需要 OTP：
    curl --location --request POST'https://ds.ssl.com/v1/pdf/sign'\ –header'Content-Transfer-Encoding：application / json'\ --header'Content-Type：application / json'\ --header'授权：Bearer MY-ACCESS-TOKEN'\ --data-raw'{“ id”：“ MY-FILE-ID”，“ otp”：“ MY-OTP”}'\- -输出OUTPUT-FILENAME
  2. cURL将下载已签名的文件并将其保存到您指定的文件名中：
    签名PDF
  3. 在Acrobat或Acrobat Reader中打开PDF以检查签名是否有效。
    有效签名

Twitter
Facebook
LinkedIn
Reddit
电邮

SSL.com 支持团队

作者-内容管理员
所有帖子»

保持信息灵通和安全

SSL.com 是网络安全领域的全球领导者， PKI 和数字证书。注册以接收最新的行业新闻、提示和产品公告 SSL.com.

我们希望收到您的反馈

参加我们的调查，让我们知道您对最近购买的想法。

参加调查