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, indicata come valore firmato in questa guida. Il valore firmato include parametri che descrivono i contenuti che stai proteggendo, la data e l'ora di scadenza del valore firmato e così via.

Utilizza il valore firmato durante la creazione di una stringa di firma. Puoi creare una stringa di firma componendo i parametri per la 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 richieste firmate.

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 ti consente di firmare un prefisso e di aggiungere gli stessi parametri di ricerca a più URL all'interno della generazione del player o del manifest.	Cosa firmare: URLPrefix=PREFIX &Expires=EXPIRATION &KeyName=KEY_NAME &Signature=SIGNATURE Sostituisci PREFIX con il prefisso a cui concedere accesso, inclusi schema, host e 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 quando viene eseguito 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 firmato URLPrefix.	Edge-Cache-Cookie: URLPrefix=PREFIX: Expires=EXPIRATION: KeyName=KEY_NAME: Signature=SIGNATURE

Crea una firma

Nota: i componenti host e percorso dell'URL (o URLPrefix) vengono utilizzati per verificare le firme. Quando fornisci un URL a una di queste API programmatiche, ometti la porta. In altre parole, per un percorso come https://example.com:443/path, specifica il percorso come https://example.com/path.

1. Crea un valore firmato concatenando una stringa contenente i campi di firma obbligatori e i campi di firma facoltativi desiderati.

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

   Separa ogni campo e tutti i parametri con quanto segue:

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

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.

Creare un URL firmato

Gli esempi di codice riportati di seguito mostrano come creare un URL firmato tramite programmazione.

Go

Per autenticarti a Media CDN, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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 autenticarti a Media CDN, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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

Crea un prefisso URL firmato

Gli esempi di codice riportati di seguito mostrano come creare programmaticamente un prefisso URL firmato.

Go

Per autenticarti a Media CDN, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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 autenticarti a Media CDN, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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

Creare un cookie URL firmato

Gli esempi di codice riportati di seguito mostrano come creare programmaticamente un cookie URL firmato.

Go

Per autenticarti a Media CDN, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.

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

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

	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,
		"Edge-Cache-Cookie=%s:Signature=%s",
		toSign,
		base64.RawURLEncoding.EncodeToString(sig),
	)

	return nil
}

Python

Per autenticarti a Media CDN, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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_cookie(
    url_prefix: str, key_name: str, base64_key: str, expiration_time: datetime.datetime
) -> str:
    """Gets the Signed cookie value for the specified URL prefix and configuration.

    Args:
        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 Edge-Cache-Cookie value based on the specified configuration.
    """
    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_policy = "Edge-Cache-Cookie={policy}:Signature={signature}".format(
        policy=policy, signature=signature
    )
    return signed_policy

Crea un componente del percorso firmato

I seguenti esempi di codice mostrano come creare programmatically un componente del percorso firmato.

Python

Per autenticarti a Media CDN, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare 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 di 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 illustra ciascun parametro:

Nome campo	Parametri di firma	Valore firmato
Expires	Secondi interi trascorsi dall'epoca di Unix (1970-01-01T00:00:00Z)	Expires=EXPIRATION_TIME, dopodiché 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 con codifica base64 della firma.	Non applicabile

Campi di 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 tabella seguente spiega il nome e i dettagli di ciascun parametro per i parametri facoltativi della firma:

Nome campo	Parametri di firma	Valore firmato
HeaderName	Un nome di campo dell'intestazione della richiesta che deve essere presente nella richiesta. Deve essere in minuscolo quando è firmato perché i nomi dei campi delle intestazioni sono sensibili alle maiuscole. Media CDN mette in minuscolo l'intestazione prima di convalidare la firma.	HeaderName=HEADER_NAME
HeaderValue	Un valore del campo dell'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 i quali 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 esposti a rischi di migrazioni WAN o nei casi in cui il percorso di rete al frontend dell'applicazione è diverso dal percorso di importazione. 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 in cui Media CDN potrebbe rifiutare i clienti con un codice HTTP 403: Ambienti dual-stack (IPv4, IPv6) Migrazione della connessione (da Wi-Fi a rete mobile e da rete mobile a Wi-Fi) Reti mobili che utilizzano NAT gateway dell'operatore (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 di un video. Se l'indirizzo IP del cliente cambia dopo che hai concesso l'accesso e il cliente tenta di scaricare un segmento di video nel proprio buffer di riproduzione, riceve un messaggio HTTP 403 da Media CDN.	IPRanges=BASE_64_IP_RANGES
URLPrefix	Il prefisso dell'URL base64 (sicuro per l'URL) a cui concedere l'accesso. La specifica di un URLPrefix ti consente di firmare un prefisso e di aggiungere gli stessi parametri di query a più URL all'interno del player o della generazione del manifest. URLPrefix è obbligatorio quando si utilizza il formato del cookie firmato.	URLPrefix=BASE_64_URL_PREFIX