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

Guia de Implementação da SES GO - Segurança - Local Development build (v0.0.2) built by the FHIR (HL7® FHIR® Standard) Build Tools. 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://www.gov.br/iti/pt-br/assuntos/repositorio/certificados-das-acs-da-icp-brasil-arquivo-unico-compactado/ACcompactado.zip.
  • URL do arquivo de hash: https://www.gov.br/iti/pt-br/assuntos/repositorio/certificados-das-acs-da-icp-brasil-arquivo-unico-compactado/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 em memória obtido de um repositório local atualizado com o conteúdo do trust store ICP-Brasil. 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 brutos baixados do ITI (arquivo de certificados .zip e arquivo de hash .txt). Não contém índices.

  • 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.

Entradas

  1. Endereço (URL) do arquivo de certificados.
  2. Endereço (URL) do arquivo contendo o hash do arquivo de certificados.
  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. TTL do cache de consulta: padrão 24 horas, intervalo [1, 168].

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

1 Verificação de disponibilidade do repositório local

  • Verifique se o repositório local contém os arquivos de certificados (item 1 da entrada) e de hash (item 2 da entrada).
  • Se ambos os arquivos não estiverem disponíveis no repositório local, prossiga para o download (seção 3).
  • Se ambos os arquivos estiverem disponíveis no repositório local, continue normalmente na próxima seção.

2 Verificação de atualização

2.1 Faça o download do arquivo de hash (item 2).

2.2 Se o download é bem-sucedido:

  • Recupere o conteúdo do arquivo de hash baixado e compare com o conteúdo do arquivo de hash disponível no repositório local.
  • Se os hashes coincidem, o cache local está atualizado. Prossiga para a validação de integridade (seção 5).
  • Se os hashes não coincidem, prossiga para o download completo (seção 3).

2.3 As ações abaixo são executadas, na ordem abaixo, apenas se o download falhar após o número máximo de tentativas.

2.4 Análise do cache local

  • Verifique a idade do cache local (timestamp da última atualização bem-sucedida)
  • Se cache < TTL_CRÍTICO (padrão: 72 horas):
    • Registre WARNING: "Falha na verificação de atualização, utilizando cache local válido"
    • Prossiga para validação de integridade (seção 5)
    • Configure flag: CACHE_STATUS = "STALE_BUT_VALID"
  • Se cache >= TTL_CRÍTICO mas < TTL_MÁXIMO (padrão: 168 horas):
    • Registre ALERT: "Cache crítico - falha prolongada na verificação de atualização"
    • Prossiga para validação de integridade (seção 5)
    • Configure flag: CACHE_STATUS = "CRITICAL_STALE"
    • Notifique administradores via canal de alertas
  • Se cache >= TTL_MÁXIMO:
    • Registre ERROR: "Cache expirado - impossível garantir segurança"
    • Retorne CACHE.EXPIRED-UNSAFE

3 Download do arquivo de certificados

  • Baixe o arquivo de certificados do endereço fornecido (item 1) no repositório local.
  • O arquivo contém todos os certificados das ACs da ICP-Brasil compactados (.zip).
  • Se o download falhar após o número máximo de tentativas, retorne NETWORK.ZIP-DOWNLOAD-FAILED.

4 Download do arquivo de hash

  • Baixe o arquivo de hash do endereço fornecido (item 2) no repositório local.
  • O arquivo contém o hash SHA-512 do arquivo de certificados (.zip).
  • Se o download falhar após o número máximo de tentativas, retorne NETWORK.HASH-DOWNLOAD-FAILED.

5 Validação de integridade

  • Calcule o hash SHA-512 do arquivo de certificados disponível no repositório local.
  • Obtenha o conteúdo do arquivo de hash disponível no repositório local.
  • Compare o hash calculado com aquele recuperado do conteúdo do arquivo de hash.
  • Se os hashes não coincidem:
    • Descarte os arquivos do repositório local (arquivo de certificados e o arquivo de hash).
    • Retorne SECURITY.HASH-VALIDATION-FAILED.

6 Extração e processamento dos certificados

  • Extraia o conteúdo do arquivo ZIP.
  • Para cada certificado encontrado:
    • Valide o formato X.509 do certificado.
    • Calcule o hash SHA-256 do certificado em formato DER.
    • Verifique se o certificado contém extensão Certificate Policies com OID iniciado por 2.16.76.1.
    • Se algum certificado for inválido, retorne CERT.INVALID-FORMAT.
    • Se algum certificado não for ICP-Brasil, retorne CERT.NOT-ICP-BRASIL.

7 Montagem do cache de consulta

  • Crie índices para consultas eficientes:
    • Índice por tipo de AC: raiz, intermediária e folha (end entity).
    • Índice por período de validade (Not Before / Not After).
    • Índice por Subject DN (normalizado para busca parcial).
    • Índice por SKI (Subject Key Identifier).
    • Índice por hash SHA-256 para acesso direto.
  • Configure metadados de consulta:
    • Estatísticas de distribuição por tipo de AC.
    • Períodos de validade mínimos e máximos.
    • Contadores de certificados por emissor.
    • Timestamp de última atualização dos índices.
  • Valide a integridade dos índices:
    • Confirme que todos os certificados estão indexados.
    • Verifique consistência entre índices e dados.
    • Se algum índice estiver corrompido, reconstrúa-o.
  • Em caso de falha na montagem:
    • Se a criação de índices falhar, retorne STORAGE.INDEX-CREATION-FAILED.
    • Se a validação de índices falhar, retorne STORAGE.INDEX-VALIDATION-FAILED.

8 Invalidação do cache

O cache de consulta em memória, montado conforme a seção 7, será considerado inválido se o tempo decorrido desde a sua montagem for superior ao valor definido no TTL do cache de consulta (item 5 da entrada). Qualquer nova solicitação de consulta a um cache invalidado exigirá a sua reconstrução, executando novamente o processo a partir da seção 1.

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.
  • O TTL do cache deve ser configurado considerando a frequência de atualizações do repositório oficial.
  • 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_POR_TTL O cache em memória foi invalidado porque seu tempo de vida (TTL) expirou. Timestamp, TTL configurado, idade do cache no momento da invalidação.

Relação com outros casos de uso