SSL.com的SWS API –简介

管理大量证书可能很麻烦。 随机发生的事件，例如最近的全行业 序列号熵问题，可能需要管理员一次手动吊销并重新发布数百个证书。 我们自己的支持代理和管理员在过去也经历过这一事实，这一事实促使SSL.com实施了更实用的解决方案： SSL.com Web服务（SWS）API.

SWS API可用于通过各种编程或脚本语言自动执行各种与证书相关的操作，例如颁发证书，重新键入密钥和重新处理订单，管理用户访问等等。 要获取针对单个订单的预生成的API cURL命令，请尝试附加 /developer 在该证书订单页面的末尾（例如 https://www.ssl.com/certificate_orders/co-1234xyz/developer).

为了介绍API的某些功能，本教程将引导您完成发行 域验证（DV）Web服务器证书。 在此过程中，我们将涉及许多有用的主题，例如访问API，创建 CSR，并准备服务器进行域控制验证。 此外，我们将看到如何通过API批量撤销证书，这在发生安全事件时特别有用。

沙盒

任何形式的自动化都需要在投入生产系统之前进行大量测试，尤其是在涉及金钱的情况下。 因此，SSL.com已实施并维护了 砂箱。 沙盒是我们生产API的开发克隆。 它包含原始数据库的所有功能，但未连接到生产数据库。 这意味着您可以自由创建新用户并进行实验，而不必担心弄乱某些东西并为错误付费。

当您对沙盒中的自动化功能感到满意时，可以将代码移至生产环境，并确保脚本不会失败。

可以在以下URL中找到生产API：

https://sws.sslpki.com/

要对沙盒执行API调用，您只需更改域名即可，如以下代码片段所示：

https://sws-test.sslpki.com/

准备环境

在开始使用API​​之前，必须首先准备一个工作环境。 在本教程中，我们将使用的工具是Linux终端和可信赖的文本编辑器。

您首先需要的是所有必需文件的目录。 为了实用程序的缘故，我们将此目录称为 sslcom_api_test/ 或“工作目录”。 要创建并输入目录，请在终端中发出以下命令。

$ mkdir〜/ sslcom_api_test $ cd〜/ sslcom_api_test

接下来，您必须下载 SSL.com的中间证书捆绑包，这是一个归档文件，其中包含用于安全访问API的所有必需的证书文件。 这样，您与API服务器交换的所有数据都将被加密，并且您可以放心，任何敏感信息（例如API密钥）都将受到保护，以防止被窃听。

从上面的链接下载ZIP存档，并将其解压缩到工作目录。 （请确保您进行更改 ~/Downloads 到保存ZIP文件的目录（如果需要）。 我们在本文中将使用的证书文件是 SSL_COM_RSA_SSL_SUBCA.crt.

$解压缩〜/ Downloads / SSLcom_DV_CA_Zip.zip -d。 存档：./ SSLcom_DV_CA_Zip.zip提取：./ SSL_COM_RSA_SSL_SUBCA.crt提取：./ SSL_COM_ROOT_CERTIFICATION_AUTHORITY_RSA.crt提取：./ CERTUM_TRUSTED_NETWORK_CA.crt

我们将使用 卷曲，一种典型的Linux网络工具，适用于本教程中的所有API调用。 cURL可以执行任何HTTP操作，并且在大多数Linux发行版中默认安装。 此外，可以通过cURL项目页面中提供的二进制可执行文件或在Cygwin安装程序中选择cURL，将cURL轻松安装在Windows上。 但是，请注意，由于API基于开放格式，因此您几乎可以使用任何其他此类网络工具或编程语言来访问它。

而且，我们将使用 OpenSSL的 准备我们的证书订单。 OpenSSL是一个开源工具包，几乎可以执行您可能需要的任何加密操作。 该工具也包含在Cygwin软件包列表中，因此，您可以在设置Cygwin实例时选择要安装的工具，也可以通过项目主页中提供的二进制文件手动安装。

最后，您将需要两个与您的用户帐户相关联的API密钥才能使用沙箱。 如果您在沙箱中还没有帐户，请通过沙箱的  登记表格。 该过程与创建普通的SSL.com客户帐户相同。 如果沙箱中已经有一个帐户，则可以安全地跳过此步骤。

