Criptografia da camada de aplicativos

As APIs Standard Payments aceitam PGP ou JWE na criptografia da camada de aplicativos.

Criptografia PGP

O PGP é um conjunto padrão de algoritmos de criptografia, descriptografia e assinatura que oferece privacidade e autenticação criptográfica.

Ao usar o PGP para criptografar payloads, os parceiros precisam oferecer suporte a:

  • Criptografar e descriptografar payloads com várias chaves PGP.
  • Assinatura de payloads com várias chaves PGP.
  • Verificação de um payload com várias assinaturas. Qualquer uma delas pode ser a assinatura com a chave fornecida pelo Google.
  • Descriptografia de payloads codificados em base64 seguros para a Web.

As chaves públicas PGP fornecidas ao Google precisam ter uma subchave usada para criptografia. Ela permite a rotação independente da chave mestra. A chave mestra é usada para a verificação de identidade. Chaves privadas precisam ser RSA de 2.048 bits ou mais que expiram em um ano com um ciclo de vida máximo de dois anos.

Antes de iniciar o desenvolvimento, você precisa trocar chaves PGP com o Google. Nesta etapa, é preciso gerar um par de chaves públicas/privadas PGP, fornecer uma chave pública ao Google e receber outra do Google. Durante o desenvolvimento, você só precisará trocar as chaves de sandbox usadas para desenvolvimento e testes fora da produção. Para fazer o teste de produção e o lançamento, é preciso realizar outra troca de chaves de produção.

Como gerar uma nova chave PGP

Supondo que você tenha um binário GPG no caminho do sistema, use o seguinte comando POSIX para criar um novo par de chaves.

$ gpg --full-generate-key

Quando solicitado, selecione uma chave RSA com pelo menos 2048 bits de entropia e expiração de 1-2 anos. Esse comando criará uma chave mestra (rotulada como SC de "S"igning and "C"ertificate, ou geração de assinatura e certificado) e uma subchave (rotulada como E de "E"ncryption, ou criptografia).

Configuração da biblioteca PGP

Enviar payloads

  1. Ao assinar, você precisa usar SHA384 como o algoritmo de resumo. Não use SHA1ou MD5
  2. Ao criptografar, use AES256 como o algoritmo de criptografia simétrica. não use CAST5 ou IDEA
  3. Ao criptografar ou assinar mensagens, selecione a subchave com a finalidade correspondente. Use a chave CAN_SIGN para assinar e a chave ENCRYPT_COMMS/ENCRYPT_STORAGE para criptografar

Receber payloads

  1. Ao verificar um payload, certifique-se de que a biblioteca seja compatível com algoritmos de hash modernos, como SHA384. O Google vai começar a usar esses algoritmos em todas as novas chaves a partir de 14 de maio de 2023.
  2. Ao descriptografar um payload, verifique se a biblioteca é compatível com algoritmos modernos de criptografia simétrica, como AES256. O Google vai começar a usar esses algoritmos em todas as novas chaves a partir de 14 de maio de 2023.

Exemplo de criptografia de payload do GPG

O comando abaixo é um exemplo de como selecionar opções seguras ao usar o GPG. Espera-se que essa operação seja realizada em um ambiente confiável em que as pessoas não tenham acesso às chaves privadas ou aos arquivos de entrada confidenciais.

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

O GPG vai selecionar automaticamente a chave adequada do pacote para cada operação solicitada.

Criptografia JWE com assinatura JWS

O JSON Web Encryption (JWE) é um padrão definido por rfc7516 (em inglês) para criptografar conteúdo no nível do aplicativo. O JSON Web Signature (JWS) é um padrão definido por rfc7515 (link em inglês) para assinar conteúdo no nível do aplicativo.

Solicitações e respostas serão tokens JWE criptografados usando criptografia assimétrica (chave pública) com a opção "Serialização compacta". O token JWE conterá o payload assinado como um token JWS. O JWS também usa chaves assimétricas, chave privada para assinatura e chave pública para verificação.

Ao enviar um payload, assine-o primeiro e depois criptografe-o. Ao receber um payload, descriptografe-o primeiro e, em seguida, verifique a assinatura.

Ao usar o JWE, os parceiros precisam oferecer suporte às seguintes opções:

  • Serialização compacta.
  • Descriptografia de payloads de uma das várias chaves JWE.
  • O algoritmo RSA-OAEP, RSA-OAEP-256 ou ECDH-ES para gerenciamento de chaves.
  • O algoritmo A256GCM, A128GCM, A128CBC-HS256 ou A256CBC-HS512 para criptografia de conteúdo.
    • Preenchido no cabeçalho enc.
  • Cabeçalho kid para identificar a chave pública de criptografia.
  • Os payloads de mensagens que usam criptografia JWE precisam usar o tipo de conteúdo application/jose; charset=utf-8.

Ao usar o JWS, os parceiros precisam oferecer suporte às seguintes opções:

  • Serialização compacta.
  • Verificação de payloads de uma das várias chaves JWS
  • O algoritmo HS256, HS384, HS512, RS256, RS384, RS512, ES256, PS256, PS384 ou PS512 para a criação de assinaturas
  • kid para identificar a chave de assinatura privada.

As strings JWE/JWS serão codificadas como strings UTF-8, e os payloads delas podem ser bytes arbitrários.

Chaves privadas precisam ser RSA/ECDH-ES que expiram em um ano, com um ciclo de vida máximo de dois anos. Todas as identidades de chave privada precisam sempre permanecer no servidor do parceiro e, portanto, todos os valores de assinatura precisam ser calculados no servidor do parceiro.

Antes de iniciar o desenvolvimento, você precisa trocar as chaves JWE e JWS com o Google. As chaves precisam ser trocadas no formato JWK, conforme definido em rfc7517 (em inglês). Nesta etapa, é preciso gerar um par de chaves públicas/privadas, fornecer uma chave pública ao Google e receber uma outra em troca. Durante o desenvolvimento, você só precisará trocar as chaves de sandbox usadas para desenvolvimento e testes fora da produção. Para fazer o teste de produção e o lançamento, é preciso realizar outra troca de chaves de produção.