All Products
Search
Document Center

Edge Security Acceleration:Configure URL signing

Last Updated:Apr 18, 2025

Edge Security Acceleration (ESA) Edge Routine templates offer three URL signing methods. URLs that fail authentication are blocked to protect your resources. This topic includes code examples and parameter descriptions to help you configure and debug URL signing.

Scenarios

  • Accessing files

  • Making API requests

Methods

Methods A, B, and C encrypt data using MD5. The client’s MD5 hash is compared to the hash stored on the point of presence (POP). If they match, the resource is returned; if not, access is denied.

Method A

  • Authentication URL format: http://DomainName/Filename?auth_key={timestamp}-{rand}-{uid}-{md5hash}. For details of the URL fields, see Field descriptions.

  • Sample code

    import { createHash } from "node:crypto";
    
    async function handleRequest(request) {
      const url = new URL(request.url);
      const path = url.pathname;
      const delta = 3600;
    
      const authKeyTypeA = url.searchParams.get('auth_key');
    
      const privateKey = 'your_secret_key'
      const currentTimestamp = Math.floor(Date.now() / 1000);
    
      if (!authKeyTypeA) {
        return new Response('Unauthorized', { status: 401 });
      }
    
      const [timestamp, rand, uid, signature] = authKeyTypeA.split('-');
    
      if (currentTimestamp > parseInt(timestamp)+ delta) {
        return new Response('Link expired', { status: 403 });
      }
    
      const signString = [path, timestamp, rand, uid, privateKey].join('-');
    
      const md5 = createHash('md5').update(signString).digest('hex');
    
      if (md5 !== signature) {
        return new Response('Unauthorized', { status: 401 });
      }
    
      // If the resource is on another domain, the code is as follows:
      // const yourUrl = `https://your-dcdn-domain.com${path}${url.search}`
      // const cdnResponse = await fetch(yourUrl, request)
      // return new Response(cdnResponse.body, cdnResponse)
    
      // In most cases, it is origin fetch.
      return fetch(request.url)
    }
    
    export default {
      async fetch(request) {
        return handleRequest(request)
      }
    }
  • Testing and verification

    • Use the command line tool to test a URL that should pass authentication: curl -I http://esa.aliyun.top/video/test.mp4?auth_key=1743388566-61b20a42d14f403ba3790d1b82502027-1-ee1c2c463a41ef4d72fcff5987f1e08c . The HTTP response code 200 indicates successful authentication.

      image

    • Use the command line tool to test a URL that should fail authentication: curl -I http://esa.aliyun.top/test.mp4. The HTTP response code 401 indicates authentication failure.

      image

Method B

  • Authentication URL format: http://DomainName/{timestamp}/{md5hash}/FileName. For details of the URL fields, see Field descriptions.

  • Sample code

    import { createHash } from "node:crypto";
    
    function handleRequest(request) {
      const url = new URL(request.url);
      const path = url.pathname;
      const parts = path.split('/');
      const delta = 3600;
      const privateKey = 'your_secret_key'
      const currentTimestamp = Math.floor(Date.now() / 1000);
      const timestamp = parts[1];
      const signature = parts[2];
    
      if (!timestamp || !signature) {
        return new Response('Unauthorized', { status: 401 });
      }
    
      const filePath = '/' + parts.slice(3).join('/');
      const signString = [privateKey, timestamp, filePath].join('');
      const md5 = createHash('md5').update(signString).digest('hex');
    
      if (md5 !== signature) {
        return new Response('Unauthorized', { status: 403 });
      }
    
      if (currentTimestamp > parseInt(timestamp)+ delta) {
        return new Response('Link expired', { status: 403 });
      }
    
      // If the resource is on another domain, the code is as follows:
      // const yourUrl = `https://your-dcdn-domain.com${path}${url.search}`
      // const cdnResponse = await fetch(yourUrl, request)
      // return new Response(cdnResponse.body, cdnResponse)
    
      // For method B authentication, the content is in the path and needs to be reconstructed
      return fetch(url.origin + filePath)
    }
    
    export default {
      async fetch(request) {
        return handleRequest(request)
      }
    }
  • Testing and verification

    • Use the command line tool to test a URL that should pass authentication: http://esa.aliyun.top/1743391454/f1415e282ae5ae650455e7b525231eff/test.mp4. The HTTP response code 200 indicates successful authentication.

      image

    • Use the command line tool to test a URL that should fail authentication: http://esa.aliyun.top/test.mp4. The HTTP response code 401 indicates authentication failure.

      image

