Generare firme

Questa guida spiega come creare una firma e i campi obbligatori e facoltativi per le firme.

Per creare una firma, componi una stringa da firmare, che in questa guida chiamiamo valore firmato. Il valore firmato include parametri che descrivono i contenuti che stai proteggendo, il tempo di scadenza del valore firmato e così via.

Utilizzi il valore firmato durante la creazione di una stringa di firma. Crea una stringa di firma componendo i parametri della firma, ad esempio una firma Ed25519 con chiave asimmetrica del valore firmato.

Media CDN utilizza la firma composta finale per proteggere i tuoi contenuti.

Formati di firma supportati

Media CDN supporta i seguenti formati di richiesta firmata.

Formato Comportamento Esempio
Parametri di query (URL esatto)

URL esatto, per concedere l'accesso a un URL specifico.

Esatta:

https://media.example.com/content/manifest.m3u8?
Expires=EXPIRATION
&KeyName=KEY_NAME
&Signature=SIGNATURE
Parametri di query (prefisso URL) La specifica di un URLPrefix consente di firmare un prefisso e aggiungere gli stessiparametri di ricercay a più URL all'interno del lettore o della generazione del manifest.

Cosa firmare:

URLPrefix=PREFIX
&Expires=EXPIRATION
&KeyName=KEY_NAME
&Signature=SIGNATURE

Sostituisci PREFIX con il prefisso a cui concedere l'accesso, inclusi lo schema, l'host e il percorso parziale.

Componente percorso

Prefisso: consente l'accesso a qualsiasi URL con un prefisso precedente al componente "/edge-cache-token=[...]".

In questo modo, gli URL manifest relativi ereditano automaticamente il componente URL firmato durante il recupero delle risorse secondarie.

 https://media.example.com/video/edge-cache-token=Expires=EXPIRATION
&KeyName=KEY_NAME
&Signature=SIGNATURE/manifest_12382131.m3u8
Cookie firmato Prefisso: il cookie consente l'accesso a qualsiasi URL con il prefisso specificato nel valore URLPrefix firmato.

Edge-Cache-Cookie:

URLPrefix=PREFIX:
Expires=EXPIRATION:
KeyName=KEY_NAME:
Signature=SIGNATURE

Crea una firma

  1. Crea un valore firmato concatenando una stringa che contiene i campi della firma obbligatori e i campi della firma facoltativi desiderati.

    Se specificato, URLPrefix deve essere il primo, seguito da Expires, KeyName e poi da eventuali parametri facoltativi.

    Separa ogni campo e tutti i parametri con i seguenti simboli:

    • Per i cookie, utilizza i due punti :.
    • Per parametri di ricerca e i componenti del percorso, utilizza il carattere e commerciale &.

  2. Firma il valore firmato con una firma Ed25519.

  3. Aggiungi un separatore di campo (: o &) seguito da Signature= e dalla firma Ed25519 alla fine della stringa.

Crea un URL firmato

I seguenti esempi di codice mostrano come creare un URL firmato in modo programmatico.

Go

Per eseguire l'autenticazione in Media CDN, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale. 

import (
	"crypto/ed25519"
	"encoding/base64"
	"fmt"
	"io"
	"strings"
	"time"
)

// signURL prints the signed URL string for the specified URL and configuration.
func signURL(w io.Writer, url, keyName string, privateKey []byte, expires time.Time) error {
	// url := "http://example.com"
	// keyName := "your_key_name"
	// privateKey := "[]byte{34, 31, ...}"
	// expires := time.Unix(1558131350, 0)

	sep := '?'
	if strings.ContainsRune(url, '?') {
		sep = '&'
	}
	toSign := fmt.Sprintf("%s%cExpires=%d&KeyName=%s", url, sep, expires.Unix(), keyName)
	sig := ed25519.Sign(privateKey, []byte(toSign))

	fmt.Fprintf(w, "%s&Signature=%s", toSign, base64.RawURLEncoding.EncodeToString(sig))

	return nil
}

Python

Per eseguire l'autenticazione in Media CDN, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale. 

import base64
import datetime

import cryptography.hazmat.primitives.asymmetric.ed25519 as ed25519


from six.moves import urllib

def sign_url(
    url: str, key_name: str, base64_key: str, expiration_time: datetime.datetime
) -> str:
    """Gets the Signed URL string for the specified URL and configuration.

    Args:
        url: URL to sign as a string.
        key_name: name of the signing key as a string.
        base64_key: signing key as a base64 encoded byte string.
        expiration_time: expiration time as a UTC datetime object.

    Returns:
        Returns the Signed URL appended with the query parameters based on the
        specified configuration.
    """
    stripped_url = url.strip()
    parsed_url = urllib.parse.urlsplit(stripped_url)
    query_params = urllib.parse.parse_qs(parsed_url.query, keep_blank_values=True)
    epoch = datetime.datetime.utcfromtimestamp(0)
    expiration_timestamp = int((expiration_time - epoch).total_seconds())
    decoded_key = base64.urlsafe_b64decode(base64_key)

    url_pattern = "{url}{separator}Expires={expires}&KeyName={key_name}"

    url_to_sign = url_pattern.format(
        url=stripped_url,
        separator="&" if query_params else "?",
        expires=expiration_timestamp,
        key_name=key_name,
    )

    digest = ed25519.Ed25519PrivateKey.from_private_bytes(decoded_key).sign(
        url_to_sign.encode("utf-8")
    )
    signature = base64.urlsafe_b64encode(digest).decode("utf-8")
    signed_url = "{url}&Signature={signature}".format(
        url=url_to_sign, signature=signature
    )

    return signed_url

