Recomendações de Segurança

Este é um guia com recomendações de segurança para consumir as APIs Elo.

Feito para:  Estabelecimentos ComerciaisEmissoresFacilitadoresAdquirentesOutros DesenvolvedoresMerchantsIssuersAcquirersPayment Service ProvidersOther DevelopersCredenciadoresSubcredenciadoresCarteiras DigitaisDigital WalletsPortadores de CartãoCardholders

Durante o desenvolvimento de aplicativos de pagamentos, é indicado a Carteira Digital e seguir as melhores práticas de desenvolvimento seguro. A camada do aplicativo é de alto risco e pode ser explorada por ameaças internas e externas. Sem uma segurança adequada, os dados do titular do cartão e outras informações confidenciais podem ser expostas. A bandeira Elo, recomenda a realização de avaliações durante a etapa de desenvolvimento e homologação, utilizando técnicas de codificação seguras de mercado evitando publicação de aplicativos de pagamento vulneráveis e inseguros aos seus portadores:

  • PCI - PA-DDS: Programa de certificação PCI conhecido por indicar as melhores práticas na proteção de dados em aplicativos de pagamento, é possível encontrar guias e plano de teste para segurança em aplicativos de pagamento.

  • OWASP - Mobile Application Security Verification Standard (MASVS) e NIST – Mobile Device Security: Guias de melhores práticas para construção segura de aplicativos.

  • OWASP Top 10: Catálogo das principais falhas de segurança em website e aplicativos.

  • OWASP Threat Modeling: Modelagem de ameaças, identificação e avaliação de possíveis brechas de segurança, ajudando a prevenir, mitigar e medir os impactos das ameaças nos aplicativos de pagamento.

A segurança de informação Elo, disponibiliza ao emissor o canal de comunicação csirt@elo.com.br, esse canal é utilizado para apoio na investigação de incidentes de segurança

Além das recomendações feitas pelos frameworks mencionados acima, a Elo faz as seguintes recomendações para o TR Client (Lado Cliente):

  • O Parceiro deverá controlar a confiabilidade nos cadastros de pessoas físicas e criações de credenciais de login;

  • O Parceiro deverá garantir a autenticação segura no provisionamento dos cartões na Carteira Digital;

  • O Parceiro deverá oferecer suporte para desativação das credenciais em caso de perda ou roubo do dispositivo móvel;

  • As chaves secretas geradas pela Elo para uso do APP, devem ser armazenas de maneira através de recursos com KeyStore e KeyChain;

  • Credenciais de pagamentos nunca deverão ser armazenadas no Dispositivo.

Além das recomendações feitas pelos frameworks mencionados acima, a Elo faz as seguintes recomendações para o TR Server (Lado Cliente):

  • MTLS é um requisito mandatório para o ambiente produtivo;

  • O Parceiro deverá prover, obrigatoriamente, infraestrutura intermediária entre o aplicativo mobile e o Hub Qr Code ELO;

  • Whitelist de conexão, é recomendado para garantir o acesso restrito da infraestrutura intermediaria do emissor ao produto Hub Qr Code ELO demonstrado na figura 5. Para configuração do whiteList, basta informar a equipe de projeto Elo e o range de saída da infraestrutura intermediaria para configuração do canal de entrada do produto;

  • O Parceiro deverá garantir segurança das chaves de acesso ao produtos de pagamentos Elo (client_id, secrets e certificados) impedindo que a informação seja divulgada ou comprometida. Recomendamos implementar a arquitetura do aplicativo mobile em 3 camadas (aplicativo mobile, infraestrutura emissor e API’s ELO), preservando as credenciais de acesso ao produto na camada privada de infraestrutura do emissor, evitando a publicação diretamente no aplicativo;

  • É de responsabilidade do Parceiro monitorar as defesas e tratamento de incidentes no perímetro de infraestrutura privada, de aplicativos da Canal Originador Carteira Digital Emissor disponibilizado aos portadores através das Lojas Virtuais e Website.

