cybercore-systems/cybercore-signer
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
feature/pdf-signing-flow
cybercore-signer/docs/pades.md
T

9.9 KiB
Raw Permalink Blame History

alt text# Assinaturas PDF (PAdES) e Selos Visuais em SVG

Este documento descreve a arquitetura e o funcionamento da assinatura digital de arquivos PDF no padrão PAdES (PDF Advanced Electronic Signatures) no CyberCore Signer, incluindo o subsistema de selos visuais temáticos baseados em SVG.

1. Visão Geral da Arquitetura

O CyberCore Signer implementa assinatura PAdES em dois modos complementares:

  1. Modo Desacoplado via Protocolo CCSP/1 (Web): A aplicação web prepara a estrutura /ByteRange, envia apenas o digest SHA-256 e o CyberCore assina localmente com o certificado A1/A3 sem expor a chave privada.
  2. Modo Desktop Completo (Desktop UI): O usuário seleciona um arquivo PDF localmente, escolhe o certificado ICP-Brasil, customiza o selo visual e o PdfSigningService gera o PDF assinado completo com envelope CMS/PKCS#7 e estampa gráfica.
graph TD
    A[Arquivo PDF Original] --> B[PdfSigningService]
    C[Tema de Selo SVG] --> D[PdfSealRenderer Java2D]
    E[Metadados Signatário] --> D
    D -->|Estampa Visual 300 DPI| B
    F[Chave Privada A1/A3] --> G[Bouncy Castle CMS Generator]
    B -->|PAdES Incremental| H[PDF Assinado Digitalmente]
    G --> H

2. Subsistema de Selos Visuais em SVG e Temas

O selo visual é uma representação gráfica da assinatura estipulada em conformidade com as recomendações do ITI e MP nº 2.200-2/2001.

2.1 Temas Pré-configurados e Ícones Vetoriais (PdfSealThemeRegistry & PdfSealRenderer)

Os brasões e ícones padrão do sistema ficam centralizados em:

  • Catálogo de Temas: modules/cybercore-core/.../pdf/seal/PdfSealThemeRegistry.java (definição de cores, dimensões, textos padrão e tipo de ícone).
  • Desenho Vetorial Java2D: modules/cybercore-core/.../pdf/seal/PdfSealRenderer.drawThemeIcon() (renderização matemática em Java2D dos brasões padrão: shield, star, crystal, notary, etc.).
ID do Tema Nome Descrição Ícone Vetorial
icp-brasil ICP-Brasil Oficial Padrão clássico com brasão e cadeado verde/azul Escudo e cadeado
cybercore-modern CyberCore Modern Estilo tecnológico neon com cristal multifacetado Cristal vetorial
minimal-clean Minimalista Clean Monocromático para relatórios executivos sóbrios Carimbo notarial com check
gov-br Gov.br Oficial Identidade visual Verde-Oliva conforme MP 2.200-2/2001 Brasão estelar estilizado

2.2 Renderização Gráfica (PdfSealRenderer)

  • O núcleo cybercore-core não depende de JavaFX, atendendo às regras estritas de arquitetura (ArchitectureTest).
  • A renderização é efetuada através da API Java2D (AWT) nativa com anti-aliasing duplo (RenderingHints.VALUE_ANTIALIAS_ON, subpixel text, escala 2x / 300 DPI).
  • Exporta tanto BufferedImage quanto byte[] PNG para inclusão no PDFBox ou pré-visualização dinâmica na interface com ImageView.

