Utilizzare i cookie firmati

Questa pagina fornisce una panoramica dei cookie firmati e le istruzioni per utilizzarli con Cloud CDN. I cookie firmati forniscono l'accesso alle risorse a tempo limitato a un insieme di file, indipendentemente dal fatto che gli utenti abbiano Account Google.

I cookie firmati sono un'alternativa agli URL firmati. I cookie firmati proteggono l'accesso quando non è possibile firmare separatamente decine o centinaia di URL per ogni utente nella tua applicazione.

I cookie firmati ti consentono di:

• Autorizza un utente e fornisci un token a tempo limitato per accedere ai tuoi contenuti protetti (anziché firmare ogni URL).
• Limita l'accesso dell'utente a un prefisso URL specifico, ad esempiohttps://media.example.com/videos/, e concedi all'utente autorizzato l'accesso ai contenuti protetti solo all'interno di quel prefisso URL.
• Mantieni invariati gli URL e i manifest dei contenuti multimediali, semplifica la pipeline di imballaggio e migliora la memorizzazione nella cache.

Se invece vuoi limitare l'accesso a URL specifici, ti consigliamo di utilizzare URL firmati.

Prima di iniziare

Prima di utilizzare i cookie firmati, segui questi passaggi:

• Assicurati che Cloud CDN sia abilitato. Per istruzioni, consulta Utilizzare Cloud CDN. Puoi configurare i cookie firmati su un backend prima di attivare Cloud CDN, ma non avranno alcun effetto finché Cloud CDN non sarà attivato.

• Se necessario, esegui l'aggiornamento alla versione più recente di Google Cloud CLI:

  gcloud components update
  

Per una panoramica, consulta URL e cookie firmati.

Configurazione delle chiavi per le richieste firmate

La creazione di chiavi per gli URL o i cookie firmati richiede diversi passaggi, descritti nelle sezioni seguenti.

Considerazioni sulla sicurezza

Cloud CDN non convalida le richieste nelle seguenti circostanze:

• La richiesta non è firmata.
• Il servizio di backend o il bucket di backend per la richiesta non ha attivato Cloud CDN.

Le richieste firmate devono sempre essere convalidate all'origine prima di inviare la risposta. Questo perché le origini possono essere utilizzate per pubblicare una combinazione di contenuti firmati e non firmati e perché un client potrebbe accedere direttamente all'origine.

• Cloud CDN non blocca le richieste senza un parametro di query Signature o un cookie HTTP Cloud-CDN-Cookie. Rifiuta le richieste con parametri non validi (o con formato non corretto).
• Quando l'applicazione rileva una firma non valida, assicurati che risponda con un codice di risposta HTTP 403 (Unauthorized). I codici di risposta HTTP 403 non sono memorizzabili nella cache.
• Le risposte alle richieste firmate e non firmate vengono memorizzate nella cache separatamente, pertanto una risposta positiva a una richiesta firmata valida non viene mai utilizzata per soddisfare una richiesta non firmata.
• Se la tua applicazione invia un codice di risposta memorizzabile in cache a una richiesta non valida, le richieste future valide potrebbero essere rifiutate erroneamente.

Per i backend Cloud Storage, assicurati di rimuovere l'accesso pubblico, in modo che Cloud Storage possa rifiutare le richieste per le quali manca una firma valida.

La seguente tabella riassume il comportamento.

Creare chiavi di richiesta firmate

Per attivare il supporto degli URL e dei cookie firmati di Cloud CDN, crea una o più chiavi su un servizio di backend, un bucket di backend o entrambi abilitati per Cloud CDN.

Per ogni servizio di backend o bucket di backend, puoi creare ed eliminare le chiavi in base alle tue esigenze di sicurezza. Ogni backend può avere fino a tre chiavi configurate contemporaneamente. Ti consigliamo di ruotare periodicamente le chiavi eliminando la più vecchia, aggiungendo una nuova chiave e utilizzandola per firmare gli URL o i cookie.