Para utilizar as APIs da Elo, o usuário deve possuir um access_token válido e informá-lo no header das requisições no padrão Bearer Authentication. O processo de autenticação da aplicação e obtenção do access_token é realizado através do recurso POST /payment/<API>/v1/oauth/access-token, informando no header da requisição o client_id e o atributo Authorization, conforme descrito nas seções anteriores.

Exemplo do corpo da requisição:

{
  "grant_type": "client_credentials"
}

Exemplo do cabeçalho da requisição:

Authorization: "Basic " + base64(client_id + ":" + client_secret)

Exemplo do corpo de resposta:

{
  "access_token": "ZTFmOTY2ODktY2E4My0zMzVhLTg1OWQtN2VkYzRhOGZjMmI4OjI5OWZjMjVjLWFjNDEtM2ViMi1iNGM0LTk4ZjA4ZWI3OWNkYg==",
  "token_type": "Bearer",
  "expires_in": 600
}

O campo expires_in é o valor em segundos.

O algoritmo será composto pelo Content Encryption Algorithm (enc) como A256GCM e o Content Encryption Key Algorithm (alg) como ECDH-ES. O parceiro fará a requisição da chave pública Elo, e fará a criptografia dos dados utilizando essa chave. O formato do dado segue as especificações JWE, para maiores informações acesse RFC7518.

O recurso GET /payment/<API>/v1/public-keys é utilizado para realização desse processo.

No exemplo abaixo, é possível identificar os dados que são retornados pela Elo.

{
  "keyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "keyData": {
    "kty": "EC",
    "x": "vG2i-qVjdoCpgRPp0RgadBtDObDhEjVjqIK-4APa0Hc",
    "y": "k4Aya9MrjGOz_PcGkFeagYpb8NOXWlxZ6pxtltiK98Y",
    "crv": "P-256",
    "use": "enc",
    "kid": "Key1",
    "alg": "ECDH-ES"
  },
  "keyExpiration": 3600
}

Nota:

  • A chave sempre será retornada no formato JWK;

  • Para casos onde o valor retornado é um dado sensível, a Carteira terá que informar uma chave pública na requisição do recurso em uso.

Caso o Parceiro opte por usar o serviço Device Binding, ele terá que usar uma Chave Síncrona, que será criada pela Elo, para autenticação de um dispositivo. Essa chave terá um Time To Live parametrizado, e após sua expiração, ela será substituída. A troca de chaves acontecerá através da API callback que será exposta pelo Parceiro, ou seja, o Parceiro deve estar preparado para receber um callback assíncrono.

Essa chave secreta será utilizada para garantir a autenticidade do dispositivo em chamadas de APIs sensíveis. O dispositivo terá que assinar um conjunto de dados utilizando o algoritmo HMAC-SHA256. Os dados que serão assinados, serão definidos pela API em uso.

O cadastro do dispositivo é um processo de vinculação de um segredo Elo a um dispositivo. Com isso, é possível autenticar e garantir que as transações sejam originadas por uma fonte confiável.

Para iniciar o processo de Cadastro, a Carteira Digital deverá Informar os dados do dispositivo e a instância da carteira, essas informações serão usadas para criar esse vínculo.

O recurso /payment/device-binding/v1/bonds é utilizado para realização desse processo. No exemplo abaixo, é possível identificar os dados que podem ser enviados:

{
  "devicePublicKey": {
    "kty": "EC",
    "x": "vG2i-qVjdoCpgRPp0RgadBtDObDhEjVjqIK-4APa0Hc",
    "y": "k4Aya9MrjGOz_PcGkFeagYpb8NOXWlxZ6pxtltiK98Y",
    "crv": "P-256",
    "use": "enc",
    "kid": "Key1",
    "alg": "ECDH-ES"
  },
  "deviceId": "string",
  "walletId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "deviceName": "string",
  "manufacturer": "string",
  "model": "string",
  "type": "PC",
  "networkType": "string",
  "country": "string",
  "os": "ANDROID"
}

