蚂蚁金服网站新服务器证书兼容性验证和修正指引

1. 背景介绍

蚂蚁金服网站使用HTTPS来保证通信安全,软件或系统在调用蚂蚁金服提供的系统服务或API过程中会使用数字证书权威认证机构(CA)的根证书来校验蚂蚁金服网站服务器身份的真实性。

蚂蚁金服网站服务器证书当前通过权威电子认证机构VeriSign签发,根CA为“VeriSign Class 3 Public Primary Certification Authority - G5”,计划于2018年7月10日启用的新服务器证书,由权威电子认证机构DigiCert签发,根CA为“DigiCert Global Root CA”。

为了提升兼容性,在部署新证书时,我们将在服务上增加部署Baltimore CyberTrust Root根对DigiCert Global Root CA的根交叉认证证书,因此,客户端信任根证书库中只要包含Baltimore CyberTrust Root或DigiCert Global Root CA中任意一个即可。

大部分操作系统和执行环境的默认信任根证书库都已内置上述两个根CA证书,也就是说,一般情况下,大部分系统无需做特别的配置即可兼容新服务器证书。

2. 新、旧根证书信息

下表列出了4个根证书的基本信息、在常见OS和执行环境默认配置下的兼容性情况:
表1 蚂蚁金服新老服务器根CA证书的信息

根证书名称 证书序列号 有效期 Windows Java Android IOS Firefox 备注
DigiCert Global Root CA 08:3b:e0:56:90:42:46:b1:a1:75:6a:c9:59:91:c7:4a 10/11/2006~10/11/2031 Windows 7+ 1.6.05+ 2.3.3+ iOS 5+ 2.0+ 这是新证书的根CA.如果出现不能兼容新证书的场景,添加这个根证书到执行环境的信任库。
Baltimore CyberTrust Root 02:00:00:b9 12/5/2000~12/5/2025 Windows XP+ 1.4.2+ 2.0+ iOS 5+ 1.0+ 这是新证书的兼容性根。
VeriSign Class 3 Public Primary Certification Authority - G5 18:da:d1:9e:26:7d:e8:bb:4a:21:58:cd:cc:6b:3b:4a 8/11/2006~16/7/2036 Windows 7+ 1.6.19+ 2.3.3+ iOS 5+ 2.0+ 这是旧证书的根CA,如果采用自主管理信任根的方式,需要用到这个根证书文件。
Class 3 Public Primary Certification Authority 70:ba:e4:1d:10:d9:29:34:b6:38:ca:7b:03:cc:ba:bf 29/1/1996~2/8/2028 Windows XP+ 1.4.2+ 2.0+ iOS 5+ 1.0+ 这是旧证书的根CA。

注:

  1. macOS: 根据DigiCert官网提供的兼容性信息,所有Mac OS X都可兼容新证书;根据目前能从Apple官网查到“macOS中可用的受信任根证书列表”的最早版本为OS X Mavericks(即10.9,2013年发布的版本),能确认自该版本起的macOS版本均包含上述四个根CA证书。
  2. Linux:Linux系统信任根证书的保存位置因发行版(Distribution)不同有所差异,大部分Linux发行版使用目录"/etc/ssl/certs/"或文件"/etc/pki/tls/certs/ca-bundle.crt"来包含系统信任根证书库。预期在绝大部分Linux发行版中,都可同时兼容我们的新旧证书。
  3. 如何获取根证书文件?一般需要从CA机构的官方网站下载根CA证书文件,为方便合作伙伴升级,我们将DER和PEM格式的"VeriSign Class 3 Public Primary Certification Authority - G5" 和 "DigiCert Global Root CA"的根证书文件打包于一个文件中,您可下载root-certs.zip(链接如下)并解压,然后根据操作命令需要的格式选择使用PEM或DER格式的文件。压缩包中的文件后缀标识格式,文件名体现了根CA名称。
    download: root-certs.zip

3. 需要您做什么

需要您确认贵司业务系统中与蚂蚁金服网站系统交互的系统或组件可兼容新服务器证书,并:

  • 如果验证结果为可兼容,贵司不需要做其他任何事情。
  • 如果不能兼容,您需要对贵司系统进行必要的修正。

