Referência rápida do Web PKI

O essencial do Web PKI em uma página, com links para os artigos completos.

Para que serve

O Web PKI permite que aplicações web usem, por JavaScript, os certificados do computador do usuário: listá-los, ler suas propriedades e seu encoding binário e assinar dados ou um digest pré-calculado com eles. Seu papel principal é a parte da assinatura feita no cliente: um SDK no servidor prepara os bytes a assinar e monta o arquivo assinado, porque signData e signHash devolvem só a saída bruta do algoritmo de assinatura. Se você já tem um SDK de criptografia ou escreve o backend por conta própria, o Web PKI sozinho cobre a parte do frontend.

Alternativa	Quando é a melhor escolha
Rest PKI (legado)	Seu backend já usa o Rest PKI em pki.rest: o guia de certificação digital recomenda o Rest PKI com o Web PKI para assinaturas web remotas em qualquer linguagem.
Rest PKI Core	Você prefere não escrever código de assinatura: sua aplicação cria uma sessão de assinatura e o Rest PKI Core hospeda a página de assinatura, em que os usuários assinam pelo Web PKI ou com certificados em nuvem.
PKI SDK	Seu backend é .NET: o PKI SDK faz o lado servidor das assinaturas web remotas, com o Web PKI no navegador.
PKI Express	Seu backend roda em Windows ou Linux, em praticamente qualquer linguagem: o PKI Express assina no servidor, e seus exemplos usam o Web PKI no navegador.
Signer	Você precisa de um gerenciador completo de documentos e assinaturas, e não de um componente; o widget de assinatura embutida dele exige uma licença do Web PKI para o domínio da sua página.

Instalação

Linguagem	Pacote	Major atual	Registry
JavaScript / TypeScript (npm)	web-pki	2 (mais recente: 2.18.0)	https://www.npmjs.com/package/web-pki
Tag script (CDN)	lacuna-web-pki-2.18.0.min.js	2	https://cdn.lacunasoftware.com/libs/web-pki/lacuna-web-pki-2.18.0.min.js

<script type="text/javascript" src="https://cdn.lacunasoftware.com/libs/web-pki/lacuna-web-pki-2.18.0.min.js"
  integrity="sha256-utM/CTsggW5QWTZgkLcAwVGkMBhYKTz3n0992V4r2y4="
  crossorigin="anonymous"></script>

npm install web-pki --save

Com o npm, importe a classe como faz o exemplo em Angular:

import LacunaWebPKI from 'web-pki';

O Web PKI também precisa dos seus componentes no computador do usuário: quando eles faltam ou estão desatualizados, ou o navegador não é suportado, init() leva o usuário à página de instalação, que o devolve à sua página ao terminar. Os componentes se atualizam sozinhos; atualize regularmente a biblioteca JavaScript na sua aplicação, pois as atualizações são retrocompatíveis. Veja Browsers suportados e, para redes Windows, a distribuição via GPO.

Configuração e autenticação

O Web PKI roda no navegador do usuário: não há chave de API. Fora do localhost, sua página precisa de uma licença vinculada aos seus domínios, passada ao construtor de LacunaWebPKI em formato binário ou JSON.

var webPkiLicense = 'ASYAanNma...Q==';
var pki = new LacunaWebPKI(webPkiLicense);

• A licença não é necessária no localhost (qualquer porta), nem com o Rest PKI em nuvem, inclusive em produção.
• A licença JSON lista allowedDomains e homologDomains (homologação); estes incluem as faixas de IP privado 10.x, 127.x, 172.16–172.31 e 192.168.x. Use a licença inteira: o campo signature sozinho não é uma licença. Veja Licenciamento.
• Para obter uma licença, fale com a Lacuna; as licenças do PKI SDK em geral vêm acompanhadas de uma licença do Web PKI.

Os argumentos de init() que um cliente define:

