Documentação
Guias de ImplementaçãoReferência da APIAPI StatusAjuda

TOTP - Time-based One-time Password

Suggest Edits

O que é?

É uma senha de uso único gerada por um algoritmo para confirmar a identidade do seu cliente. Os TOTPs são considerados seguros porque expiram após um período predeterminado de tempo. O TOTP é frequentemente parte do 2FA (autenticação de dois fatores - Time-based one-time password).
Com essa opção ativada, dispensa a solicitação de sessão por SMS, deixando a aplicação muito mais independente de possíveis problemas com cobertura de dados das operadoras de celular.


Quais recursos necessários para utilizar?

Para utilizar o TOTP no 2FA é necessário os seguintes itens:

  • O cliente deve estar liberado para acessar o 2FA incluindo o IP e chaves de acesso;
  • O usuário já deve ter o acesso a sessão do 2FA por SMS;
  • O marketplace necessita gerar um conjunto de chaves :
    • Public Key - usada para criptografia e decriptografia. A chave enviada para Zoop, deve estar no formato string, contendo apenas o texto sem quebra de página
    • Private Key - usada para a criptografia e decriptografia
      Formato das chaves deve obedecer o padrão RSA/ECB/OAEPWithSHA-256AndMGF1Padd (formato de encriptação)

Alinhando conceitos sobre Chaves Public e Private Key:

Uma chave pública, disponível a todos, é usada para criptografar a mensagem. Essa chave não consegue descriptografar
Uma chave privada, conhecida SOMENTE pelo destinatário, tem o poder de descriptografar as mensagens.


Registrando um usuário no TOTP

Com os pré-requisitos já atendidos, será necessário realizar o registro do usuário no TOTP e validar esse registro. Se a validação ocorrer com sucesso, esse usuário estará pronto para iniciar uma sessão de 2FA utilizando o TOTP, o que dispensa o recebimento de SMS.

Os passos para esse registro são:

  1. Ter uma sessão de usuário validada por SMS
  2. Ter criado uma Public Key e Private Key usando o padrão RSA/ECB/OAEPWithSHA-256AndMGF1Padd
  3. Chamar a API de registro de usuário no TOTP
  4. Chamar a API de validação do registro de usuário no TOTP

Na chamada API de registro de usuário no TOTP, terá que ser passado o UserSessionToken, UserToken e a KeyPublic (chave pública gerada pelo marketplace). Lembrar que a public key e a private key, necessitam serem passadas no formato string, contendo apenas o texto sem quebra de página e sem as marcações de chaves públicas (-----BEGIN RSA PUBLIC KEY-----\n e \n-----END RSA PUBLIC KEY-----\n).

O retorno dessa API entregará uma SeedRSA criptografada em formato base64. Com essa SeedRSA gerada, deve-se usar a chave privada (private key) para decriptografar.

OBS: Armazene a Seed retornada em lugar seguro. Ela será utilizada nas solicitações de sessões futuras.

Antes de chamar a API de validação do registro de TOTP é necessário alguns passos para obter o código a ser validado:

  1. Importar a chave privada (private key) para uma estrutura RSA. Ela será usada para descriptografar os dados mais a frente;
  2. Especificar o algoritmo de hash;
  3. Fazer o encode utf8 do SeedRSA;
  4. Fazer o decode do base64 (b64decode) – Importante - atenção aqui o hash que devolverá não é ainda o código que devemos enviar para a api precisamos seguir para geração de um TOTP;
  5. Realiza a decriptografia usando o algoritmo hash do item B;
  6. Realiza o decode utf8 da SeedRSA;
  7. Gerar o código TOTP com 6 dígitos.

Exemplo em python:

import pyotp
import time

KEY_PRIV = RSA.importKey(prikey)
CIPHER = PKCS1_OAEP.new(key=KEY_PRIV, hashAlgo=SHA256, mgfunc=lambda x, y: pss.MGF1(x, y, SHA1))

seed = seedRSA.encode("utf-8")
seed = base64.b64decode(seed)
seed = CIPHER.decrypt(seed)
seed = seed.decode("utf-8")


totp = pyotp.TOTP(seed, interval=30, digits=6).now()

Na última linha é onde é gerado o código que será usado na próxima chamada de API e os atributos utilizados são:

  • totp - é a variável que receberá o código a ser passado na próxima chamada de API
  • seed - é a SeedRSA utilizada nos passos 1 até 7;

  • interval - janela de tempo que o acesso é concedido (geralmente 30 segundos)
  • digits - determina o número de dígitos (padrão é 6)

Com os passos acima retornando sucesso, a variável totp terá que ser passada na chamada de validação. O que deve ser informado nessa chamada são: UserSessionToken, UserToken e o TOTP e caso seja validado, o usuário estará pronto para realizar iniciar uma sessão via TOTP.


Solicitando uma sessão no TOTP

Agora que o usuário está registrado no TOTP, não será necessário receber o SMS para validar sessões de 2FA.

Os passos aqui são solicitar a sessão passando o UserToken e OnTimPassword, conforme a chamada de API.

Já para chamar a API de validação de sessão TOTP, será necessário utilizar o procedimento do item 1 até o 7 do tópico anterior (Registrando um usuário no TOTP), pois nesse ponto é necessário gerar a SeedRSA e o código totp para ser passado na chamada.
Deverá ser passado o UserToken (vem do response da solicitação de sessão via TOTP) e o UserSessionPassword onde esse último é o código do totp gerado.

Updated 5 months ago