Nota: o campo devicePublicKey deve conter a chave pública do keypair gerado no dispositivo conforme citado no quarto item da seção Recomendações de Segurança | Lado Cliente.

No exemplo abaixo, é possível identificar os dados que são retornados pela Elo.

{
  "bondId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "deviceId": "string",
  "cipheredSecretKey": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiRUNESC1FUyIsImtpZCI6Ikp1cS00bkJ0WVhaME5iSWV1R3BtX3JKOElnWlhjMThoemFicGx5Vm1rOFUiLCJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsIngiOiJOM05iQmxUZThNUWZsMUllUHRKWEMtV0JYTFhkSUFlLWxOTEF5MFM3c2hzIiwieSI6ImgzNjZWclRzZTVGZ3FRdnRRaUlTQ1R4VTlMX0paaHZrdFNuRGZwWmgxWEkifX0..cKIqNX_KAVM9WE98.ivgbqZGfvL1IYALx6o-Yxu2WFCJBQPvfpetEApR2OSR3FamONwKHkrUZHNB9hGqcx677B06fliLUxgvxccrvVhSdA7kSDFr9ACH-BzLoDFKz3xpKcvgq5R-2NHXIHSQ_42Geb4uRzZAtabR4px7RBNsTlD1YGuPxAASsmvb84nBUlEo8Oi_5THFPwtsiz0rzq9LfH6RhK_u0zqUyMHNXANh5zX7Sd981f2fLqsHNrpj6t9HGXKoV7Fc7mlB5u8c6vtjAEsAK3KjRvsjbsQQXbh74kfEtL9zoyFxeeF3FpL-6_hrGFEeTnMh8ExlLoZuwB-JW6-Uwuv50kakGYeEoN4DZ7ClhM2WP9C_w5gKBjp3tgEtzAvxtKWFZuk9oKFaWNeowdaHwgdDLr_5GDmNf7aPskwb75ZHzk-U8VGVJfB3Nhzmucip2bRnvhl6G9GbLHey9AbJJAIIjdQ6-rzbtZUdLB2sLQJ6PUTBeP9x9ELi2boTTyxoFq0QmedTEEj6t3Bvc1_j766VYwBv35PL7X9n2VMAj2f4p55vlYnSNYadNAUY-ojkGDelP-B1tcVInlXCEFvD4dntIJTKEzoOqrL_NxigaPNMLQQsMUDyuK-a7_vlKN5guIlOgoNJpKxUH0lcaOEgFJAKELc6E4_ccvjGE75KMS0KDkgvVxajMYOcZV-xS4SWXOpvT1j-j_eHlt83hYtsgg0o-fJSm3NYSz3OMhCx2WO0wBk2BehuckNUR6X8tpd7_HwjbrH24_iWKMwJ6vOEz7Q.3WBaXCmW6bIh-HSlO_KK9A",
  "keyExpiration": 3600,
  "transactionCounter": 0
}

A chave cipheredSecretKey está criptografada com a chave pública que foi enviada pelo dispositivo. Ela deve ser decriptografada e armazenada de maneira segura no dispositivo, a partir desse momento, juntamente com o modelo de criptografia, ela será responsável por garantir Autenticidade desse aparelho.

O contador transactionCounter retornado será usado para fins de prevenção e como meio de evitar ataques de repetição (Replay Attack). Esse campo deve ser enviado como 0 na primeira requisição de Token e deverá ser populado pela Elo a cada nova requisição. É responsabilidade da Carteira Digital enviar o campo conforme retornado pela Elo a cada requisição de Token.

A Carteira Digital terá que expor a API /callback/key-exchange-notifications, essa que será utilizada para realização da troca de chaves após a expiração do seu TTL. No exemplo abaixo, é possível identificar os dados que serão enviados pela Elo.

