Firme

Le firme sono un metodo per l'autenticazione delle richieste inviate all'API Cloud Storage XML. Le firme vengono utilizzate, ad esempio, quando si lavora con URL firmati o moduli HTML.

Panoramica

Le firme forniscono identità e un'autenticazione efficace, assicurando che le richieste a Cloud Storage vengano elaborate utilizzando l'autorità di un account specifico. Le firme raggiungono tale autenticazione senza rivelare le informazioni chiave sensibili, chiamate segreti, associate all'account.

Quando fai una richiesta con una firma, Cloud Storage utilizza la sua copia del secret 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 pertinente.

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

Inoltre, le firme possono essere utilizzate durante la creazione di:

  • Richieste dirette firmate all'API XML.

L'utilizzo delle firme nelle richieste dirette è utile quando si eseguono semplici migrazioni da Amazon S3, tuttavia il flusso di autenticazione consigliato per le richieste dirette è utilizzare i token OAuth 2.0.

Struttura

I componenti e il processo di creazione di una firma dipendono dal motivo per cui la utilizzerai e dalla chiave di autenticazione con cui lavori; in genere esistono due componenti per una firma: la chiave di firma e le informazioni di richiesta. Applichi un algoritmo di firma a questi due componenti per creare la firma. La tabella che segue riepiloga i diversi casi d'uso per le firme e i componenti necessari per costruire la firma in ogni caso:

Caso d'uso Chiave di firma Richiedi informazioni
Modulo HTML con una chiave RSA Utilizza direttamente il secret della chiave RSA Documento dei criteri con codifica Base64
Modulo HTML con chiave HMAC Estrai i dati dal segreto HMAC Documento dei criteri con codifica Base64
URL firmato o richiesta firmata con una chiave RSA Utilizza direttamente il secret della chiave RSA Stringa da firmare
URL firmato o richiesta firmata con una chiave HMAC Estrai i dati dal segreto HMAC Stringa da firmare

Stringa per firma

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

Struttura

Un elemento stringa da firmare deve essere codificato in UTF-8 e ha la seguente struttura, incluso l'uso di nuove righe tra ciascun 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 ricerca:

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

Timestamp attivo

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

  • Per gli URL firmati, la firma può essere utilizzata dai 15 minuti precedenti alla data e l'ora di attivazione fino alla data e all'ora specificate. Il valore della data e l'ora attivi deve corrispondere al 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 firmate, la firma è utilizzabile da 15 minuti prima della data e ora attive fino a 15 minuti dopo la data/ora attiva. La data e l'ora attive devono corrispondere all'intestazione della richiesta x-goog-date firmata 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 deve avere una libreria per la creazione di hash SHA-256. Un valore hash di esempio è simile al seguente:

436b7ce722d03b17d3f790255dd57904f7ed61c02ac5127a0ca8063877e4e42c

Esempio

Di seguito è riportato un esempio di stringa da firmare formattata correttamente, con le nuove righe mostrate come nuove righe e non con \n:

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

Documento di criteri

Un documento di criteri definisce gli utenti che hanno accesso al modulo HTML corrispondente che possono caricare 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 i documenti relativi ai criteri per consentire ai visitatori di un sito web di caricare file in Cloud Storage.

Un documento di criteri è integrato in JavaScript Object Notation (JSON). Il documento del criterio deve essere codificato in UTF-8 e Base64. Un documento di criteri contiene le seguenti sezioni:

Entry Descrizione
expiration La data di scadenza del documento del criterio, nel formato di base ISO 8601 YYYYMMDD'T'HHMMSS'Z'. Un documento di norme 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 che utilizzi nel modulo HTML, ad eccezione dei campi x-goog-signature, file e policy.

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

Se vuoi utilizzare più istruzioni condizionali per lo stesso campo, devi creare un modulo HTML distinto per ciascuna. Nelle dichiarazioni condizioni possono essere utilizzati 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 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 del modulo HTML validi ad eccezione di Content-Length possono utilizzare la condizione starts-with.

  • Intervallo di lunghezza 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 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 un 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 che viene visualizzata nei documenti stringa-sign-e e nei criteri. L'ambito delle credenziali ha la seguente struttura:

DATE/LOCATION/SERVICE/REQUEST_TYPE

L'ambito delle credenziali ha 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 è il valore location associato 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 alle risorse di Cloud Storage, questo valore è storage. Quando utilizzi le estensioni per Amazon S3 x-amz, questo valore è s3.
  • REQUEST_TYPE: il tipo di richiesta. Nella maggior parte dei casi quando si accede alle risorse di Cloud Storage, questo valore è goog4_request. Quando utilizzi le estensioni per Amazon S3 x-amz, questo valore è aws4_request.

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

20191102/us-central1/storage/goog4_request

Anche se l'ambito delle credenziali quando utilizzi un'estensione stringa per firma con le estensioni x-amz ha il seguente aspetto:

20150830/us-east1/s3/aws4_request

Firma

Per creare una firma, utilizza un algoritmo di firma, noto anche come funzione hash di crittografia, per firmare il documento di tipo stringa o firma. L'algoritmo di firma che utilizzi dipende dal tipo di chiave di autenticazione che hai:

Chiave di autenticazione Algoritmo di firma Chiave di firma
chiave RSA RSA-SHA256 Utilizza direttamente il secret della chiave RSA
Chiave HMAC HMAC - SHA256 Estrai i dati dal segreto HMAC

Ricava la chiave di firma dalla chiave HMAC

Quando esegui la firma con una chiave HMAC, devi creare una chiave di firma codificata UTF-8 che provenga dal secret della chiave HMAC. La chiave derivata è specifica per la data, la località, 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 Cloud Storage, 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 effettuare e firmare la richiesta.
  • DATE, LOCATION, SERVICE, REQUEST_TYPE: questi valori devono corrispondere ai valori specificati nell'ambito delle credenziali.

Dopo la firma

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

Esempio

Di seguito è riportato lo pseudo-codice per la firma di un documento di criteri:

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

Di seguito è riportato uno pseudo-codice per la firma di una stringa da firmare:

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