Richieste canoniche

Le richieste canoniche definiscono gli elementi di una richiesta che un utente deve includere quando invia richieste autenticate con firma V4, ad esempio URL firmati, a Cloud Storage.

Panoramica

Una richiesta canonica è una stringa che rappresenta una richiesta HTTP specifica a Cloud Storage. Utilizza una richiesta canonica insieme a una chiave cryptographica, ad esempio una chiave RSA, per creare una firma che viene poi inclusa nella richiesta effettiva come autenticazione.

Una richiesta canonica include informazioni come il verbo HTTP, i parametri della stringa di query e le intestazioni che dovrebbero essere utilizzate nella richiesta effettiva, nonché l'oggetto, il bucket o un'altra risorsa da richiedere.

Una richiesta canonica assicura che, quando Cloud Storage riceve richiesta, può calcolare la stessa firma che hai calcolato. Se la tua versione e la versione calcolata da Cloud Storage non corrispondono, la richiesta non va a buon fine.

Strutturazione

Le richieste canoniche hanno la seguente struttura, incluso l'utilizzo di a capo tra ogni elemento:

HTTP_VERB
PATH_TO_RESOURCE
CANONICAL_QUERY_STRING
CANONICAL_HEADERS

SIGNED_HEADERS
PAYLOAD

Verbi HTTP

Le richieste firmate possono utilizzare i seguenti verbi HTTP, che devono essere specificati come della richiesta canonica:

  • DELETE
  • GET
  • HEAD
  • POST1
  • PUT

1 Gli URL firmati possono essere utilizzati solo per le richieste POST che avviano un caricamento riassumibile. Per saperne di più, consulta Utilizzare URL firmati con caricamenti ripristinabili informazioni.

Percorso della risorsa

Le richieste canoniche includono il percorso della risorsa a cui si applica la richiesta. Il percorso della risorsa è tutto ciò che segue il nome host, ma precede qualsiasi stringa di query.

Ad esempio, se l'URL di Cloud Storage è https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg, il percorso della risorsa è /example-bucket/cat-pics/tabby.jpeg.

Se usi un URL di Cloud Storage alternativo come https://example-bucket.storage.googleapis.com/cat-pics/tabby.jpeg il percorso della risorsa sarà /cat-pics/tabby.jpeg.

Per ulteriori endpoint URL che possono essere utilizzati con gli URL firmati, consulta Endpoint per richieste API XML.

Quando definisci il percorso della risorsa, devi codificare in percentuale i seguenti caratteri riservati: ?=!#$&'()*+,:;@[]" qualsiasi altra codifica in percentuale utilizzata nell'URL deve essere inclusa anche nel percorso della risorsa.

Stringa di query canonica

Le richieste canoniche specificano ogni parametro della stringa di query che verrà successivamente incluso in qualsiasi richiesta firmata che utilizza la firma pertinente, con l'eccezione del parametro della stringa di query X-Goog-Signature o X-Amz-Signature. La stringa di query specificata nella richiesta canonica è chiamata stringa di query canonica

La stringa di query è tutto ciò che segue il punto interrogativo (?) alla fine del percorso della risorsa.

Ad esempio, se l'URL di Cloud Storage è https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?generation=1360887697105000&userProject=my-project, la stringa di query è generation=1360887697105000&userProject=my-project.

Quando viene creata la stringa di query canonica:

  • I parametri nella stringa di query devono essere ordinati per nome utilizzando un l'ordinamento grammaticale per valore in punti di codice.

  • Ogni parametro nella stringa di query deve essere separato da &.

  • Se la stringa di query canonica è vuota, questa parte della richiesta canonica complessiva è solo una nuova riga (\n).

Parametri stringa di query obbligatori

La maggior parte dei parametri della stringa di query viene aggiunta in base alle esigenze, ma i seguenti devono essere inclusi nella richiesta canonica se intendi utilizzarla per creare un URL firmato:

  • X-Goog-Algorithm: l'algoritmo che utilizzerai per firmare l'URL. I valori validi sono GOOG4-RSA-SHA256 e GOOG4-HMAC-SHA256.
  • X-Goog-Credential: le credenziali che utilizzerai per firmare l'URL. Le credenziali sono costituite da un autorizzatore e da un ambito delle credenziali specificato nel formato: AUTHORIZER%2FCREDENTIAL_SCOPE. La autorizzato può essere un nome account di servizio o un ID di accesso alla chiave HMAC.
  • X-Goog-Date: la data e l'ora in cui l'URL firmato diventa utilizzabile, nel Formato di base ISO 8601 YYYYMMDD'T'HHMMSS'Z'.
  • X-Goog-Expires: la durata dell'URL firmato, misurata in secondi da X-Goog-Date. Il valore di scadenza più lungo è 604.800 secondi (7 giorni).
  • X-Goog-SignedHeaders: un elenco di nomi delle intestazioni separati da punto e virgola definita nella richiesta canonica. Sono note anche come intestazioni firmate. host deve essere uno dei nomi delle intestazioni.