O campo cipheredSecretKey é a nova chave simétrica, que está criptografada pela antiga, dessa maneira podemos garantir que apenas o mesmo dispositivo possa ter acesso a ela.

O algoritmo usado para criptografar a nova chave será composto pelo Authenticated Encryption como A256GCM e Content Encryption Algorithm como dir. O formato é Direct Encryption conforme definido nas especificações JWE, para maiores informações acesse RFC7518.

{
  "bondId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "deviceId": "string",
  "cipheredSecretKey": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiRUNESC1FUyIsImtpZCI6Ikp1cS00bkJ0WVhaME5iSWV1R3BtX3JKOElnWlhjMThoemFicGx5Vm1rOFUiLCJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsIngiOiJOM05iQmxUZThNUWZsMUllUHRKWEMtV0JYTFhkSUFlLWxOTEF5MFM3c2hzIiwieSI6ImgzNjZWclRzZTVGZ3FRdnRRaUlTQ1R4VTlMX0paaHZrdFNuRGZwWmgxWEkifX0..cKIqNX_KAVM9WE98.ivgbqZGfvL1IYALx6o-Yxu2WFCJBQPvfpetEApR2OSR3FamONwKHkrUZHNB9hGqcx677B06fliLUxgvxccrvVhSdA7kSDFr9ACH-BzLoDFKz3xpKcvgq5R-2NHXIHSQ_42Geb4uRzZAtabR4px7RBNsTlD1YGuPxAASsmvb84nBUlEo8Oi_5THFPwtsiz0rzq9LfH6RhK_u0zqUyMHNXANh5zX7Sd981f2fLqsHNrpj6t9HGXKoV7Fc7mlB5u8c6vtjAEsAK3KjRvsjbsQQXbh74kfEtL9zoyFxeeF3FpL-6_hrGFEeTnMh8ExlLoZuwB-JW6-Uwuv50kakGYeEoN4DZ7ClhM2WP9C_w5gKBjp3tgEtzAvxtKWFZuk9oKFaWNeowdaHwgdDLr_5GDmNf7aPskwb75ZHzk-U8VGVJfB3Nhzmucip2bRnvhl6G9GbLHey9AbJJAIIjdQ6-rzbtZUdLB2sLQJ6PUTBeP9x9ELi2boTTyxoFq0QmedTEEj6t3Bvc1_j766VYwBv35PL7X9n2VMAj2f4p55vlYnSNYadNAUY-ojkGDelP-B1tcVInlXCEFvD4dntIJTKEzoOqrL_NxigaPNMLQQsMUDyuK-a7_vlKN5guIlOgoNJpKxUH0lcaOEgFJAKELc6E4_ccvjGE75KMS0KDkgvVxajMYOcZV-xS4SWXOpvT1j-j_eHlt83hYtsgg0o-fJSm3NYSz3OMhCx2WO0wBk2BehuckNUR6X8tpd7_HwjbrH24_iWKMwJ6vOEz7Q.3WBaXCmW6bIh-HSlO_KK9A",
  "keyExpiration": 3600
}

Nota: Caso o dispositivo não faça nenhuma movimentação em um intervalo de 30 dias, ele será considerado como inativo, portanto, não serão enviadas novas chaves. Para ativar o dispositivo, a carteira terá que chamar o recurso Ativar Dispositivo.

O recurso PATCH /payment/device-binding/v1/bonds é utilizado para realização da ativação de um dispositivo. No exemplo abaixo, é possível visualizar o dado que deve ser enviado para ativação do dispositivo.

{
  "status": "ACTIVE"
}

No exemplo abaixo, é possível identificar os dados que são retornados pela Elo.

