Utilize cookies assinados

Esta página oferece uma vista geral dos cookies assinados e instruções para a respetiva utilização com a RFC na nuvem. Os cookies assinados dão acesso aos recursos por tempo limitado a um conjunto de ficheiros, independentemente de os utilizadores terem Contas Google.

Os cookies assinados são uma alternativa aos URLs assinados. Os cookies assinados protegem o acesso quando não é viável assinar separadamente dezenas ou centenas de URLs para cada utilizador na sua aplicação.

Os cookies assinados permitem-lhe fazer o seguinte:

• Autorizar um utilizador e fornecer-lhe um token por tempo limitado para aceder ao seu conteúdo protegido (em vez de assinar cada URL).
• Restrinja o acesso do utilizador a um prefixo de URL específico, como https://media.example.com/videos/, e conceda ao utilizador autorizado acesso apenas ao conteúdo protegido nesse prefixo de URL.
• Mantenha os URLs e os manifestos de multimédia inalterados, simplificando o pipeline de pacotes e melhorando a capacidade de colocação em cache.

Se, em alternativa, quiser restringir o acesso a URLs específicos, considere usar URLs assinados.

Antes de começar

Antes de usar cookies assinados, faça o seguinte:

• Certifique-se de que o Cloud CDN está ativado. Para obter instruções, consulte o artigo Usar o Cloud CDN. Pode configurar cookies assinados num back-end antes de ativar o Cloud CDN, mas não têm efeito até o Cloud CDN ser ativado.

• Se necessário, atualize para a versão mais recente da CLI Google Cloud:

  gcloud components update
  

Para uma vista geral, consulte o artigo URLs assinados e cookies assinados.

Configurar chaves de pedidos assinados

A criação de chaves para os seus URLs assinados ou cookies assinados requer vários passos, que são descritos nas secções seguintes.

Considerações de segurança

A RFC de multimédia na nuvem não valida os pedidos nas seguintes circunstâncias:

• O pedido não está assinado.
• O serviço de back-end ou o contentor de back-end do pedido não tem o Cloud CDN ativado.

Os pedidos assinados têm de ser sempre validados na origem antes de publicar a resposta. Isto deve-se ao facto de as origens poderem ser usadas para publicar uma combinação de conteúdo assinado e não assinado, e porque um cliente pode aceder diretamente à origem.

• A RFC não bloqueia pedidos sem um parâmetro de consulta Signature ou um cookie HTTP Cloud-CDN-Cookie. Rejeita pedidos com parâmetros de pedido inválidos (ou com um formato incorreto).
• Quando a sua aplicação deteta uma assinatura inválida, certifique-se de que a aplicação responde com um código de resposta HTTP 403 (Unauthorized). Os códigos de resposta HTTP 403 não são armazenáveis em cache.
• As respostas a pedidos assinados e não assinados são colocadas em cache separadamente, pelo que uma resposta bem-sucedida a um pedido assinado válido nunca é usada para publicar um pedido não assinado.
• Se a sua aplicação enviar um código de resposta memorizável em cache para um pedido inválido, os pedidos futuros válidos podem ser rejeitados incorretamente.

Para backends do Cloud Storage, certifique-se de que remove o acesso público para que o Cloud Storage possa rejeitar pedidos que não tenham uma assinatura válida.

A tabela seguinte resume o comportamento.

Crie chaves de pedidos assinados

Ativa o suporte para URLs assinados e cookies assinados do Cloud CDN através da criação de uma ou mais chaves num serviço de back-end, num contentor de back-end ou em ambos ativados para o Cloud CDN.

Para cada serviço de back-end ou contentor de back-end, pode criar e eliminar chaves conforme as suas necessidades de segurança. Cada back-end pode ter até três chaves configuradas em simultâneo. Sugerimos que rode periodicamente as chaves eliminando a mais antiga, adicionando uma nova chave e usando a nova chave ao assinar URLs ou cookies.

