Uso de assinaturas de mensagens para garantir a segurança dos webhooks recebidos

Conversas unilaterais não são divertidas — na Vonage, apostamos nas conversas bidirecionais, e isso inclui nossas APIs. Por exemplo, para enviar um SMS, você acessa nossa API. Para receber uma resposta por SMS, seu aplicativo precisará processar um webhook de entrada. Os webhooks são excelentes para usar HTTP na notificação de eventos, mas exigem que seu aplicativo esteja disponível em uma URL pública. A desvantagem? Sua URL pública é, bem, pública. Qualquer pessoa ou sistema poderia enviar dados para ela, e como você teria certeza de que as mensagens vieram da Vonage?

Observação: Atualmente, o uso de assinaturas de mensagem para verificar webhooks recebidos está disponível apenas na SMS API da Vonage.

Esse é um problema comum com webhooks em todos os tipos de applications. Na Vonage, recomendamos que você habilite a assinatura de mensagens on its account to ensure the security of webhooks received. This article will explain how message signatures work and how to configure them for your own applications. The same approach is used in a few cases, but today's example shows it in the context of SMS receipt, we have some exemplos de código para receber um SMS , caso você tenha interesse em conferi-los antes de entrarmos no assunto.

Ativar assinatura de mensagens

As novas contas da Vonage não têm a assinatura de mensagens ativada por padrão; portanto, o primeiro passo é enviar um e-mail para support@nexmo.com solicitando que as assinaturas de mensagens sejam ativadas na sua Account. Há uma segunda opção para exigir que todas as mensagens que você enviar também tenham uma assinatura; não abordaremos esse recurso hoje, mas vale a pena saber que ele existe.

Descubra o segredo da sua assinatura

Depois de ativar a assinatura, você deverá acessar a página de configurações no seu painel. Lá, você pode definir qual algoritmo de assinatura usar (estou usando a SHA-256 HMAC opção nestes exemplos) e acessar seu segredo de assinatura. Copie esse segredo de assinatura, pois ele é o “segredo compartilhado” que usaremos para calcular as assinaturas tanto no servidor quanto no cliente.

Um “segredo compartilhado” é uma chave que é compartilhada previamente entre duas partes, neste caso, entre os servidores da Vonage e você. Esse segredo compartilhado nunca é transmitido, mas é utilizado tanto pela Vonage quanto pelo seu aplicativo para garantir que os dados sejam provenientes do servidor esperado e não tenham sofrido nenhuma alteração.

Nessa mesma página de configurações, há também a opção de alterar o verbo HTTP dos seus webhooks para POST. O padrão é GET e os exemplos aqui usam GET , mas se você quiser alterá-lo (eu, pessoalmente, prefiro POST pessoalmente), essa configuração está aqui em “Configuração padrão de SMS” -> “Método HTTP”.

A Vonage cria uma marca registrada

Quando uma mensagem SMS chega ao seu número da Vonage, a Vonage envia um webhook para a URL configurada para esse número, contendo todas as informações sobre a mensagem recebida. Com as assinaturas de mensagem ativadas, ela também calcula uma assinatura para enviar junto com a mensagem.

Você pode ler as instruções detalhadas do manual para criar uma assinatura , mas a versão resumida é:

• Obter os campos do formulário em ordem alfabética e concatená-los em uma longa sequência de chaves e valores

• Acrescente o segredo de assinatura ao final

• Calcule o hash da string que você criou de acordo com o algoritmo escolhido, por exemplo, SHA-256 HMAC. Pronto! Essa é a assinatura

Um hash é uma representação textual de uma sequência de caracteres (geralmente mais longa). Não é possível, a partir do hash, reconstruir a sequência original. Podemos transmitir esse hash com segurança (neste caso, trata-se da assinatura da mensagem) sem o risco de revelar a sequência a partir da qual ele foi criado.

A Vonage envia os dados e uma assinatura

Depois que a assinatura for criada, o webhook contendo os dados da mensagem e a assinatura, mas NÃO o segredo, é enviado para a URL que você configurou para esse número. Fica mais ou menos assim:

msisdn: 44784xxxxxxx
to: 44741xxxxxxx
messageId: 16000002632BEC99
text: Next step
type: text
keyword: NEXT
message-timestamp: 2019-01-23 10:51:39
timestamp: 1548240699
nonce: 9a706fdd-2b68-4761-87ab-c6ea80cab452
sig: 062470CA9A00C81FBF32FACE34B73D819BCDED07B36203DF7C0714E1094D86DE

Recebemos esses dados em nosso aplicativo e podemos usá-los, juntamente com o segredo de assinatura que copiamos anteriormente, para recriar a assinatura e compará-la com a que foi recebida.

Calcular a assinatura esperada

A partir dos dados enviados, juntamente com o segredo de assinatura, podemos seguir as mesmas etapas para criar uma assinatura e garantir que o resultado seja exatamente o mesmo. O processo manual foi descrito e linkado acima, mas nossos SDKs de servidor para a pilha de tecnologia escolhida por você criarão a assinatura automaticamente.

Por exemplo, aqui está a biblioteca PHP em ação:

    $signature = new \Nexmo\Client\Signature(
        $_GET,
        NEXMO_API_SIGNATURE_SECRET,
        'sha256'
    );
    $isValid = $signature->check($_GET['sig']);

O valor de $isValid indicará se as assinaturas corresponderam ou não.

Analisando seu próprio código

Você pode tentar fazer algumas brincadeiras com a plataforma de desenvolvimento local, capturando as solicitações usando o Ngrok, capturar os dados e tentar enviar webhooks para seu aplicativo usando um cliente HTTP, como o Postman. Se você alterar qualquer campo — a mensagem, o número de telefone, o carimbo de data/hora —, a verificação da assinatura falhará.

Garantindo a segurança dos webhooks recebidos

Em aplicativos web tradicionais, contamos com informações de sessão/cookies, tokens CSRF e outras medidas para nos proteger contra dados maliciosos recebidos. Os webhooks não têm o mesmo contexto e, portanto, uma abordagem como um segredo compartilhado com assinatura de mensagem pode proteger contra ataques de temporização e dados recebidos que tenham sido adulterados ou que se originem de algum lugar que não seja os servidores da Vonage. Pela minha experiência, a maioria dos dados “maliciosos” na verdade se resume a alguém ter inserido uma URL errada em algum lugar ou algo igualmente inofensivo. Seja um ataque ou não, isso ainda resulta em dados que seu aplicativo não deveria estar processando.

Reserve um tempo para ativar as assinaturas na sua Account da Vonage e adicionar o código de verificação; aplicativos seguros são aplicativos felizes :)