TOTP - Time-based One-time Password
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:
- Ter uma sessão de usuário validada por SMS
- Ter criado uma Public Key e Private Key usando o padrão RSA/ECB/OAEPWithSHA-256AndMGF1Padd
- Chamar a API de registro de usuário no TOTP
- 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:
- Importar a chave privada (private key) para uma estrutura RSA. Ela será usada para descriptografar os dados mais a frente;
- Especificar o algoritmo de hash;
- Fazer o encode utf8 do SeedRSA;
- 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;
- Realiza a decriptografia usando o algoritmo hash do item B;
- Realiza o decode utf8 da SeedRSA;
- 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 4 months ago