Pode usar o mesmo nome de chave em vários serviços de back-end e contentores de back-end, porque cada conjunto de chaves é independente dos outros. Os nomes das chaves podem ter até 63 carateres. Para atribuir nomes às chaves, use os carateres A-Z, a-z, 0-9, _ (sublinhado) e - (hífen).

Quando criar chaves, certifique-se de que as mantém seguras, uma vez que qualquer pessoa que tenha uma das suas chaves pode criar URLs assinados ou cookies assinados que o Cloud CDN aceita até que a chave seja eliminada do Cloud CDN. As chaves são armazenadas no computador onde gera os URLs assinados ou os cookies assinados. A RFC na nuvem também armazena as chaves para validar as assinaturas de pedidos.

Para manter as chaves secretas, os valores das chaves não são incluídos nas respostas a pedidos da API. Se perder uma chave, tem de criar uma nova.

Para criar uma chave de pedido assinada, siga estes passos.

head -c 16 /dev/urandom | base64 | tr +/ -_ > KEY_FILE_NAME

gcloud compute backend-services \
   add-signed-url-key BACKEND_NAME \
   --key-name KEY_NAME \
   --key-file KEY_FILE_NAME

gcloud compute backend-buckets \
   add-signed-url-key BACKEND_NAME \
   --key-name KEY_NAME \
   --key-file KEY_FILE_NAME

Configure as autorizações do Cloud Storage

Se usar o Cloud Storage e tiver restringido quem pode ler os objetos, tem de conceder autorização ao Cloud CDN para ler os objetos adicionando a conta de serviço do Cloud CDN às ACLs do Cloud Storage.

Não precisa de criar a conta de serviço. A conta de serviço é criada automaticamente na primeira vez que adiciona uma chave a um contentor de back-end num projeto.

Antes de executar o comando seguinte, adicione, pelo menos, uma chave a um bucket do back-end no seu projeto. Caso contrário, o comando falha com um erro porque a conta de serviço de preenchimento da cache da RFC na nuvem não é criada até adicionar uma ou mais chaves para o projeto.

gcloud storage buckets add-iam-policy-binding gs://BUCKET \
  --member=serviceAccount:service-PROJECT_NUMBER@cloud-cdn-fill. \
  --role=roles/storage.objectViewer

Substitua PROJECT_NUMBER pelo número do seu projeto e BUCKET pelo seu contentor de armazenamento.

A conta de serviço do Cloud CDN service-PROJECT_NUMBER@cloud-cdn-fill. não aparece na lista de contas de serviço no seu projeto. Isto deve-se ao facto de a conta de serviço do Cloud CDN ser propriedade do Cloud CDN e não do seu projeto.

Para mais informações sobre os números dos projetos, consulte o artigo Localize o ID do projeto e o número do projeto na Google Cloud documentação de ajuda da consola.

Personalize o tempo máximo da cache

A RFC na nuvem armazena em cache as respostas a pedidos assinados, independentemente do cabeçalho Cache-Control do back-end. O tempo máximo durante o qual as respostas podem ser colocadas em cache sem revalidação é definido pela flag signed-url-cache-max-age, que tem um valor predefinido de uma hora e pode ser modificada, conforme mostrado aqui.

Para definir o tempo máximo da cache para um serviço de back-end ou um contentor de back-end, execute um dos seguintes comandos:

gcloud compute backend-services update BACKEND_NAME
  --signed-url-cache-max-age MAX_AGE

gcloud compute backend-buckets update BACKEND_NAME
  --signed-url-cache-max-age MAX_AGE

Liste os nomes das chaves de pedidos assinados

Para listar as chaves num serviço de back-end ou num contentor de back-end, execute um dos seguintes comandos:

gcloud compute backend-services describe BACKEND_NAME

gcloud compute backend-buckets describe BACKEND_NAME

Elimine chaves de pedidos assinados