访问API

我们的SWS API基于HTTP（浏览器使用的协议），并且所有数据都在 JSON格式.

大多数API调用都会要求您添加一个 account_key 的网络 secret_key 用于授权目的的参数。 您始终可以在“沙箱”的“信息中心”页面中找到您帐户的凭据，尽管在这种情况下，我们将通过API检索它们。

下一段代码中列出的命令将使您登录到门户网站，并检索您的帐户信息，包括这些API密钥。 如果要在终端窗口中复制和粘贴命令，请确保已替换 USERNAME 和 PASSWORD 与您的帐户的凭据。

$ curl -L --cacert SSL_COM_RSA_SSL_SUBCA.crt-请求GET --data-urlencode'password = PASSWORD'\'https：//sws-test.sslpki.com / user / USERNAME'{“ login”：“ JDemo”，“ email”：“ jdemo@mailinator.com”，“ account_number”：“ abc-1ec6012”，“ account_key”：“ 4497618e5c98”，“ secret_key”： “ FY + s9 / ghUrv7SQ ==”，“ status”：“已启用”，“ user_url”：“ https：//sws-test.sslpki.com / users / 1322857“，” available_funds“：” $ 0.00“}

尽管 cURL的语法 非常简单，让我们通过详细了解上一个电话让您更加熟悉它。

• -L 指示cURL遵循所有HTTP重定向。 您应该在所有调用中都包含此选项，以避免出现任何问题。
• --cacert SSL_COM_RSA_SSL_SUBCA.crt 指示cURL 验证API服务器的证书，以及我们在捆绑软件中下载的证书。 这将允许cURL加密发送到服务器的所有数据。
• --request GET 指示cURL执行HTTP GET请求。 有些呼叫仅接受HTTP POST或PUT请求。 此选项是处理此类请求的方法。
• --data-urlencode 准备帐户的密码以传输到服务器。 GET请求可以在URL中包含参数，而PUT和POST请求仅在正文中包含参数。 由于密码将通过URL传递，因此我们必须对其进行编码以转义任何符号（例如 / , ? or # ），可能会混淆服务器。 这个过程叫做 网址编码.

API调用的结果是一个包含帐户信息的JSON对象，其中包括 account_key 和 secret_key，在后续的API调用中是必需的。

颁发服务器证书

在准备好工作环境并掌握了API密钥之后，现在就可以开始使用API​​了。 举例来说，我们将要求发出 基本SSL证书 对于一个名为的假想Web服务器 example.ssl.com。 无论您使用的是API还是客户门户，证书的颁发都需要遵循某些步骤。

这些步骤包括生成私钥和公钥对，创建 证书签名请求（CSR)，创建证书订单并执行 域控制验证.

产生 CSR

这里有 几种方法 创造一个 CSR，但是由于我们已经在使用终端，因此让我们看一下如何创建 CSR 使用OpenSSL。 如果您已经有一个 CSR 您可以为此目的使用，则可以跳过此步骤。

A CSR 是base64编码的文件，其中包含将包含在最终证书文件中的大多数信息。 其中最重要的内容是 公钥 和 服务器域名 将为该证书颁发证书。

这意味着我们将需要一个公共密钥对，然后发出一个 CSR。 以下命令将创建一个新的 质子交换膜 文件在工作目录中，名为 example.ssl.com.key，包含两个键。

$ openssl genrsa -out example.ssl.com.key 2048生成RSA私钥，2048位长模数.......... +++ ...... ................................................... ...... +++ e是65537（0x010001）

使用密钥对，OpenSSL现在可以生成一个 CSR 为了你。 为此，请使用以下代码片段中显示的命令。

$ openssl req -new -key example.ssl.com.key -out example.ssl.com。csr

