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的开发克隆。 它包含原始数据库的所有功能,但未连接到生产数据库。 这意味着您可以自由创建新用户并进行实验,而不必担心弄乱某些东西并为错误付费。

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

注意: 本文是针对沙盒开发的,您可以尝试使用本文档中包含的任何API调用。

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

https://sws.sslpki.com/

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

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

准备环境

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

注意: 这些说明是针对香草编写的 Ubuntu Linux操作系统 分布,这是现实世界中可能会遇到的一种典型开发环境。 话虽如此,本文档中提供的脚本也可以通过以下方式在Windows上运行: Cygwin的.

您首先需要的是所有必需文件的目录。 为了实用程序的缘故,我们将此目录称为 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.

注意: 在Windows上,您将必须找到ZIP存档,双击它,然后将文件解压缩到工作目录中。
$解压缩〜/ 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 # ),可能会混淆服务器。 这个过程叫做 网址编码.
注意: 反斜线(\)在第一行末尾强制Linux终端忽略换行符,并继续解析下一行中的字符,这是原始命令的一部分。 我们将使用此语法将长命令分成多行,以使它们更具表现力。

API调用的结果是一个包含帐户信息的JSON对象,其中包括 account_keysecret_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.

请注意: 请确保已从中删除所有换行符 CSR 在将其添加到命令之前。 换行符用于指示终端处理输入的文本,直到换行符为止。 保留字符可能会使您的cURL命令失败。

完成所有设置后,您现在就可以创建订单了。 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_pagepage 请求参数。 要根据证书的颁发日期限制证书的数量,您可以使用 startend 参数。 最后,您可以使用条件(例如产品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! 如有任何疑问,请通过电子邮件与我们联系 Support@SSL.com,致电 1-877-SSL-SECURE,或只需单击此页面右下方的聊天链接。 您还可以在我们的网站上找到许多常见支持问题的答案 知识库.
Twitter
Facebook
LinkedIn
Reddit
邮箱地址

保持信息灵通和安全

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

我们希望收到您的反馈

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