Creare un prefisso URL firmato

I seguenti esempi di codice mostrano come creare a livello di programmazione un prefisso URL firmato.

Go

Per eseguire l'autenticazione in Media CDN, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale. 

import (
	"crypto/ed25519"
	"encoding/base64"
	"fmt"
	"io"
	"strings"
	"time"
)

// signURLPrefix prints the signed URL string for the specified URL prefix and configuration.
func signURLPrefix(w io.Writer, urlPrefix, keyName string, privateKey []byte, expires time.Time) error {
	// urlPrefix := "https://examples.com"
	// keyName := "your_key_name"
	// privateKey := "[]byte{34, 31, ...}"
	// expires := time.Unix(1558131350, 0)

	sep := '?'
	if strings.ContainsRune(urlPrefix, '?') {
		sep = '&'
	}

	toSign := fmt.Sprintf(
		"URLPrefix=%s&Expires=%d&KeyName=%s",
		base64.RawURLEncoding.EncodeToString([]byte(urlPrefix)),
		expires.Unix(),
		keyName,
	)
	sig := ed25519.Sign(privateKey, []byte(toSign))

	fmt.Fprintf(
		w,
		"%s%c%s&Signature=%s",
		urlPrefix,
		sep,
		toSign,
		base64.RawURLEncoding.EncodeToString(sig),
	)

	return nil
}

Python

Per eseguire l'autenticazione in Media CDN, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale. 

import base64
import datetime

import cryptography.hazmat.primitives.asymmetric.ed25519 as ed25519


from six.moves import urllib

def sign_url_prefix(
    url: str,
    url_prefix: str,
    key_name: str,
    base64_key: str,
    expiration_time: datetime.datetime,
) -> str:
    """Gets the Signed URL string for the specified URL prefix and configuration.

    Args:
        url: URL of request.
        url_prefix: URL prefix to sign as a string.
        key_name: name of the signing key as a string.
        base64_key: signing key as a base64 encoded string.
        expiration_time: expiration time as a UTC datetime object.

    Returns:
        Returns the Signed URL appended with the query parameters based on the
        specified URL prefix and configuration.
    """
    stripped_url = url.strip()
    parsed_url = urllib.parse.urlsplit(stripped_url)
    query_params = urllib.parse.parse_qs(parsed_url.query, keep_blank_values=True)
    encoded_url_prefix = base64.urlsafe_b64encode(
        url_prefix.strip().encode("utf-8")
    ).decode("utf-8")
    epoch = datetime.datetime.utcfromtimestamp(0)
    expiration_timestamp = int((expiration_time - epoch).total_seconds())
    decoded_key = base64.urlsafe_b64decode(base64_key)

    policy_pattern = (
        "URLPrefix={encoded_url_prefix}&Expires={expires}&KeyName={key_name}"
    )
    policy = policy_pattern.format(
        encoded_url_prefix=encoded_url_prefix,
        expires=expiration_timestamp,
        key_name=key_name,
    )

    digest = ed25519.Ed25519PrivateKey.from_private_bytes(decoded_key).sign(
        policy.encode("utf-8")
    )
    signature = base64.urlsafe_b64encode(digest).decode("utf-8")
    signed_url = "{url}{separator}{policy}&Signature={signature}".format(
        url=stripped_url,
        separator="&" if query_params else "?",
        policy=policy,
        signature=signature,
    )
    return signed_url

I seguenti esempi di codice mostrano come creare in modo programmatico un cookie URL firmato.

Creare un componente del percorso firmato

I seguenti esempi di codice mostrano come creare a livello di programmazione un componente del percorso firmato.

Python

Per eseguire l'autenticazione in Media CDN, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per un ambiente di sviluppo locale. 

import base64
import datetime
import hashlib
import hmac

import cryptography.hazmat.primitives.asymmetric.ed25519 as ed25519


def base64_encoder(value: bytes) -> str:
    """
    Returns a base64-encoded string compatible with Media CDN.

    Media CDN uses URL-safe base64 encoding and strips off the padding at the
    end.
    """
    encoded_bytes = base64.urlsafe_b64encode(value)
    encoded_str = encoded_bytes.decode("utf-8")
    return encoded_str.rstrip("=")


