Gerar assinaturas

Este guia explica como criar uma assinatura e os campos obrigatórios e opcionais para assinaturas.

Para criar uma assinatura, você precisa compor uma string a ser assinada, que chamamos de valor assinado neste guia. O valor assinado inclui parâmetros que descrevem o conteúdo que você está protegendo, o tempo de expiração do valor assinado e assim por diante.

Você usa o valor assinado ao criar uma string de assinatura. Para isso, você precisa compor os parâmetros da assinatura, como uma assinatura Ed25519 de chave assimétrica do valor assinado.

O Media CDN usa a assinatura composta final para ajudar a proteger seu conteúdo.

Formatos de assinatura compatíveis

O Media CDN oferece suporte aos seguintes formatos de solicitação assinada.

Formato	Comportamento	Exemplo
Parâmetros de consulta (URL exato)	URL exato, para conceder acesso a um URL específico.	Exato: https://media.example.com/content/manifest.m3u8? Expires=EXPIRATION &KeyName=KEY_NAME &Signature=SIGNATURE
Parâmetros de consulta (prefixo de URL)	Especificar um URLPrefix permite assinar um prefixo e anexar os mesmos parâmetros de consulta a vários URLs na geração de player ou manifesto.	O que assinar: URLPrefix=PREFIX &Expires=EXPIRATION &KeyName=KEY_NAME &Signature=SIGNATURE Substitua PREFIX pelo prefixo para conceder acesso, incluindo o esquema, o host e o caminho parcial.
Componente do caminho	Prefixo: permite o acesso a qualquer URL com um prefixo antes do "/edge-cache-token=[...]" componente. Isso permite que os URLs de manifesto relativos herdem automaticamente o componente de URL assinado ao buscar sub-recursos.	https://media.example.com/video/edge-cache-token=Expires=EXPIRATION &KeyName=KEY_NAME &Signature=SIGNATURE/manifest_12382131.m3u8
Cookie assinado	Prefixo: o cookie permite o acesso a qualquer URL com o prefixo especificado no valor assinado URLPrefix.	Edge-Cache-Cookie: URLPrefix=PREFIX: Expires=EXPIRATION: KeyName=KEY_NAME: Signature=SIGNATURE

Criar uma assinatura

Observação: os componentes de host e caminho do URL (ou URLPrefix) são usados para validar assinaturas. Ao fornecer um URL para qualquer uma dessas APIs programáticas, omita a porta. Em outras palavras, para um caminho como https://example.com:443/path, especifique o caminho como https://example.com/path.

1. Crie um valor assinado concatenando uma string que contenha os campos de assinatura obrigatórios e os campos de assinatura opcionais desejados.

   Se especificado, URLPrefix precisa vir primeiro, seguido por Expires, KeyName e, em seguida, todos os parâmetros opcionais.

   Separe cada campo e parâmetro com o seguinte:

   • Para cookies, use um caractere de dois pontos :.
   • Para parâmetros de consulta e componentes de caminho, use um caractere comercial &.

2. Assine o valor assinado com uma assinatura Ed25519.

3. Anexe um separador de campo (: ou &), seguido por Signature= e a assinatura Ed25519 ao final da string.

Criar um URL assinado

Os exemplos de código a seguir mostram como criar um URL assinado de maneira programática.

Go

Para autenticar no Media CDN, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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

Para autenticar no Media CDN, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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

Criar um prefixo de URL assinado

Os exemplos de código a seguir mostram como criar um prefixo de URL assinado de maneira programática.

Go

Para autenticar no Media CDN, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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

Para autenticar no Media CDN, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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

Criar um cookie de URL assinado

Os exemplos de código a seguir mostram como criar um cookie de URL assinado de maneira programática.

Go

Para autenticar no Media CDN, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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

Para autenticar no Media CDN, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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

Criar um componente de caminho assinado

Os exemplos de código a seguir mostram como criar um componente de caminho assinado de maneira programática.

Python