Argumento	Finalidade	Artigo
ready	Callback chamado quando o componente está pronto	Primeiros passos
license	A licença, quando não foi passada ao construtor	Licenciamento
defaultFail	Callback de falha para toda chamada que não tenha o seu	Callback de erro padrão
notInstalled	Substitui o redirecionamento para a página de instalação	Componente não instalado
restPkiUrl	Sua instância do Rest PKI, quando não é a padrão https://pki.rest	URL do Rest PKI
requiredApiVersion	Conjunto de recursos da API de que a página precisa (padrão: API 1.3), evitando atualizações desnecessárias	Versões da API
brand	Página de instalação personalizada	Página de instalação personalizada
angularScope, ngZone	Executa os callbacks dentro dos ciclos do AngularJS ou do Angular	Callbacks e AngularJS

Com o Rest PKI, o Web PKI se comunica diretamente com a instância do Rest PKI, por padrão pela https://restpki.lacunasoftware.com/, uma URL alternativa do serviço em nuvem em https://pki.rest, com menos chance de ser bloqueada por firewalls.

Operações principais

Todos os métodos são assíncronos: devolvem uma Promise na qual você registra os callbacks success() e fail() (Chamadas assíncronas). A referência da API traz todos os métodos, inclusive os que não aparecem aqui, como sendAuthenticatedRequest() para requisições autenticadas com o certificado do usuário via SSL/TLS mútuo.

Inicializar o componente

Crie um LacunaWebPKI e chame init() antes de qualquer outro método; seu callback ready é chamado quando o componente está pronto. Veja Primeiros passos.

var pki = new LacunaWebPKI();
pki.init({
    ready: onWebPkiReady,
    defaultFail: onWebPkiFail
});

Listar os certificados do usuário

listCertificates() devolve os certificados ordenados por subjectName, cada um com propriedades como thumbprint, subjectName, issuerName e validityEnd; com selectId, preenche um elemento select. Veja Personalizando a listagem de certificados e Propriedades dos certificados. Mostre todos os certificados e pré-valide o escolhido em vez de usar filtros, que a documentação desaconselha.

pki.listCertificates({
    selectId: 'certificateSelect',
    selectOptionFormatter: getCertText
});

function getCertText(cert) {
    return cert.subjectName + ' (issued by ' + cert.issuerName + ')';
}

Ler um certificado

readCertificate() devolve o encoding do certificado em Base64, que você envia ao backend quando ele inicia uma assinatura remota. Veja Primeiros passos. Passe { thumbprint }: a biblioteca também aceita a string do thumbprint, como faz o exemplo em Java, mas a declaração de tipos TypeScript (lacuna-web-pki.d.ts) aceita só o objeto.

pki.readCertificate({ thumbprint: selectedCertThumbprint }).success(function (certEncoding) {
    // certEncoding contains the certificate's encoding (in Base64)
});

Assinar dados

signData() assina bytes em Base64 com a chave privada do certificado escolhido e devolve a assinatura em Base64. Veja signData e signHash.

pki.signData({
    thumbprint: '...',     // as returned by the listCertificates method
    data: '...',           // bytes encoded in Base64 (typically given by server)
    digestAlgorithm: '...' // for instance 'SHA-256' (typically given by server)
}).success(function (signature) {
    // signature contains the result of the signature operation (encoded in Base64)
});

Assinar um hash vindo do backend

signHash() assina o digest que o SDK no servidor devolve ao iniciar uma assinatura remota (PKI Express, PKI SDK, Rest PKI Core); em seguida, o backend conclui a assinatura com o resultado. Veja Assinaturas web remotas.

pki.signHash({
    thumbprint: formElements.certThumbField.val(),
    hash: formElements.toSignHashField.val(),
    digestAlgorithm: formElements.digestAlgorithmField.val()
}).success(function (signature) {
    // Fill the "signature" field, needed on server-side to complete the signature.
    formElements.signatureField.val(signature);
    formElements.form.submit();
});

Assinar com o Rest PKI

signWithRestPki() recebe o token que o backend obteve do Rest PKI e o thumbprint do certificado; o Web PKI troca os dados da assinatura diretamente com o Rest PKI, e depois o backend conclui a assinatura. Veja Rest PKI.

