Firme

Le firme sono un metodo per autenticare le richieste inviate API XML di Cloud Storage. Le firme vengono utilizzate, ad esempio, quando si lavora con URL firmati o moduli HTML. Questa pagina si applica alle firme create utilizzando la procedura di firma V4, che è la procedura consigliata per la creazione delle firme.

Le firme sono specifiche dell'API XML di Cloud Storage e sono diverse dai token OAuth 2.0. I token OAuth 2.0 possono essere utilizzati anche con l'API XML e sono applicabili in modo più generale ai servizi Google Cloud, inclusa l'API JSON di Cloud Storage.

Panoramica

Signatures fornisce sia l'identità che l'autenticazione avanzata, il che garantisce che le richieste a Cloud Storage vengano elaborate utilizzando l'autorità di un account specifico. Le firme consentono di ottenere questa autenticazione senza rivelare le informazioni sulle chiavi sensibili, chiamate secret o chiavi private, associate all'account.

Quando effettui una richiesta con una firma, Cloud Storage utilizza la sua copia delle informazioni chiave per calcolare una firma equivalente per la richiesta. Se la firma inclusa nella richiesta corrisponde a quella calcolata da Cloud Storage, Cloud Storage sa che la firma è stata creata utilizzando la chiave privata o segreta pertinente.

In Cloud Storage, le firme devono essere utilizzate quando si lavora con:

Inoltre, le firme possono essere utilizzate nell'intestazione Authorization delle richieste dell'API XML.

L'utilizzo delle firme nelle richieste dirette è utile quando semplici migrazioni da Amazon S3; tuttavia, i valori consigliati il flusso di autenticazione per le richieste dirette consiste nell'utilizzare i token OAuth 2.0.

Strutturazione

I componenti e la procedura per creare una firma dipendono da come la utilizzerai e dalla chiave di autenticazione con cui stai lavorando. In generale, una firma è composta da due componenti: la chiave di firma e le informazioni sulla richiesta. Tu applicare un algoritmo di firma a questi due componenti per creare firma. La tabella seguente riassume i diversi casi d'uso per le firme e i componenti necessari in ogni caso per creare la firma:

Caso d'uso Chiave di firma Richiedi informazioni
Modulo HTML con una chiave RSA Utilizzare direttamente la chiave privata RSA Documento delle norme con codifica Base64
Modulo HTML con una chiave HMAC Dedurre dal secret della chiave HMAC Documento dei criteri con codifica Base64
URL firmato o intestazione firmata con una chiave RSA Usa direttamente la chiave privata RSA Stringa da firmare
URL firmato o intestazione firmata con una chiave HMAC. Dedurre dal secret della chiave HMAC Da stringa a segno

Da stringa a segno

Una stringa da firmare include meta informazioni sulla richiesta e un hash della richiesta canonica che vuoi firmare.

Strutturazione

Una stringa da firmare deve essere codificata in UTF-8 e avere la seguente struttura, incluso l'uso di interruzioni di riga tra ogni elemento:

SIGNING_ALGORITHM
ACTIVE_DATETIME
CREDENTIAL_SCOPE
HASHED_CANONICAL_REQUEST

Algoritmo di firma

Il valore utilizzato per SIGNING_ALGORITHM dipende dal tipo di chiave e dalle estensioni utilizzate per le intestazioni o i parametri di query:

Caso d'uso Valore per SIGNING_ALGORITHM
x-goog-* estensione e una chiave RSA GOOG4-RSA-SHA256
x-goog-* e una chiave HMAC GOOG4-HMAC-SHA256
x-amz-* e una chiave HMAC AWS4-HMAC-SHA256

Data/ora attiva

La data e l'ora in cui è possibile utilizzare la firma nel formato ISO 8601 formato di base YYYYMMDD'T'HHMMSS'Z'.

  • Per gli URL firmati, è possibile usare la firma 15 minuti prima dell'attivazione fino alla scadenza specificata. La data/ora attiva deve corrispondere il parametro della stringa di query X-Goog-Date dell'URL firmato e deve utilizzare lo stesso giorno specificato nell'ambito delle credenziali.

  • Per le richieste con intestazioni firmate, la firma è utilizzabile 15 minuti prima della data e dell'ora attive fino a 15 minuti dopo la data e l'ora attive. La data e l'ora attive devono corrispondere all'intestazione x-goog-date della richiesta che utilizza la firma e devono utilizzare lo stesso giorno specificato nell'ambito delle credenziali.

