签名算法 - 抖音

遇到任何签名问题强烈建议请先通读本文，从历史经验看，平台当前遇到的 oncall 问题都可以从本文中找到答案，提 oncall 问题并得到解答的时间往往比通读本文自行解决要慢，因此强烈建议遇到签名问题时先从本文中寻找答案。

签名算法

鉴权认证机制采用 SHA256-RSA2048 实现，字符编码采用 UTF-8 编码集。

本签名规范中，加签和验签的原文组装方式略有不同，请严格按照规范要求进行组装。

使用说明

在鉴权认证机制中，需要 4 个密钥，分别为

平台公钥：

每个「小程序」对应的平台公钥是不一样的，平台公钥由「开放平台」负责生成，并告知「小程序」开发者。

平台私钥：

每个「小程序」对应的平台私钥是不一样的，平台私钥由「开放平台」负责生成和保存。

应用公钥：

「小程序」的应用公钥由开发者生成并上传到「开放平台」，可支持更换。

应用私钥：

「小程序」的应用私钥由开发者生成并保存，不能对外提供，可支持更换。

交互方式如下图所示

应用密钥

应用公钥和私钥由开发者生成并保存，同时应用公钥需要在「抖音开放平台」的小程序管理后台上传。

生成方式

应用公钥和私钥的生成方式可参考：

o p e n ss lOp e n SS L > g e n rs a - o u tp r i v a t e_{k} ey . p e m 2048 G e n er a t in g RS A p r i v a t e k ey, 2048 bi tl o n g m o d u l u s .................... + + + ........................................................................... + + + e i s 65537 (0 x 10001) Op e n SS L > rs a - in p r i v a t e_{k} ey . p e m - p u b o u t - o u tp u b l i c_{k} ey . p e m w r i t in g RS A k ey Op e n SS L > e x i t

lsprivate_key.pem public_key.pem

上传方式

平台公钥

平台公钥和私钥由「开放平台」负责生成和保存，不同「小程序」的平台公钥和私钥是不同的。

获取方式

开发指南

生成签名

「小程序」应按照下述步骤生成请求的签名信息。

第一步：构造待签名串

待签名串一共有五行，每一行必须以 \n（换行符，ASCII 编码值为 0x0A）结束。

HTTP请求方法\nURL\n请求时间戳\n请求随机串\n请求报文主体\n

其中：

HTTP 请求方法

如：POST，GET，PUT 等。注意请使用大写。

URI

获取请求的绝对 URL，并去除域名部分得到参与签名的 URI。 URI必须以斜杠字符“/”开头。如

PATH=https://open.douyin.com/api/trade/v2/query URI 则为 /api/trade/v2/queryPATH=https://open.douyin.com/api/trade/v2/query?a=x URI 则为 /api/trade/v2/query?a=x

请求时间戳

发起请求时系统的当前时间戳，即格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒(北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒)起至现在的总秒数，作为请求时间戳。「开放平台」会拒绝处理一个小时之前发起的请求。

请求随机串

任意生成一个随机字符串（长度不限制），以保证相同时间相同参数发起的请求签名值不一样。

请求报文主体

获取请求中的请求报文主体（request body）。

请求方法为GET时，报文主体为空。

当请求方法为POST或PUT时，请使用报文内容。

第二步：计算签名值

「小程序」成功构造待签名串后，「小程序」使用应用私钥对待签名串进行SHA256-RSA2048签名，并对签名结果进行Base64编码得到签名值。

第三步：设置 Header

签名信息通过 HTTP 头Byte-Authorization传递，Byte-Authorization由认证类型和签名信息两部分组成。

Byte-Authorization: 认证类型签名信息

认证类型：

目前为 SHA256-RSA2048

签名信息：

应用 appid

请求随机串 nonce_str

请求时间戳 timestamp

公钥版本 key_version

签名值 signature

注意：

以上五项签名信息，无顺序要求。按照以下示例格式，key="value"，签名信息之间用英文逗号,隔开。

请求随机串和请求时间戳必须和计算签名值时使用的请求随机串和请求时间戳保持一致。

公钥版本必须填写计算签名值时采用的应用私钥对应的应用公钥版本，应用公钥版本可通过「开发管理-开发设置-密钥设置」处获取。

示例如下：

