安全接入——后台

目前，TENCENT SOTER一共有5个后台相关接口。为了简化客户端网络接入代码编写，我们在soterwrapper这个gradle plugin中提供了5个网络封封装体。你可以在我们简单的客户端sample工程中看到如何使用他们。现在，介绍下在后台如何实现你的逻辑：

检查是否支持TENCENT SOTER

尽管我们提供了一个客户端接口检查本设备是否支持TENCENT SOTER，我们依然强烈建议通过后台接口检查本设备的支持情况，因为只有加入到后台白名单中的型号，才是真正经过腾讯验收的TENCENT SOTER设备。我们在这里定义了一个web service接口来提供这种后台检查。你可以在任何你需要的时候调用这个接口。客户端侧，我们提供了一个名字叫IWrapGetSupportNet的网络封装体(NetWrapper)以完成这件事。

上传ASK公钥

我们已经在之前章节介绍过什么叫ASK了。目前，只有腾讯的TAM server可以检查ASK的有效性。因此，你需要在客户端生成ASK之后，上传ASK公钥，然后根据文档调用后台接口检查所生成的ASK是否合法。如果是一个合法的密钥，那么将密钥对应上cpu_id+uid（稍后介绍他们是什么）存储在应用服务器。我们在客户端提供了一个名为IWrapUploadKeyNet的网络封装体来协助你上传处理这部分数据。2.0版本之后的ASK有两种形式：传统格式和证书链格式。

1.传统格式

ASK客户端上传数据包括两个部分：密钥结构体（JSON格式）和ATTK对该JSON的签名(Base64编码后的签名)。请不要将签名Base64解码，直接将编码后的签名作为请求发送验签。

客户端所上传的密钥结构体示例如下：

