Criptografia da camada de aplicativos

As APIs Standard Payments são compatíveis com PGP ou JWE para criptografia da camada de aplicativos.

Criptografia PGP

O PGP é um conjunto padrão de algoritmos de criptografia, descriptografia e assinatura que oferecem 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.
  • a verificação de um payload com várias assinaturas, sendo que 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 da identidade. As chaves privadas precisam ser RSA de 2048 bits ou mais e expirar em um ano com uma duração máxima de dois anos.

Para começar o desenvolvimento, é necessário trocar chaves PGP com o Google. Nesta etapa, você gera um par de chaves públicas/privadas PGP, fornece uma chave pública ao Google e recebe uma chave pública em troca. Durante o desenvolvimento, você só vai precisar trocar as chaves do sandbox usadas no desenvolvimento e teste fora da produção. Antes do teste de produção e do 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

Como enviar payloads

  1. Ao assinar, use 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, verifique se a biblioteca é 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 sensíveis.

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. A assinatura JSON Web (JWS) é um padrão definido por rfc7515 (em inglês) para assinar conteúdo no nível do aplicativo.

As 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 vai 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 depois verifique a assinatura.

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

  • Serialização compacta.
  • Descriptografia de payloads de uma de várias chaves JWE.
  • Os algoritmos RSA-OAEP, RSA-OAEP-256 ou ECDH-ES para gerenciamento de chaves.
  • Os algoritmos A256GCM, A128GCM, A128CBC-HS256 ou A256CBC-HS512 para criptografia de conteúdo.
    • Preenchido no cabeçalho enc.
  • cabeçalho kid para identificar a chave de criptografia pública.
  • 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.
  • Os algoritmos HS256, HS384, HS512, RS256, RS384, RS512, ES256, PS256, PS384 ou PS512 para criação de assinaturas.
  • cabeçalho 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 nesse mesmo lugar.

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, você vai 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ó vai precisar trocar as chaves do sandbox usadas no desenvolvimento e teste fora da produção. Antes do teste de produção e do lançamento, é preciso realizar outra troca de chaves de produção.