Puoi utilizzare lo stesso nome della chiave in più servizi e bucket di backend perché ogni insieme di chiavi è indipendente dagli altri. I nomi delle chiavi possono contenere fino a 63 caratteri. Per assegnare un nome alle chiavi, utilizza i caratteri A-Z, a-z, 0-9, _ (trattino basso) e - (trattino).

Quando crei le chiavi, assicurati di mantenerle al sicuro, perché chiunque abbia una delle tue chiavi può creare URL o cookie firmati accettati da Cloud CDN finché la chiave non viene eliminata da Cloud CDN. Le chiavi vengono archiviate sul computer su cui generi gli URL o i cookie firmati. Cloud CDN memorizza anche le chiavi per verificare le firme delle richieste.

Per mantenere le chiavi segrete, i valori delle chiavi non sono inclusi nelle risposte alle richieste dell'API. Se perdi una chiave, devi crearne una nuova.

Per creare una chiave di richiesta firmata:

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

Configura le autorizzazioni Cloud Storage

Se utilizzi Cloud Storage e hai limitato chi può leggere gli oggetti, devi concedere a Cloud CDN l'autorizzazione per leggere gli oggetti aggiungendo l'account di servizio Cloud CDN ai criteri ACL di Cloud Storage.

Non è necessario creare l'account di servizio. L'account di servizio viene creato automaticamente la prima volta che aggiungi una chiave a un bucket di backend in un progetto.

Prima di eseguire il comando seguente, aggiungi almeno una chiave a un bucket di backend nel tuo progetto. In caso contrario, il comando non va a buon fine a causa di un errore perché il account di servizio di compilazione della cache Cloud CDN non viene creato finché non aggiungi una o più chiavi per il progetto.

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

Sostituisci PROJECT_NUM con il numero del progetto e BUCKET con il bucket di archiviazione.

L'account di servizio Cloud CDN service-PROJECT_NUM@cloud-cdn-fill.iam.gserviceaccount.com non è presente nell'elenco degli account di servizio del tuo progetto. Questo accade perché l'account di servizio Cloud CDN è di proprietà di Cloud CDN, non del tuo progetto.

Per ulteriori informazioni sui numeri di progetto, consulta Trovare l'ID progetto e il numero di progetto nella documentazione della guida della Google Cloud console.

Personalizzare il tempo massimo della cache

Cloud CDN memorizza nella cache le risposte per le richieste firmate indipendentemente dall'intestazione Cache-Control del backend. Il tempo massimo per cui le risposte possono essere memorizzate nella cache senza essere convalidate nuovamente è impostato dal flag signed-url-cache-max-age, che per impostazione predefinita è pari a un'ora e può essere modificato come mostrato qui.

Per impostare il tempo massimo della cache per un servizio o un bucket di backend, esegui uno dei seguenti comandi:

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

Elenca i nomi delle chiavi per le richieste firmate

Per elencare le chiavi in un servizio o un bucket di backend, esegui uno dei seguenti comandi:

gcloud compute backend-services describe BACKEND_NAME

gcloud compute backend-buckets describe BACKEND_NAME

Eliminare le chiavi per le richieste firmate

Quando non è più necessario rispettare gli URL firmati da una determinata chiave, esegui uno dei seguenti comandi per eliminare la chiave dal servizio di backend o dal bucket di backend:

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

Creazione di un criterio

I criteri dei cookie firmati sono una serie di coppie key-value (delimitate dal carattere :), simili ai parametri di ricerca utilizzati in un URL firmato. Per esempi, vedi Emettere cookie per gli utenti.

I criteri rappresentano i parametri per i quali una richiesta è valida. I criteri vengono firmati utilizzando un codice HMAC (Hash-based Message Authentication Code) che Cloud CDN convalida a ogni richiesta.

Definizione del formato e dei campi dei criteri

Esistono quattro campi obbligatori che devi definire nel seguente ordine:

• URLPrefix
• Expires
• KeyName
• Signature

Le coppie key-value in un criterio dei cookie firmati sono sensibili alle maiuscole.

URLPrefix

