Extensão e agente
O que o usuário instala, em quais sites funciona e como detectar e orientar.
Para assinar com token ou cartão A3, com certificado A1 instalado no Windows ou com certificado em nuvem, o computador do usuário precisa de duas peças que conversam entre si:
- a extensão ShieldSign, para Chrome, Edge ou Opera. É a ponte entre o site e o agente, mostra a janela de confirmação e é onde o PIN do token é digitado;
- o agente ShieldSign, um programa local para Windows que fala com o token e com o repositório de certificados. É instalado uma vez.
O site nunca recebe o PIN nem a chave privada.
Certificado A1 em arquivo (.pfx)
Quem tem o A1 como arquivo pode assinar sem instalar nada, importando o .pfx no navegador (A1Signer, no SDK JavaScript). A chave fica na memória do navegador, não extraível, e some ao fechar a página.
Para o usuário final#
Leve o usuário à página https://pki.shieldsign.com.br/instalar/. Ela detecta o que já está instalado, mostra o passo que falta e leva à loja certa para o navegador em uso:
- Extensão: Chrome Web Store (Chrome e Opera) ou Edge Add-ons (Edge).
- Agente: instalador para Windows, que não exige administrador e instala só para o usuário atual.
A página confere sozinha a cada poucos segundos e mostra "Tudo pronto" quando as duas peças estão instaladas. Se o usuário instalou a extensão em outra aba, ao voltar a página se recarrega para enxergá-la.
Primeira vez em cada site
Na primeira vez que um site pede para usar a extensão, abre uma janela "Permitir que este site use o ShieldSign?", com o endereço do site. O usuário confere e clica em Permitir. Depois disso, cada assinatura ainda pede a aprovação dele. O usuário pode remover sites nas configurações da extensão.
Em quais sites a extensão funciona#
A extensão só atua em https://. Num site http:// (sem HTTPS) ela não existe para a página, mesmo instalada: use HTTPS no seu sistema. Para desenvolver em ambiente local, sirva a sua página por HTTPS (por exemplo, com um certificado local gerado pelo mkcert).
Detectar e orientar o usuário#
No seu site, antes de oferecer a assinatura, verifique se a extensão está disponível e, se não estiver, leve o usuário à página de instalação:
import { ExtensionSigner } from "/assets/shieldsign-sdk.browser.mjs";
ExtensionSigner.installUrl = "https://pki.shieldsign.com.br/instalar/"; // já é o padrão do SDK
if (!(await ExtensionSigner.isAvailable())) {
ExtensionSigner.redirectToInstallPage(); // ou mostre um aviso com o link
}
Para mostrar uma mensagem específica, use o diagnóstico. Ele diz por que a extensão não está disponível, com um texto pronto em português:
const d = await ExtensionSigner.diagnose();
// { available, reason, message, origin, info? }
// reason: "ok"
// | "origin_not_supported" (o site não usa https)
// | "not_installed_or_blocked" (não instalada, desativada ou sem acesso a este site)
// | "agent_unavailable" (a extensão respondeu, mas o agente local não)
if (!d.available) mostrarAviso(d.message);
ExtensionSigner.info() devolve as versões da extensão e do agente.
Erros da extensão (ExtensionError.code)#
A tabela completa e atualizada está no SDK (EXTENSION_ERROR_CODES, com retry e meaning por código).
| Código | Quando | Tentar de novo? |
|---|---|---|
extension_not_found |
A extensão não respondeu (veja reason e diagnose()). |
Não |
timeout |
Sem resposta no prazo (a assinatura espera até 195 s: PIN ou aprovação). | Sim |
origin_not_allowed |
Site fora da política da empresa, ou o usuário negou. | Não |
forbidden_frame, forbidden, invalid_request, unknown_action |
Pedido inválido ou proibido (erro de integração; o PIN nunca pode ir pela página). | Não |
auth_origin_mismatch, auth_message_invalid |
Login por certificado emitido para outro site, ou formato desconhecido. | Não |
consent_unavailable, consent_expired |
A janela de confirmação não abriu (pop-up bloqueado?) ou expirou. | Sim |
user_cancelled |
O usuário cancelou, ou negou a aprovação no aplicativo do certificado em nuvem. | Sim (silencioso) |
certificate_not_found, key_not_found |
Token removido, ou certificado sem chave neste computador. | Liste de novo |
pin_required, pin_incorrect |
O PIN é pedido na janela da extensão, que já pede de novo. Seu código normalmente não repete. | — |
pin_locked |
PIN bloqueado: desbloquear com o PUK na AC. | Não |
unsupported, sign_failed |
Algoritmo ou chave não suportado, ou falha do provedor (veja message). |
Não |
agent_disconnected, connect_failed |
O agente local fechou ou não está instalado. | Reinstalar |
PIN errado e tentativas restantes#
O padrão dos tokens (PKCS#11) não informa o número exato de tentativas restantes. O que o token informa, o ShieldSign mostra na janela: "Restam poucas tentativas antes de o token bloquear" e "a próxima tentativa errada vai BLOQUEAR o token". O código continua pin_incorrect, e o PIN nunca é repetido em mensagem alguma. Em certificados do repositório do Windows, quem pergunta o PIN é o próprio provedor, que costuma mostrar as tentativas restantes.
Certificado em nuvem#
A janela do provedor (ou a aprovação no aplicativo do celular) abre pelo Windows. O agente espera até 3 minutos. Se o usuário nega no aplicativo: user_cancelled. Se demora mais que o prazo: timeout, com "o usuário não concluiu a aprovação/PIN", e nada foi assinado. Para que a sessão da API não expire enquanto isso, veja Sessões.
Se não funcionar#
| Sintoma | O que fazer |
|---|---|
| O site diz que não detectou a extensão | Confira que o site usa HTTPS e que a extensão está ativada e com acesso ao site (nas configurações da extensão). await ExtensionSigner.diagnose() informa o motivo. |
| O popup mostra o agente desconectado | Reinstale o agente e reinicie o navegador. |
| O certificado do token não aparece | Instale o driver do fabricante do token (SafeNet/eToken, SafeSign, Gemalto, Watchdata…) e plugue o token. |
| "PIN incorreto" com aviso de poucas tentativas | Pare e confira o PIN: erros seguidos bloqueiam o token. |
| Certificado em nuvem: a aprovação no celular demora | O agente espera até 3 minutos. Se passar, tente de novo. |
Ambientes corporativos#
A TI pode fixar a lista de sites que falam com a extensão por política do navegador (allowedOrigins, no Chrome e no Edge). Nesse modo, só os sites listados funcionam, sem perguntar, e o usuário não consegue alterar a lista. A política é aplicada por GPO ou Intune, em HKEY_LOCAL_MACHINE, e exige administrador. Valide-a numa máquina de teste antes de distribuir; fale com o suporte para receber o modelo.
Limites atuais#
O instalador do agente é para Windows. Suporte a macOS e Linux está no roteiro.