{"pub_key":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxV+PdfwSQ2m97yw9Wcev\nAqIPteSi8wc92tqZ0EmJ2ACE12pbewuJw9v01v3GMTco10buL99/k+aeR5uXetuK\nrw0SDoIABPqnX3ttZrszV8xsleSiab032upmVgLcDypXU09wDqeJE5lPhM5WCm6f\nnKduf1XoGqbPe9uZTLqLM/moyC+QCXnhxxWFngyqI19hvzbFFpP6RtFdra+3yIKw\nKPxITIpFJ9GdWas1AaHfBlprUiGi5rPdD7ACQOanxLeo8KS/Amh4Q/u9asBf4JaJ\njn/T1sXY6PU2LxrG4mwZi6sWYOcsBB5L3T9HNdCxwSDY9ODwTNrXqcUmZi3NUBLU\n0wIDAQAB\n-----END PUBLIC KEY-----\n", "cpu_id":"0f000000262300000b5f094d1cf4c411", "counter":181, "uid":"10206"}

其中，pub_key即开发者需要保存的ASK公钥部分。直接将公钥值取出存为pem格式（直接后缀为.pem即可）。

同时，为了防止重放攻击（即攻击方直接拦截请求并重放），建议存储counter字段（该字段在上传ASK、上传AuthKey以及最终验证签名的请求中均存在，存储在TEE中，每一个SOTER相关请求之后都会自增，并且不随着设备升级或者清空数据等被重置，因此非常可靠），该字段仅仅和cpu_id字段有关联性，后续请求先检查是否counter比之前对应设备下的值要大，如果不是，则可以认为是非法请求，否则就更新该设备的counter值为所上传值。

2.证书链格式

证书链格式ASK客户端上传的数据包括2个以上的x.509证书，从0~n分别对应ask、attk以及上游直到根证书的一系列证书。后台发送TAM进行验签的时候只需将签名部分留空，传入证书链结构体即可。ASK公钥可以从证书中直接解出，cpu_id、counter和uid信息则包含在第0位的ASK证书中，存放于证书的扩展部分，OID地址为1.3.6.1.4.1.11129.2.1.17 ，具体解法可参考server-demo或者sdk源码。

格式如下：

{"certs":["-----BEGIN CERTIFICATE-----\nMIIDsDCCApqgAwIBAgIBATALBgkqhkiG9w0BAQswHTEbMBkGA1UEAxMSSHVhd2Vp\nIEtleVN0b3JlICAgMB4XDTE4MTIxODEzMjM1MFoXDTI4MTIxODEzMjM1MFowGjEY\nMBYGA1UEAxMPQSBLZXltYXN0ZXIgS2V5MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A\nMIIBCgKCAQEA0IEGtWJI\/5ZiM8PWwdvxFqFd7y2MudZjTBoykZw\/I0cSunUFPhS9\nrpoJrm88BvSBW4NfUigpoJ15equLUDnhHRoQcaokbdOG+arhoG6Pspjt95fa\/I7h\nDDsXcpKy90igMbR11LcWYD2SVtuPIcyuHh2m3co4NuXL2u2jHHywZPpLBmmEK4ms\n52+q\/XVKH9i7tsZvLfest1b2nj2FFPRKS5+I+uUQ5tossCmGcRICD+N8\/z5XVZxH\nb+IHINOVTGewKBdOxJ\/t1XHwSnWWutgV71nHrjI3KqMqzw4HPVafzzs+KxnYUh1r\nLzMY40bDEbQ\/enInGvpvpxtYUJDqyu7\/\/QIDAQABo4IBADCB\/TALBgNVHQ8EBAMC\nAAAwCAYDVR0fBAEAMIHjBgorBgEEAdZ5AgERBIHUMIHRAgECCgEBAgEDCgEBBHd7\nImNwdV9pZCI6IkhVQVdFSV9IV0xZQV9iMzE2MTQwMS02MmZhLTRkOWItYTEwMi1l\nMTJhNzlkODE0YTYtNTQ4NDNhNjEiLCJjb3VudGVyIjo4OCwidWlkIjoiMTAxNDci\nLCJyc2FfcHNzX3NhbHRsZW4iOjMyfQQAMBK\/g3cCBQC\/hT0IAgYBZ8F8onUwNKEJ\nMQcCBQD\/AQABogMCAQGjBAICCAClBTEDAgEEpgUxAwIBA7+BSAUCAwEAAb+FPgMC\nAQAwCwYJKoZIhvcNAQELA4IBAQDViQXLqKk6hK+M8mURvkGvxsIUppka8PwF5PbM\nFtqdX+Yk\/EnepbAOnnxVn+wbyzjh4CAknM+nkdw70j5VvpRecqCvrRFCXrjrare9\nZDRpw8UqFjgTD9Sbns6ERqEcj9oNADzxS4SDmk2ezRtXlq5RwTPcJFsmnp394zm9\ngKmYhsi7pJkzlNx1aE3TSqmOl5Y65sE1m9JSmL37gTqyaXu5IWUmBRbi\/OzYwb+U\nJXJpLXWWUPzkt5cTobYlDQC17MXIcf5DJ3\/I73zG81ygO+JuiA5yQs+\/tfOq1xfa\nzj\/NtbkD3PADju1GrAUZxQS\/kPl8qgVrPqs6sddLtMeVuJTA\n-----END CERTIFICATE-----\n","-----BEGIN CERTIFICATE-----\nMIIEQDCCAyigAwIBAgIQIBgEJRUJVUHc90M1kMViTjANBgkqhkiG9w0BAQsFADBc\nMQswCQYDVQQGEwJDTjEPMA0GA1UECgwGSHVhd2VpMRMwEQYDVQQLDApIdWF3ZWkg\nQ0JHMScwJQYDVQQDDB5IdWF3ZWkgQ0JHIE1vYmlsZSBFcXVpcG1lbnQgQ0EwHhcN\nMTgwNDI1MDcwOTU1WhcNMjgwNDIyMDcwOTU1WjBvMQswCQYDVQQGEwJDTjEPMA0G\nA1UECgwGSHVhd2VpMRMwEQYDVQQLDApIdWF3ZWkgQ0JHMTowOAYDVQQDDDFIVUFX\nRUlfSFdMWUFfYjMxNjE0MDEtNjJmYS00ZDliLWExMDItZTEyYTc5ZDgxNGE2MIIB\nIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5um46VjstvFEnYvA6Pu\/\/qyk\nGn01FLwDWXBxp8tbCN78xtfAzOnHtX2u3ZtRO6X8sqkpvMkSZMnIcEoSEf0r4c28\nBSaCFFmfvZQxUxvwXMoxYOlUrqmnw8bc2pRlO9AKF6xqz5lGjNlOyYoYPCGi42vf\nAmTdp1MANO7MR2Gzfp0X\/ESAE+j0f4y5VUvzpLsg27g1Jdk8hG4+6jvw\/BjP4d\/u\ns+SxvAci2TajBzNvDiS5K3lwZLLvBQvWtWEijUfU2mClV8nm2d4jmg9IUkVwlVid\nKpNsg478wfqaUm41eediiJ\/JW4Qg\/Nh7oLb0bDBFbIfcs6Aa+nL2Pjx5Tkf9IwID\nAQABo4HqMIHnMB8GA1UdIwQYMBaAFDXT2UhPcFFNI7Ey1dXdJSHOBS7dMB0GA1Ud\nDgQWBBTnFv2xJTE+66X7o3MXaE3W+3Gz8TARBglghkgBhvhCAQEEBAMCBsAwCwYD\nVR0PBAQDAgTwMGYGA1UdHwRfMF0wW6BZoFeGVWh0dHA6Ly9jcGtpLWNhd2ViLmh1\nYXdlaS5jb20vY3BraS9zZXJ2bGV0L2NybEZpbGVEb3duLmNybD9jZXJ0eXBlPTQm\neWVhcj0vY3JsMjAxOC5jcmwwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMC\nMA0GCSqGSIb3DQEBCwUAA4IBAQBUTYlEYmVddqAqdsITDeyB119KF3p2qMt0f0vG\nD+CwC3\/Wwfs5EZ+3VVhLDzL4jrkvRDQcfC4HVTiAgsH7cnOM7fOtmexEXxZD\/kQk\n4p1fDQcA39p1lf\/mP0MHpeT9S1xzaYE+aEOgecVQjjdaP+EzXOoiAm\/97uKMwurV\nWkF8cmYQfYcyS3zlbb3rRvVxQz8KDRMdWOnD9s3YJ1pYe+AGpi1sCxYVVzJupWQs\nKXSKBS5u7lWA1WoiL4e5EKzaSZ\/xXcYOtnA6ANW8FlU+QaUaPiT+wY\/EYz42cSvG\ny8x3SYEaiRtZZqF\/ur9hl2xoZiTJDewyOLZn4tjpkot6AIyy\n-----END CERTIFICATE-----\n","-----BEGIN CERTIFICATE-----\nMIIE9jCCAt6gAwIBAgIIGLiVkB1V\/dowDQYJKoZIhvcNAQELBQAwUDELMAkGA1UE\nBhMCQ04xDzANBgNVBAoMBkh1YXdlaTETMBEGA1UECwwKSHVhd2VpIENCRzEbMBkG\nA1UEAwwSSHVhd2VpIENCRyBSb290IENBMB4XDTE3MDgyMTExMTE1NFoXDTM3MDgx\nNjExMTE1NFowXDELMAkGA1UEBhMCQ04xDzANBgNVBAoMBkh1YXdlaTETMBEGA1UE\nCwwKSHVhd2VpIENCRzEnMCUGA1UEAwweSHVhd2VpIENCRyBNb2JpbGUgRXF1aXBt\nZW50IENBMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzFwCSSlfQ\/sM\nyGs534kxNYPWFWSlNsduoSXHHDYmDqHoRON7dw256Ly4vQfz+YLcTqGh8Zkaqh+9\nlOb5Qj2N0dxrPqyxa8kMNdqtWyMRQC2JGrd1+stOVOTJ1zjsxABpL+9BOjO43Q4J\nsZH9xLK\/Y7ObSCZPd+fKGLzw2SxjC031n40w0M2tAyKMqnPoxhWT7xJbZO1vXX1r\niBFVCbGYHviA0nJm7YIyepxvfvzELdp9c+IMNYSzvHQrpHMkHJxobiDnw289rZLK\n5RYuWxhzWaD5tafWeAgH8wqr7a8Z75f+4ZESkYWvQu\/glyDAAUPn+\/pQX2S3OSp2\nj9UZtNQHTQIDAQABo4HHMIHEMB8GA1UdIwQYMBaAFKrE03lH6G4ja+\/wqWwicz16\nGWmhMB0GA1UdDgQWBBQ109lIT3BRTSOxMtXV3SUhzgUu3TAPBgNVHRMBAf8EBTAD\nAQH\/MA4GA1UdDwEB\/wQEAwIBBjBhBgNVHR8EWjBYMFagVKBShlBodHRwOi8vY3Br\naS1jYXdlYi5odWF3ZWkuY29tL2Nwa2kvc2VydmxldC9jcmxGaWxlRG93bi5jcmw\/\nY2VydHlwZT0xJi9yb290Y3JsLmNybDANBgkqhkiG9w0BAQsFAAOCAgEAW\/ZYMPfM\nsxWoPUaG2rOk4FmdL8Jz2cxWKOIUvmG6qQ\/4ITWthYJOS3SjTbDyhwQM6tPBCl67\nHlMhqgfstUTqU1byT7QneBmG4XndfyjlTs3yC3TRkfr4ySV21mddTvNMU2BCJtJQ\nTqISeLvjxLKwxX\/syBRB5S2MdWQLPLaU2jvCWGM\/qHoI3u5FVoCmtrgx\/tncK1g\/\nJ\/8PRD4fYt4S2VpQqIzvqvoZSEdQuuP5FETTEo9Glc7UyDh4heqZovwDdla54E4i\nAtq09w4yYhqz1w3eis3csZFoUUKm9sLCXxDS9WFBYNtOnckmyu9uoJ8z2Sx2E\/2c\nEF8DcbM9LB19BpR4PEEV6tXTNOD6doHJ9igF22UvHrWgiLHWcfTl7LLhfVxZuugE\n9GfJSKEID8WaKYxbR\/FiwJfLXC4\/mTtGevmV\/NVKrMZ8t4WjXJCbSNQzvS4rZZ4W\n43yyXzlMJDDaQCujKNt5BcgyLKeT5QjY7I8fy33ODIZF8muYnpwE9iBYOy7BRyvV\nucN2p9uYJlfIvrHy4KZ2ik0jjcljlMqjDvmulnjPB+2OukKwoL2Hg+zKBVkfnIMF\nWpddI3wLQMJYfb7AnWyd1Dp\/LvMJass3bLFV0dSmFe9NMB\/\/EcyVeqKLFA3SRNqa\n0uVSOEYODEFGUT6oeTs6DvM+96q7tKi\/Jt8=\n-----END CERTIFICATE-----\n","-----BEGIN CERTIFICATE-----\nMIIFZDCCA0ygAwIBAgIIYsLLTehAXpYwDQYJKoZIhvcNAQELBQAwUDELMAkGA1UE\nBhMCQ04xDzANBgNVBAoMBkh1YXdlaTETMBEGA1UECwwKSHVhd2VpIENCRzEbMBkG\nA1UEAwwSSHVhd2VpIENCRyBSb290IENBMB4XDTE3MDgyMTEwNTYyN1oXDTQyMDgx\nNTEwNTYyN1owUDELMAkGA1UEBhMCQ04xDzANBgNVBAoMBkh1YXdlaTETMBEGA1UE\nCwwKSHVhd2VpIENCRzEbMBkGA1UEAwwSSHVhd2VpIENCRyBSb290IENBMIICIjAN\nBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA1OyKm3Ig\/6eibB7Uz2o93UqGk2M7\n84WdfF8mvffvu218d61G5M3Px54E3kefUTk5Ky1ywHvw7Rp9KDuYv7ktaHkk+yr5\n9Ihseu3a7iM\/C6SnMSGt+LfB\/Bcob9Abw95EigXQ4yQddX9hbNrin3AwZw8wMjEI\nSYYDo5GuYDL0NbAiYg2Y5GpfYIqRzoi6GqDz+evLrsl20kJeCEPgJZN4Jg00Iq9k\n++EKOZ5Jc\/Zx22ZUgKpdwKABkvzshEgG6WWUPB+gosOiLv++inu\/9blDpEzQZhjZ\n9WVHpURHDK1YlCvubVAMhDpnbqNHZ0AxlPletdoyugrH\/OLKl5inhMXNj3Re7Hl8\nWsBWLUKp6sXFf0dvSFzqnr2jkhicS+K2IYZnjghC9cOBRO8fnkonh0EBt0evjUIK\nr5ClbCKioBX8JU+d4ldtWOpp2FlxeFTLreDJ5ZBU4\/\/bQpTwYMt7gwMK+MO5Wtok\nUx3UF98Z6GdUgbl6nBjBe82c7oIQXhHGHPnURQO7DDPgyVnNOnTPIkmiHJh\/e3vk\nVhiZNHFCCLTip6GoJVrLxwb9i4q+d0thw4doxVJ5NB9OfDMV64\/ybJgpf7m3Ld2y\nE0gsf1prrRlDFDXjlYyqqpf1l9Y0u3ctXo7UpXMgbyDEpUQhq3a7txZQO\/17luTD\noA6Tz1ADavvBwHkCAwEAAaNCMEAwDgYDVR0PAQH\/BAQDAgEGMA8GA1UdEwEB\/wQF\nMAMBAf8wHQYDVR0OBBYEFKrE03lH6G4ja+\/wqWwicz16GWmhMA0GCSqGSIb3DQEB\nCwUAA4ICAQC1d3TMB+VHZdGrWJbfaBShFNiCTN\/MceSHOpzBn6JumQP4N7mxCOwd\nRSsGKQxV2NPH7LTXWNhUvUw5Sek96FWx\/+Oa7jsj3WNAVtmS3zKpCQ5iGb08WIRO\ncFnx3oUQ5rcO8r\/lUk7Q2cN0E+rF4xsdQrH9k2cd3kAXZXBjfxfKPJTdPy1XnZR\/\nh8H5EwEK5DWjSzK1wKd3G\/Fxdm3E23pcr4FZgdYdOlFSiqW2TJ3Qe6lF4GOKOOyd\nWHkpu54ieTsqoYcuMKnKMjT2SLNNgv9Gu5ipaG8Olz6g9C7Htp943lmK\/1Vtnhgg\npL3rDTsFX\/+ehk7OtxuNzRMD9lXUtEfok7f8XB0dcL4ZjnEhDmp5QZqC1kMubHQt\nQnTauEiv0YkSGOwJAUZpK1PIff5GgxXYfaHfBC6Op4q02ppl5Q3URl7XIjYLjvs9\nt4S9xPe8tb6416V2fe1dZ62vOXMMKHkZjVihh+IceYpJYHuyfKoYJyahLOQXZykG\nK5iPAEEtq3HPfMVF43RKHOwfhrAH5KwelUA\/0EkcR4Gzth1MKEqojdnYNemkkSy7\naNPPT4LEm5R7sV6vG1CjwbgvQrWCgc4nMb8ngdfnVF7Ydqjqi9SAqUzIk4+Uf0ZY\n+6RY5IcHdCaiPaWIE1xURQ8B0DRUURsQwXdjZhgLN\/DKJpCl5aCCxg==\n-----END CERTIFICATE-----\n"]}

上传AuthKey

正如ASK一样，关于AuthKey的介绍也在前面的章节。有所不同的是，因为隐私原因，应用方应当自己检查AuthKey的合法性。当从客户端获取密钥JSON结构体之后，你应当用之前存储的该设备对应的ASK公钥检查该JSON结构体是否合法（公钥验签）。我们并不关心你是用的是哪一种语言来做这件事情，但是如论怎么做，验签行为都应当等同于下面这条OpenSSL语句：

openssl dgst -sha256 -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:20  -verify pubkey.pem -signature sign.bin authkey_json.txt

这里，pubkey.pem 是之前存储的对应设备以及uid的ASK公钥，sign.bin是所上传的签名经过Base64解码之后的二进制数据，authkey_json 是所上传的公钥结构体。

简单解释下上面的OpenSSL命令：

• 算法是RSA2048withSha256
• PaddingMode是PSS
• Saltlength是20

在python中有各种各样的第三方库可以实现同样表现的库（如：PyCrypto。对于Java而言，如果你使用的是JDK8，那么可以很容易实现同样表现；如果不是，也有著名的BouncyCastle可以实现。

我们很快会给出更多语言对应的验签语句。同时，我们也欢迎你通过Pull Request提供更多示例。

和ASK的情况一样，我们在客户端使用名为IWrapUploadKeyNet的网络封装结构体来封装易错逻辑。

典型的上传AuthKey请求的结构体如下图：

{"pub_key":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5p+nrphn+xDjobEoXpJe\nnlfM+aKRcGU6VV3huBLT7CoudKfLAeOahUXvFQBSOR6K+WTvljSVGy9fsyKiCfTE\n2/jbgVwMLuSXfhCiGPJYbCLUNIo5f1qQVJhtx0TqBs6+uvrrZYrqTKU4kSIzYe3v\nYqZFL/TFG63kYhDGj0rhmj6gwgr/UDaasghWirGFHQBAWbLBsi0EZXrmHpVAFOnY\naQ/uNOq47KjcXQh3JYXDk8xwx/ElfCWX7HfwKjVRk2NpCXAegAE4wBTXafMHroRO\n8FWuC+rEU0hN813mvb9RmV0mSDstEeuk6gCiEi8tXFNa6YT7ZNcVY0QspwBW3Gwp\n9QIDAQAB\n-----END PUBLIC KEY-----\n", "cpu_id":"0f000000262300000b5f094d1cf4c411", "counter":183, "uid":"10206"}

由于结构和ASK是一致的，因此不再赘述一一分析。

同时，我们需要提醒的是，我们依然强烈建议先判断结构体中counter字段（见上传ASK中的说明）。

获取挑战因子

挑战因子是签名过程中你需要真正进行签名的数据里你可以控制的那部分。大部分情况下，这是一个后台指定的随机串。应用后台应当有生成挑战因子的逻辑。我们在客户端提供了一个叫IWrapUploadKeyNet的网络封装结构体来做这件事。注意由于某些机型有限制，挑战因子最好不要超过64字节。

验证最终签名

这是所有后台接口中最重要的一个。该接口会检查客户端所生成签名——该签名只有用户使用了系统中录入的指纹才能生成——是否合法。在大部分的情况下，这个接口并不是独立的。客户端接口生成的JSON结构体以及对应的签名应当只是授权接口的两个参数（比如支付时认证接口）。你应当在客户端让认证网络结构体实现（implements）IWrapUploadSignature接口，之后TENCENT SOTER会帮你封装所有的其他逻辑。

验证最终签名对应的OpenSSL语句如下：

openssl dgst -sha256 -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:20  -verify pubkey.pem -signature sign.bin final_json.txt

这里，pubkey.pem 是之前存储的对应设备、uid以及业务的AuthKey公钥，sign.bin是所上传的签名经过Base64解码之后的二进制数据，final_json 是所上传的结果结构体。

• 算法是RSA2048withSha256
• PaddingMode是PSS
• Saltlength是客户端所上传的saltlength

典型的最终结果结构体JSON如下：

{ "raw":"I'm a demo challenge string" , "fid":"3" , "counter":246 , "tee_n":"QSEE" , "tee_v":"4.0" , "fp_n":"ET" , "fp_v":"320" , "cpu_id":"0f000000262300000b5f094d1cf4c411" , "uid":"10206" }

其中，raw即为你所传入的challenge字段，你可以检查其是否合法。fid即用户本次授权使用的指纹编号，注意，每一部设备上虽然不同的指纹编号不会重复（比如删掉指纹之后重新录入，指纹编号一定不同），但是仅仅限于本机，换一台机器可能会出现同一个指纹编号的情况，因此检查指纹编号之前请先限定是在该cpu_id范围内。tee_n tee_v fp_n fp_v 分别为TEE的名称和版本号、指纹传感器的名称和版本号，这些信息是为了确保如果某天某个TEE或者指纹传感器出现了无法修复（或者暂时未修复）的漏洞，可以及时封堵住这些请求。最后，cpu_id和uid 的作用和之前相同，用于识别设备和应用。