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