Handshake de Autenticação
Uma etapa compartilhada, usada de forma idêntica byte a byte pela porta do cliente e pela porta Raft do cluster. Assim que a conexão é estabelecida (após o handshake TLS ser concluído, se o TLS estiver em uso), o servidor fala primeiro e envia um challenge. É uma troca de texto de duas linhas delimitadas por nova linha (\n), realizada uma vez por conexão.
A única coisa que muda conforme a porta é qual conjunto de tokens é usado para verificar — a porta do cliente verifica contra client_tokens, a porta Raft contra cluster_tokens. Veja Conexão e Autenticação (Cluster) para as regras de token específicas da porta Raft (qual token é enviado, e como rotacionar tokens com zero downtime).
Fluxo
1. Challenge (servidor → quem conecta)
<hash> <nonce>\n ex.: SHA-256 aB3dEf_g\n| Campo | Conteúdo |
|---|---|
hash | Nome do algoritmo de digest. Atualmente sempre SHA-256, e o servidor não aceita outro |
nonce | Um valor aleatório de 8 caracteres em base64url. O enquadramento é delimitado por nova linha, então seu comprimento pode crescer no futuro — quem conecta deve tratar tudo após o primeiro espaço como o nonce |
2. Resposta (quem conecta → servidor)
<digest>\n
digest = base64url_nopad( SHA-256( token_bytes ∥ nonce_bytes ) )(∥ é concatenação de bytes — os bytes ASCII da string do nonce são anexados diretamente após os bytes brutos do token)
- base64url é o alfabeto seguro para URL, sem padding (
A–Z a–z 0–9 - _). Um digest SHA-256 tem sempre 43 caracteres. - O servidor verifica com uma comparação em tempo constante contra toda a lista de tokens configurada — qual token combinou, ou até onde uma comparação chegou, nunca vaza pela temporização.
- Um servidor sem tokens configurados aceita um único token vazio
"". Nesse caso, enviardigest = base64url(SHA-256(nonce))passa. A etapa de handshake em si nunca pode ser pulada. - A linha de resposta que o servidor lê tem um limite de 256 bytes.
3. Resultado
- Sucesso: o servidor não envia nada e passa diretamente ao protocolo principal — o protocolo binário de quadros do lock na porta do cliente, ou RPC com prefixo de comprimento na porta Raft. Envie a primeira requisição logo em seguida.
- Falha: o servidor envia
E auth_failede fecha a conexão. Se a conexão cair ou uma linha estiver malformada no meio do handshake, ele também pode simplesmente fechar silenciosamente, sem quadro de erro.
Terminologia
- Desafio-resposta (challenge-response) — um esquema de autenticação em que, em vez de enviar o segredo (token) diretamente, o servidor propõe um desafio único e quem conecta prova que conhece o segredo enviando de volta apenas a resposta.
- Nonce — um número usado uma única vez. Ele muda a cada conexão, então uma resposta roubada não pode ser reutilizada em um ataque de replay.
- Comparação em tempo constante — uma comparação que sempre leva a mesma quantidade de tempo, independentemente de até onde ela combinou, fechando ataques de temporização que, de outra forma, vazariam o segredo.
- base64url — uma variante do base64 que usa apenas um alfabeto seguro para URL (
A–Z a–z 0–9 - _). Usado aqui sem padding (=).