{
  "status": "ACTIVE",
  "cipheredSecretKey": "eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiRUNESC1FUyIsImtpZCI6Ikp1cS00bkJ0WVhaME5iSWV1R3BtX3JKOElnWlhjMThoemFicGx5Vm1rOFUiLCJlcGsiOnsia3R5IjoiRUMiLCJjcnYiOiJQLTI1NiIsIngiOiJOM05iQmxUZThNUWZsMUllUHRKWEMtV0JYTFhkSUFlLWxOTEF5MFM3c2hzIiwieSI6ImgzNjZWclRzZTVGZ3FRdnRRaUlTQ1R4VTlMX0paaHZrdFNuRGZwWmgxWEkifX0..cKIqNX_KAVM9WE98.ivgbqZGfvL1IYALx6o-Yxu2WFCJBQPvfpetEApR2OSR3FamONwKHkrUZHNB9hGqcx677B06fliLUxgvxccrvVhSdA7kSDFr9ACH-BzLoDFKz3xpKcvgq5R-2NHXIHSQ_42Geb4uRzZAtabR4px7RBNsTlD1YGuPxAASsmvb84nBUlEo8Oi_5THFPwtsiz0rzq9LfH6RhK_u0zqUyMHNXANh5zX7Sd981f2fLqsHNrpj6t9HGXKoV7Fc7mlB5u8c6vtjAEsAK3KjRvsjbsQQXbh74kfEtL9zoyFxeeF3FpL-6_hrGFEeTnMh8ExlLoZuwB-JW6-Uwuv50kakGYeEoN4DZ7ClhM2WP9C_w5gKBjp3tgEtzAvxtKWFZuk9oKFaWNeowdaHwgdDLr_5GDmNf7aPskwb75ZHzk-U8VGVJfB3Nhzmucip2bRnvhl6G9GbLHey9AbJJAIIjdQ6-rzbtZUdLB2sLQJ6PUTBeP9x9ELi2boTTyxoFq0QmedTEEj6t3Bvc1_j766VYwBv35PL7X9n2VMAj2f4p55vlYnSNYadNAUY-ojkGDelP-B1tcVInlXCEFvD4dntIJTKEzoOqrL_NxigaPNMLQQsMUDyuK-a7_vlKN5guIlOgoNJpKxUH0lcaOEgFJAKELc6E4_ccvjGE75KMS0KDkgvVxajMYOcZV-xS4SWXOpvT1j-j_eHlt83hYtsgg0o-fJSm3NYSz3OMhCx2WO0wBk2BehuckNUR6X8tpd7_HwjbrH24_iWKMwJ6vOEz7Q.3WBaXCmW6bIh-HSlO_KK9A",
  "keyExpiration": 3600
}

O certificado de autenticação Mútua (MTLS) é utilizado para proteger informações durante a integração, impedindo que sejam interceptadas, capturadas ou visualizadas durante transferência dos dados entre os servidores do Parceiros e as APIs Elo.

A Elo exige que o acesso as suas APIs transacionais façam uso da Autenticação Mútua TLS, também conhecido por MTLS, trazendo assim maior segurança para a troca de pacotes que ocorrerá através da Internet.

Atualmente, temos dois possíveis cenários para a troca de certificados, o primeiro onde o Parceiro atua como cliente, sendo o originador dessas mensagens. O segundo onde o parceiro atua como servidor, nesse cenário, a Elo é originadora das mensagens.

    1. O Parceiro deve enviar uma Requisição de Assinatura de Certificado (.csr) para a Elo.

    1. A Elo assinará essa requisição utilizando sua CA Privada, e devolverá ao parceiro o certificado (.crt) que deverá ser utilizado em todas as chamadas de APIs.

    1. Nesse cenário, o certificado Server da Elo é assinado por uma CA pública.

    1. A Elo deve enviar uma Requisição de Assinatura de Certificado (.csr) para o Parceiro.

    1. O Parceiro deverá assinar essa requisição utilizando sua CA Privada ou uma CA Pública, e devolverá à Elo o certificado (.crt) que deverá ser utilizado em todas as chamadas de APIs.

    1. Nesse cenário, o certificado Server do Parceiro deve ser assinado obrigatoriamente por uma CA pública.