Creare una firma

​

Creazione di una firma

Questa pagina spiega come generare una firma HMAC-SHA1 OAuth 1.0a per una richiesta HTTP. Questa firma è adatta per essere inviata alla X API come parte di una richiesta autorizzata, come descritto in autorizzare una richiesta.

La richiesta utilizzata per illustrare la procedura di firma è una richiesta POST a https://api.x.com/1.1/statuses/update.json. La richiesta in forma grezza è la seguente:

POST /1.1/statuses/update.json?include_entities=true HTTP/1.1
Accept: */*
Connection: close
User-Agent: OAuth gem v0.4.4
Content-Type: application/x-www-form-urlencoded
Content-Length: 76
Host: api.x.com

status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21

Raccolta del metodo e dell’URL della richiesta

Per generare una firma, iniziate determinando il metodo HTTP e l’URL della richiesta. Questi due elementi sono noti quando si crea la richiesta, quindi sono facili da reperire.

Per le richieste alla X API, il metodo sarà quasi sempre GET o POST.

Metodo HTTP	POST

L’URL di base è l’URL a cui è indirizzata la richiesta, senza eventuali parametri di query o hash. È importante usare il protocollo corretto: assicuratevi che la parte “https://” dell’URL corrisponda alla richiesta effettiva inviata all’API.

URL di base	https://api.x.com/1.1/statuses/update.json

​

Raccolta dei parametri

Successivamente, raccogli tutti i parametri inclusi nella richiesta. Esistono due posizioni per questi parametri aggiuntivi: l’URL (come parte della query string) e il corpo della richiesta. La richiesta di esempio include un solo parametro in entrambe le posizioni:

POST /1.1/statuses/update.json?include_entities=true HTTP/1.1
Accept: */*
Connection: close
User-Agent: OAuth gem v0.4.4
Content-Type: application/x-www-form-urlencoded
Content-Length: 76
Host: api.x.com

status=Hello%20Ladies%20%2b%20Gentlemen%2c%20a%20signed%20OAuth%20request%21

Una richiesta HTTP ha parametri codificati nell’URL, ma dovresti raccogliere i valori grezzi. Oltre ai parametri della richiesta, ogni parametro oauth_* deve essere incluso nella firma, quindi raccogli anche quelli. Ecco i parametri da autorizzare una richiesta:

status	Hello Ladies + Gentlemen, a signed OAuth request!
include_entities	true
oauth_consumer_key	xvz1evFS4wEEPTGEFPHBog
oauth_nonce	kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg
oauth_signature_method	HMAC-SHA1
oauth_timestamp	1318622958
oauth_token	370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb
oauth_version	1.0

Questi valori devono essere codificati in un’unica stringa, che verrà utilizzata più avanti. Il processo per costruire la stringa è molto specifico:

1. Codifica in percentuale ogni chiave e valore che verranno firmati.
2. Ordina l’elenco dei parametri in ordine alfabetico [1] in base alla chiave codificata [2].
3. Per ogni coppia chiave/valore:
4. Aggiungi la chiave codificata alla stringa di output.
5. Aggiungi il carattere “=” alla stringa di output.
6. Aggiungi il valore codificato alla stringa di output.
7. Se rimangono altre coppie chiave/valore, aggiungi un carattere “&” alla stringa di output.  

[1] La specifica OAuth indica di ordinare lessicograficamente, che è l’ordinamento alfabetico predefinito per molte librerie.

[2] Nel caso di due parametri con la stessa chiave codificata, la specifica OAuth indica di continuare l’ordinamento in base al valore. Tuttavia, X non accetta chiavi duplicate nelle richieste API  

Stringa dei parametri

La seguente stringa dei parametri verrà prodotta ripetendo questi passaggi con i parametri raccolti sopra:

status	Hello Ladies + Gentlemen, a signed OAuth request!
include_entities	true
oauth_consumer_key	xvz1evFS4wEEPTGEFPHBog
oauth_nonce	kYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg
oauth_signature_method	HMAC-SHA1
oauth_timestamp	1318622958
oauth_token	370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb
oauth_version	1.0

​

Creazione della signature base string