Quando os URLs assinados por uma chave específica já não devem ser respeitados, execute um dos seguintes comandos para eliminar essa chave do serviço de back-end ou do contentor de back-end:

gcloud compute backend-services \
   delete-signed-url-key BACKEND_NAME --key-name KEY_NAME

gcloud compute backend-buckets \
   delete-signed-url-key BACKEND_NAME --key-name KEY_NAME

Criar uma política

As políticas de cookies assinados são uma série de pares key-value (delimitados pelo caráter : ), semelhantes aos parâmetros de consulta usados num URL assinado. Para ver exemplos, consulte o artigo Emitir cookies para utilizadores.

As políticas representam os parâmetros para os quais um pedido é válido. As políticas são assinadas através de um código de autenticação de mensagens baseado em hash (HMAC) que o Cloud CDN valida em cada pedido.

Definir o formato e os campos da política

Existem quatro campos obrigatórios que tem de definir pela seguinte ordem:

• URLPrefix
• Expires
• KeyName
• Signature

Os pares key-value numa política de cookies assinada são sensíveis a maiúsculas e minúsculas.

URLPrefix

URLPrefix denota um prefixo de URL codificado em base64 seguro para URL que abrange todos os caminhos para os quais a assinatura deve ser válida.

Um URLPrefix codifica um esquema (http:// ou https://), um FQDN e um caminho opcional. Terminar o caminho com um / é opcional, mas recomendado. O prefixo não deve incluir parâmetros de consulta nem fragmentos, como ? ou #.

Por exemplo, https://media.example.com/videos corresponde a pedidos a ambos os seguintes:

• https://media.example.com/videos?video_id=138183&user_id=138138
• https://media.example.com/videos/137138595?quality=low

O caminho do prefixo é usado como uma substring de texto e não estritamente como um caminho de diretório. Por exemplo, o prefixo https://example.com/data concede acesso a ambos os seguintes elementos:

• /data/file1
• /database

Para evitar este erro, recomendamos que termine todos os prefixos com /, a menos que opte intencionalmente por terminar o prefixo com um nome de ficheiro parcial, como https://media.example.com/videos/123, para conceder acesso ao seguinte:

• /videos/123_chunk1
• /videos/123_chunk2
• /videos/123_chunkN

Se o URL pedido não corresponder ao URLPrefix, a RFC rejeita o pedido e devolve um erro HTTP 403 ao cliente.

Expira em

Expires tem de ser uma data/hora Unix (o número de segundos desde 1 de janeiro de 1970).

KeyName

KeyName é o nome da chave de uma chave criada em relação ao contentor de back-end ou ao serviço de back-end. Os nomes das chaves são sensíveis a maiúsculas e minúsculas.

Assinatura

Signature é a assinatura HMAC-SHA-1 codificada em base64 segura para URL dos campos que compõem a política de cookies. Esta validação é feita em cada pedido. Os pedidos com uma assinatura inválida são rejeitados com um erro HTTP 403.

Criar cookies assinados através de programação

Os exemplos de código seguintes demonstram como criar cookies assinados programaticamente.

import (
	"crypto/hmac"
	"crypto/sha1"
	"encoding/base64"
	"fmt"
	"io"
	"io/ioutil"
	"net/http"
	"os"
	"time"
)

// signCookie creates a signed cookie for an endpoint served by Cloud CDN.
//
// - urlPrefix must start with "https://" and should include the path prefix
// for which the cookie will authorize access to.
// - key should be in raw form (not base64url-encoded) which is
// 16-bytes long.
// - keyName must match a key added to the backend service or bucket.
func signCookie(urlPrefix, keyName string, key []byte, expiration time.Time) (string, error) {
	encodedURLPrefix := base64.URLEncoding.EncodeToString([]byte(urlPrefix))
	input := fmt.Sprintf("URLPrefix=%s:Expires=%d:KeyName=%s",
		encodedURLPrefix, expiration.Unix(), keyName)

	mac := hmac.New(sha1.New, key)
	mac.Write([]byte(input))
	sig := base64.URLEncoding.EncodeToString(mac.Sum(nil))

	signedValue := fmt.Sprintf("%s:Signature=%s",
		input,
		sig,
	)

	return signedValue, nil
}

import java.net.MalformedURLException;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.InvalidKeyException;
import java.security.Key;
import java.security.NoSuchAlgorithmException;
import java.time.ZonedDateTime;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class SignedCookies {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.

    // The name of the signing key must match a key added to the back end bucket or service.
    String keyName = "YOUR-KEY-NAME";
    // Path to the URL signing key uploaded to the backend service/bucket.
    String keyPath = "/path/to/key";
    // The Unix timestamp that the signed URL expires.
    long expirationTime = ZonedDateTime.now().plusDays(1).toEpochSecond();
    // URL prefix to sign as a string. URL prefix must start with either "http://" or "https://"
    // and must not include query parameters.
    String urlPrefix = "https://media.example.com/videos/";

    // Read the key as a base64 url-safe encoded string, then convert to byte array.
    // Key used in signing must be in raw form (not base64url-encoded).
    String base64String = new String(Files.readAllBytes(Paths.get(keyPath)),
        StandardCharsets.UTF_8);
    byte[] keyBytes = Base64.getUrlDecoder().decode(base64String);

    // Create signed cookie from policy.
    String signedCookie = signCookie(urlPrefix, keyBytes, keyName, expirationTime);
    System.out.println(signedCookie);
  }

  // Creates a signed cookie for the specified policy.
  public static String signCookie(String urlPrefix, byte[] key, String keyName,
      long expirationTime)
      throws InvalidKeyException, NoSuchAlgorithmException {

    // Validate input URL prefix.
    try {
      URL validatedUrlPrefix = new URL(urlPrefix);
      if (!validatedUrlPrefix.getProtocol().startsWith("http")) {
        throw new IllegalArgumentException(
            "urlPrefix must start with either http:// or https://: " + urlPrefix);
      }
      if (validatedUrlPrefix.getQuery() != null) {
        throw new IllegalArgumentException("urlPrefix must not include query params: " + urlPrefix);
      }
    } catch (MalformedURLException e) {
      throw new IllegalArgumentException(
          "urlPrefix malformed: " + urlPrefix);
    }

    String encodedUrlPrefix = Base64.getUrlEncoder().encodeToString(urlPrefix.getBytes(
        StandardCharsets.UTF_8));
    String policyToSign = String.format("URLPrefix=%s:Expires=%d:KeyName=%s", encodedUrlPrefix,
        expirationTime, keyName);

    String signature = getSignatureForUrl(key, policyToSign);
    return String.format("Cloud-CDN-Cookie=%s:Signature=%s", policyToSign, signature);
  }

  // Creates signature for input string with private key.
  private static String getSignatureForUrl(byte[] privateKey, String input)
      throws InvalidKeyException, NoSuchAlgorithmException {

    final String algorithm = "HmacSHA1";
    final int offset = 0;
    Key key = new SecretKeySpec(privateKey, offset, privateKey.length, algorithm);
    Mac mac = Mac.getInstance(algorithm);
    mac.init(key);
    return Base64.getUrlEncoder()
        .encodeToString(mac.doFinal(input.getBytes(StandardCharsets.UTF_8)));
  }
}

