Générer des signatures

Ce guide explique comment créer une signature et présente les champs obligatoires et facultatifs pour les signatures.

Pour créer une signature, vous devez composer une chaîne à signer, que nous appellerons une valeur signée dans le présent guide. La valeur signée inclut des paramètres qui décrivent le contenu que vous protégez, le délai d'expiration de la valeur signée, etc.

Vous utilisez la valeur signée lors de la création d'une chaîne de signature. Vous créez une chaîne de signature en composant les paramètres de la signature, par exemple une signature Ed25519 de clé asymétrique associée à la valeur signée.

Media CDN utilise la signature composée finale pour protéger votre contenu.

Formats de signature acceptés

Media CDN est compatible avec les formats de requêtes signées suivants.

Format	Comportement	Exemple
Paramètres de requête (URL exacte)	URL exacte, pour accorder l'accès à une URL spécifique.	Exact : https://media.example.com/content/manifest.m3u8? Expires=EXPIRATION &KeyName=KEY_NAME &Signature=SIGNATURE
Paramètres de requête (préfixe d'URL)	Spécifier un URLPrefix vous permet de signer un préfixe et d'ajouter les mêmes paramètres de requête à plusieurs URL dans votre génération de lecteur ou de fichier manifeste.	Quels éléments signer : URLPrefix=PREFIX &Expires=EXPIRATION &KeyName=KEY_NAME &Signature=SIGNATURE Remplacez PREFIX par le préfixe auquel vous souhaitez accorder l'accès, en incluant le schéma, l'hôte et le chemin d'accès partiel.
Composant de chemin	Préfixe : permet d'accéder à n'importe quelle URL avec un préfixe placé avant le composant "/edge-cache-token=[...]". Cela permet aux URL de fichier manifeste relatif d'hériter automatiquement du composant d'URL signé lors de la récupération des sous-ressources.	https://media.example.com/video/edge-cache-token=Expires=EXPIRATION &KeyName=KEY_NAME &Signature=SIGNATURE/manifest_12382131.m3u8
Cookie signé	Préfixe : le cookie permet d'accéder à n'importe quelle URL comportant le préfixe spécifié dans la valeur URLPrefix signée.	Edge-Cache-Cookie : URLPrefix=PREFIX: Expires=EXPIRATION: KeyName=KEY_NAME: Signature=SIGNATURE

Créer une signature

Remarque : Les composants d'hôte et de chemin de l'URL (ou du préfixe d'URL) sont utilisés pour valider les signatures. Lorsque vous fournissez une URL à l'une de ces API programmatiques, omettez le port. En d'autres termes, pour un chemin tel que https://example.com:443/path, spécifiez le chemin d'accès https://example.com/path.

1. Créez une valeur signée en concaténant une chaîne contenant les champs de signature requis et les champs de signature facultatifs souhaités.

   Le cas échéant, URLPrefix doit apparaître en premier, suivi de Expires, KeyName, puis de tout paramètre facultatif.

   Séparez chaque champ et tous les paramètres avec les éléments suivants :

   • Pour les cookies, utilisez le caractère deux-points :.
   • Pour les paramètres de requête et les composants de chemin d'accès, utilisez une esperluette &.

2. Signez la valeur signée avec une signature Ed25519.

3. Ajoutez un séparateur de champ (: ou &) suivi de Signature= et de la signature Ed25519 à la fin de la chaîne.

Créer une URL signée

Les exemples de code suivants montrent comment créer une URL signée de manière programmatique.

Go

Pour vous authentifier auprès de Media CDN, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour vous authentifier auprès de Media CDN, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Créer un préfixe d'URL signé

Les exemples de code suivants montrent comment créer un préfixe d'URL signé par programmation.

Go

Pour vous authentifier auprès de Media CDN, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour vous authentifier auprès de Media CDN, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Créer un cookie d'URL signée

Les exemples de code suivants montrent comment créer une URL signée par programmation un cookie.

Go

Pour vous authentifier auprès de Media CDN, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Pour vous authentifier auprès de Media CDN, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Créer un composant de chemin signé

Les exemples de code suivants montrent comment créer un composant de chemin signé par programmation.

Python

Pour vous authentifier auprès de Media CDN, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

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

Champs de signature obligatoires

Les champs suivants sont obligatoires pour chaque signature :

• Expires
• KeyName
• Signature

Si des paramètres de requête sont présents, ils doivent être regroupés en tant que derniers paramètres dans l'URL. Sauf indication contraire, les noms de paramètres et leurs valeurs sont sensibles à la casse.

Le tableau suivant explique chaque paramètre :

Nom du champ	Paramètres de signature	Valeur signée
Expires	Nombre entier de secondes écoulées depuis l'époque Unix (1970-01-01T00:00:00Z)	Expires=EXPIRATION_TIME, après lequel la signature n'est plus valide.
KeyName	Nom de l'objet EdgeCacheKeyset utilisé pour signer cette requête. KeyName fait référence à l'ensemble de la collection de clés, et non aux clés individuelles de la collection.	KeyName=EDGE_CACHE_KEYSET
Signature	Version de la signature encodée en base64.	Non applicable

Champs de signature facultatifs

Si des paramètres de requête sont présents, ils doivent être regroupés en tant que derniers paramètres dans l'URL. Sauf indication contraire, les noms de paramètres et leurs valeurs sont sensibles à la casse.

Le tableau suivant décrit le nom et les détails de chaque paramètre de signature facultatif :

Nom du champ	Paramètres de signature	Valeur signée
HeaderName	Nom du champ d'en-tête de requête nommé qui doit être présent dans la requête. Doit être en minuscules lorsqu'il est signé, car les noms de champs d'en-tête sont sensibles à la casse. Media CDN convertit l'en-tête en minuscules avant de valider la signature.	HeaderName=HEADER_NAME
HeaderValue	Une valeur de champ d'en-tête de requête nommé qui doit être présente dans la requête. Il s'agit généralement d'un identifiant utilisateur ou d'un autre identifiant opaque. Les requêtes avec HeaderValue mais sans HeaderName sont rejetées.	HeaderValue=HEADER_VALUE
IPRanges	Liste incluant jusqu'à cinq adresses IPv4 et IPv6 au format CIDR pour lesquelles cette URL est valide au format base64 web-safe. Par exemple, pour spécifier les plages d'adresses IP "192.6.13.13/32,193.5.64.135/32", spécifiez IPRanges=MTkyLjYuMTMuMTMvMzIsMTkzLjUuNjQuMTM1LzMy. Les plages d'adresses IP peuvent ne pas être utiles à inclure dans les signatures lorsque les clients sont susceptibles d'effectuer des migrations WAN ou dans les cas où le chemin d'accès réseau à l'interface de l'application est différent du chemin de distribution. Media CDN rejette les clients disposant d'un code HTTP 403 lorsqu'ils se connectent avec une adresse IP ne faisant pas partie de la requête signée. Les cas suivants peuvent entraîner le rejet des clients avec le code HTTP 403 dans Media CDN : Environnements double pile (IPv4, IPv6) Migration de connexion (Wi-Fi vers mobile et mobile vers Wi-Fi) Réseaux mobiles utilisant la passerelle NAT (CGNAT ou CGN) TCP multi-chemin (MPTCP) Tous ces facteurs peuvent contribuer à ce qu'un client donné ait une adresse IP non déterministe pendant une session de lecture vidéo. Si l'adresse IP du client change après avoir accordé l'accès et que le client tente de télécharger un segment vidéo dans son tampon de lecture, il reçoit une erreur HTTP 403 de Media CDN.	IPRanges=BASE_64_IP_RANGES
URLPrefix	Préfixe d'URL en base64 (URL-safe) auquel accorder l'accès. Spécifier un URLPrefix vous permet de signer un préfixe et d'ajouter les mêmes paramètres de requête à plusieurs URL dans votre génération de lecteur ou de fichier manifeste. L'élément URLPrefix est requis lors de l'utilisation du format de cookie signé.	URLPrefix=BASE_64_URL_PREFIX