建议您按照“如何验证”章节的方法尽快完成验证。

如果验证结果为不兼容,贵司需要修改相关的系统实现或配置,建议在2018年6月26日前完成修正。最晚应于2018年7月10日前修正,否则贵司业务系统与蚂蚁金服网站/服务之间将不能正常进行HTTPS通讯,将影响业务正常运行。

在验证和修正过程中遇到问题,您可以联系支付宝开放平台技术支持中心

4. 如何验证

您可通过支付宝开放平台沙箱环境生产验证环境来验证贵司系统是否可兼容新的服务器证书。部分API和系统服务可能在沙箱环境不具备,对这部分API或系统服务,您可通过生产验证环境来进行验证。

如果贵司系统可正常获得蚂蚁金服系统的响应,说明是兼容的。

如果贵司系统不能正常获得蚂蚁金服系统的响应,很有可能是不兼容的。

如果验证结果为不兼容,您需要:

  1. 查看贵司系统所使用的TLS/SSL库的使用文档,确保新服务器证书的根CA包含在执行环境的信任根证书库中。我们总结了常见环境可能的修正方法于本文档第6章,您可参考。
  2. 完成上述步骤后,重新验证。

4.1 沙箱环境验证

您可在开放平台沙箱环境按照正常使用方法进行测试验证,如果业务测试可以顺利进行,说明是可兼容新服务器证书的。沙箱环境(alipaydev.com域名)将在2018年5月24日启用新的服务器证书方案。

注意:

  1. 在沙箱环境验证时应使用跟贵司业务系统生产环境相同的操作系统、执行环境、开发语言及程序逻辑进行验证,这样验证出来的结果才是可靠的。
  2. 应使贵司系统同时兼容新老两套服务器证书。

4.2 HOST绑定IP方式,连生产验证环境验证

我们将在生产验证环境一小部分机器上部署新的服务器证书,可通过HOST绑定IP的方式来访问已部署了新证书的环境。HOST和IP的对应关系请查看 “表2 新证书生产验证环境的IP地址”。

HOST绑定IP可通过修改操作系统的hosts文件来进行,例如,可在hosts文件中新增一行如下内容,实现将域名"openapi.alipay.com"绑定到新证书环境:

110.75.129.10 openapi.alipay.com

注:

  1. 生产验证环境可以访问的接口与生产正式环境相同,且被视为生产正式业务。
  2. 在使用生产验证环境验证前,请充分评估对贵司业务系统以及业务的影响。
  3. 因验证环境机器数量有限,不应绑定该环境进行生产正式业务,请在验证完成后尽快解除HOST绑定。
  4. 请根据贵司系统的当前连支付宝系统的实际域名替换上述内容中的"openapi.alipay.com",如果您的系统连接到多个域名,验证一个即可。
  5. 在linux系统下,hosts文件的完整路径为"/etc/hosts",在Windows系统下,hosts文件的完整路径为"C:\Windows\System32\drivers\etc\hosts"。

表2 新证书生产验证环境的IP地址

域名
IP
启用时间
intl.alipay.com
open-na.alipay.com
205.204.107.49
2018年5月31日
zmopenapi.zmxy.com.cn
110.75.246.5
2018年6月7日
使用证书CN="*.alipay.com"的其他域名,例如:
openapi.alipay.com mapi.alipay.com supergw.alipay.com
查看域名当前使用证书信息的方法请参阅第5章 常见问题 Q6
110.75.129.10
2018年5月24日

5. 常见问题

Q1:什么是服务器证书?
A:服务器证书通常又称为“SSL证书”、“域名证书”、"SSL Certificate"、"Server Certificate"、"SSL Web Server Certificates"、"TLS/SSL server certificate"。通常由权威机构颁发的证书,用于对网站进行身份鉴定,并使客户端与网站之间通过TLS/SSL协议建立起安全传输通道,HTTPS协议是最常见的基于TLS/SSL的应用层协议之一。