Ambito delle credenziali

L'ambito delle credenziali per la richiesta.

Hash della richiesta canonica

L'hash SHA-256 esadecimale codificato di una richiesta canonica. Utilizza una funzione di hashing SHA-256 per creare un valore hash della richiesta canonica. La tua programmazione deve avere una libreria per la creazione di hash SHA-256. Un valore di hashing di esempio è simile al seguente:

436b7ce722d03b17d3f790255dd57904f7ed61c02ac5127a0ca8063877e4e42c

Esempio

Di seguito è riportato un esempio di stringa-to-sign nel formato corretto, con nuove righe mostrate come nuove righe e non \n:

GOOG4-RSA-SHA256
20191201T190859Z
20191201/us-central1/storage/goog4_request
54f3076005db23fbecdb409d25c0ccb9fb8b5e24c59f12634654c0be13459af0

Documento relativo alle norme

Un documento dei criteri definisce quali utenti hanno accesso ai Il modulo HTML può essere caricato su Cloud Storage. Un documento di criteri fornisce l'autorizzazione per garantire che il modulo HTML possa caricare file nel bucket di destinazione. Puoi utilizzare la documentazione relativa alle norme per consentire ai visitatori di un sito web di caricare contenuti in Cloud Storage.

Un documento di criteri viene creato in JavaScript Object Notation (JSON). La il documento delle norme deve avere codifica sia UTF-8 che Base64. Un documento sulle norme contiene le seguenti sezioni:

Voce Descrizione
expiration La data di scadenza del documento delle norme, nel formato di base ISO 8601 YYYYMMDD'T'HHMMSS'Z'. Un documento di criteri scaduto causa l'interruzione del modulo HTML.
conditions Un array di condizioni che ogni caricamento deve soddisfare.

La sezione conditions deve includere:

  • Un'istruzione di condizione per ogni campo utilizzato nel modulo HTML; tranne che per i campi x-goog-signature, file e policy.

  • Un'istruzione di condizione "bucket", anche se non utilizzi il campo bucket in del modulo HTML.

Se vuoi utilizzare più istruzioni di condizione per lo stesso campo, devi crea un modulo HTML separato per ciascuno. Nelle dichiarazioni delle condizioni puoi utilizzare tre tipi di condizioni:

  • Corrispondenza esatta

    Esegue la corrispondenza esatta di un campo. Il valore utilizzato nel campo specificato del modulo HTML deve corrispondere al valore impostato in questa condizione. Imposta questa condizione utilizzando uno dei seguenti stili di sintassi:

    {"field" : "value"}
     
    ["eq", "$field", "value"]

    Tutti i campi del modulo HTML validi, ad eccezione di Content-Length, possono utilizzare la corrispondenza esatta.

  • Inizia con

    Se il valore di un campo deve iniziare con un determinato prefisso, utilizza la condizione starts-with con la seguente sintassi:

    ["starts-with", "$field", "value"]

    Se il valore di un campo non ha limitazioni, utilizza la condizione starts-with con la seguente sintassi:

    ["starts-with", "$field", ""]

    Tutti i campi del modulo HTML validi, ad eccezione di Content-Length, possono utilizzare la condizione starts-with.

  • Intervallo durata contenuti

    Specifica un intervallo di valori accettabili che possono essere utilizzati nella Campo Content-Length. Specifica questa condizione utilizzando la seguente sintassi:

    ["content-length-range", min_range, max_range]

Esempio

Di seguito è riportato un esempio di documento relativo alle norme:

{"expiration": "2020-06-16T11:11:11Z",
 "conditions": [
  ["starts-with", "$key", ""],
  {"bucket": "travel-maps"},
  {"success_action_redirect": "http://www.example.com/success_notification.html"},
  ["eq", "$Content-Type", "image/jpeg"],
  ["content-length-range", 0, 1000000],
  {"x-goog-algorithm": "GOOG4-RSA-SHA256"},
  {"x-goog-credential": "example_account@example_project.iam.gserviceaccount.com/20191102/us-central1/storage/goog4_request"},
  {"x-goog-date": "20191102T043530Z"}
  ]
}

Questo documento delle norme definisce le seguenti condizioni:

  • Il modulo scade il 16 giugno 2020 alle 11:11:11 UTC.
  • Il nome del file può iniziare con qualsiasi carattere valido.
  • Il file deve essere caricato nel bucket travel-maps.
  • Se il caricamento va a buon fine, l'utente viene reindirizzato a http://www.example.com/success_notification.html.
  • Il modulo consente di caricare solo immagini.
  • Un utente non può caricare un file di dimensioni superiori a 1 MB.