您将被要求输入将被合并到您的证书申请中的信息。 您将要输入的是专有名称或DN。 有很多字段，但您可以留空。对于某些字段，将使用默认值。如果输入“。”，则该字段将保留为空白。 -----国家名称（2个字母代码）[AU]：美国州或省名称（全名）[某些州]：德克萨斯州名称（例如城市）[]：休斯顿组织名称（例如公司） [Internet Widgits Pty Ltd]：示例组织单位名称（例如，部分）[]：示例部门通用名称（例如服务器FQDN或您的姓名）[]：example.ssl.com电子邮件地址[]：admin@example.ssl。 com请输入以下“额外”属性，以与您的证书请求一起发送。挑战密码[]：可选的公司名称[]：

OpenSSL将询问您基本的联系信息以及 通用名称 证书。 对于SSL证书，“公用名”是服务器的域名（在这种情况下， example.ssl.com）。 运行上面的命令将创建一个文件，名为 example.ssl.com.csr，在包含base64编码的当前目录中 CSR.

$ cat example.ssl.com。csr 

-----BEGIN CERTIFICATE REQUEST-----
MIIC5DCCAcwCAQAwgZ4xCzAJBgNVBAYTAlVTMQ4wDAYDVQQIDAVUZXhhczEQMA4G
A1UEBwwHSG91c3RvbjEQMA4GA1UECgwHRXhhbXBsZTEbMBkGA1UECwwSRXhhbXBs
ZSBEZXBhcnRtZW50MRgwFgYDVQQDDA9leGFtcGxlLnNzbC5jb20xJDAiBgkqhkiG
9w0BCQEWFWFkbWluQGV4YW1wbGUuc3NsLmNvbTCCASIwDQYJKoZIhvcNAQEBBQAD
ggEPADCCAQoCggEBAN7XMG7+zhaGfimdD1F0P3xxUS8dC6knKId3ONEt14Wa5E62
ZIUkyNgQC7gd3Be31jBhcuzJKn8UbTcWnPXd3OCbznbkqXtnljiF3yN9cRnj2f7y
89Hfmje8C07xe6AsoUMSTYzwsoo3zai1bxOUhy+uDU8FzxcSHunepdx/naHXY1Md
waQwzBCp668hFeIOslEjkTCNle3HK1LrgjZCIg0tyHBuZTNuUcQOyXrrDSrtOxx8
dqOD7sYqJie2xiCC9kkpNGYYTEuCuVKidgiC3e/DuLUNbhoUMfSENv64TGA7lRIj
nEBrrEm6FOSgPEGgEsM78cexVaqNCavNXNy49ysCAwEAAaAAMA0GCSqGSIb3DQEB
CwUAA4IBAQAV1Ac9nYH64BrB4OHlOYPkZbK6qCKfipTg7s4Xdcc3TponjTnMJyaQ
NNh0koCUOFJaYPjWIk/YkCeGNv/fbce+sddNbh0jtcVTPw8EFvs53IaUAE99zDvn
577Azj+OXfmaLQXjK15BtnT5hbmRKsrpPxnAdk4NOohM7QKWNEdBrcfTuH1q3WpD
6jSD35FlIFUfMgNi34mxF4vYamGrWgdURIb7DCk2h7B2LQK+vRNx1uPm9FVSeYZc
tHZWTiw2xEExw2Qco6lqXYl8t0Eo07gYl4gAEx9bibvVqYMo3Zss1mRg6+WEB8Xs
G+Hn1TG3XIaIbmvlpRNma/l766KZwLXG
-----END CERTIFICATE REQUEST-----

创建证书订单

获得了 CSR，您现在可以通过API创建证书订单了。 我们查看的第一个API调用是GET请求，而这个是POST。 POST请求必须在其主体中包括所有参数作为JSON对象。 因此，您需要使用JSON格式设置证书订单的参数。 以下代码段中提供了此示例的JSON配置。

{“ account_key”：“ 4497618e5c98”，“ secret_key”：“ FY + s9 / ghUrv7SQ ==”，“ product”：“ 106”，“ period”：“ 365”，“ server_software”：“ 15”，“ organization_name” ：“ Example”，“ street_address_1”：“ Example st”，“ locality_name”：“休斯敦”，“ state_or_province_name”：“ Texas”，“邮政编码”：“ 77777”，“ country_name”：“ US”，“ duns_number”： “ 1234567”，“ company_number”：“示例编号”，“ registered_country_name”：“ US”，“ unique_value”：“ 1ed1c72baf”，“csr“：” -----开始证书请求----- MIIDIjCCAgwaRlkPnuD ... 0QQ3JKQqJbii3760Rgon8hZmbkiE = -----结束证书请求-----“}