URLPrefix indica un prefisso URL con codifica Base64 sicuro per gli URL che comprende tutti i percorsi per i quali la firma deve essere valida.

Un URLPrefix codifica uno schema (http:// o https://), un FQDN e un percorso facoltativo. Terminare il percorso con un / è facoltativo, ma consigliato. Il prefisso non deve includere parametri di ricerca o frammenti come ? o #.

Ad esempio, https://media.example.com/videos corrisponde alle richieste per entrambi i seguenti elementi:

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

Il percorso del prefisso viene utilizzato come sottostringa di testo, non come percorso di directory. Ad esempio, il prefisso https://example.com/data concede l'accesso a entrambi i seguenti elementi:

• /data/file1
• /database

Per evitare questo errore, ti consigliamo di terminare tutti i prefissi con /, a meno che non scelga intenzionalmente di terminare il prefisso con un nome file parziale come https://media.example.com/videos/123 per concedere l'accesso a quanto segue:

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

Se l'URL richiesto non corrisponde a URLPrefix, Cloud CDN rifiuta la richiesta e restituisce un errore HTTP 403 al client.

Scadenza

Expires deve essere un timestamp Unix (il numero di secondi dal 1° gennaio 1970).

KeyName

KeyName è il nome della chiave creata per il bucket di backend o per il servizio di backend. I nomi delle chiavi sono sensibili alle maiuscole.

Firma

Signature è la firma HMAC-SHA-1 con codifica Base64 sicura per gli URL dei campi che costituiscono le norme relative ai cookie. Questo viene convalidato a ogni richiesta; le richieste con una firma non valida vengono rifiutate con un errore HTTP 403.

Creazione di cookie firmati in modo programmatico

I seguenti esempi di codice mostrano come creare programmaticamente cookie firmati.

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

Convalida dei cookie firmati

La procedura di convalida di un cookie firmato è essenzialmente la stessa della generazione di un cookie firmato. Ad esempio, supponiamo che tu voglia convalidare la seguente intestazione del cookie firmata:

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

Puoi utilizzare la chiave segreta denominata da KEY_NAME per generare in modo indipendente la firma e poi convalidarne la corrispondenza con SIGNATURE.

Emissione di cookie agli utenti

L'applicazione deve generare ed emettere per ogni utente (client) un singolo cookie HTTP contenente un criterio firmato correttamente:

1. Crea un firmatario HMAC-SHA-1 nel codice dell'applicazione.

2. Firma il criterio utilizzando la chiave scelta, prendendo nota del nome della chiave che hai aggiunto al backend, ad esempio mySigningKey.

3. Crea un criterio relativo ai cookie con il seguente formato, tenendo presente che sia il nome che il valore sono sensibili alle maiuscole:

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

   Intestazione Set-Cookie di esempio:

   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
   

   Gli attributi Domain e Path nel cookie determinano se il client invia il cookie a Cloud CDN.

Consigli e requisiti

• Imposta esplicitamente gli attributi Domain e Path in modo che corrispondano al prefisso del dominio e del percorso da cui intendi pubblicare i contenuti protetti, che potrebbero essere diversi dal dominio e dal percorso in cui viene emesso il cookie (example.com rispetto a media.example.com o /browse rispetto a /videos).

• Assicurati di avere un solo cookie con un determinato nome per gli stessi Domain e Path.

• Assicurati di non emettere cookie in conflitto, in quanto ciò potrebbe impedire l'accesso ai contenuti in altre sessioni del browser (finestre o schede).

• Imposta i flag Secure e HttpOnly, se applicabili. Secure garantisce che il cookie venga inviato solo tramite connessioni HTTPS. HttpOnly impedisce di rendere il cookie disponibile a JavaScript.

• Gli attributi dei cookie Expires e Max-Age sono facoltativi. Se li ometti, il cookie esiste finché esiste la sessione del browser (scheda, finestra).

• In caso di riempimento della cache o fallimento della cache, il cookie firmato viene trasmesso all'origine definita nel servizio di backend. Assicurati di convalidare il valore del cookie firmato su ogni richiesta prima di pubblicare i contenuti.