Authentication Method V
Overview
In order to enhance permission control for video scenarios, EO has launched a solution to TypeV authentication. The features of this solution are as follows:
It supports specifying an expiration time in the URL, which cannot be used for a long time after being obtained by others;
It supports including a client IP in the signature calculation in the URL, which cannot be used after being obtained by others;
It supports specifying the preview duration in the URL to realize the preview feature;
It supports specifying a Referer blocklist/allowlist in the URL;
It supports specifying in the URL the start of video playback from a Unix timestamp to realize the pseudo-live streaming feature;
Developers use a
KEY to sign the URL and include the signature in the URL. As long as a user's key is not leaked, other users cannot forge the encrypted URL;The EdgeOne node checks the parameters and signature in the encrypted URL to control access requests. If a request fails to pass the check, a 403 response code will be returned.
Authentication Parameters
The following are the meaning and value description of each parameter in the authentication URL.
Parameter name | Required | Description |
KEY | Yes | The key filled in when TypeV authentication is enabled. It should contain 8-20 characters, including uppercase and lowercase letters (a-Z), numbers (0-9), and special characters. The random generation of it on the console is supported. |
Path | Yes | The Path part of the original URL. If the original URL is http://example.vod2.myqcloud.com/dir1/dir2/myVideo.mp4, the Path is /dir1/dir2/myVideo.mp4. |
t | Yes | The expiration timestamp (in seconds) of the URL accessed, expressed in the lowercase hexadecimal format of Unix time. Once expiration, the URL will no longer be valid, and a 403 response code will be returned. Considering the possible time difference between machines, the actual expiration time of the authentication URL is generally 5 minutes longer than the specified expiration time, that is, an additional tolerance time of 300 seconds is given. It is recommended that the expiration timestamp should not be too short, in order to ensure that users can complete downloads or video playback within the validity period. |
exper | No | Preview duration in seconds, expressed in the decimal format. If the value is empty or 0, it means no preview (i.e., the full video is returned). The preview duration should not exceed the original video duration, as this may cause playback failures. |
us | No | Link identifier, used to randomize an authentication URL and enhance the uniqueness of the link. It is recommended to specify a random 'us' value each time an authentication URL is generated. |
plive | No | This parameter is in seconds, and is expressed in the lowercase hexadecimal format of Unix time. It enables the start of video playback from a specified time to realize the pseudo-live streaming feature. Example: If the value of plive is 669f9b40, it means that the resources corresponding to the encrypted request can be accessed only after 20:00:00, July 23, 2024. |
whref | No | List of allowed domain names, which contain 1 to 10 items and are separated by half-width commas. No protocol name (http:// or https://) should be added to the beginning of a domain name. The domain name is in the form of exact match (for example, if abc.com is filled in, only abc.com can be matched and abc.com.cn cannot be matched), and wildcards (such as *.abc.com) are supported. |
bkref | No | List of forbidden domain names, which contain 1 to 10 items and are separated by half-width commas. No protocol name (http:// or https://) should be added to the beginning of a domain name. The domain name is in the form of exact match (for example, if abc.com is filled in, only abc.com can be matched and abc.com.cn cannot be matched), and wildcards (such as *.abc.com) are supported. |
whip | No | List of allowed client IPs, which contain 1 to 10 items and are separated by half-width commas. Client IPs can be IPs or IP segments, such as 192.168.0.0 or 192.168.0.0/24. Among others, 0.0.0.0/0 represents all IPv4 addresses, and ::/0 represents all IPv6 addresses. The client IP is obtained through the X-Forwarded-For header. If there are multiple header values, the first one is taken. |
bkip | No | The list of forbidden client IPs, which contain 1 to 10 items and are separated by half-width commas. Client IPs can be IPs or IP segments, such as 192.168.0.0 or 192.168.0.0/24. Among others, 0.0.0.0/0 represents all IPv4 addresses, and ::/0 represents all IPv6 addresses. The client IP is obtained through the X-Forwarded-For header. If there are multiple header values, the first one is taken. |
sign | Yes | Hotlink protection signature, represented by a 40-character hexadecimal number. It is used to verify the validity of the authentication URL. If the signature verification fails, a 403 response code will be returned. For the calculation method, refer to the signature calculation formula. |
Note:
For the VOD origin server, all the above parameters are supported. For non-VOD origin servers, the
us and plive parameters are not supported.Signature Calculation Formula
sign = sha1(KEY + Path + t + plive + exper + us + whref + bkref + whip + bkip)
In the formula,
+ represents string concatenation, and optional parameters can be an empty string.URL Generation Rules for Hotlink Protection
At the end of the original URL, hotlink protection parameters are added in the form of QueryString, as shown below:
http://example.vod2.myqcloud.com/dir1/dir2/myVideo.mp4?t=[t]&exper=[exper]&us=[us]&whref=[whref]&whip=[whip]&sign=[sign]
Note:
In the formula,
+ represents string concatenation, and optional parameters can be an empty string;In the signature calculation, each parameter must strictly follow the order in the signature calculation formula. If the order is incorrect, an erroneous signature will be generated.
Configuration Examples
Assume the original URL is
http://example.vod2.myqcloud.com/dir1/dir2/myVideo.mp4. The developer has configured TypeV authentication, the generated Key is 24FEQmTzro4V5u3D5epW and the generated random string is 72d4cd1101. Below are scenarios for ''validity time control of video playback URL'', ''the same authentication URL allowing access by only one client IP'' and ''allowed video playback by client IP'', which describe how to generate an authentication URL.
Example 1: Validity Time Control of Video Playback URL
If you need to generate an authentication URL for this video with an expiration time of 20:00:00, January 31, 2018 (Unix time: 1517400000), refer to the steps below.
Step 1: Determining Authentication Parameters
Parameter name | Value | Description |
KEY | 24FEQmTzro4V5u3D5epW | The key selected by the developer in enabling key hotlink protection |
Dir | /dir1/dir2/myVideo.mp4 | The Path part of the original URL |
t | 5a71afc0 | The hexadecimal representation of the expiration timestamp 1517400000 |
us | 72d4cd1101 | A random string generated |
Step 2: Calculating the Signature
sign = sha1(''24FEQmTzro4V5u3D5epW/dir1/dir2/myVideo.mp45a71afc072d4cd1101'') = ''3ff5ab708b018fce5c3023b6d27ca938d7ab75e3''
Step 3: Generating Authentication URL
The authentication parameters are concatenated into the original video URL's QueryString to get a video authentication URL:
http://example.vod2.myqcloud.com/dir1/dir2/myVideo.mp4?t=5a71afc0&us=72d4cd1101&sign=3ff5ab708b018fce5c3023b6d27ca938d7ab75e3
Example 2: The Same Authentication URL Allowing Access by Only One Client IP
If the same authentication URL requires access by only one client IP, refer to the steps below.
Step 1: Determining Authentication Parameters
Parameter name | Value | Description |
KEY | 24FEQmTzro4V5u3D5epW | The key selected by the developer in enabling key hotlink protection |
Path | /dir1/dir2/myVideo.mp4 | The Path part of the original URL |
t | 5a71afc0 | The hexadecimal representation of the expiration timestamp 1517400000 |
us | 72d4cd1101 | A random string generated |
whip | 192.168.0.0 | Allowed client IP |
Step 2: Calculating the Signature
sign = sha1(''24FEQmTzro4V5u3D5epW/dir1/dir2/5a71afc072d4cd1101192.168.0.0'') = ''c8cd894ef4ee0387c99ac488f46bbe8205bc63af''
Step 3: Generating Authentication URL
The authentication parameters are concatenated into the original video URL's QueryString to get a video authentication URL:
http://example.vod2.myqcloud.com/dir1/dir2/myVideo.mp4?t=5a71afc0&us=72d4cd1101&whip=192.168.0.0&sign=c8cd894ef4ee0387c99ac488f46bbe8205bc63af
Example 3: Control of Allowed Playback Duration
If you need to generate a preview URL, with the preview duration being the first 5 minutes of the video (when the original video duration is greater than 5 minutes), refer to the steps below.
Step 1: Determining Authentication Parameters
Parameter name | Value | Description |
KEY | 24FEQmTzro4V5u3D5epW | The key selected by the developer in enabling key hotlink protection |
Path | /dir1/dir2/myVideo.mp4 | The Path part of the original URL |
t | 5a71afc0 | The hexadecimal representation of the expiration timestamp 1517400000 |
exper | 300 | A preview of the first 5 minutes, i.e. 300 seconds |
us | 72d4cd1101 | A random string generated |
Step 2: Calculating the Signature
sign = sha1(''24FEQmTzro4V5u3D5epW/dir1/dir2/myVideo.mp45a71afc030072d4cd1101'') = ''3a50217aff3e39fbf795b8db40925bc61735fe83''
Step 3: Generating Authentication URL
The authentication parameters are concatenated into the original video URL's QueryString to get a video authentication URL:
http://example.vod2.myqcloud.com/dir1/dir2/myVideo.mp4?t=5a71afc0&exper=300&us=72d4cd1101&sign=3a50217aff3e39fbf795b8db40925bc61735fe83