Q2:什么是根证书?
A:根证书用于标识权威机构的身份,是权威机构用自己的身份私钥对自己的身份公钥签发的数字证书。根证书需要经不易被篡改的通道分发;浏览器、操作系统、TLS/SSL开发库通常随软件发行包预置其信任的权威机构的根证书。

Q3:如何确认是否可兼容新证书?
A:建议按照第4章介绍的方法进行验证;如果您对TLS/SSL技术和应用非常精通,也可仅通过检查相关的系统代码和配置,来判断是否可兼容新证书。

Q4:请问应在何时安装新的根CA证书?
A:必须在2018年7月10日前将新的根CA证书安装于贵司系统中。建议在2018年6月26日之前完成,因为自6月26日起,我们将在生产正式环境小量灰度应用新证书,以检验合作伙伴系统的准备情况。

Q5:修正过程中有哪些注意事项?
A:必须以新增安装根CA证书的方式(即应该同时兼容老证书和新证书),且必须在2018年7月10日前完成。因为我们将以灰度方式逐步启用新证书,在灰度期间,生产正式环境中将有一部分服务器使用的是新证书,一部分服务器使用的是老证书。

Q6:本次升级涉及的网站/域名有哪些?
A:本次服务器证书升级以证书为操作控制粒度,通过X.509 V3的Subject Alternative Name(SAN,中文名:主题备用名称)扩展使一个证书可适用于多个域名。本次升级包含三个证书,证书主题通用名(Subject CommonName)分别为:"*.alipay.com"、"render.alipay.com"、"*.alipayobjects.com"。您可以通过下述方法来协助确认:

以,使用openssl命令行工具快速确认某个域名是否在本次升级范围,命令行格式为:

openssl s_client -connect real_domain_name:443 -servername real_domain_name -showcerts

以域名“www.alipay.com”为例:如下为运行结果截图,可以看到证书的主题CN与上述三个中的第一个相同,说明"www.alipay.com"域名在本次升级范围。

img

Q7:请问应在何时完成对应验证?如果无法按时完成验证会有什么影响?
A:建议您在2018年6月26日前完成验证,最迟应在2018年7月10日完成验证。如果贵司系统的实现方式已能兼容新的服务器证书,那么,不会影响贵司的业务;如果贵司系统的实现方式不能兼容新的服务器证书,那么会导致贵司系统与蚂蚁金服相关系统不能正常交互,影响业务顺利进行

Q8:请问应在何时完成对应修改?如果无法按时完成兼容修改,有什么临时解决方案?
A:如果您的系统经验证是不能兼任新证书的,建议您在2018年6月26日前完成修改,最迟应在2018年7月10日完成修改。如果无法按时完成修改,我们可为部分业务仍使用旧证书的临时环境,您可通过HOST绑定IP的方式使用(HOST和IP对应关系请查看 表3. 旧证书临时环境的IP地址),以临时规避证书升级产生的影响。请务必在2018年7月29日16点之前完成系统修改,并取消绑定临时环境IP,恢复以正常的方式连接蚂蚁金服生产正式环境。

表3. 旧证书临时环境的IP地址

域名
IP
可用时间
intl.alipay.com
open-na.alipay.com
zmopenapi.zmxy.com.cn
110.75.246.6
2018年6月7日~2018年7月19日
使用证书CN="*.alipay.com"的其他域名,例如:
openapi.alipay.com mapi.alipay.com supergw.alipay.com
110.75.139.10
2018年5月24日~2018年7月29日

6. 参考修正方法

6.1 JAVA

6.1.1 不兼容的现象

如果验证时不能正常获得蚂蚁金服系统的响应,并在您的系统中出现如下错误信息,说明不兼容新的证书。

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed...

6.1.2 修正方案

如果您的系统程序是使用Java程序开发,您使用的信任根证书(trustStore)库可能是如下两种情况之一: 一种是使用jre发行包中的cacerts,另一种是使用自主管理的trustStore。

使用jre发行包中的cacerts