我们之前已经看过API密钥。 但是，要订购证书，我们还必须包括其他参数，例如 product 身份证和有效期 period。 您可以在 SWS API文档。 在此示例中，订购的有效期为1年的基本SSL证书。 下一组参数存储有关注册人（即您）的联系信息。 的 unique_value 参数（可选），包含一个字母数字字符串，可确保请求的唯一性。 如果您没有提供唯一值，则会为您生成一个随机值。 如果要在SSL.com用户门户之外生成DCV文件或CNAME条目，则以这种方式指定唯一值很有用。 最后， csr 参数必须包含有效的base64编码 CSR，就像我们保存在 example.ssl.com.csr.

用您自己的值替换参数 详细联系方式 和 CSR，并将此JSON配置保存在名为的文件中 example.ssl.com.json.

完成所有设置后，您现在就可以创建订单了。 cURL可以作为内联字符串或通过文件名接受JSON参数。 由于第一个选项太冗长，我们改为传递文件名。

请注意 --data-binary cURL开关，指示cURL在POST请求的正文中包含文件的内容。

$ curl -L --cacert SSL_COM_RSA_SSL_SUBCA.crt --request POST --header“ Content-Type：application / json” \ --data-binary“ @ example.ssl.com.json”'https：// sws-test .sslpki.com / certificates'{“ ref”：“ co-ac1ecm200”，“ registrant”：{“ organization”：“ Example”，“ organization_unit”：null，“ street_address_1”：“ Example st”，“ street_address_2”：null， “ street_address_3”：空，“位置”：“休斯敦”，“ state_or_province”：“德州”，“ post_office_box”：空，“邮政编码”：“ 77777”，“国家/地区”：“美国”，“电子邮件”：空} ，“ order_status”：“需要验证”，“验证”：null，“ order_amount”：“ $ 49.00”，“ certificate_url”：“ https://sandbox.ssl.com/team/abc-1ec6012/certificate_orders/co-ac1ecm200 “，” receipt_url“：” https://sandbox.ssl.com/team/abc-1ec6012/orders/fe3b-1ecm201“，” smart_seal_url“：” https://sandbox.ssl.com/team/abc-1ec6012 / certificate_orders / co-ac1ecm200 / site_seal“，” validation_url“：” https://sandbox.ssl.com/team/abc-1ec6012/certificate_orders/co-ac1ecm200/validation“，” external_order_number“：null，”证书“：空值 }

操作的结果是另一个JSON对象，其中包含新创建的证书订单的详细信息。 我们可以看到它 order_status，其参考编号在 ref 用于在所有后续API调用中引用此顺序的参数。 此外，输出中包含各种URL，例如 certificate_url，它指向门户中的订单详细信息以及 validation_url，它指向订单的验证页面。

最后， certificates 将包含与订单关联的所有证书。 由于尚未验证订单，因此未创建证书。

域控制验证

如证书订单中所述 order_status of validation required，您需要先执行验证，然后再颁发证书。

需要公共信任的CA（例如SSL.com）来验证证书购买者确实控制了将向其颁发证书的服务器，然后再向其颁发任何证书。 这可以通过完成 多种方法，然后您可以通过下一个API调用查看特定订单的所有可用验证方法。

请确保您替换参考编号 共AC1ECM200 在网址中输入您的订单参考号，该参考号是在上一个API调用中生成的。

$ curl --cacert SSL_COM_RSA_SSL_SUBCA.crt --request GET \ --data-urlencode'secret_key = FY + s9 / ghUrv7SQ =='--data-urlencode'account_key = 4497618e5c98'\'https：//sws-test.sslpki.com / certificate / co-ac1ecm200 / validations / methods'{“指令”：“ https://www.ssl.com/faqs/ssl-dv-validation-requirements/”，“ md5_hash”：“ 29BD4C00B65613CCEC04C19C0050D931”，“ sha2_hash “： ”BF340FDFD9C43D45B8310FC4A400E4D4B61CAF8D2002BAAF0945252E35F9D751“， ”dns_sha2_hash“： ”BF340FDFD9C43D45B8310FC4A400E4D4.B61CAF8D2002BAAF0945252E35F9D751.167c8a5c49“， ”dcv_methods“：{ ”example.ssl.com“：{ ”EMAIL_ADDRESSES“： ”admin@ssl.com“，” 管理员@ SSL .com”，“ webmaster@ssl.com”，“ hostmaster@ssl.com”，“ postmaster@ssl.com”，“ admin@example.ssl.com”，“ administrator@example.ssl.com”，“ webmaster” @ example.ssl.com”，“ hostmaster@example.ssl.com”，“ postmaster@example.ssl.com”]，“ http_csr_hash“：{” http“：” http://example.ssl.com/.well-known/pki-validation / 29BD4C00B65613CCEC04C19C0050D931.txt”，“ allow_https”：“ true”，“ contents”：“ BF340FDFD9C43D45B8310FC4A400E4D4B61CAF8D2002BAAF0945252E35F9D751 \ nssl.com \ n167c8a5c49_}csr_hash”：{“ cname”：“ _ 29BD4C00B65613CCEC04C19C0050D931.example.ssl.com。 CNAME ff8716e0fd.ssl.com。“，”名称“：” _ 29BD4C00B65613CCEC04C19C0050D931.example.ssl.com“，”值“：” BF340FDFD9C43D45B8310FC4A400E4D4.B61CAF8D2002BAAF0945252E35F9D751.ff.s。“ com“}

返回的输出将包含执行域控制验证所需的所有信息。 例如，如果您想使用 http_csr_hash  验证方法，您必须在将为此证书颁发证书的服务器中创建一个文件，名为 .well_known/pki-validation/29BD4C00B65613CCEC04C19C0050D931.txt。 该文件应 究竟 包含 contents 参数。

之后，您可以访问 validation_url 在创建订单的上一个呼叫中找到并继续进行验证，就像通常通过客户门户网站创建的订单一样。 （您可以随时访问 验证方式 页并找到特定订单的网址）。

成功进行域控制验证后，将颁发证书并可以下载它。

取回证书

您可以在Web门户中找到您的证书或通过API检索它。 为了我们的目的，我们将使用API​​。 如上一节所述，在创建新的证书订单时，响应中包含一个参考号。 该编号可用于检索订单的详细信息，包括实际的证书数据。

$ curl --request GET -L --cacert SSL_COM_RSA_SSL_SUBCA.crt \ --data-urlencode'secret_key = FY + s9 / ghUrv7SQ =='--data-urlencode'account_key = 4497618e5c98'\'https：// sws-test .sslpki.com / certificate / co-ac1ecm200？response_type = individually＆response_encoding = base64'{“ description”：“ 1年基本SSL”，“ product”：“ 106”，“ product_name”：“ basicssl”，“ order_status”：“已发布” ，“ order_date”：“ 2019-05-02T10：08：48.000-05：00”，“注册人”：{“ organization”：“ Example”，“ organization_unit”：null，“ street_address_1”：“ Example st”，“ street_address_2”：空，“ street_address_3”：空，“ locality”：“ Houston”，“ state_or_province”：“ Texas”，“ post_office_box”：空，“ postal_code”：“ 77777”，“ country”：“ US”，“ email“：null}，”证书“：” \ nMIIE1TCCA72gAwIBAgIRANsjhF + t ... 4CAw5Egg73IgIHggE1QEZiYQRu + 0wDQY \ n“，” common_name“：” example.ssl.com“，” domains_qty_purchased“”：1 0”，“ subject_alternative_names”：[“ example.ssl.com”，“ www.example.ssl.com”]，“ validations”：null，“生效日期”：“ 2019-05-03T11：22：37.000-05： 00“，” expiration_date“：” 2020-05-02T11：22：37.000-05：00“，” algorithm“：” SHA256“，” external_order_number“：null，” domains“：null，” site_seal_code “：空，” subscriber_agreement“：空，” server_software“：15，”联系人“：[{...}，{...}]}

由于该API是要以编程方式使用的，因此您必须解析JSON响应才能隔离证书并将其保存到文件中。 JSON解析超出了本文的范围。 但是，这是一个简单的任务，可以用大多数现代脚本或编程语言轻松实现。

搜索证书订单

如果您手边没有参考号，则可以发出API调用来检索您所有帐户的证书订单。 通过此调用，您可以过滤订单以及将显示哪些信息。

$ curl --cacert SSL_COM_RSA_SSL_SUBCA.crt --request GET \ --data-urlencode'secret_key = FY + s9 / ghUrv7SQ =='--data-urlencode'account_key = 4497618e5c98'\'https：//sws-test.sslpki.com / certificates？fields = domains，ref，order_status'[{“ ref”：“ co-ac1ecm200”，“ order_status”：“发布”，“ domains”：[“ example.ssl.com”]}，{“ ref“：” co-581eclsap“，” order_status“：”正在验证，请稍候“，” domains“：[” example.ssl.com“]}，{” ref“：” co-6f1ecm1of“，” order_status“： “等待客户的联系信息”，“域”：[“ test.ssl.com”]}}

fields URL参数使您可以控制哪些证书详细信息将显示在输出中。 您还可以通过 per_page 和 page 请求参数。 要根据证书的颁发日期限制证书的数量，您可以使用 start 和 end 参数。 最后，您可以使用条件（例如产品ID，有效期或证书中包含的任何其他字段）来筛选和搜索订单。 有关更多信息，请查看 SSL.com的API文档.

吊销证书

我们将在本指南中介绍的最后一个功能是批量证书吊销。 只要只有您（或您信任的人）持有与证书关联的私钥，证书就可以保护您。 万一私钥遭到破坏，或者需要更改证书上的任何信息，则必须立即吊销证书并颁发新证书。

如果怀疑私钥被盗，则客户端软件（例如浏览器或操作系统）必须尽快停止接受其有效。 因此，我们强烈建议您实施一个自动系统，以在服务器上吊销，重新发行，检索和安装证书。

SSL.com的SWS API允许您以编程方式吊销任何证书订单下的一个，多个或所有证书。 以下API调用将吊销证书顺序下的所有证书 共AC1ECM200:

curl --cacert SSL_COM_RSA_SSL_SUBCA.crt --request DELETE --header“ Content-Type：application / json” \ --data-binary'{“ account_key”：“ 4497618e5c98”，“ secret_key”：“ FY + s9 / ghUrv7SQ = =“，”原因“：”被盗“}'\'https：//sws.sslpki.com / certificate / co-ac1ecm200'{“ status”：“ revoked”}

此cURL命令发出DELETE HTTP请求（而不是像以前的命令一样的GET或POST），并提供内联的JSON配置。 创建具有JSON内容的文件并将其通过文件名传递给cURL也是有效的，其方式与发出证书顺序的命令相同。

您可以在[ reason  参数，并且可以选择在JSON中包含证书序列号列表，以仅撤消与这些序列匹配的证书。 如果不包括序列号，则属于指定证书顺序的所有证书都将被吊销。

有关此API调用的更多信息，请查看我们的 API文档.

结论

本文介绍了一个简单的颁发和吊销DV服务器证书的过程，作为可通过SSL.com的SWS API执行的操作的简单示例。 SSL.com鼓励在可能的情况下使用自动化，因为它消除了手动执行相同重复任务的麻烦，更重要的是，在紧急情况下，可以更快地响应（请参阅 序列号熵问题).

请随时尝试我们的 砂箱 和 软件接口，如果您遇到任何问题，请立即与我们的支持代理联系。

• 您的SSL.com帐户-提交一个 CSR
• 预测试失败？
• 您的SSL.com帐户-验证
• 您的SSL.com帐户-订单
• 您的SSL.com帐户-域
• SSL /TLS ACME证书颁发和吊销
• 支持的Cloud HSM用于文档签名和EV代码签名