2.3 Criação, Instalação e Privacidade de Selos Personalizados

  • Foco Exclusivo no Titular (Sem Emissor/AC no Gráfico): O selo foi desenhado para ser limpo e elegante. Dados técnicos do certificado e o emissor da Autoridade Certificadora não são exibidos no gráfico do selo, evitando poluição visual.
  • Obrigatoriedade do Nome Completo: O renderizador calcula dinamicamente a métrica de fontes via drawFittedText() para garantir que o nome completo do signatário seja sempre exibido na íntegra, com destaque tipográfico (13.5pt a 14.5pt em negrito), sem cortes ou truncamentos.
  • Upload de Logotipo / Emblema Próprio: Suporte a upload de imagens de logotipos (PNG, JPG, BMP) armazenadas de forma portável em Base64 dentro do tema, com renderização redimensionada e anti-aliasing de 300 DPI.
  • Campos Customizáveis (Matrícula, Cargo, OAB, etc.): Permite definir rótulo e valor padrão no tema (ex: Matrícula: 104829/SP ou Cargo: Auditor Fiscal) ou informar pontualmente durante a assinatura via customExtraInfo. A informação é posicionada de forma harmônica na linha de identificação do signatário.
  • Privacidade do CPF (LGPD): O modelo CpfDisplayMode suporta três modalidades:
    • FULL: exibe o documento completo (CPF: 123.456.789-00).
    • MASKED: mascara dígitos sensíveis (CPF: ***.456.789-**).
    • NONE: oculta totalmente o CPF do gráfico do selo.
  • Data e Hora Opcional: Parâmetro booleano para incluir ou suprimir data/hora no gráfico.
  • Instalação e Persistência Local: Através de CustomSealStorage, novos selos criados ou importados são salvos em ~/.cybercore/seals/*.json e registrados dinamicamente no PdfSealThemeRegistry.

2.4 Gerenciamento Centralizado de Selos (SealManagementDialog)

  • Lista Completa: Exibição unificada de selos embutidos do sistema e selos personalizados instalados pelo usuário.
  • Selo Padrão Ativo: Permite definir qual selo é o padrão ativo para todas as assinaturas do usuário, gravado em AgentConfiguration (defaultSealThemeId).
  • Pré-visualização em Tempo Real: Renderização fiel do selo com dados de exemplo ao navegar pela lista.
  • Clonagem e Edição: Permite duplicar qualquer selo (inclusive os embutidos) e abri-lo no SealDesignerDialog para customização.
  • Importação e Exportação: Exportação de temas em arquivos .json e importação com um clique para compartilhamento entre máquinas e equipes.

3. Posicionamento e Pré-Visualização Interativa

A posição e a página da estampa são parametrizáveis via PdfSignatureOptions:

  • Posições Automáticas: BOTTOM_RIGHT, BOTTOM_LEFT, TOP_RIGHT, TOP_LEFT.
  • Posição Interativa Personalizada (CUSTOM): O usuário clica ou arrasta o selo diretamente sobre a página do PDF na interface gráfica. As coordenadas na tela são matematicamente mapeadas para as coordenadas de mídia do PDFBox: X_{pdf} = \frac{X_{clique}}{Largura_{view}} \times Largura_{pdf} Y_{pdf} = Altura_{pdf} - \left(\frac{Y_{clique}}{Altura_{view}} \times Altura_{pdf}\right) - Altura_{selo}
  • Páginas: LAST_PAGE (recomendado), FIRST_PAGE, ALL_PAGES, ou página específica numérica (targetPageNumber).
  • Dimensões padrão: 200 pt de largura por 55 pt de altura, com margens de segurança e clamping contra extravasamento.
  • Renderização da Folha: O PdfSigningService fornece renderPagePngBytes(pdfBytes, pageIndex, dpi) via PDFBox PDFRenderer, permitindo que o diálogo da UI JavaFX renderize a folha de papel em background thread com paginação e sobreposição visual do selo.

4. Estrutura Criptográfica PAdES

  • Motor: Apache PDFBox 3.0.4 + Bouncy Castle 1.80 (bcpkix-jdk18on).
  • Filtro: /Filter /Adobe.PPKLite e /SubFilter /adbe.pkcs7.detached.
  • Algoritmo: SHA256withRSA / PKCS#1 v1.5 com digest SHA-256.
  • Salva Incremental: Preserva a integridade de assinaturas anteriores e do documento original sem quebrar certificações prévias.

5. Ferramentas Web do SDK (@cybercore/signer-sdk)

O SDK web fornece componentes visuais nativos em JavaScript vanilla para aplicações web:

5.1 PdfStampPicker (Posicionador Visual de Selo)

Permite que o usuário final suba um PDF no navegador, folheie páginas, selecione cantos predefinidos ou arraste a estampa visual interativamente. O componente mapeia as coordenadas do canvas para o sistema de coordenadas do PDFBox (ISO 32000, com origem no canto inferior esquerdo) e gera em tempo real o payload JSON para a requisição.

import { PdfStampPicker } from '@cybercore/signer-sdk';

const picker = new PdfStampPicker({
  container: '#picker-container',
  pdfSource: pdfArrayBuffer, // ou URL / Base64
  initialScale: 1.0,
  onPositionChange: (pos) => {
    console.log('Página:', pos.page, 'X:', pos.x, 'Y:', pos.y);
  }
});

// Obtém parâmetros prontos para a requisição CCSP
const stampConfig = picker.getStampConfig();

5.2 PdfSealDesigner (Criador & Personalizador de Selos)

Componente interativo com live preview em SVG vetorial para personalização de selos:

  • Paleta de cores primária, secundária, fundo e texto.
  • Ícones vetoriais (shield, certificate, lock) e upload de logotipo em Base64.
  • Regras LGPD para mascaramento ou ocultação de CPF/CNPJ.
  • Exportação da configuração JSON para envio inline via seal_custom na requisição signPdfDocument().

5.3 Assinatura Completa via Base64 (signPdfDocument)

Permite enviar o PDF completo em Base64 e receber de volta o PDF assinado completo em Base64 para envio direto ao backend:

const result = await signer.signPdfDocument({
  certificateId: cert.id,
  pdf: pdfArrayBuffer, // ou base64
  page: stampConfig.page,
  x: stampConfig.x,
  y: stampConfig.y,
  scale: stampConfig.scale,
  seal_theme_id: 'icp-brasil', // ou seal_custom: customSealConfig
  reason: 'Documento homologado',
  location: 'São Paulo, SP'
});

console.log('PDF Assinado Base64:', result.signed_pdf);
console.log('SHA-256 do Documento Final:', result.sha256);

6. Políticas de Assinatura ICP-Brasil (DOC-ICP-15)

O padrão brasileiro de assinaturas digitais mantido pelo ITI prevê quatro perfis progressivos de conformidade:

Política Denominação Status no CyberCore Signer Componentes Arquiteturais
AD-RB Assinatura com Referência Básica Homologado / Ativo Envelope PAdES detached CMS com selo Java2D e /ByteRange validado pelo ITI
AD-RT Assinatura com Referência de Tempo Em Integração Cliente TSA RFC 3161 resiliente (TsaClient) com retentativas e fallback
AD-RC Assinatura com Referências Completas Roadmap Validador de cadeia (CertificateChainValidator) e cache de revogação (RevocationCache)
AD-RA Assinatura com Referência para Arquivamento Roadmap Dicionário LTV (/DSS) embutido no PDF com carimbos periódicos de arquivo
Reference in New Issue View Git Blame Copy Permalink