Questi parametri della stringa di query in seguito devono essere utilizzati nell'URL firmato insieme al parametro della stringa di query X-Goog-Signature, che contiene la firma che autentica la richiesta.

Intestazioni canoniche

Le richieste canoniche includono tutte le intestazioni che devono essere successivamente incluse nelle richieste firmate che utilizzano la firma pertinente. Tuttavia, queste richieste firmate possono includere intestazioni aggiuntive non specificate nella richiesta canonica, tranne che per quanto indicato nelle intestazioni obbligatorie. Intestazioni specificate nella richiesta canonica sono chiamate intestazioni canoniche.

Le intestazioni canoniche possono includere intestazioni personalizzate e intestazioni di estensione che iniziano con x-goog-.

Quando specifichi le intestazioni canoniche, tieni presente quanto segue:

  • Rendi tutti i nomi delle intestazioni in minuscolo.
  • Ordina tutte le intestazioni per nome utilizzando un ordinamento lessicografico per punto di codice valore.
  • Separa ogni intestazione con un a capo (\n).
  • Elimina i nomi di intestazione duplicati creando un nome di intestazione con un elenco di valori separati da virgola. Assicurati che non ci siano spazi tra i valori e che l'ordine dell'elenco separato da virgole corrisponda all'ordine in cui le intestazioni vengono visualizzate nella richiesta. Per ulteriori informazioni, consulta RFC 7230 sezione 3.2.
  • Sostituisci eventuali spazi vuoti pieghevoli o nuove righe (CRLF o LF) con un singolo spazio. Per ulteriori informazioni su come comprimere lo spazio vuoto, RFC 7230, sezione 3.2.4..

  • Rimuovi gli spazi vuoti intorno al due punti visualizzato dopo il nome dell'intestazione.

    Ad esempio, se utilizzi l'intestazione personalizzata x-goog-acl: private senza rimuoverla lo spazio dopo i due punti restituisce un errore 403 Forbidden, perché la richiesta di firma calcolata non corrisponde alla firma Cloud Storage esegue i calcoli.

Esempio

Se hai il seguente insieme di intestazioni:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

La struttura delle intestazioni canoniche nella richiesta canonica sarebbe:

content-type:text/plain
host:storage.googleapis.com
x-goog-meta-reviewer:jane,john

Intestazioni canoniche obbligatorie

La maggior parte delle intestazioni, ad esempio content-type, viene aggiunta secondo necessità, ma quanto segue e devono sempre essere definite nelle intestazioni canoniche, se intendi utilizzare nella richiesta firmata:

  • host: l'URI utilizzato per accedere a Cloud Storage.
  • Intestazioni con prefisso x-goog-. L'unica intestazione di questo tipo che è facoltativa da includere come intestazione canonica è x-goog-content-sha256.
  • Intestazioni con prefisso x-amz-. L'unica intestazione di questo tipo che è facoltativa includi come intestazione canonica è x-amz-content-sha256.

Intestazioni firmate

Un'intestazione firmata è la parte relativa al nome di un'intestazione canonica.

Per creare l'elenco delle intestazioni firmate, converti tutti i nomi delle intestazioni in lettere minuscole, ordina specificandoli in base al codice di carattere e utilizza un punto e virgola (;) per separarli.

Esempio

Se hai il seguente insieme di intestazioni:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

La costruzione delle intestazioni firmate nella richiesta canonica sarà:

content-type;host;x-goog-meta-reviewer

Payload

  • Se la tua richiesta canonica verrà utilizzata per creare un URL firmato, questo valore dovrebbe essere la stringa UNSIGNED-PAYLOAD.

  • Se la richiesta canonica verrà utilizzata all'interno di una richiesta che utilizza un'intestazioneAuthorization:

    • Utilizza UNSIGNED-PAYLOAD se vuoi consentire payload arbitrari all'interno della richiesta. Quando si avvia una richiesta di caricamento ripristinabile, viene ti consigliamo di utilizzare UNSIGNED-PAYLOAD. Qualsiasi valore sha256 incluso viene ignorato per i caricamenti ripristinabili.

    • Se vuoi consentire solo un payload specifico, questo valore deve essere un hash SHA-256 con codifica esadecimale in minuscolo del payload desiderato. Per richiedere un payload vuoto, utilizza una stringa vuota come input per la funzione hash. Un esempio di payload sottoposto ad hashing (in questo caso un payload vuoto) è:

      e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Esempio

Di seguito è riportato un esempio di richiesta canonica formattata correttamente, con le nuove righe visualizzate come nuove righe effettive e non \n:

GET
/example-bucket/tabby.jpeg

host:storage.googleapis.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20190301T190859Z

host;x-amz-content-sha256;x-amz-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Passaggi successivi