本指南介绍了如何生成令牌,以及令牌的必填字段和可选字段。
如需创建令牌,您需要编写一个要签名的字符串,在本指南中,我们将其称为“签名值”。签名值包含描述您要保护的内容的参数、签名值的到期时间等。
您可以在创建令牌字符串时使用签名值。您可以通过组合令牌的参数(例如已签名值的对称密钥基于哈希的消息认证码 [HMAC])来创建令牌字符串。
媒体 CDN 使用最终组合的令牌来帮助保护您的内容。
创建令牌
使用 Ed25519 签名或对称密钥 HMAC 对签名值进行签名。
通过串联包含必填令牌字段和可选令牌字段的字符串来编写令牌。使用波浪号
~字符分隔每个字段和所有参数。在组合令牌时,每个参数的值在签名值和令牌字符串之间是相同的,但以下情况除外:
FullPathHeaders
以下代码示例展示了如何以编程方式创建令牌:
Python
如需向 Media CDN 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Media CDN 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
以下部分介绍了令牌使用的字段。
必填令牌字段
每个令牌都必须包含以下字段:
Expires- 以下任一:
PathGlobsURLPrefixFullPath
- 以下任一项:
Signaturehmac
除非另有说明,否则参数名称及其值区分大小写。
下表介绍了各个参数:
| 字段名称/别名 | 令牌参数 | 有符号值 |
|---|---|---|
|
自 Unix 纪元 (1970-01-01T00:00:00Z) 以来经过的整数秒数 | Expires=EXPIRATION_TIME,之后令牌将失效。 |
|
最多包含 5 个路径段的列表,用于授予访问权限。这些片段可以用英文逗号 (
不允许使用路径参数(用分号 [ 因此,请确保您的网址不包含以下特殊字符: |
PathGlobs=PATHS |
URLPrefix |
可在 web 环境中安全使用的 base64 编码网址,包括协议 例如,对于 `https://example.com/foo/bar.ts`,一些有效的 URLPrefix 值为 `https://example.com`、`https://example.com/foo` 和 `https://example.com/foo/bar`。 |
URLPrefix=BASE_64_URL_PREFIX |
FullPath |
无。在令牌中指定 FullPath 时,请勿重复您在签名值中指定的路径。在令牌中,添加不带 = 的字段名称。 |
FullPath=FULL_PATH_TO_OBJECT |
Signature |
可在 web 环境中安全使用的 base64 编码签名。 | 不适用 |
hmac |
HMAC 值的可在 web 环境中安全使用的 base64 编码版本。 | 不适用 |
PathGlobs 通配符语法
下表介绍了 PathGlobs 通配符语法。
| 运算符 | Matches | 示例 |
|---|---|---|
*(星号) |
匹配网址路径中的零个或零个以上字符,包括正斜杠 (/) 字符。
|
|
?(问号) |
匹配网址路径中的单个字符,不包括正斜杠 (/) 字符。
|
/videos/s?main.m3u8与/videos/s1main.m3u8匹配。它与 /videos/s01main.m3u8 或 /videos/s/main.m3u8 都不匹配。
|
对于网址路径,glob 必须以星号 (*) 或正斜杠 (/) 开头。
由于 * 和 /* 与所有网址路径匹配,因此我们不建议在已签名令牌中使用这两者。为实现最大程度的保护,请确保您的 glob 与您要授予访问权限的内容相匹配。
可选令牌字段
除非另有说明,否则参数名称及其值区分大小写。
下表介绍了可选参数的参数名称、别名和详细信息:
| 字段名称/别名 | 参数 | 有符号值 |
|---|---|---|
|
自 Unix 纪元 (1970-01-01T00:00:00Z) 以来经过的秒数(整数) | Starts=START_TIME |
IPRanges |
采用 CIDR 格式的 IPv4 和 IPv6 地址列表(最多 5 个),此网址在这些地址中有效,采用网址安全 base64 格式。例如,如需指定 IP 范围“192.6.13.13/32,193.5.64.135/32”,请指定 如果客户端面临广域网迁移风险,或者通往应用前端的网络路径与传送路径不同,那么在令牌中包含 IPRanges 可能没有帮助。
当客户端使用不属于签名请求的 IP 地址进行连接时,Media CDN 会拒绝这些客户端并返回 以下情况可能会导致 Media CDN 拒绝客户端并返回
所有这些因素都可能导致给定客户端在视频播放会话期间具有不确定的 IP 地址。如果客户端 IP 地址在您授予访问权限后发生更改,并且客户端随后尝试将视频片段下载到其播放缓冲区,则会收到来自 Media CDN 的 |
IPRanges=BASE_64_IP_RANGES |
|
任意字符串,可用于日志分析或播放跟踪。 为避免创建无效令牌,请使用经过 % 编码或网络安全的 base64 编码字符串。不得在 |
SessionID=SESSION_ID_VALUE |
|
任意字符串,对日志分析很有用。 为避免创建无效令牌,请使用经过 % 编码或网络安全的 base64 编码字符串。不得在 |
data=DATA_VALUE |
Headers |
一个以英文逗号分隔的列表,最多包含 10 个标头字段名称。在请求中查找时,标头名称不区分大小写。签名值中的标头名称区分大小写。如果缺少标头,则值为空字符串。
因此,我们建议您使用不透明的值(例如会话或设备标识符)对自定义标头进行签名。避免对值通常包含英文逗号的标头(例如 |
Headers=HEADER_1_NAME=HEADER_1_EXPECTED_VALUE,
HEADER_2_NAME=HEADER_2_EXPECTED_VALUE |
示例
以下部分展示了生成令牌的示例。
使用 FullPath 的示例
请参考以下使用 FullPath 字段的示例:
- 请求的商品:
http://example.com/tv/my-show/s01/e01/playlist.m3u8 - 到期时间:160000000
签名值为:
Expires=160000000~FullPath=/tv/my-show/s01/e01/playlist.m3u8
如需创建令牌,请使用 Ed25519 签名或对称密钥 HMAC 对签名值进行签名。
以下是根据签名值创建的令牌示例:
Ed25519 签名
Expires=160000000~FullPath~Signature=SIGNATURE_OF_SIGNED_VALUE
其中,SIGNATURE_OF_SIGNED_VALUE 是之前创建的签名值的 ED25519 签名。
对称密钥 HMAC
Expires=160000000~FullPath~hmac=HMAC_OF_SIGNED_VALUE
其中,HMAC_OF_SIGNED_VALUE 是之前创建的签名值的对称密钥 HMAC。
在前面的示例中,令牌中提供了 FullPath,但该值不会从签名值中指定的路径重复。这样,您就可以对请求的完整路径进行签名,而无需在令牌中复制请求。
使用 URLPrefix 的示例
请参考以下使用 URLPrefix 字段的示例:
- 请求的商品:
http://example.com/tv/my-show/s01/e01/playlist.m3u8 - 到期时间:160000000
签名值为:
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4
在前面的示例中,我们将所请求项的路径 http://example.com/tv/my-show/s01/e01/playlist.m3u8 替换为采用网址安全 Base64 格式的项路径 aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4。
如需创建令牌,请使用 Ed25519 签名或对称密钥 HMAC 对签名值进行签名。
以下是根据签名值创建的令牌示例:
Ed25519 签名
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4~Signature=SIGNATURE_OF_SIGNED_VALUE
其中,SIGNATURE_OF_SIGNED_VALUE 是之前创建的签名值的 ED25519 签名。
对称密钥 HMAC
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4~hmac=HMAC_OF_SIGNED_VALUE
其中,HMAC_OF_SIGNED_VALUE 是之前创建的签名值的对称密钥 HMAC。
使用 Headers 的示例
请参考以下使用 Headers 字段的示例:
- 请求的商品:
http://example.com/tv/my-show/s01/e01/playlist.m3u8 - 到期时间:160000000
- PathGlobs 值:
* - 预期请求标头:
x-session-id: abcd1234x-client-version: 5.2.0
签名值为:
Expires=160000000~PathGlobs=*~Headers=x-session-id=abcd1234,x-client-version=5.2.0
如需创建令牌,请使用 Ed25519 签名或对称密钥 HMAC 对签名值进行签名。
以下是根据签名值创建的令牌示例:
Ed25519 签名
Expires=160000000~PathGlobs=*~Headers=x-session-id,x-client-version~Signature=SIGNATURE_OF_SIGNED_VALUE
其中,SIGNATURE_OF_SIGNED_VALUE 是之前创建的签名值的 ED25519 签名。
对称密钥 HMAC
Expires=160000000~PathGlobs=*~Headers=x-session-id,x-client-version~hmac=HMAC_OF_SIGNED_VALUE
其中,HMAC_OF_SIGNED_VALUE 是之前创建的签名值的对称密钥 HMAC。
在前面的示例中,令牌中提供了 Headers=x-session-id,x-client-version,但预期的标头值不会从签名值中重复。这样,您就可以对特定请求标头键值对进行签名,而无需在令牌中复制这些值。