curl -v -d '{"appid":"ttxxx","order_id":"xxx"}' -H 'Byte-Authorization: SHA256-RSA2048 appid="ttxxx",nonce_str="DC10180A100073E70A48F195DA2AF2E6",timestamp="1623934869",key_version="1",signature="nwd1L3wCX+01/TVTkILeovF1DtYeghC1VHjrcjTHVkh7+gRaONEQkC2Y72Mw8JdSnIyeAtyp/pDHzyKGywjVqv5+JOBEhQG1/pvwNHN49wD26qg3AJL4hXw0fMJSRiTQEV1MszwDLuaabvo/qM9OXL9KyYiEPwVJqYtzmho4cHXT6mYgzNOW1xt5d7RDf4QO74JI3i4dtk9Uj8svJTrrBabML6AUcqcx2OP/7xukdaUgPdPf+IqmMG6GC4n52LUDogcL5n/osLdfHg9l6kW5gDcDjBfNDaggz07QMPHGdVao7pnQ2ub7VqcFIuY6Q3cBL7ndQdDGKrv+WBy5Q90QjQ=="' -H 'Content-Type: application/json' -H 'Accept: application/json' -X POST https://webcast.bytedance.com/api/business/diamond/query

签名验证

「小程序」应按照下述步骤验证成功应答（HTTP 状态码为 2xx）的签名信息。

第一步：构造待签名串

应答验签名串一共有三行，每行必须以\n （ASCII 编码值为 0x0A）结束。

应答时间戳\n应答随机串\n应答报文主体\n

应答时间戳

从应答 HTTP 头Byte-Timestamp中获取应答时间戳。

应答随机串

从应答 HTTP 头Byte-Nonce-Str中获取应答随机串。

应答报文主体

应答中的报文主体（response body）。

第二步：获取应答签名

应答签名值通过 HTTP 头Byte-Signature传递。如：

Byte-Signature: hWsiaADxS4OKLW/0JpDXiiji+GNRIsnnXsux3nVdyk7X6dqoyyJVYloQR9h/C1DIhGeBKe0i1iciyp6uq4LIkScyQKLhwEaXnWpcYat3+SAgS3ZYcGFY/op/MTO1bf172wbQBamC6gwydOWF0tWlMQb33ZYhztEDnD8iw/JkogOGHjO5uo869xWbgcq0OrkRN4zPGpOc/eiOR/B7fzxbasdMZtENOQMpgPP0z3k/cgeG/DSOwtwfA0eYnpYC8YqvKZ52HI5aCPkexmkfzUqNl1tbVylbMKDQDQoipQSxQPK2fxOFHj+jYu1TQ+nQFeu6amU/1rsMbT8JWa94bwwgkg==

对 Byte-Signature 的签名值使用Base64解码，得到应答签名。

第三步：验证签名

使用平台公钥对验签名串和应答签名进行SHA256-RSA2048签名验证。

示例代码

签名示例代码

