Guia de Implementação da SES GO - Segurança
0.1.0 - draft Brazil flag

Guia de Implementação da SES GO - Segurança - Downloaded Version 0.1.0 See the Directory of published versions

Disponibilizar cache

O trust store ICP-Brasil é fundamental para a validação de certificados e construção de cadeias de confiança. Toda operação de criação de assinatura e validação depende de acesso eficiente ao trust store.

Trust store ICP-Brasil

O ITI (ICP-Brasil) disponibiliza o trust store para uso amplo:

  • URL do arquivo de certificados: https://acraiz.icpbrasil.gov.br/credenciadas/CertificadosAC-ICP-Brasil/ACcompactado.zip.
  • URL do arquivo de hash: https://acraiz.icpbrasil.gov.br/credenciadas/CertificadosAC-ICP-Brasil/hashsha512.txt.
  • O arquivo de certificados (.zip) conteḿ um arquivo .crt para cada Autoridade Certificadora (AC) vigente.
  • O arquivo .crt está no formato PEM (sem proteção).
  • O conteúdo PEM apenas "embrulha" o conteúdo binário do certificado X.509v3 no formato DER.
  • O arquivo de hash contém o valor de hash SHA-512 do arquivo .zip, útil para verificação de integridade.

Este caso de uso é dependente da estratégia de distribuição adotada pelo ITI (ICP-Brasil), assim como do conteúdo detalhado acima. Qualquer mudança na distribuição e no formato do trust store exige alteração do presente caso de uso.

Objetivo

Disponibilizar um cache do trust store em um repositório local. O cache deve oferecer acesso eficiente aos certificados das Autoridades Certificadoras (AC) vigentes na ICP-Brasil.

Termos e definições

  • Cache de consulta: armazenamento/estrutura de dados em memória com os certificados processados e os índices de busca. É derivado do conteúdo do repositório local e otimizado para consultas.

  • Repositório local: armazenamento persistente dos artefatos conforme baixados do ITI (arquivo de certificados .zip e arquivo de hash .txt). Não contém índices.

  • Repositório temporário: armazenamento utilizado temporariamente durante operação de download, seja do arquivo de certificados ou do valor de hash correspondente.

  • Trust store ICP-Brasil: repositório contendo o conjunto de certificados vigentes de todas as autoridades certificadoras ICP-Brasil. Ou seja, é o conjunto de certificados nos quais as operações de criação e validação de assinaturas digitais confiam.

  • Última confirmação é o timestamp da última operação de download bem-sucedida dos arquivos do trust store cuja integridade foi verificada no repositório local. Esta informação é registrada no arquivo ultima-confirmacao.txt.

Entradas

  1. Endereço (URL) do arquivo de certificados (trust store ICP-Brasil).
  2. Endereço (URL) do arquivo contendo o hash do arquivo de certificados (trust store ICP-Brasil).
  3. Configurações de rede:
    • Timeout de download: padrão 60 segundos, intervalo [30, 300].
    • Número máximo de tentativas: padrão 3, intervalo [1, 10].
    • Intervalo entre tentativas: padrão 30 segundos, intervalo [10, 300].
  4. Repositório local: caminho para armazenamento persistente dos certificados.
  5. Período para recuperação de trust store atualizado (REFRESH_INTERVAL): padrão 6 horas; intervalo [1, TTL_CRITICO); deve ser estritamente menor que TTL_CRITICO.
  6. TTL_CRITICO do trust store: padrão 72 horas, intervalo [24, 168). Deve ser menor que TTL_MAXIMO.
  7. TTL_MAXIMO do trust store: padrão 168 horas, intervalo (72, 720]. Deve ser maior que TTL_CRITICO.

Saída

Para operação de atualização:

  • Status de sucesso ou código de erro específico.
  • Metadados de atualização: data/hora, hash do arquivo fonte, número de certificados processados.

Para operação de consulta:

  • Array de certificados ICP-Brasil que atendem aos critérios de busca.
  • Metadados da consulta: total de resultados, tempo de resposta, fonte dos dados (cache/atualização).
  • Se nenhum certificado for encontrado, retorne array vazio.

Processo 0: disponibilizar cache

  • Repetir a cada REFRESH_INTERVAL
    • Assegurar disponibilidade local (processo 1)
    • Recomendações operacionais:
      • Em caso de falha de verificação/atualização, utilize backoff exponencial com limite máximo inferior a TTL_CRITICO, garantindo múltiplas tentativas antes do estado crítico.

