本指南介绍了如何生成令牌,以及令牌的必需字段和可选字段。
如需创建令牌,您需要构建要签名的字符串,我们在本指南中将其称为已签名值。已签名值包含用于描述您要保护的内容、已签名值的到期时间等的参数。
您在创建令牌字符串时使用已签名值。您可以通过组合令牌的参数(例如已签名值的对称密钥基于哈希的消息身份验证代码 [HMAC])来创建令牌字符串。
媒体 CDN 会使用最终的组合令牌来帮助保护您的内容。
创建令牌
使用 Ed25519 签名或对称密钥 HMAC 对已签名值进行签名。
通过串联包含必需令牌字段和可选令牌字段的字符串来构成令牌。请使用波浪符号
~
字符分隔各个字段和任何参数。在组合令牌时,每个参数的值在已签名值和令牌字符串之间相同,但以下情况除外:
FullPath
Headers
以下代码示例展示了如何以编程方式创建令牌:
Python
如需向 Media CDN 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Media CDN 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
以下部分介绍了令牌使用的字段。
必填令牌字段
每个令牌都必须包含以下字段:
Expires
- 以下任一项:
PathGlobs
URLPrefix
FullPath
- 以下任一项:
Signature
hmac
除非另有说明,否则参数名称及其值区分大小写。
下表介绍了每个参数:
字段名称 / 别名 | 令牌参数 | 有符号值 |
---|---|---|
|
自 Unix 纪元 (1970-01-01T00:00:00Z) 起经过的整秒数 | Expires=EXPIRATION_TIME ,令牌将在此时间之后过期。 |
|
要授予访问权限的路径片段(最多 5 个)的列表。这些片段可以用英文逗号 (
不允许使用英文分号 ( 因此,请确保您的网址不包含以下特殊字符: |
PathGlobs=PATHS |
URLPrefix |
可在网址中安全使用的 base64 编码网址,包括协议 例如,`https://example.com/foo/bar.ts` 的一些有效网址前缀值是 `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 |
签名的网络安全 base64 编码版本。 | 不适用 |
hmac |
HMAC 值的可在 web 环境中安全使用的 base64 编码版本。 | 不适用 |
PathGlobs
通配符语法
下表介绍了 PathGlobs
通配符语法。
运算符 | Matches | 示例 |
---|---|---|
* (星号) |
匹配网址路径中的零个或零个以上的字符,包括正斜线 (/ ) 字符。
|
|
? (问号) |
匹配网址路径中的单个字符,不包括正斜杠 (/ ) 字符。
|
/videos/s?main.m3u8 与 /videos/s1main.m3u8 匹配。它与 /videos/s01main.m3u8 或 /videos/s/main.m3u8 都不匹配。
|
对于网址路径,正则表达式必须以星号 (*
) 或正斜杠 (/
) 开头。
由于 *
和 /*
与所有网址路径匹配,因此我们不建议在已签名令牌中使用这两者。为实现最大程度的保护,请确保您的正则表达式与您打算授予访问权限的内容相符。
可选令牌字段
除非另有说明,否则参数名称及其值区分大小写。
下表介绍了可选参数的参数名称、所有别名和详细信息:
字段名称 / 别名 | 参数 | 有符号值 |
---|---|---|
|
自 Unix 纪元 (1970-01-01T00:00:00Z) 起算的整秒数 | Starts=START_TIME |
IPRanges |
最多五个 IPv4 和 IPv6 地址的 CIDR 格式列表,此网址以网络安全的 base64 格式有效。例如,如需指定 IP 地址范围“192.6.13.13/32,193.5.64.135/32”,您可以指定 如果客户端有 WAN 迁移风险,或者应用前端的网络路径与传送路径不同,则在令牌中添加 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 |
以英文逗号分隔的标头字段名称列表。在请求中进行查找时,标头名称不区分大小写。已签名值中的标头名称区分大小写。如果缺少标头,则值为空字符串。如果某个标头有多个副本,则会以英文逗号串联。 | 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 值:
*
- 预期请求标头:
user-agent: browser
accept: text/html
带符号值为:
Expires=160000000~PathGlobs=*~Headers=user-agent=browser,accept=text/html
如需创建令牌,请使用 Ed25519 签名或对称密钥 HMAC 对已签名值进行签名。
以下是使用已签名值创建的令牌示例:
Ed25519 签名
Expires=160000000~PathGlobs=*~Headers=user-agent,accept~Signature=SIGNATURE_OF_SIGNED_VALUE
其中 SIGNATURE_OF_SIGNED_VALUE 是之前创建的已签名值的 ED25519 签名。
对称密钥 HMAC
Expires=160000000~PathGlobs=*~Headers=user-agent,accept~hmac=HMAC_OF_SIGNED_VALUE
其中 HMAC_OF_SIGNED_VALUE 是之前创建的已签名值的对称密钥 HMAC。
在前面的示例中,令牌中提供了 Headers=user-agent,accept
,但预期的标头值不会从已签名值重复。这样,您就可以对特定请求标头键值对进行签名,而无需在令牌中重复值。