Crittografia a livello di applicazione

Le API Payments Standard supportano PGP o JWE per la crittografia a livello di applicazione.

Crittografia PGP

PGP è un insieme standard di algoritmi di crittografia, decrittografia e firma che forniscono privacy e autenticazione crittografica.

Quando si utilizza PGP per criptare i payload, i partner devono supportare:

  • Crittografia e decrittografia dei payload con più chiavi PGP.
  • Firma dei payload con più chiavi PGP.
  • Verifica di un payload con più firme, ognuna delle quali può essere la firma con la chiave fornita da Google.
  • Decrittografia dei payload codificati in Base64 sicuri per il web.

Le chiavi pubbliche PGP fornite a Google devono avere una sottochiave utilizzata per la crittografia. La chiave secondaria consente la rotazione indipendente dalla chiave principale. La chiave master viene utilizzata per la verifica dell'identità. Le chiavi private devono essere chiavi RSA da 2048 (o più) bit che scadono tra un anno con una durata massima di due anni.

Prima di iniziare lo sviluppo, devi scambiare le chiavi PGP con Google. In questo passaggio generi una coppia di chiavi pubblica/privata PGP, fornisci la chiave pubblica a Google e ricevi una chiave pubblica da Google. Durante lo sviluppo, dovresti scambiare solo le chiavi della sandbox utilizzate per lo sviluppo e i test al di fuori della produzione. Prima del test e del lancio in produzione, dovrai eseguire un altro scambio di chiavi di produzione.

Generazione di una nuova chiave PGP

Supponendo che tu abbia un file binario GPG nel percorso di sistema, puoi utilizzare il seguente comando POSIX per creare una nuova coppia di chiavi.

$ gpg --full-generate-key

Quando richiesto, seleziona una chiave RSA con almeno 2048 bit di entropia e una scadenza di 1-2 anni. Questo comando deve creare sia una chiave principale (etichettata SC, per "S"igning e "C"ertificate generation) sia una sottochiave (etichettata E, per "E"ncryption).

Configurazione della libreria PGP

Invio di payload

  1. Quando firmi, devi utilizzare SHA384 come algoritmo digest; non utilizzare SHA1o MD5
  2. Durante la crittografia, devi utilizzare AES256 come algoritmo di crittografia simmetrica; non utilizzare CAST5 o IDEA
  3. Quando cripti o firmi i messaggi, assicurati di selezionare la sottochiave con lo scopo corrispondente; utilizza la chiave CAN_SIGN per la firma e la chiave ENCRYPT_COMMS/ENCRYPT_STORAGE per la crittografia

Ricezione di payload

  1. Quando verifichi un payload, assicurati che la tua libreria supporti algoritmi di hashing moderni come SHA384. Google inizierà a utilizzarla su tutte le nuove chiavi dal 14 maggio 2023.
  2. Quando decripti un payload, assicurati che la tua libreria supporti algoritmi di crittografia simmetrica moderni come AES256. Google inizierà a utilizzarlo su tutte le nuove chiavi a partire dal 14 maggio 2023.

Esempio di crittografia del payload GPG

Il comando riportato di seguito è un esempio di come selezionare opzioni sicure quando si utilizza GPG. È previsto che questa operazione venga eseguita in un ambiente attendibile in cui gli utenti non hanno accesso alle chiavi private o ai file di input sensibili.

gpg --output signed-and-encrypted.pgp \
  --sign --digest-algo SHA384 \
  --encrypt --cipher-algo AES256 \
  --armor \
  --recipient {key_id} \
  input.txt

GPG seleziona automaticamente la chiave giusta dal bundle per ogni operazione che gli chiedi di eseguire.

Crittografia JWE con firma JWS

JSON Web Encryption (JWE) è uno standard definito dalla rfc7516 per la crittografia dei contenuti a livello di applicazione. La firma web JSON (JWS) è uno standard definito da rfc7515 per la firma dei contenuti a livello di applicazione.

Le richieste e le risposte saranno token JWE criptati utilizzando la crittografia asimmetrica (chiave pubblica) con l'opzione "Serializzazione compatta". Il token JWE conterrà il payload firmato come token JWS. JWS utilizza anche chiavi asimmetriche: chiave privata per la firma e chiave pubblica per la verifica.

Quando invii un payload, firmalo prima e poi criptalo. Quando ricevi un payload, decriptalo prima e poi verifica la firma.

Quando utilizzano JWE, i partner devono supportare le seguenti opzioni:

  • Serializzazione compatta.
  • Decrittografia dei payload da una delle più chiavi JWE.
  • L'algoritmo RSA-OAEP, RSA-OAEP-256 o ECDH-ES per la gestione delle chiavi.
  • L'algoritmo A256GCM, A128GCM, A128CBC-HS256 o A256CBC-HS512 per la crittografia dei contenuti.
    • Compilato nell'intestazione enc.
  • kid per identificare la chiave pubblica di crittografia.
  • I payload dei messaggi che utilizzano la crittografia JWE devono utilizzare il tipo di contenuto application/jose; charset=utf-8.

Quando utilizzano JWS, i partner devono supportare le seguenti opzioni:

  • Serializzazione compatta.
  • Verifica dei payload da una delle più chiavi JWS.
  • L'algoritmo HS256, HS384, HS512, RS256, RS384, RS512, ES256, PS256, PS384 o PS512 per la creazione della firma.
  • kid per identificare la chiave privata di firma.

Le stringhe JWE/JWS verranno codificate come stringhe UTF-8 e i relativi payload possono essere byte arbitrari.

Le chiavi private devono essere chiavi RSA/ECDH-ES che scadono tra un anno con una durata massima di due anni. Tutte le identità delle chiavi private devono rimanere sempre sul server del partner e, di conseguenza, tutti i valori delle firme devono essere calcolati sul server del partner.

Prima di iniziare lo sviluppo, devi scambiare le chiavi JWE e JWS con Google. Le chiavi devono essere scambiate in formato JWK, come definito in rfc7517. In questo passaggio generi una coppia di chiavi pubblica/privata, fornisci la chiave pubblica a Google e ricevi una chiave pubblica da Google. Durante lo sviluppo, dovresti scambiare solo le chiavi della sandbox utilizzate per lo sviluppo e i test al di fuori della produzione. Prima del test e del lancio in produzione, dovrai eseguire un altro scambio di chiavi di produzione.