Para autenticar no Media CDN, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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

Campos de assinatura obrigatórios

Os campos a seguir são obrigatórios para todas as assinaturas:

• Expires
• KeyName
• Signature

Se houver parâmetros de consulta, eles precisarão ser agrupados como os últimos parâmetros no URL. A menos que especificado de outra forma, os nomes dos parâmetros e os valores deles diferenciam maiúsculas de minúsculas.

A tabela a seguir explica cada parâmetro:

Nome do campo	Parâmetros de assinatura	Valor assinado
Expires	Segundos inteiros que se passaram desde a época Unix (1970-01-01T00:00:00Z)	Expires=EXPIRATION_TIME, após o qual a assinatura não é mais válida.
KeyName	O nome do EdgeCacheKeyset usado para assinar esta solicitação. KeyName se refere a todo o conjunto de chaves, não a chaves individuais dentro do conjunto.	KeyName=EDGE_CACHE_KEYSET
Signature	Uma versão codificada em base64 da assinatura.	Não relevante

Campos de assinatura opcionais

Se houver parâmetros de consulta, eles precisarão ser agrupados como os últimos parâmetros no URL. A menos que especificado de outra forma, os nomes dos parâmetros e os valores deles diferenciam maiúsculas de minúsculas.

A tabela a seguir explica o nome e os detalhes de cada parâmetro para parâmetros de assinatura opcionais:

Nome do campo	Parâmetros de assinatura	Valor assinado
HeaderName	Um nome de campo de cabeçalho da solicitação nomeado que precisa estar presente na solicitação. Precisa estar em letras minúsculas quando assinado, porque os nomes dos campos de cabeçalho são diferenciam maiúsculas de minúsculas. O Media CDN converte o cabeçalho em letras minúsculas antes de validar a assinatura.	HeaderName=HEADER_NAME
HeaderValue	Um valor de campo de cabeçalho de solicitação nomeado que precisa estar presente na solicitação. Geralmente, é um ID de usuário ou outro identificador opaco. As solicitações com HeaderValue mas sem HeaderName são rejeitadas.	HeaderValue=HEADER_VALUE
IPRanges	Uma lista de até cinco endereços IPv4 e IPv6 no formato CIDR para os quais esse URL é válido no formato base64 seguro para a Web. Por exemplo, para especificar os intervalos de IP "192.6.13.13/32,193.5.64.135/32", especifique IPRanges=MTkyLjYuMTMuMTMvMzIsMTkzLjUuNjQuMTM1LzMy. Os IPRanges podem não ser úteis para incluir em assinaturas quando os clientes correm o risco de migrações de WAN ou casos em que o caminho de rede para o front-end do aplicativo é diferente do caminho de entrega. O Media CDN rejeita clientes com um HTTP 403 código quando eles se conectam com um endereço IP que não faz parte da solicitação assinada. A seguir estão os casos que podem resultar na rejeição de clientes pelo Media CDN com um código HTTP 403: Ambientes de pilha dupla (IPv4, IPv6) Migração de conexão (Wi-Fi para celular e celular para Wi-Fi) Redes móveis que usam NAT de gateway de operadora (CGNAT ou CGN) TCP de vários caminhos (MPTCP) Todos esses fatores podem contribuir para que um determinado cliente tenha um endereço IP não determinístico durante uma sessão de reprodução de vídeo. Se o endereço IP do cliente mudar depois que você tiver emitido o acesso e o cliente tentar fazer o download de um segmento de vídeo para o buffer de reprodução, ele vai receber um HTTP 403 do Media CDN.	IPRanges=BASE_64_IP_RANGES
URLPrefix	O prefixo de URL base64 (seguro para URL) para conceder acesso. Especificar um URLPrefix permite assinar um prefixo e anexar os mesmos parâmetros de consulta a vários URLs na geração de player ou manifesto. O URLPrefix é obrigatório ao usar o formato de cookie assinado.	URLPrefix=BASE_64_URL_PREFIX