Processo 1: assegurar disponibilidade local

  • Identificar e limpar o repositório temporário
  • Identificar o repositório local
  • Assegurar disponibilidade (processo 2)
  • Se a disponibilidade é TEMPORARIO
    • Validar integridade (repositório temporário) (processo 4).
    • Se SECURITY.HASH-VALIDATION-FAILED (a integridade está comprometida)
      • Limpe o repositório temporário.
      • Registre a falha.
      • Gere CACHE.UNAVAILABLE (cache não será disponibilizado).
    • Se a integridade é satisfeita, transfira os arquivos do repositório temporario, a saber, ultima-confirmacao.txt, ACcompactado.zip e hashsha512.txt, para o repositório local.
    • Se a transferência falhar:
      • Registre a falha.
      • Gere CACHE.UNAVAILABLE (cache não será disponibilizado).
  • Se a disponibilidade é LOCAL
    • Download do arquivo de hash (processo 7)
    • Se o download falhar
      • Assegurar não expiração (processo 5)
      • Retorne. Dados não necessariamente são atuais, mas não considerados expirados.
    • Se o download for executado satisfatoriamente, compare o conteúdo do arquivo de hash baixado com o conteúdo do arquivo de hash disponível no repositório local.
    • Se os hashes coincidem, o repositório local está atualizado.
      • Atualize o instante da última confirmação com o instante corrente (ultima-confirmacao.txt).
    • Se os hashes não coincidem (há versão mais nova do trust store)
      • Download do arquivo de certificados (processo 6)
      • Se o download falhar
        • Registre a falha.
        • Gere CACHE.UNAVAILABLE (cache não será disponibilizado).
      • Se o download for executado satisfatoriamente
        • Validar integridade (repositório local) (processo 4).
        • Se a resposta é SECURITY.HASH-VALIDATION-FAILED (a integridade está comprometida)
          • Registre a falha.
          • Gere CACHE.UNAVAILABLE (cache não será disponibilizado).

Processo 2: assegurar disponibilidade

  • Verificar repositório local (processo 3).
  • Se o retorno é DISPONIVEL
    • Retorne LOCAL.
  • Se o retorno é NAO_DISPONIVEL
    • Limpar o repositório local.
    • Download de arquivos (processo 8).
    • Se o download falhar
      • Registre a falha
      • Gere CACHE.UNAVAILABLE (cache não será disponibilizado)
    • Se o download for executado satisfatoriamente
      • Retorne TEMPORARIO.

Processo 3: verificar repositório local

  • Verifique se o repositório local contém os arquivos ultima-confirmacao.txt, ACcompactado.zip e hashsha512.txt.
  • Se pelo menos um dos arquivos não estiver disponível no repositório local
    • Retorne NAO_DISPONIVEL
  • Se os três arquivos estiverem disponíveis no repositório local
    • Retorne DISPONIVEL

Processo 4: validar integridade (repositório local ou temporário)

  • Arquivos ACcompactado.zip e hashsha512.txt devem estar disponíveis no repositório.
  • Calcule o hash SHA-512 do arquivo ACcompactado.zip disponível no repositório.
  • Obtenha o conteúdo do arquivo de hashsha512.txt disponível no repositório.
  • Compare o hash calculado com aquele recuperado do conteúdo do arquivo de hash.
  • Se os hashes não coincidem:
    • Retorne SECURITY.HASH-VALIDATION-FAILED.
  • Se os hashes coincidem:
    • Atualize ultima-confirmacao.txt com o instante corrente.
    • Retorne OK

Processo 5: assegurar não expiração

  • Recupere o instante da última confirmação bem-sucedida em ultima-confirmacao.txt.
  • Defina idade como o instante atual menos a última confirmação.
  • Se idade < TTL_CRITICO (padrão: 72 horas):
    • Registre WARNING: "Falha na verificação de atualização, utilizando cache local válido"
    • Defina status do cache como STALE_BUT_VALID
  • Se idade >= TTL_CRITICO mas < TTL_MAXIMO (padrão: 168 horas):
    • Registre alerta: "Cache crítico - falha prolongada na verificação de atualização"
    • Defina status do cache como CRITICAL_STALE
    • Notifique operador
  • Se idade >= TTL_MAXIMO:
    • Registre erro: "Cache expirado - não há como garantir segurança"
    • Gere CACHE.EXPIRED-UNSAFE (cache não será disponibilizado)

Processo 6: download do arquivo de certificados

  • Baixe o arquivo de certificados do endereço fornecido (item 1) no repositório temporário.
  • Se o download falhar retorne NETWORK.ZIP-DOWNLOAD-FAILED.

Processo 7: download do arquivo de hash

  • Baixe o arquivo de hash do endereço fornecido (item 2) no repositório temporário.
  • Se o download falhar retorne NETWORK.HASH-DOWNLOAD-FAILED.

Processo 8: download de arquivos

  • Download do arquivo de certificados (processo 6).
  • Se falhar, então retorne NETWORK.ZIP-DOWNLOAD-FAILED.
  • Download do arquivo de hash (processo 7).
  • Se falhar, então retorne NETWORK.HASH-DOWNLOAD-FAILED.
  • Retorne OK