def sign_path_component(
    url_prefix: str,
    filename: str,
    key_name: str,
    base64_key: str,
    expiration_time: datetime.datetime,
) -> str:
    """Gets the Signed URL string for the specified URL prefix and configuration.

    Args:
        url_prefix: URL Prefix to sign as a string.
        filename: The filename of the sample request
        key_name: The name of the signing key as a string.
        base64_key: The signing key as a base64 encoded string.
        expiration_time: Expiration time as a UTC datetime object with timezone.

    Returns:
        Returns the Signed URL appended with the query parameters based on the
        specified URL prefix and configuration.
    """

    expiration_duration = expiration_time.astimezone(
        tz=datetime.timezone.utc
    ) - datetime.datetime.fromtimestamp(0, tz=datetime.timezone.utc)
    decoded_key = base64.urlsafe_b64decode(base64_key)

    policy_pattern = "{url_prefix}edge-cache-token=Expires={expires}&KeyName={key_name}"
    policy = policy_pattern.format(
        url_prefix=url_prefix,
        expires=int(expiration_duration.total_seconds()),
        key_name=key_name,
    )

    digest = ed25519.Ed25519PrivateKey.from_private_bytes(decoded_key).sign(
        policy.encode("utf-8")
    )
    signature = base64_encoder(digest)

    signed_url = "{policy}&Signature={signature}/{filename}".format(
        policy=policy, signature=signature, filename=filename
    )

    return signed_url

Campi della firma obbligatori

I seguenti campi sono obbligatori per ogni firma:

  • Expires
  • KeyName
  • Signature

Se sono presenti parametri di ricerca, devono essere raggruppati come ultimi parametri nell'URL. Se non diversamente specificato, i nomi dei parametri e i relativi valori sono sensibili alle maiuscole.

La tabella seguente descrive ciascun parametro:

Nome campo Parametri della firma Valore firmato
Expires Secondi interi trascorsi dall'epoca di Unix (1970-01-01T00:00:00Z) Expires=EXPIRATION_TIME, dopo la quale la firma non è più valida.
KeyName Il nome del EdgeCacheKeyset utilizzato per firmare questa richiesta. KeyName si riferisce all'intero set di chiavi, non alle singole chiavi all'interno del set stesso. KeyName=EDGE_CACHE_KEYSET
Signature Una versione della firma con codifica Base64. Non applicabile

Campi della firma facoltativi

Se sono presenti parametri di ricerca, devono essere raggruppati come ultimi parametri nell'URL. Se non diversamente specificato, i nomi dei parametri e i relativi valori sono sensibili alle maiuscole.

La seguente tabella spiega il nome e i dettagli di ciascun parametro per i parametri di firma facoltativi:

Nome campo Parametri della firma Valore firmato
HeaderName

Il nome di un campo di intestazione della richiesta denominato che deve essere presente nella richiesta.

Deve essere in minuscolo quando viene firmato perché i nomi dei campi delle intestazioni sono sensibili alle maiuscole. Media CDN converte l'intestazione in minuscolo prima di convalidare la firma.

 HeaderName=HEADER_NAME
HeaderValue Un valore del campo di intestazione della richiesta denominato che deve essere presente nella richiesta. In genere si tratta di un ID utente o di un altro identificatore opaco. Le richieste con HeaderValue ma senza HeaderName vengono rifiutate. HeaderValue=HEADER_VALUE
IPRanges

Un elenco di massimo cinque indirizzi IPv4 e IPv6 in formato CIDR per cui questo URL è valido in formato base64 sicuro per il web. Ad esempio, per specificare gli intervalli IP "192.6.13.13/32,193.5.64.135/32", specifica IPRanges=MTkyLjYuMTMuMTMvMzIsMTkzLjUuNjQuMTM1LzMy.

Gli intervalli IP potrebbero non essere utili da includere nelle firme quando i client sono a rischio di migrazioni WAN o nei casi in cui il percorso di rete al frontend dell'applicazione è diverso dal percorso di distribuzione. Media CDN rifiuta i client con un codice HTTP 403 quando si connettono con un indirizzo IP che non fa parte della richiesta firmata.

Di seguito sono riportati i casi che potrebbero comportare il rifiuto dei client da parte di Media CDN con un codice HTTP 403:

  • Ambienti dual-stack (IPv4, IPv6)
  • Migrazione della connessione (dal Wi-Fi alla rete cellulare e viceversa)
  • Reti mobile che utilizzano Carrier Gateway NAT (CGNAT o CGN)
  • TCP multi-path (MPTCP)

Tutti questi fattori possono contribuire a far sì che un determinato client abbia un indirizzo IP non deterministico durante una sessione di riproduzione video. Se l'indirizzo IP del client cambia dopo che hai concesso l'accesso e il client tenta di scaricare un segmento video nel buffer di riproduzione, riceve un HTTP 403 dalla CDN Media.

IPRanges=BASE_64_IP_RANGES
URLPrefix Il prefisso URL base64 (con protezione dell'URL) a cui concedere l'accesso. Se specifichi un URLPrefix, puoi firmare un prefisso e aggiungere gli stessi parametri di query a più URL durante la generazione del lettore o del manifest. URLPrefix è obbligatorio quando si utilizza il formato del cookie firmato. URLPrefix=BASE_64_URL_PREFIX