I tre valori raccolti finora devono essere uniti per formare un’unica stringa, da cui verrà generata la firma. Nella specifica OAuth questa è chiamata signature base string.

Per codificare il metodo HTTP, l’URL di base e la stringa dei parametri in un’unica stringa:

1. Converti il metodo HTTP in maiuscolo e imposta la stringa di output uguale a questo valore.
2. Aggiungi il carattere ‘&’ alla stringa di output.
3. Applica il percent-encoding all’URL e aggiungilo alla stringa di output.
4. Aggiungi il carattere ‘&’ alla stringa di output.
5. Applica il percent-encoding alla stringa dei parametri e aggiungila alla stringa di output.  

Questo produrrà la seguente signature base string:

POST&https%3A%2F%2Fapi.x.com%2F1.1%2Fstatuses%2Fupdate.json&include\_entities%3Dtrue%26oauth\_consumer\_key%3Dxvz1evFS4wEEPTGEFPHBog%26oauth\_nonce%3DkYjzVBB8Y0ZFabxSWbWovY3uYSQ2pTgmZeNu2VS4cg%26oauth\_signature\_method%3DHMAC-SHA1%26oauth\_timestamp%3D1318622958%26oauth\_token%3D370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb%26oauth_version%3D1.0%26status%3DHello%2520Ladies%2520%252B%2520Gentlemen%252C%2520a%2520signed%2520OAuth%2520request%2521

Assicurati di applicare il percent-encoding alla stringa dei parametri. La signature base string deve contenere esattamente 2 caratteri ampersand “&”. I caratteri percentuale “%” nella stringa dei parametri devono essere codificati come %25 nella signature base string.

​

Ottenere una chiave di firma

Gli ultimi elementi da raccogliere sono i segreti che identificano la X app che effettua la richiesta e l’utente per conto del quale la richiesta viene eseguita. È molto importante notare che questi valori sono estremamente sensibili e non devono mai essere condivisi con nessuno.

Il valore che identifica la tua app presso X si chiama consumer secret e può essere recuperato dal developer portal visualizzando la pagina dei dettagli dell’app. Questo valore sarà lo stesso per ogni richiesta inviata dalla tua X app.

Consumer secret	kAcSOqF21Fu85e7zjz7ZN2U4ZRhfV3WpwPAoE3Z7kBw

Il valore che identifica l’account per conto del quale la tua applicazione agisce si chiama OAuth token secret. Questo valore può essere ottenuto in diversi modi, tutti descritti in obtaining access tokens.

OAuth token secret	LswwdoUaIvS8ltyTt5jkRh4J50vUPVVHtR2YPi5kE

Ancora una volta, è fondamentale mantenere questi valori riservati alla tua applicazione. Se ritieni che siano stati compromessi, rigenera i tuoi token (i token in questa pagina sono stati contrassegnati come non validi per richieste reali).

Entrambi questi valori devono essere combinati per formare una signing key che verrà utilizzata per generare la firma. La chiave di firma è semplicemente il token secret percent encoded:

Nota che esistono alcuni flussi, ad esempio durante l’ottenimento di un request token, in cui il token secret non è ancora noto. In questo caso, la chiave di firma deve consistere nel consumer secret percent encoded seguito da un carattere ampersand “&”.

Signing key	kAcSOqF21Fu85e7zjz7ZN2U4ZRhfV3WpwPAoE3Z7kBw&LswwdoUaIvS8ltyTt5jkRh4J50vUPVVHtR2YPi5kE

​

Calcolo della firma

Infine, la firma viene calcolata passando la signature base string e la chiave di firma all’algoritmo di hashing HMAC-SHA1. I dettagli dell’algoritmo sono illustrati nella funzione hash_hmac.

L’output della funzione di firma HMAC è una stringa binaria. Questa deve essere codificata in base64 per ottenere la stringa della firma. Ad esempio, l’output dato la base string e la chiave di firma riportate in questa pagina è 2E CF 77 84 98 99 6D 0D DA 90 5D C7 17 7C 75 07 3F 3F CD 4E. Quel valore, quando convertito in base64, è la firma OAuth per questa richiesta:

Firma OAuth	Ls93hJiZbQ3akF3HF3x1Bz8/zU4=