Processo 9: processamento do trust store

  • Extraia o conteúdo do arquivo zip.
  • Para cada certificado (arquivo .crt contido no zip):
    • Valide o formato X.509 do certificado.
    • Se for inválido, gere CERT.INVALID-FORMAT.
    • Verifique se o certificado contém extensão Certificate Policies com OID iniciado por 2.16.76.1.
    • Se algum certificado não for ICP-Brasil, gere CERT.NOT-ICP-BRASIL.

Processo 10: montagem do cache

  • Crie índices para consultas eficientes:
    • Índice por Subject DN (normalizado para busca parcial).
    • Índice por SKI (Subject Key Identifier).
    • Índice por hash SHA-256 do formato DER do certificado.
  • Em caso de falha na montagem:
    • Se a criação de índices falhar
      • Registre STORAGE.INDEX-CREATION-FAILED
      • Gere CACHE.UNAVAILABLE (cache não será disponibilizado).
    • Se a validação de índices falhar
      • Registre STORAGE.INDEX-VALIDATION-FAILED
      • Gere CACHE.UNAVAILABLE (cache não será disponibilizado).

Processo 11: invalidação do cache

O cache de consulta em memória, montado conforme o Processo 10, será invalidado e reconstruído de forma dirigida a eventos:

  • Quando houver atualização bem-sucedida do trust store (hash diferente do armazenado localmente).
  • Quando a aplicação iniciar e o cache ainda não existir (primeiro uso).
  • Por ação operacional (invalidação manual via ferramenta/rotina administrativa).
  • Em caso de falha na criação/validação de índices (Processo 10), após correção do problema.

Ao detectar qualquer um desses eventos, invalide o cache atual e reconstrua-o executando novamente a partir do Processo 10.

Observações

  • O processo de atualização deve ser executado periodicamente (recomendado: diariamente) para manter o trust store atualizado.
  • A validação de hash é obrigatória por padrão para garantir a integridade dos certificados baixados.
  • O cache local deve ser persistente e resistente a falhas de sistema.
  • Os índices devem ser otimizados para consultas frequentes por tipo de AC, período de validade e DN.
  • A invalidação do cache é dirigida a eventos (atualização do trust store, inicialização sem cache, invalidação manual, falha de índices). Recomenda-se reconstrução imediata após atualização bem-sucedida do trust store.
  • A reconstrução de índices deve ser eficiente para minimizar tempo de indisponibilidade.

Auditoria

A seguir são detalhados os eventos relevantes para auditoria. Estes eventos devem ser registrados conforme o caso de uso de auditoria.

Eventos críticos de segurança

Eventos que exigem ação imediata.

Evento Descrição Dados relevantes para registrar
FALHA_VALIDACAO_HASH O evento mais crítico. O hash do arquivo de certificados baixado não corresponde ao hash esperado. Isso pode indicar corrupção de dados ou uma tentativa de ataque (adulteração). Timestamp, IP de origem (do repositório), URL do arquivo, hash esperado, hash calculado.
CACHE_EXPIRADO_INSEGURO O sistema está operando sem um trust store válido porque o cache local está muito antigo e todas as tentativas de atualização falharam. Timestamp, idade do cache local, data da última atualização bem-sucedida.
CERTIFICADO_INVALIDO Um certificado dentro do pacote do ITI falhou na validação de formato (X.509) ou não pertence à ICP-Brasil. Timestamp, nome/assunto do certificado problemático, motivo da falha (CERT.INVALID-FORMAT ou CERT.NOT-ICP-BRASIL).

Eventos de alerta

Eventos que demandam atenção.

Evento Descrição Dados relevantes para registrar
FALHA_DOWNLOAD O sistema não conseguiu baixar o arquivo de certificados ou o arquivo de hash após todas as tentativas. Timestamp, URL do arquivo, código do erro de rede, número de tentativas.
USO_CACHE_DESATUALIZADO Uma falha na verificação de atualização forçou o sistema a usar o cache local, que está válido, mas não é o mais recente (CACHE.STALE-BUT-VALID). Timestamp, idade do cache local.
FALHA_MONTAGEM_CACHE Ocorreu um erro ao criar ou validar os índices do cache em memória. A aplicação pode não conseguir servir consultas. Timestamp, detalhes do erro (STORAGE.INDEX-CREATION-FAILED ou STORAGE.INDEX-VALIDATION-FAILED).

Eventos de rotina

Evento Descrição Dados relevantes para registrar
INICIO_ATUALIZACAO O processo de verificação e atualização do trust store foi iniciado. Timestamp, motivo (ex: "agendado", "manual", "cache invalidado").
ATUALIZACAO_CONCLUIDA O trust store foi atualizado com sucesso a partir de uma nova versão encontrada na fonte. Timestamp, hash anterior, novo hash, número de certificados processados.
CACHE_JA_ATUALIZADO Verificação concluiu que o cache local já estava na versão mais recente. Timestamp, hash verificado.
CACHE_INVALIDADO O cache em memória foi invalidado por evento. Timestamp, motivo ("atualizacao_trust_store", "inicializacao", "invalidação_manual", "falha_indices").

Relação com outros casos de uso