本指南介绍了如何生成令牌,以及令牌的必需字段和可选字段。
如需创建令牌,您需要撰写一个要签名的字符串,在本指南中,我们将其称为签名值。签名值包含用于描述您要保护的内容、签名值的到期时间等的参数。
您可以在创建令牌字符串时使用签名值。您可以通过组合令牌的参数(例如签名值的对称密钥哈希消息认证码 [HMAC])来创建令牌字符串。
Media 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`,一些有效的 网址Prefix 值包括 `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 地址(以 Web 安全的 Base64 格式表示),这些地址对应的网址有效。例如,如需指定 IP 范围“192.6.13.13/32,193.5.64.135/32”,您可指定 如果客户端面临 WAN 迁移风险,或者到达应用前端的网络路径与传送路径不同,那么在令牌中包含 IPRanges 可能没有帮助。
如果客户端连接时使用的 IP 地址不是签名请求的一部分,Media CDN 会拒绝这些客户端,并返回 以下情况可能会导致 Media CDN 以
所有这些因素都可能导致特定客户在视频播放会话期间拥有不确定的 IP 地址。如果您在授予访问权限后更改了客户端 IP 地址,并且客户端随后尝试将视频片段下载到其播放缓冲区中,则会收到来自媒体 CDN 的 |
IPRanges=BASE_64_IP_RANGES |
|
任意字符串,可用于日志分析或播放跟踪。 为避免创建无效令牌,请使用经过百分号编码或 Web 安全的 Base64 编码字符串。不得将以下字符用于 |
SessionID=SESSION_ID_VALUE |
|
任意字符串,可用于日志分析。 为避免创建无效令牌,请使用经过百分号编码或 Web 安全的 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
替换为采用 Web 安全 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
,但预期标头值不会重复使用签名值。这样一来,您就可以对特定的请求标头键值对进行签名,而无需在令牌中复制这些值。