cacerts文件是Java环境默认使用的信任根证书库,位于%JAVA_HOME%/lib/security/目录下,cacerts文件本质是一个JKS (Java KeyStore),可使用Java发行包中自带的keytool工具来查看和修改,默认密码为“changeit”,keytool命令行工具在%JAVA_HOME%/bin目录下。 说明:蚂蚁金服所提供Java语言版SDK为这种方式。 如表1所列,正常情况下JDK1.4.2及以上版本的cacerts应已经包含了Baltimore CyberTrust Root,JDK 1.6.05及以上版本的cacerts应已经包含了DigiCert Global Root CA。 如果系统实际验证结果为不通过,可以通过如下方法检查执行环境中的cacerts是否包含蚂蚁金服新服务器证书的根CA(表1中前2个根CA之一)。
检查方法

  1. 将cacerts中信息输出为易于阅读的文本形式。命令行下输入如下命令,回车后,输入cacerts的保护密码。 keytool -list -v -keystore %JAVA_HOME%/lib/security/cacerts > cacerts.txt
  2. 查找其中是否包含特定主题的可信证书。 以DigiCert Global Root CA为例:在上一步中输出的文件中(cacerts.txt)查找是否包含主题(Subject)和签发者(issuer)CN(Common Name)皆为"DigiCert Global Root CA"的trustedCertEntry的项目,找到后,核对证书序列号是否与表1中相同。

img

img

说明:证书序列号的显示方式一般有两种,一种是带":"的,以两个16进制数一组;一种是不带":"的,与前一种表示方法相比,其数值相同,但是最左边的0会被省略。

添加根证书到cacerts
如果没有查找到,您需要添加根CA证书到cacerts。
在命令行下输入如下命令,回车后输入cacerts的保护密码,看到增加成功的提示即说明添加成功。

keytool -keystore $JAVA_HOME$/lib/security/cacerts -importcert -alias CAFriendlyName -file rootca-cert.pem 
--注:rootca-cert.pem为PEM格式的根CA证书文件,请使用表1中链接下载PEM格式根证书,CAFriendlyName是计划给此根CA的友好名称/别名,您可以用根证书主题名称代替,这个别名在一个jks中必须唯一。

使用指定的trustStore

如果您的系统程序目前是用指定trustStore的方式,有两种修正方法:

一、修改系统实现代码,改为使用jre自带cacerts的方式,可使用支付宝开放平台提供的SDK或参考其写法;同时检查您的java版本,官方Java发行包自1.4.2版本起都内置了上述新旧服务器证书的兼容根CA。稳妥起见,您可以按前述方法确认都包含。

二、往当前trustStore增加表1中的第一个根CA证书,操作方法与往cacerts中增加相同,只是操作的keystore对象换成您应用系统中使用的。如下示例:

keytool -keystore 您系统使用的jks文件路径 -importcert -alias CAFriendlyName -file rootca-cert.pem 

Java中一般使用如下几种方式来指定trustStore:

1. 代码中设定,示例代码:
System.setProperty("javax.net.ssl.trustStore", "<same .jks file>");
2. 设置系统变量javax.net.ssl.trustStore
3. 修改JVM启动选项:"-Djavax.net.ssl.trustStore=-Djavax.net.ssl.trustStore=<some .jks file>"

参考资料:
Keytool:https://docs.oracle.com/javase/6/docs/technotes/tools/solaris/keytool.html

6.2 PHP

6.2.2 不兼容的现象

如果验证时不能正常获得蚂蚁金服系统的响应,并在您的系统中出现类似如下的错误信息,说明不兼容。

"cURL error 60: SSL certificate: unable to get local issuer certificate."

"CURLE_SSL_CACERT (60) peer certificate cannot be authenticated with known CA certificates."

6.2.3 修正方案

使用操作系统信任根证书库的情况

PHP一般使用系统中所安装的Openssl的信任根证书库,Openssl的信任根证书库根据操作系统版本的不同所在位置不同,可能的情况以及添加可信根CA证书的方法如下:

