本指南将向您展示如何使用SSL.com的文档注册文档签名证书订单 电子签名者 服务并使用Cloud Signature Consortium(CSC)API对文档哈希和PDF文件进行数字签名。 您可以将本指南与 卷曲 or Postman。 我们建议Postman用户安装 桌面应用 用于完成示例。 本指南中的示例均适用于 SSL.com 的生产和测试 eSigner 和 eSealing 环境。 以下部分解释了生产模式和测试模式之间命令的差异。
要遵循这些说明,您将需要:
订购您的 SSL.com 文档签名证书
如何在生产环境中订购证书
请参阅本指南文章,了解如何订购生产文档签名证书的说明: 代码和文档签名证书的订购流程
如何在 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 中注册:
- 。 导航到 订单管理 标签进入您的SSL.com帐户,然后找到您的订单。
- 点击订单的 详情 链接。
- 创建一个并确认4位PIN码,然后点击 创建PIN码 按钮。
如果您需要重设eSigner PIN,请阅读 这个方法. - 将会出现QR码。
下次重新加载页面时,QR码将不可见。 如果您需要查看或重置您的eSigner QR码,请阅读 这个方法. - 将代码扫描到移动设备上的2因子身份验证应用程序中,例如 谷歌身份验证 or Authy。 该应用程序将为您提供一次性密码(OTP),供您在签名时使用。 每个OTP有效期为30秒。
可选:将 OV 文档签名证书转换为密封证书
请注意: 此部分仅适用于想要进行密封的用户。为了自动进行文档签名并且不被一次性密码 (OTP) 提示,用户可以自行将其组织验证 (OV) 文档签名证书转换为其 SSL.com 帐户上的密封证书。 请注意,个人验证 (IV) 文档签名证书无法转换为密封。密封转换的详细说明如下:
- 点击 订单管理 在您的 SSL.com 帐户的顶部菜单上。
- 找到您的证书并单击 下载/详细信息 链接。
- 点击 删除 2FA 按钮。
安装Postman和导入API集合
本节中的说明仅适用于Postman用户。 如果将cURL与CSC API结合使用,则可以进入下一部分。
- 下载并解压缩 CSC API邮递员收藏 和 文档签名API邮递员集合 (见 https://www.postman.com/sslcom 用于在线 SSL.com API 集合)。
- 下载并安装 邮递员REST客户端.
- 启动Postman,然后创建一个新的Postman帐户或登录到现有的帐户。
- 点击 导入模板 按钮。
- 点击 上传文件 按钮,导航到未压缩的API集合文件(
csc-api-prod.postman_collection.json
和document-signing-api-prod.postman_collection.json
),然后打开它们。
- 点击 导入模板 按钮。
- 您将使用的API请求现在可以在 系列 邮递员窗口左侧的标签。
检索访问令牌
下一步是从SSL.com检索访问令牌。 你需要你的 客户ID 可用,以及SSL.com帐户的用户名和密码。 访问令牌在发出后一小时内有效。
使用下面的可点击标签来选择Postman或cURL的说明:
- 从CSC API集合中选择一个API请求。
- 点击 授权 选项卡,并选择 身份验证 2.0 来自 类型 菜单。
- 在表单中输入以下信息:
- 标头前缀:
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
- 标头前缀:
- 将出现一个登录表格。 输入您的SSL.com用户名和密码,然后单击 会员登录 按钮。
- 您的新访问令牌应出现在Postman中。 选择访问令牌文本并将其复制到剪贴板,然后关闭 管理访问令牌 对话框。 将您的访问令牌粘贴到文本编辑器中,您可以在其中轻松访问它。 每个访问令牌将在一个小时后过期。
您还可以保存令牌以在Postman请求中重复使用,但是我们发现将令牌直接复制并粘贴到每个请求中最可靠。
- 使用以下命令来请求访问令牌。 用您的实际值替换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" : "密码", "用户名" : "您的用户名", "密码" : "您的密码" }'
- 您应该收到一个包含访问令牌和刷新令牌的JSON对象。 复制访问令牌值以粘贴到您的API请求中。 这些示例不需要刷新令牌。
签署哈希
有了访问令牌后,就可以开始发出API请求和创建签名了。 本节将引导您完成Postman CSC集合中的五个可用请求,从而从文档哈希中创建数字签名。
- 需要一个 PDF 库来操作 PDF 进行哈希输入,然后将 PKCS#7 嵌入到 PDF 文档中。 (例如 Java 中的 ApachePDFBox)。
- 一个加密库,用于根据从 eSigner API(例如 Java 中的 BouncyCastle)收到的原始签名创建 PKCS#7。
获取CSC信息(可选)
CSC凭证列表
这款 CSC凭证列表 请求将检索您将在以后的API请求中使用的凭据。
- 输入以下命令。 (将 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"}'
- 您应该收到一个JSON对象,其中包含与用户相关联的凭据ID列表。 您的列表可能包含一个值。 将您的凭据ID复制并粘贴到文本编辑器中,以用于以后的请求。
CSC凭证信息(可选)
这款 CSC凭证信息 请求将返回证书和与凭据ID相关的其他信息,并且不需要签名。
- 输入以下命令。 如果您处于沙箱环境中,请使用
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 }'
- 您应该收到带有签名证书链和其他信息的JSON对象:
凭证授权
这款 凭证授权 请求将检索用于签名哈希的授权。
- 使用以下命令。 代替
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 " }'
- 您应该收到带有签名激活数据(SAD)的JSON对象。 复制此值并将其粘贴到文本编辑器中,以用于哈希签名请求。
签名哈希
现在您准备对文档哈希签名。
- 输入以下命令。 代替
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”}'
- 您应该收到一个包含签名的JSON对象。
签署PDF
除了签署文档哈希之外,您还可以上传和签署PDF文件。
在签署PDF时,您将处理两个POST请求:
- 上载PDF文件
- 签署PDF文件
您可以将上面使用的凭证重新使用 CSC凭证列表 请求。 您可能还需要检索一个新的 访问令牌.
上载PDF文件
- 使用以下命令。 代替
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“
- 您将收到一个JSON对象,其值为
id
。 复制此值以在下一个请求中使用。
注意:对于可见的签名,请参考以下 HTTP 请求标头(/v1/pdf/upload):
请求头 |
描述 |
---|---|
凭据 ID |
分配给密钥的唯一凭据 ID – 必需 |
签约理由 |
添加签名原因以添加签名外观和签名字典 - 可选,例如我批准此文档 |
签约地点 |
在签名字典中添加签名位置 - 可选,例如德克萨斯州休斯顿 |
联系方式 |
在签名字典中添加联系信息 - 可选,例如电话号码 |
签名字段位置 |
显示视觉签名的签名字段位置。 格式是 “x,y,宽度,高度“ - 可选的 |
页码 |
页码在哪里绘制签名 - 可选 |
手签 |
手签名的 Base64 编码 PNG 图像 - 可选 |
签署PDF文件
现在您可以签署PDF。
- 输入以下命令。 代替
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
- cURL将下载已签名的文件并将其保存到您指定的文件名中:
- 在Acrobat或Acrobat Reader中打开PDF以检查签名是否有效。