Guias de Desenvolvimento

Política e Conformidade

Signing Sessions

Guias dos SDKs

Rotação de Chaves e Segredos

A AUP exige rotação periódica de credenciais. Este guia detalha como rotacionar cada tipo de chave sem downtime.

Tipos de credenciais e cadência mínima

Credencial Onde vive Cadência obrigatória Imediata em caso de...
client_secret (OAuth2 client_credentials) Painel admin → API Keys 12 meses Exposição em log, repo público, ticket; saída de pessoa-chave; mudança ambiental
Chave privada JWT ES256 (Private Key JWT) Seu HSM ou secret manager 12 meses Mesmo que client_secret
Webhook signing secret Painel admin → Webhooks 12 meses Endpoint comprometido, dump de log do receiver
Certificado mTLS de cliente Seu emissor de certificado interno Antes da expiração (você define) Comprometimento da chave privada
Certificado ICP-Brasil A1 do tenant (assinatura corporativa, se aplicável) Painel admin → Configurações → Certificados 1 ano (validade do A1) Comprometimento da .pfx; revogação pela AC

Padrão de rotação sem downtime

A SignDocs Brasil suporta dois segredos ativos simultâneos para client_secret e webhook secret durante uma janela de overlap. Padrão:

  1. Criar a nova credencial no painel admin → ela fica ativa imediatamente, mas a antiga continua válida.
  2. Implantar a nova credencial no seu serviço, idealmente em modo "ambas aceitas" (cache em memória de ambos os secrets, com prioridade na nova) por algumas horas.
  3. Confirmar uso da nova monitorando logs/métricas — Last-Used no painel deve mostrar uso recente da nova credencial.
  4. Revogar a antiga no painel.
  5. Remover a antiga do seu serviço/secret manager.

Por tipo de credencial

client_secret OAuth2

Painel → API Keys → Selecionar credencial → "Rotacionar"

Recebe um novo client_secret (formato sds_secret_...). Os dois ficam válidos por até 90 dias; você revoga a antiga manualmente quando estiver pronto.

Recomendação: nunca confie no overlap automático para revogação. Sempre revogue explicitamente após confirmar uso da nova.

Chave privada JWT ES256 (Private Key JWT)

Para tenants que autenticam com Private Key JWT em vez de client_secret:

  1. Gerar nova chave EC P-256 localmente: openssl ecparam -name prime256v1 -genkey -noout -out new-private.pem
  2. Extrair pública: openssl ec -in new-private.pem -pubout -out new-public.pem
  3. No painel admin, anexar a nova chave pública como chave adicional (não substitui a anterior).
  4. Cada chave tem um kid (Key ID) próprio. Atualizar seu serviço para emitir JWT assertions com o novo kid.
  5. Após confirmar uso, remover a chave antiga no painel.

Webhook signing secret

Painel → Webhooks → Selecionar webhook → "Rotacionar segredo"

Recebe um novo segredo. Por 48 horas, a SignDocs Brasil envia eventos assinados com ambos os segredos (header X-SignDocs-Signature carrega duas assinaturas separadas por vírgula). Seu receiver deve aceitar qualquer uma das duas.

function verifyWebhook(rawBody: string, header: string, secrets: string[]): boolean {
  const signatures = header.split(',').map(s => s.trim());
  for (const sig of signatures) {
    for (const secret of secrets) {
      const expected = hmac256(rawBody, secret);
      if (timingSafeEqual(sig, expected)) return true;
    }
  }
  return false;
}

Após 48h, o segredo antigo é desativado automaticamente.

Certificado mTLS de cliente

Os endpoints mtls-api.signdocs.com.br e mtls-api-hml.signdocs.com.br exigem certificado de cliente. A SignDocs Brasil aceita até 3 cadeias de certificação confiáveis por tenant — então rotação é por adição:

  1. Gerar nova chave + CSR localmente.
  2. Anexar a nova chave pública ao tenant via painel admin.
  3. Cliente HTTP passa a usar a nova chave/cert.
  4. Após validação, remover a chave antiga do tenant.

Certificado ICP-Brasil A1 do tenant (assinatura corporativa)

Para tenants que usam um certificado A1 corporativo único para assinar Evidence Packs em nome da empresa:

  1. Adquirir novo certificado A1 junto a uma AC ICP-Brasil credenciada antes do antigo expirar.
  2. Upload do novo .pfx no painel admin → Certificados.
  3. O painel valida a cadeia ICP-Brasil e marca o novo cert como ativo.
  4. Documentos assinados a partir do timestamp da troca usam o novo cert; documentos anteriores permanecem inalterados (Evidence Packs antigos continuam verificáveis pelo certificado antigo, que fica em arquivo).
  5. Eliminar o .pfx da máquina onde foi feito o upload.

Princípio do menor privilégio

Use chaves separadas por aplicação, ambiente e função:

prod/api-server/client_id   ←  servidor backend, escopos completos
prod/cron-job/client_id     ←  job batch, escopos limitados a transactions:read
hml/api-server/client_id    ←  HML
hml/integration-tests/client_id  ←  CI, escopos mínimos

Comprometimento de uma só limita o blast radius. Vetor comum: chave de produção em commit publico → atacante exfiltra evidências de meses. Mitigação: keys de menor privilégio + rotação imediata + monitoramento Last-Used no painel.

Detecção de exposição

A SignDocs Brasil monitora algumas heurísticas de comprometimento:

Em caso de auto-revogação, o painel mostra o motivo e oferece fluxo de "rotação de emergência" — o tenant precisa autenticar com 2FA elevado para gerar novo secret.

Reportar suspeita de exposição

security@signdocs.com.br. Inclua:

A SignDocs Brasil ajuda na análise de logs para confirmar uso indevido. Inclui auditoria documental para Enterprise se exigida.

Cross-references