Method C

  • Authentication URL format: http://DomainName/{md5hash}/{timestamp}/FileName. For details of the URL fields, see Field descriptions.

  • Sample code

    import { createHash } from "node:crypto";
    
    function handleRequest(request) {
      const url = new URL(request.url);
      const path = url.pathname;
      const parts = path.split('/');
      const delta = 3600;
      const privateKey = 'your_secret_key'
      const currentTimestamp = Math.floor(Date.now() / 1000);
      const signature = parts[1];
      const hexTime = parts[2];
      const timestamp = parseInt(hexTime, 16);
    
      if (!hexTime || !signature) {
        return new Response('Unauthorized', { status: 401 });
      }
    
      const filePath = '/' + parts.slice(3).join('/');
      const signString = [privateKey, filePath, hexTime].join('-');
      const md5 = createHash('md5').update(signString).digest('hex');
    
      if (md5 !== signature) {
        return new Response('Unauthorized', { status: 403 });
      }
    
      if (currentTimestamp > parseInt(timestamp)+ delta) {
        return new Response('Link expired', { status: 403 });
      }
    
      // If the resource is on another domain, the code is as follows:
      // const yourUrl = `https://your-dcdn-domain.com${path}${url.search}`
      // const cdnResponse = await fetch(yourUrl, request)
      // return new Response(cdnResponse.body, cdnResponse)
    
      // For method C authentication, the content is in the path and needs to be reconstructed
      return fetch(url.origin + filePath)
    }
    
    export default {
      async fetch(request) {
        return handleRequest(request)
      }
    }
  • Testing and verification

    • Use the command line tool to test a URL that should pass authentication: http://esa.aliyun.top/e59c904c85f19a48413b6283fc9d2f5a/1743400480/test.mp4. The HTTP response code 200 indicates successful authentication.

      image

    • Use the command line tool to test a URL that should fail authentication: http://esa.aliyun.top/test.mp4. The HTTP response code 401 indicates authentication failure.

      image

Field descriptions

  • DomainName: The DNS record of the ESA website.

  • timestamp: The time when the authentication server generates the authentication URL. It determines the expiration time of the authentication URL together with the Time To Live (TTL) of the authentication URL. The time is in UTC+8 and follows the YYYYMMDDHHMM format.

    Note

    In most cases, the TTL of the authentication URL is set in ESA . Sometimes, it is increased during the calculation process. Then the timestamp is calculated as the Unix timestamp plus the increased time. The actual expiration time of the authentication URL is the timestamp plus the TTL set in ESA.

  • FileName: The actual file path accessed for the origin fetch. For authentication, FileName must start with /.

  • md5hash: A verification string calculated using the MD5 algorithm, consisting of numbers 0 to 9 and lowercase English letters a to z, with a fixed length of 32.

    The calculation method for the md5hash value:

    • Authentication method A: getMd5(FileName + "-" + timestamp + "-" + rand + "-" + uid + "-" + your_secret_key).

    • Authentication method B: getMd5(your_secret_key + timestamp + FileName).

    • Authentication method C: getMd5(your_secret_key + "-" + FileName + "-" + timestamp).

    Note

    You need to implement the getMd5 function manually.

  • rand: A random number. We recommend using UUID without hyphens -, for example: 477b3bbc253f467b8def6711128c7bec.

  • uid: User ID.

  • auth_key: The authentication information for this request, consisting of timestamp, rand, uid, and md5hash.