Le firme sono un metodo per autenticare le richieste inviate API XML di Cloud Storage. Le firme vengono utilizzate, ad esempio, durante il lavoro 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 per l'API XML di Cloud Storage e sono distinte dalle token OAuth 2.0; I token OAuth 2.0 possono essere utilizzati anche con l'API XML e sono più generalmente applicabili ai servizi Google Cloud, tra cui API JSON Cloud Storage.
Panoramica
Le firme forniscono sia identità sia autenticazione avanzata, che garantisce che le richieste a Cloud Storage vengano elaborate tramite l'autorità di per un account specifico. Le firme raggiungono questa autenticazione senza rivelare il le informazioni sensibili, chiamate segreti o chiavi private, associate 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 Cloud Storage, allora Cloud Storage sa che la firma è stato creato utilizzando il secret o la chiave privata pertinente.
In Cloud Storage, le firme devono essere utilizzate quando si lavora con:
Inoltre, è possibile utilizzare le firme nell'intestazione Authorization
dei file XML
richieste API.
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. Per creare la firma, devi applicare un algoritmo di firma a questi due componenti. La tabella che segue riassume i diversi casi d'uso delle firme e i componenti necessari in ciascun caso per creare la firma:
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 | Estrazione dal segreto 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. | Estrazione dal segreto della chiave HMAC | Stringa da firmare |
Stringa da firmare
Un elemento string-to-sign include meta informazioni relative alla tua richiesta e un hash di la richiesta canonica che vuoi firmare.
Strutturazione
Un elemento string-to-sign deve avere la codifica UTF-8 e avere la seguente struttura: incluso l'uso di nuove righe 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 che utilizzi e le estensioni che utilizzi per le intestazioni o i parametri di ricerca:
Caso d'uso | Valore per SIGNING_ALGORITHM |
---|---|
x-goog-* estensione e una chiave RSA |
GOOG4-RSA-SHA256 |
x-goog-* estensione e una chiave HMAC |
GOOG4-HMAC-SHA256 |
x-amz-* estensione 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 a partire da 15 minuti prima della data/ora attiva fino a 15 minuti dopo la data/ora attiva. La la data/ora attiva deve corrispondere all'intestazione
x-goog-date
della richiesta utilizzando e la data/ora attiva deve essere uguale a quella specificata l'ambito delle credenziali.
Ambito credenziali
L'ambito delle credenziali per la richiesta.
Hash della richiesta canonica
L'hash SHA-256 esadecimale codificato di una richiesta canonica. Utilizza un hash 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 da segno formattata correttamente, con le interruzioni di riga visualizzate 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 di criteri definisce cosa possono caricare su Cloud Storage gli utenti con accesso al corrispondente modulo HTML. Un documento delle norme fornisce per garantire che il modulo HTML possa caricare file nella di sincronizzare la directory di una VM con un bucket. Puoi utilizzare la documentazione relativa alle norme per consentire ai visitatori di un sito web di caricare contenuti in Cloud Storage.
Viene creato un documento dei criteri in JSON (JavaScript Object Notation). La il documento delle norme deve avere codifica sia UTF-8 che Base64. Un documento delle 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 dei 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 per i campi
x-goog-signature
,file
epolicy
.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. Si possono utilizzare tre tipi di condizioni le tue dichiarazioni sulla condizione:
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, tranne
Content-Length
, possono utilizzare la corrispondenza esatta.Inizia con
Se il valore di un campo deve iniziare con un determinato prefisso, utilizza
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, tranne
Content-Length
, possono utilizzarestarts-with
.Intervallo di lunghezza dei contenuti
Specifica un intervallo di valori accettabili che possono essere utilizzati nel
Content-Length
campo. Specifica questa condizione utilizzando la seguente sintassi:["content-length-range", min_range, max_range]
Esempio
Di seguito è riportato un esempio di documento delle 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 ore 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 file di dimensioni superiori a 1 MB.
Ambito delle credenziali
L'ambito delle credenziali è una stringa che viene visualizzata sia nei documenti di stringa a indicatori sia nei documenti delle norme. 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 Cloud Storage, puoi utilizzare qualsiasi valore per LOCATION. Il valore consigliato da utilizzare è
location associata alla risorsa a cui si applica la firma.
Ad esempio:
us-central1
. Questo parametro esiste 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 utilizzi le estensionix-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 si utilizza Estensionix-amz
di Amazon S3; questo valore èaws4_request
.
Ad esempio, un ambito delle credenziali tipico è il seguente:
20191102/us-central1/storage/goog4_request
Mentre un ambito delle credenziali, quando si usa una stringa per la firma con estensioni x-amz
,
ha il seguente aspetto:
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 di tipo "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 | Usa direttamente la chiave privata RSA |
Chiave HMAC | HMAC-SHA256 | Estrazione dal segreto 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. Lo pseudocodice seguente 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 è composto dai seguenti componenti:
- PREFIX: nella maggior parte dei casi, quando si accede a Cloud Storage
di risorse, questo valore è
GOOG4
. Quando utilizzi le estensionix-amz
di Amazon S3,AWS4
è questo valore. - HMAC_KEY_SECRET: il secret della chiave HMAC in uso per effettuare 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, denominato messaggio, digest deve essere codificato 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 quest'ultimo utilizza blocchi codifica di trasferimento. Utilizza i token OAuth 2.0 se vuoi usare blocchi trasferire la codifica nei caricamenti.
Passaggi successivi
- Utilizza la tua firma in un URL firmato.
- Utilizza la tua firma in una richiesta con un'intestazione
Authorization
. - Utilizza la tua firma in un modulo HTML.