Ambito delle credenziali

L'ambito delle credenziali è una stringa che compare sia in string-to-sign sia documenti relativi alle norme. L'ambito delle credenziali ha la seguente struttura:

DATE/LOCATION/SERVICE/REQUEST_TYPE

L'ambito delle credenziali è costituito dai seguenti componenti:

  • DATE: la data in cui la firma diventa utilizzabile, nel formato AAAAMMGG.
  • LOCATION: per le risorse Cloud Storage, puoi utilizzare qualsiasi valore per LOCATION. Il valore consigliato da utilizzare è la posizione associata alla risorsa a cui si applica la firma. Ad esempio: us-central1. Questo parametro è presente per mantenere la compatibilità con Amazon S3.
  • SERVICE: il nome del servizio. Nella maggior parte dei casi, quando si accede Risorse Cloud Storage, questo valore è storage. Quando si utilizza Estensioni x-amz di Amazon S3; questo valore è s3.
  • REQUEST_TYPE: il tipo di richiesta. Nella maggior parte dei casi, quando si accede Risorse Cloud Storage, questo valore è goog4_request. Quando utilizzi le estensioni x-amz di Amazon S3, questo valore è aws4_request.

Ad esempio, un ambito delle credenziali tipico è il seguente:

20191102/us-central1/storage/goog4_request

Mentre l'ambito di una credenziale quando si utilizza una stringa da firmare con estensioni x-amz è simile al seguente:

20150830/us-east1/s3/aws4_request

Firma

Per creare una firma, utilizzi un algoritmo di firma, chiamato anche funzione hash crittografica, per firmare il tuo documento "string-to-sign" o "criteri". L'algoritmo di firma che utilizzi dipende dal tipo di chiave di autenticazione hai:

Chiave di autenticazione Algoritmo di firma Chiave di firma
Chiave RSA RSA-SHA256 Utilizza direttamente la chiave privata RSA
Chiave HMAC HMAC-SHA256 Dedurre dal secret della chiave HMAC

Consulta l'articolo Creare firme per una guida su come firmare i criteri o la stringa per la firma utilizzando una chiave RSA e il metodo IAM signBlob.

Ricava la chiave di firma dalla chiave HMAC

Quando firmi con una chiave HMAC, devi creare una chiave di firma codificata UTF-8 che derivato dal secret della chiave HMAC. La chiave derivata è specifica per la data, la località, il servizio e il tipo di richiesta associati alla tua richiesta. La il seguente pseudocodice mostra come ricavare la chiave di firma:

key_date = HMAC-SHA256("PREFIX" + HMAC_KEY_SECRET, "DATE")
key_region = HMAC-SHA256(key_date, "LOCATION")
key_service = HMAC-SHA256(key_region, "SERVICE")
signing_key = HMAC-SHA256(key_service, "REQUEST_TYPE")

Lo pseudocodice ha i seguenti componenti:

  • PREFIX: nella maggior parte dei casi, quando si accede a Cloud Storage di risorse, questo valore è GOOG4. Quando utilizzi le estensioni x-amz di Amazon S3, questo valore è AWS4.
  • HMAC_KEY_SECRET: il secret per la chiave HMAC che stai utilizzando per creare e firmare la richiesta.
  • DATE, LOCATION, SERVICE, REQUEST_TYPE: questi valori devono corrispondere a quelli specificati nell'ambito delle credenziali.

Dopo la firma

Per completare la firma, l'output della firma, chiamato digest del messaggio, deve essere codificato in esadecimale.

Esempio

Di seguito è riportato lo pseudocodice per firmare un documento dei criteri:

EncodedPolicy = Base64Encode(PolicyDocument)
MessageDigest = SigningAlgorithm(SigningKey, EncodedPolicy)
Signature = HexEncode(MessageDigest)

Di seguito è riportato uno pseudocodice per la firma di una stringa "string-to-sign":

MessageDigest = SigningAlgorithm(SigningKey, StringToSign)
Signature = HexEncode(MessageDigest)

Limitazioni

Le firme non possono essere utilizzate per autenticare un caricamento se utilizza la codifica di trasferimento suddivisa in blocchi. Utilizza i token OAuth 2.0 se vuoi utilizzare la codifica di trasferimento suddivisa in blocchi per i tuoi caricamenti.

Passaggi successivi