import argparse
import base64
from datetime import datetime, timezone
import hashlib
import hmac
from urllib.parse import parse_qs, urlsplit


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

    Args:
        url_prefix: URL prefix to sign.
        key_name: name of the signing key.
        base64_key: signing key as a base64 encoded string.
        expiration_time: expiration time as time-zone aware datetime.

    Returns:
        Returns the Cloud-CDN-Cookie value based on the specified configuration.
    """
    encoded_url_prefix = base64.urlsafe_b64encode(
        url_prefix.strip().encode("utf-8")
    ).decode("utf-8")
    epoch = datetime.fromtimestamp(0, timezone.utc)
    expiration_timestamp = int((expiration_time - epoch).total_seconds())
    decoded_key = base64.urlsafe_b64decode(base64_key)

    policy = f"URLPrefix={encoded_url_prefix}:Expires={expiration_timestamp}:KeyName={key_name}"

    digest = hmac.new(decoded_key, policy.encode("utf-8"), hashlib.sha1).digest()
    signature = base64.urlsafe_b64encode(digest).decode("utf-8")

    signed_policy = f"Cloud-CDN-Cookie={policy}:Signature={signature}"

    return signed_policy

Validar cookies assinados

O processo de validação de um cookie assinado é essencialmente o mesmo que o de geração de um cookie assinado. Por exemplo, suponha que quer validar o seguinte cabeçalho de cookie assinado:

Cookie: Cloud-CDN-Cookie=URLPrefix=URL_PREFIX:Expires=EXPIRATION:KeyName=KEY_NAME:Signature=SIGNATURE; Domain=media.example.com; Path=/; Expires=Tue, 20 Aug 2019 02:26:49 GMT; HttpOnly

Pode usar a chave secreta com o nome KEY_NAME para gerar independentemente a assinatura e, em seguida, validar se corresponde a SIGNATURE.

Emitir cookies para utilizadores

A sua aplicação tem de gerar e emitir a cada utilizador (cliente) um único cookie HTTP que contenha uma política corretamente assinada:

1. Crie um signatário HMAC-SHA-1 no código da sua aplicação.

2. Assine a política com a chave escolhida, tendo em atenção o nome da chave que adicionou ao back-end, como mySigningKey.

3. Crie uma política de cookies com o seguinte formato, tendo em atenção que o nome e o valor são sensíveis a maiúsculas e minúsculas:

   Name: Cloud-CDN-Cookie
   Value: URLPrefix=$BASE64URLECNODEDURLORPREFIX:Expires=$TIMESTAMP:KeyName=$KEYNAME:Signature=$BASE64URLENCODEDHMAC
   

   Exemplo de cabeçalho Set-Cookie:

   Set-Cookie: Cloud-CDN-Cookie=URLPrefix=aHR0cHM6Ly9tZWRpYS5leGFtcGxlLmNvbS92aWRlb3Mv:Expires=1566268009:KeyName=mySigningKey:Signature=0W2xlMlQykL2TG59UZnnHzkxoaw=; Domain=media.example.com; Path=/; Expires=Tue, 20 Aug 2019 02:26:49 GMT; HttpOnly
   

   Os atributos Domain e Path no cookie determinam se o cliente envia o cookie para a RFC na nuvem.

Recomendações e requisitos

• Defina explicitamente os atributos Domain e Path para corresponderem ao prefixo do domínio e do caminho a partir do qual pretende publicar o seu conteúdo protegido, que pode diferir do domínio e do caminho onde o cookie é emitido (example.com em comparação com media.example.com ou /browse em comparação com /videos).

• Certifique-se de que tem apenas um cookie com um determinado nome para o mesmo Domain e Path.

• Certifique-se de que não está a emitir cookies em conflito, uma vez que tal pode impedir o acesso a conteúdo noutras sessões do navegador (janelas ou separadores).

• Defina as flags Secure e HttpOnly, quando aplicável. Secure garante que o cookie é enviado apenas através de ligações HTTPS. HttpOnly impede que o cookie fique disponível para JavaScript.

• Os atributos de cookie Expires e Max-Age são opcionais. Se os omitir, o cookie existe enquanto a sessão do navegador (separador, janela) existir.

• Num preenchimento da cache ou numa falha da cache, o cookie assinado é transmitido à origem definida no serviço de back-end. Certifique-se de que está a validar o valor do cookie assinado em cada pedido antes de publicar conteúdo.