pki.signWithRestPki({
    token: formElements.token,
    thumbprint: selectedCertThumbprint
}).success(function () {
    // Once the operation is completed, we submit the form.
    formElements.form.submit();
});

Assinar um PDF local

signPdf() assina um PDF no computador do usuário, sem enviar nada a um servidor; escolha o arquivo com showFileBrowser(). As assinaturas locais exigem a extensão de assinatura local (fale com a Lacuna) e só funcionam no Windows. Veja Assinaturas web locais.

pki.signPdf({
    fileId: file.id,
    output: { mode: 'autoSave', fileNameSuffix: '-signed' },
    certificateThumbprint: $('#certificateSelect').val(),
    policy: 'basic',
    trustArbitrators: [pki.standardTrustArbitrators.pkiBrazil]
}).success(function (result) {
    // result.isValid, result.signatureInfo
});

Erros

Uma chamada que falha chama seu callback fail(), ou o defaultFail definido em init(); sem nenhum dos dois, uma exceção é lançada. O callback recebe um ExceptionModel com userMessage (para o usuário), code, error, origin e message. Veja Callback de erro padrão.

• Componente ausente ou desatualizado, ou navegador não suportado: não é um código de erro. init() redireciona para a página de instalação, ou chama seu notInstalled(status, message) com NOT_INSTALLED, OUTDATED ou BROWSER_NOT_SUPPORTED. Veja Componente não instalado.
• Códigos de erro: code indica qual erro ocorreu, e Callback de erro padrão descreve cada um. Com license_not_set, license_invalid, license_expired, license_domain_not_allowed e license_restricted, confira a licença com o artigo Licenciamento; outros códigos comuns são user_cancelled (o usuário cancelou a operação) e certificate_not_found (o certificado não está no repositório do usuário nem no dispositivo criptográfico).
• "Could not get pending signature" com signWithRestPki(): o Web PKI não consegue se comunicar com a instância do Rest PKI, o que é comum com instâncias on-premises; verifique primeiro se o computador do usuário consegue acessá-la. Veja o artigo de solução de problemas.

TODO(docs): 13 códigos de erro não têm descrição, nem na documentação nem na declaração de tipos da biblioteca: algorithm_not_supported, signed_pdf_to_mark, json_error, io_error, keychain_error, keychain_sign_error, decode_error, csp_invalid_algorithm, csp_invalid_provider_type, mobile_not_authorized, command_decrypt_error, blocked_domain e invalid_operation.

Certificados e credenciais de teste

• Use os certificados da PKI de teste da Lacuna, em Certificados de teste; nunca confie nessa PKI em produção.
• Para testar o Web PKI no Windows, você precisa de um certificado no repositório de certificados do Windows: o certmgr.msc deve mostrar um na pasta Pessoal, com a chave privada. Para usar um certificado de teste, importe o arquivo PKCS #12 dele (senha 1234) para esse repositório.
• A licença não é necessária no localhost, e servidores de homologação em IPs privados são cobertos pelos homologDomains da licença.
• Com o Rest PKI, confie na PKI de teste pelo ID de contexto de segurança informado em Certificados de teste; para assinaturas locais, adicione a raiz de teste, Lacuna Root Test v3, como trust arbitrator trustedRoot (só em desenvolvimento). O exemplo em .NET faz isso com uma raiz antiga, a Lacuna Root Test v1, que expirou em janeiro de 2025 e não aceita os certificados de teste atuais.

TODO(docs): como instalar os arquivos PKCS #12 de teste para que o Web PKI os liste no Linux e no macOS.

Experimente

Rode as demos do Web PKI ou os exemplos na sua linguagem:

Demonstrações e exemplos

• Demonstração: Your certificates in the browser
• Demonstração: Sign a file with your certificate
• Sign a local PDF in the browser with Web PKI: .NET
• Sign a local file with CAdES in the browser using Web PKI: .NET
• List the user's certificates with Web PKI: .NET · Java · Node.js · Python · Ruby
• Read a certificate's details with Web PKI: .NET · Java · Node.js · Python · Ruby
• Sign data with RSA in the browser using Web PKI: .NET · Java · Node.js · Python · Ruby