操作系统类型 信任根证书库位置 添加可信根CA证书的方法
Linux /etc/ssl/certs/ 拷贝根CA的证书文件(DigiCertGlobalRootCA.pem)到目录下
Linux /etc/pki/tls/certs/ca-bundle.crt cat DigiCertGlobalRootCA.pem >> /etc/pki/tls/certs/ca-bundle.crt
Linux /etc/ssl/certs/ca-bundle.crt cat DigiCertGlobalRootCA.pem >> /etc/ssl/certs/ca-bundle.crt
Linux /etc/pki/tls/certs/ca-bundle.trust.crt cat DigiCertGlobalRootCA.pem >> /etc/pki/tls/certs/ca-bundle.trust.crt
Unix /System/Library/OpenSSL/ 拷贝根CA的证书文件(DigiCertGlobalRootCA.pem)到目录下

使用自主管理信任根证书库的情况

PHP代码中可能设定使用自主管理的根CA证书文件,典型代码如下:

curl_setopt(pCurl, CURLOPT_CAINFO,  "./rootca.pem");

修复方法:将表1中新服务器证书的根CA证书(DigiCertGlobalRootCA.pem)添加到rootca.pem。可用cat操作命令:

cat DigiCertGlobalRootCA.pem >> ./rootca.pem

6.3 .NET

.NET环境一般默认使用Windows操作系统维护的受信任的根证书颁发机构。Windows XP及以上一般均可兼容我们的新旧服务器证书。

6.3.1 不兼容的现象

如果验证时不能正常获得蚂蚁金服系统的响应,并在您的系统中出现类似如下的错误信息,说明不兼容。

The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel.```

6.3.2 修正方案

如果出现SSL相关异常,请您的系统管理员下载表中第一个根CA证书,并将其导入到受信任的根证书颁发机构区域。

6.4 PYTHON

6.4.1 综述

当使用标准库的http client (urllib, urllib2, http, httplib)时,python自2.7、3.4、3.5版本起,默认校验服务器证书是否由可信签发机构签发、证书主题(或SAN)是否与服务器域名匹配,且使用ssl模块的信任根证书库。详细信息可查看:https://www.python.org/dev/peps/pep-0476/

早期的python版本默认既不校验服务器证书是否由可信签发机构签发,也不校验证书主题(或SAN)是否与服务器域名匹配,因此,不会遇到问题。

6.4.2 不兼容的现象

如果验证时不能正常获得蚂蚁金服系统的响应,并在您的系统中出现类似如下的错误信息,说明不兼容。

SSL: CERTIFICATE_VERIFY_FAILED

6.4.3 修正方案

Python默认使用系统ssl模块(通常为Openssl)的信任根证书库,也可以通过cafile、capath、cadata来指定。

如果是使用系统ssl模块(Openssl)的信任根证书库,可参考6.2节的介绍,往系统库中增加新的根CA证书(表1中第一个)。

如果是使用自主管理的信任根证书库,往其中增加新的根CA证书(表1中第一个)。

可能的代码写法:

# ssl.create_default_context(purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)
context = ssl.create_default_context() # 按照系统默认配置的写法。
urllib.urlopen("https://site.sample.com", context=context)

参考文档:
https://docs.python.org/2.7/library/ssl.html
https://docs.python.org/3/library/ssl.html

7. 特别提醒

  1. 如果您的系统是用预置蚂蚁金服服务器证书的方式来与蚂蚁金服网站建立HTTPS连接,由于我们每年将至少更新一次证书密钥,为避免贵司业务受证书密钥更新的影响,强烈建议您改为TLS/SSL协议中普遍使用的X509证书链校验方式。
  2. 为了检验商家和开发者系统兼容新证书的准备情况,将在6月26日至7月初的部分时间段将部分请求灰度到部署了新证书的服务器上。如果您的系统此时还不兼容新的服务器证书,可能会出现部分业务失败,通常情况下重试即可恢复业务。

8. 联系我们

蚂蚁技术支持中心提供多种问题反馈和获取技术支持的通道。如对本次升级有任何疑问、验证或修正过程遇到困难,请联系蚂蚁技术支持中心,中心首页:https://opensupport.alipay.com/support/home.htm

onlineServer