Códigos de erro ​

Estes são os códigos de erro comuns às bibliotecas de serviço oficialmente suportadas pelo DAT.

Cada código carrega dois valores — impacto e repetição — e alguns recebem ainda a etiqueta suspeita.

Impacto — o golpe que o serviço sofre ​

É o critério para disparar um alerta. Observa-se apenas uma coisa: "o serviço está parado neste momento?".

Sem impacto não é caso de alerta. Se toda a equipe de plantão tivesse que verificar porque uma entrada errada chegou uma única vez, o alerta perderia todo o sentido.

Suspeita — investigar se persistir ​

Os códigos com a etiqueta Suspeita fazem parte da operação normal quando aparecem isolados. O cliente pode enviar valores errados a qualquer momento, e o papel da biblioteca é justamente filtrá-los.

No entanto, se esses erros ocorrerem de forma persistente ou concentrados em uma origem específica, trata-se de um destes dois casos.

• Anomalia de configuração — implantação incorreta, clientes de uma versão antiga ainda em operação, ou certificados desalinhados.
• Tentativa de invasão — tentativa de passar na verificação com tokens ou chaves adulterados, ou uma varredura em busca de valores válidos.

Por isso, para esses códigos o correto é acompanhar a contagem como métrica. Basta avisar quando ultrapassar um limiar.

Repetição ​

Token ​

Problemas com a própria cadeia do token recebido.

Certificado ​

O formato da cadeia do certificado e a questão de saber se esse certificado pode ser usado agora.

DAT_CERT_NOT_FOUND e DAT_CERT_NOT_SYNCED apresentam os mesmos sintomas, mas exigem reações diferentes. O primeiro é um cid que nunca emitimos: esperar não muda nada. O segundo se resolve assim que a sincronização acontece.

Um DAT_CERT_NOT_FOUND isolado basta filtrar; se o número crescer de repente, é porque a implantação saiu do compasso ou há tokens falsificados circulando.

Assinatura ​

Criptografia ​

Problemas de cifragem e decifragem do payload secure.

Um payload secure vazio não é erro. Entrada vazia vira saída vazia, e nenhum código é emitido.

No caminho que pula a verificação de assinatura, a tag GCM é a única checagem de integridade. Por isso DAT_CRYPTO_TAG_MISMATCH não é agrupado com as demais falhas de decifragem sob um mesmo código.

Chave ​

Três casos parecidos, mas diferentes:

Gerenciador ​

O estado do objeto que guarda os certificados e é usado para emitir e verificar.

A causa (cause) de DAT_MANAGER_NO_ISSUABLE_CERTIFICATE é uma destas quatro. O que fazer difere completamente conforme a origem.

Se o servidor emissor estiver configurado para receber apenas certificados de verificação, aparece DAT_CERT_VERIFY_ONLY. Esperar nunca resolve, portanto não é caso de repetição.

Configuração ​

Problemas com os valores passados por quem chama. A família CONFIG é composta inteiramente por erros que precisam ser corrigidos no código; se aparecerem em produção, é porque a implantação está errada.

Interno ​

Problemas do ambiente de execução e do runtime.

DAT_INTERNAL_UNAVAILABLE se resolve corrigindo o ambiente de implantação; DAT_INTERNAL_UNKNOWN costuma ser uma falha de runtime ou um bug da biblioteca.

Sincronização do CMS ​

Sem a sincronização com o CMS, estes códigos não aparecem.

Os códigos em que a sincronização é considerada falha permanente (UNAUTHORIZED, FORBIDDEN, ENDPOINT_NOT_FOUND, MALFORMED, IMPORT_FAILED) são todos críticos. Repetir não resolve nada enquanto os certificados continuam expirando: se ficar sem tratamento, o serviço acabará necessariamente parando.

Já UNREACHABLE e SERVER_ERROR são parciais. Tudo continua com os certificados existentes e a sincronização se recupera sozinha no ciclo seguinte — mas se as falhas continuarem, no fim passa para crítico. Coloque o alerta sobre o número de falhas consecutivas.

Servidor ​

Códigos emitidos pelo servidor CMS. Os clientes não os geram, apenas os recebem.

Envelope de resposta:

{
  "code": "DAT_REQ_ALG_UNSUPPORTED",
  "details": { "algorithm": "BOGUS-ALG" }
}

Para os erros que surgem ao criar e manipular certificados, o servidor usa como estão os códigos comuns acima (DAT_CERT_*, DAT_KEY_*, DAT_CONFIG_*).

Ao receber um código do servidor ​

O cliente envolve o código do servidor no seu próprio código CMS e preserva o original em cause.

Buscar por sintoma ​

Apêndice ​

Sintaxe dos códigos ​

DAT_<área>_<causa>

• Quando a mesma causa ocorre em áreas diferentes, o nome da causa é idêntico. DAT_TOKEN_MALFORMED e DAT_CERT_MALFORMED diferem apenas no objeto; o sentido é o mesmo.
• _UNKNOWN é exclusivamente o recuo de cada área. Não é usado com outro sentido, como "algoritmo desconhecido" (para isso existe _UNSUPPORTED).
• A cadeia do código é um contrato público. A mensagem pode ser alterada livremente; o código, não.

Acesso conforme o cliente ​

Evento de segurança só retorna true nos dois casos em que a falsificação ou a adulteração é certa (DAT_SIG_MISMATCH, DAT_CRYPTO_TAG_MISMATCH). A etiqueta suspeita deste documento abrange mais (chegando a tokens, chaves e requisições adulterados); por ora é apenas uma classificação da documentação e não é exposta pela API do cliente.

O nível de impacto também é uma classificação da documentação. Um mesmo código pode atingir de formas diferentes conforme onde ocorre — DAT_KEY_INVALID, por exemplo, não tem impacto quando serve para filtrar um token recebido, mas faz toda a sincronização fracassar quando ocorre ao ler um certificado durante a sincronização com o CMS.

As causas subjacentes não são perdidas. DAT_MANAGER_NO_ISSUABLE_CERTIFICATE e DAT_CMS_IMPORT_FAILED transmitem a origem pelo encadeamento de exceções de cada linguagem (cause / __cause__ / InnerException / Unwrap()).