Le firme sono un metodo per autenticare le richieste inviate all'API XML di Cloud Storage. Le firme vengono usate, ad esempio, quando si lavora con URL firmati o moduli HTML. Questa pagina si applica alle firme create utilizzando il processo di firma V4, che è il processo consigliato per la creazione di firme.
Le firme sono specifiche per l'API XML di Cloud Storage e sono distinte dai token OAuth 2.0; i token OAuth 2.0 possono essere utilizzati anche con l'API XML e sono più generalmente applicabili a tutti i servizi di Google Cloud, inclusa l'API JSON di Cloud Storage.
Panoramica
Firme fornisce sia l'identità sia l'autenticazione avanzata, che garantisce che le richieste a Cloud Storage vengano elaborate utilizzando l'autorità di un account specifico. Le firme ottengono questa autenticazione senza rivelare le informazioni chiave sensibili, chiamate secrets o secrets, associate all'account.
Quando effettui una richiesta con una firma, Cloud Storage utilizza la propria copia delle informazioni della chiave per calcolare una firma equivalente per la richiesta. Se la firma inclusa nella richiesta corrisponde alla firma calcolata da Cloud Storage, Cloud Storage sa che la firma è stata creata utilizzando il secret o la chiave privata pertinenti.
In Cloud Storage, è necessario utilizzare le firme quando si lavora con:
Inoltre, le firme possono essere utilizzate per:
- Le richieste firmate dirette all'API XML.
L'utilizzo delle firme nelle richieste dirette è utile quando si eseguono migrazioni semplici da Amazon S3. Tuttavia, il flusso di autenticazione consigliato per le richieste dirette è l'utilizzo di token OAuth 2.0.
Strutturazione
I componenti e la procedura per creare una firma dipendono dall'utilizzo che intendi farne e dalla chiave di autenticazione con cui lavori; in generale, una firma ha due componenti: la chiave di firma e la richiesta di informazioni. Applichi un algoritmo di firma a questi due componenti per creare la firma. La tabella riportata di seguito riassume i diversi casi d'uso delle firme e i componenti necessari per creare la firma in ciascun caso:
Caso d'uso | Chiave di firma | Richiedi informazioni |
---|---|---|
Modulo HTML con una chiave RSA | Usa direttamente la chiave privata RSA | Documento dei criteri con codifica Base64 |
Modulo HTML con una chiave HMAC | Derire dal secret della chiave HMAC | Documento dei criteri con codifica Base64 |
URL firmato o richiesta firmata con una chiave RSA | Usa direttamente la chiave privata RSA | Stringa per firma |
URL firmato o richiesta firmata con una chiave HMAC | Derire dal secret della chiave HMAC | Stringa per firma |
Stringa per firma
Un elemento string-to-sign include meta informazioni sulla tua richiesta e un hash della richiesta canonica che vuoi firmare.
Strutturazione
Una stringa-to-sign deve avere codifica UTF-8 e avere la seguente struttura, incluso l'utilizzo di ritorni a capo tra ogni elemento:
SIGNING_ALGORITHM ACTIVE_DATETIME CREDENTIAL_SCOPE HASHED_CANONICAL_REQUEST
Algoritmo di firma
Il valore che utilizzi per SIGNING_ALGORITHM dipende dal tipo di chiave utilizzato e dalle estensioni usate per le intestazioni o i parametri di ricerca:
Caso d'uso | Valore per SIGNING_ALGORITHM |
---|---|
x-goog-* estensioni e una chiave RSA |
GOOG4-RSA-SHA256 |
Estensioni x-goog-* e una chiave HMAC |
GOOG4-HMAC-SHA256 |
Estensioni 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 di base ISO 8601 YYYYMMDD'T'HHMMSS'Z'
.
Per gli URL firmati, la firma è utilizzabile dai 15 minuti precedenti alla data/ora attiva fino alla scadenza specificata. La data/ora attiva deve corrispondere al parametro della stringa di query
X-Goog-Date
dell'URL firmato e deve utilizzare lo stesso giorno specificato nell'ambito credenziali.Per le richieste firmate, la firma può essere utilizzata da 15 minuti prima della data/ora attiva fino a 15 minuti dopo la data/ora attiva. La data/ora attiva deve corrispondere all'intestazione della richiesta
x-goog-date
della richiesta firmata e deve utilizzare lo stesso giorno specificato nell'ambito credenziali.
Ambito delle credenziali
L'ambito delle credenziali per la richiesta.
Hash della richiesta canonica
L'hash SHA-256 con codifica esadecimale di una richiesta canonica. Usare una funzione di hashing SHA-256 per creare un valore hash della richiesta canonica. Il tuo linguaggio di programmazione deve avere una libreria per la creazione di hash SHA-256. Un esempio di valore hash è simile al seguente:
436b7ce722d03b17d3f790255dd57904f7ed61c02ac5127a0ca8063877e4e42c
Esempio
Di seguito è riportato un esempio di stringa-significato correttamente formattata, con le nuove righe mostrate come nuove righe effettive e non come \n
:
GOOG4-RSA-SHA256 20191201T190859Z 20191201/us-central1/storage/goog4_request 54f3076005db23fbecdb409d25c0ccb9fb8b5e24c59f12634654c0be13459af0
Documento relativo alle norme
Un documento dei criteri definisce quali utenti con accesso al modulo HTML corrispondente possono caricare in Cloud Storage. Un documento dei criteri fornisce l'autorizzazione per garantire che il modulo HTML possa caricare file nel bucket di destinazione. Puoi utilizzare i documenti dei criteri per consentire ai visitatori di un sito web di caricare file in Cloud Storage.
Viene creato un documento dei criteri in JSON (JavaScript Object Notation). Il documento del criterio deve utilizzare sia la codifica UTF-8 sia quella Base64. Un documento relativo alle 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' . La scadenza di un documento relativo alle norme comporta 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 che utilizzi nel modulo HTML, ad eccezione dei campi
x-goog-signature
,file
epolicy
.Un'istruzione di condizione
"bucket"
, anche se non utilizzi il campo bucket nel modulo HTML.
Se vuoi utilizzare più istruzioni di condizione per lo stesso campo, devi creare un modulo HTML separato per ciascuna. Nelle istruzioni per la condizione puoi utilizzare tre tipi di condizioni:
Corrispondenza esatta
Esegue la corrispondenza esatta per 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 HTML validi del modulo HTML, tranne
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 HTML validi del modulo HTML tranne
Content-Length
possono utilizzare la condizionestarts-with
.Intervallo lunghezza contenuti
Specifica un intervallo di valori accettabili che possono essere utilizzati nel 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 relativo alle 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 ha esito positivo, 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 visualizzata sia nei documenti "string-to-sign" che nei documenti dei criteri. L'ambito delle credenziali ha la seguente struttura:
DATE/LOCATION/SERVICE/REQUEST_TYPE
L'ambito delle credenziali include i seguenti componenti:
- DATE: la data in cui la firma diventa utilizzabile, nel formato AAAAMMGG.
- LOCATION: per le risorse di Cloud Storage, puoi utilizzare qualsiasi valore per LOCATION. Il valore consigliato è la località associata alla risorsa a cui si applica la firma.
Ad esempio:
us-central1
. Questo parametro ha lo scopo di mantenere la compatibilità con Amazon S3. - SERVICE: il nome del servizio. Nella maggior parte dei casi, quando accedi alle risorse di Cloud Storage, questo valore è
storage
. Quando utilizzi le estensionix-amz
di Amazon S3, questo valore ès3
. - REQUEST_TYPE: il tipo di richiesta. Nella maggior parte dei casi, quando accedi alle risorse di Cloud Storage, questo valore è
goog4_request
. Quando utilizzi le estensionix-amz
di Amazon S3, questo valore èaws4_request
.
Ad esempio, un tipico ambito delle credenziali ha il seguente aspetto:
20191102/us-central1/storage/goog4_request
Mentre l'ambito delle credenziali quando si utilizza una stringa per firmare con le estensioni x-amz
ha il seguente aspetto:
20150830/us-east1/s3/aws4_request
Firma
Per creare una firma, utilizzi un algoritmo di firma, anche noto come funzione di hash crittografico, per firmare il documento stringa-firma o il documento del criterio. L'algoritmo di firma che utilizzi dipende dal tipo di chiave di autenticazione che utilizzi:
Chiave di autenticazione | Algoritmo di firma | Chiave di firma |
---|---|---|
Chiave RSA | RSA-SHA256 | Usa direttamente la chiave privata RSA |
Chiave HMAC | HMAC-SHA256 | Derire dal secret della chiave HMAC |
Consulta Creazione di firme per una guida alla firma del documento string-to-Sign o Policy Controller utilizzando una chiave RSA e il metodo signBlob
IAM.
Estrai la chiave di firma dalla chiave HMAC
Quando accedi con una chiave HMAC, devi creare una chiave di firma con codifica UTF-8 derivata dal secret della chiave HMAC. La chiave derivata è specifica per la data, la posizione, il servizio e il tipo di richiesta associati alla richiesta. 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 alle risorse di Cloud Storage, questo valore è
GOOG4
. Quando utilizzi le estensionix-amz
di Amazon S3, questo valore èAWS4
. - HMAC_KEY_SECRET: il secret per la chiave HMAC che stai utilizzando per effettuare e firmare la richiesta.
- DATE, LOCATION, SERVICE, REQUEST_TYPE: questi valori devono corrispondere ai valori specificati nell'ambito credenziali.
Dopo la firma
Per completare la firma, l'output della firma, chiamato digest dei messaggi, deve essere con codifica esadecimale.
Esempio
Di seguito è riportato uno pseudocodice per la firma di 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-significato:
MessageDigest = SigningAlgorithm(SigningKey, StringToSign) Signature = HexEncode(MessageDigest)
Limitazioni
Le firme non possono essere utilizzate per autenticare un caricamento se questo utilizza la codifica di trasferimento in blocchi. Utilizza i token OAuth 2.0 se vuoi utilizzare la codifica di trasferimento in blocchi nei tuoi caricamenti.
Passaggi successivi
- Utilizza la tua firma in un URL firmato.
- Utilizza la tua firma in una richiesta firmata.
- Utilizza la tua firma in un modulo HTML.