Como funciona
Sessão, política, contexto de segurança, extensão e agente: o vocabulário da API.
Os atores#
| Quem | O que faz |
|---|---|
| Usuário | A pessoa que assina. Tem um certificado digital (token A3, arquivo A1 ou nuvem) no próprio computador. |
| Seu navegador (front-end) | Mostra os certificados, pede a assinatura à extensão e conversa só com o seu servidor. |
| Seu servidor (back-end) | Guarda a chave de API e fala com a API ShieldSign PKI: inicia, prepara e conclui a assinatura. |
| API ShieldSign PKI | Valida o certificado, monta o PDF para assinatura, incorpora a assinatura e o carimbo de tempo e devolve o documento. |
| Extensão e agente | A extensão (Chrome, Edge, Opera) e o agente local (Windows) são a ponte entre o site e o certificado: a chave privada nunca sai do token ou do repositório do usuário. Veja Extensão e agente. |
O navegador nunca fala com a API
A chave de API fica só no seu servidor. O navegador chama endpoints do seu sistema (iniciar, preparar, concluir), e o seu servidor repassa à API. É por isso que a API não habilita CORS.
O vocabulário da API#
Sessão e token. Cada assinatura é uma sessão, identificada por um token de 43 caracteres que a API devolve ao iniciar. A sessão vale 15 minutos (renovável, até 60 minutos desde o início) e guarda os PDFs no servidor enquanto durar. Veja Sessões.
Documento e transação. Cada PDF concluído é uma transação, com um transactionId público que aparece no painel e na auditoria. Num lote de 10 PDFs são 10 transações.
Política de assinatura (signaturePolicyId). O perfil da assinatura: pades-basic, ou os perfis ICP-Brasil pades-icpbrasil-ad-rb, -ad-rt, -ad-rc e -ad-ra. A política declarada no PDF vem sempre da lista oficial do ITI, nunca de um texto fixo. Veja Políticas e contextos.
Contexto de segurança (securityContextId). O conjunto de raízes de confiança contra o qual o certificado é validado. icp-brasil usa as raízes oficiais da ICP-Brasil. private:<identificador> é a PKI privada do seu cliente, isolada das demais.
Os dados a assinar (toSignData). O que a API devolve no prepare e o usuário assina com a chave privada. Quem decide o que se assina é a API; o navegador só o repassa à extensão.
Chave de API (ssk_...). A credencial do seu servidor. Pertence a um cliente e aparece uma única vez, na criação. Veja Autenticação.
O ciclo de uma assinatura#
- Iniciar (
POST /v1/pades-signaturesou.../multipart): você envia o PDF e escolhe a política e o contexto. A API devolve otoken. - Preparar (
POST .../{token}/prepare): você envia o certificado do usuário. A API valida cadeia, validade e uso da chave, e devolve os dados a assinar. É aqui que um certificado inadequado é recusado, antes do PIN. - Assinar (no computador do usuário): a extensão pede o PIN em sua própria janela e assina os dados.
- Concluir (
POST .../{token}/complete): você envia a assinatura. A API incorpora-a ao PDF, acrescenta o carimbo de tempo e devolve o documento assinado. - Guardar e apagar: você baixa o PDF, guarda os identificadores e apaga a sessão (
DELETE).
Onde ficam os dados#
- O PIN é digitado só na janela da extensão. Nem o seu código nem a API o veem.
- A chave privada não sai do token, do cartão ou do repositório do usuário.
- Os PDFs ficam em disco no servidor da API só durante a sessão e são apagados ao concluir, ao descartar ou ao expirar.
- A auditoria registra quem assinou o quê e quando, sem o conteúdo dos documentos.