JAVAGOPHP public static String getSignature(String privateKeyStr, String method, String uri, long timestamp, String nonce, String body) throws Exception { //method内容必须大写，如GET、POST，uri不包含域名，必须以'/'开头 String rawStr = method + "\n" + uri + "\n" + timestamp + "\n" + nonce + "\n" + body + "\n"; Signature sign = Signature.getInstance("SHA256withRSA"); sign.initSign(string2PrivateKey(privateKeyStr)); sign.update(rawStr.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(sign.sign());} public static PrivateKey string2PrivateKey(String privateKeyStr) { PrivateKey prvKey = null; try { byte[] privateBytes = Base64.getDecoder().decode(privateKeyStr); PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(privateBytes); KeyFactory keyFactory = KeyFactory.getInstance("RSA"); prvKey = keyFactory.generatePrivate(keySpec); } catch (Exception ex) { ex.printStackTrace(); } return prvKey;}

验签示例代码

JAVAGOPHPpublic static boolean verify(String httpBody, String publicKey, String signStr, Long timestamp, String nonce) throws Exception { StringBuffer buffer = new StringBuffer(); buffer.append(timestamp).append("\n"); buffer.append(nonce).append("\n"); buffer.append(httpBody).append("\n"); String message = buffer.toString(); Signature sign = Signature.getInstance("SHA256withRSA"); sign.initVerify(string2PublicKey(publicKey)); sign.update(message.getBytes(StandardCharsets.UTF_8)); return sign.verify(Base64.getDecoder().decode(signStr.getBytes(StandardCharsets.UTF_8)));}public static PublicKey string2PublicKey(String publicKey) throws Exception{ byte[] decoded = Base64.getDecoder().decode(publicKey); return KeyFactory.getInstance("RSA").generatePublic(new X509EncodedKeySpec(decoded));}

自查数据

以下提供了一套标准 PKCS8 格式的 2048 位密钥和待签名串和签名串，开发者可以自行验证签名验签代码是否正确。

注意事项

1.密钥长度必须为2048位

2.不同的签名验签代码，对密钥格式有不同的要求，比如JAVA一般使用PKCS8格式的密钥，其他语言一般使用PKCS1格式的密钥（区分小技巧：开头为"-----BEGIN PRIVATE KEY-----"的密钥格式为PKCS8，开头为"-----BEGIN RSA PRIVATE KEY-----"的密钥格式为PKCS1）

3.每次提交新的应用公钥，公钥版本会发生变化

4.请注意使用原生的request body中的内容进行验签，避免因框架解析导致字段顺序变化。

5.如果使用的低版本的JDK（JDK7及以下），请不要使用sun.misc.BASE64包进行base64编解码，请使用org.apache.commons.codec.binary.Base64包或者javax.xml.bind.DatatypeConverter包

6.java中使用gjson做序列化的时候可能出现long类型参数被实际序列化成了string类型，而请求发送给平台的时候对应参数仍然是long类型从而导致平台验证签名无法通过，这种情况下请使用(new GsonBuilder()).setLongSerializationPolicy(LongSerializationPolicy.DEFAULT).create()创建gjson对象，同时通过调整LongSerializationPolicy的值来根据实际需求情况来对long类型的值进行序列化

FAQ

签名生成的使用场景

签名生成是指开发者在请求开放平台交易系统的 open api 时，需要携带签名等信息，开发者使用自己生成的应用私钥给签名串生成签名，携带在 header 中。交易系统服务会使用开发者上传的应用公钥进行签名验证，验证通过后放行请求。

签名验证的使用场景

签名验证是开放平台交易系统使用平台私钥对签名串生成签名，开发者使用平台公钥进行签名验证。签名验证有两个场景

a.开发者请求开放平台交易系统open api时，开放平台会放http resp的header中返回签名信息

b.开放平台交易系统服务请求开发者的api时（回调场景、状态通知等），交易系统服务会在http request的header中携带签名信息

设置应用公钥时出错

如果报 Request params error 注意应用公钥应该是这样的格式，包含----BEGIN 一直到 END PUBLIC KEY----

验签不通过

如果签名验证不通过，请开发者先使用自己生成的公私钥测试加解密的过程，如果可以用私钥加密的数据，可以用公钥完成解密，再考虑以下几个因素

1.确认当前参与签名的小程序已经在平台设置了公钥，设置方法参考上面的密钥设置环节

2.确认上传的公钥与自己使用的公钥相同，以及和加签使用的私钥是匹配的

3.检查小程序平台上是否更新了公钥。如果更新了公钥，确认签名使用的公私钥与版本key_version一致。key_version在公私钥设置页面可以看到。

4.给body加解密的过程中，确保body数据严格一致，不能增加空格空行等。服务端以收到的http request body数据为准，开发者验证过程中也需要保证body和服务端收到的一致。

5.拼接 "\n"的时候使用双引号不要用单引号。

6.确认生成签名的加签串和请求request中的数据一致。详细规则请看上面的加签环节。

7.java语言中有些框架会对原始包body进行解析并重新拼接再返回给最上层的业务使用，这个过程中可能对原始请求包的字段顺序进行了变更，建议在接收到请求的原始包处将原始包日志打印出来，并在验签处也将body打印出来进行对比。

8.java语言在读取网络包的时候如果使用了readLine函数则可能导致验签通不过，因为readLine默认会在每次读取的时候在行位append '\n'字符。

为什么有的接口验签可以通过，有的接口不能通过

开平的签名算法针对所有接口都是相同的逻辑，如果遇到这样的情况，有可能是中文字符串遇到转义问题。

验签时需要接收原始的 http request body 数据，并不要进行任何处理。保证原始的 body 数据，作为字符串参与验签。如果是 JAVA 语言，回调接口需要用字符串接收，不要用 Bean 接收，Bean 接收参数会乱序导致验签不过。

oncall 指引

为减少 oncall 沟通过程提高问题解决效率，请提 oncall 的时候务必提供以下内容：

签名问题：请提供参与签名的全部参数，提供签名计算代码。

验签问题：请提供接收到的平台请求包原始内容，提供验签代码。