Firme

Le firme sono un metodo per autenticare le richieste inviate all'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 il processo di firma V4, che è quello consigliato per la creazione delle firme.

Le firme sono specifiche dell'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 ai servizi Cloud de Confiance by S3NS , inclusa l'API JSON di Cloud Storage.

Panoramica

Le firme forniscono sia l'identità sia l'autenticazione forte, il 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 sensibili della chiave, chiamate secret o chiavi private, associate all'account.

Quando effettui una richiesta con una firma, Cloud Storage utilizza la sua copia delle informazioni della 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 segreta o privata pertinente.

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

• URL firmati.
• Moduli HTML.

Inoltre, le firme possono essere utilizzate nell'intestazione Authorization delle richieste 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 dei token OAuth 2.0.

Strutturazione

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

Stringa da firmare

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'utilizzo 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 dalle estensioni che utilizzi per le intestazioni o parametri di ricerca:

Data e ora di attivazione

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 da 15 minuti prima della data e ora di attivazione fino alla data e ora di scadenza specificata. La data e l'ora attive devono corrispondere al parametro della stringa di query X-Goog-Date dell'URL firmato e devono utilizzare lo stesso giorno specificato nell'ambito delle credenziali.

• Per le richieste con intestazioni firmate, la firma è utilizzabile da 15 minuti prima della data e ora attive fino a 15 minuti dopo la data e ora attive. La data e l'ora di attivazione 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 con codifica esadecimale di una richiesta canonica. Utilizza una funzione di hashing SHA-256 per creare un valore hash della richiesta canonica. Il tuo linguaggio di programmazione dovrebbe avere una libreria per la creazione di hash SHA-256. Un esempio di valore hash è:

436b7ce722d03b17d3f790255dd57904f7ed61c02ac5127a0ca8063877e4e42c

Esempio

Di seguito è riportato un esempio di stringa da firmare formattata correttamente, 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 delle norme

Un documento della policy definisce ciò che gli utenti con accesso al modulo HTML corrispondente possono caricare su Cloud Storage. Un documento di policy fornisce l'autorizzazione per garantire che il modulo HTML possa caricare i file nel bucket di destinazione. Puoi utilizzare i documenti delle policy per consentire ai visitatori di un sito web di caricare file su Cloud Storage.

Un documento di policy è costruito in JavaScript Object Notation (JSON). Il documento della policy deve essere codificato sia in UTF-8 che in Base64. Un documento delle policy contiene le seguenti sezioni:

La sezione conditions deve includere:

• Un'istruzione di condizione per ogni campo utilizzato nel modulo HTML, ad eccezione dei campi x-goog-signature, file e policy.

• 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 condizionali 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 dei moduli 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 dei moduli HTML validi, ad eccezione di Content-Length, possono utilizzare la condizione starts-with.

• Intervallo di durata dei 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 di policy:

{"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.s3ns.iam.gserviceaccount.com/20191102/us-central1/storage/goog4_request"},
  {"x-goog-date": "20191102T043530Z"}
  ]
}

Questo documento delle policy definisce le seguenti condizioni:

• Il modulo scade il 16 giugno 2020 alle 11:11:11 UTC.
• Il nome 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 appare sia nei documenti string-to-sign sia nei documenti delle policy. 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 località 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 accedi alle risorse Cloud Storage, questo valore è storage. Quando utilizzi le estensioni Amazon S3 x-amz, questo valore è s3.
• REQUEST_TYPE: il tipo di richiesta. Nella maggior parte dei casi, quando accedi alle risorse Cloud Storage, questo valore è goog4_request. Quando utilizzi le estensioni Amazon S3 x-amz, questo valore è aws4_request.

Ad esempio, un tipico ambito delle credenziali è simile al seguente:

20191102/us-central1/storage/goog4_request

Mentre un ambito delle credenziali quando utilizzi una stringa da 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, noto anche come funzione hash di crittografia, per firmare la stringa da firmare o il documento di policy. L'algoritmo di firma produce un digest del messaggio, che deve essere codificato in formato esadecimale per creare la firma finale. L'algoritmo di firma che utilizzi dipende dal tipo di chiave di autenticazione che hai:

L'algoritmo di firma RSA-SHA256 può essere eseguito utilizzando il metodo IAM signBlob. Strumenti come gcloud CLI e la maggior parte delle librerie client Cloud de Confiance consentono di creare URL firmati utilizzando il metodo signBlob.

Puoi anche creare firme di chiave RSA localmente utilizzando un linguaggio di programmazione che dispone di una libreria per l'esecuzione di firme RSA, come la libreria pyopenssl. Tuttavia, questo metodo è sconsigliato, perché richiede la creazione e il download della chiave privata di un account di servizio.

Deriva la chiave di firma dalla chiave HMAC

Quando firmi 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 località, il servizio e il tipo di richiesta associati alla tua richiesta. Il seguente pseudocodice mostra come derivare 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 accedi alle risorse Cloud Storage, questo valore è GOOG4. Quando utilizzi le estensioni Amazon S3 x-amz, questo valore è AWS4.
• HMAC_KEY_SECRET: il secret della chiave HMAC che utilizzi per creare e firmare la richiesta.
• DATE, LOCATION, SERVICE, REQUEST_TYPE: questi valori devono corrispondere a quelli specificati nell'ambito delle credenziali.

Dopo aver ricavato la chiave di firma, crea la firma localmente utilizzando un linguaggio di programmazione che includa una libreria con l'algoritmo di firma HMAC-SHA256.

Dopo la firma

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

Esempio

Di seguito è riportato lo pseudocodice per la firma di un documento di policy:

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

Di seguito è riportato lo pseudocodice per la firma di una stringa da firmare:

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

Passaggi successivi

• Utilizza la tua firma in un URL firmato.
• Utilizza la tua firma in una richiesta con un'intestazione Authorization.
• Utilizza la firma in un modulo HTML.