---
title: "Referência rápida do Web PKI"
description: "O Web PKI em uma página: instale a biblioteca JavaScript, defina a licença, liste e leia certificados, assine no navegador e trate erros."
canonical: "https://docs.lacunasoftware.com/articles/web-pki/quick-reference"
locale: "pt-BR"
product: "Web PKI"
last_updated: "2026-10-12"
---

# 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](https://docs.lacunasoftware.com/articles/rest-pki/quick-reference) (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](https://docs.lacunasoftware.com/articles/rest-pki/core/quick-reference) | 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](https://docs.lacunasoftware.com/articles/pki-sdk/quick-reference) | Seu backend é .NET: o PKI SDK faz o lado servidor das assinaturas web remotas, com o Web PKI no navegador. |
| [PKI Express](https://docs.lacunasoftware.com/articles/pki-express/quick-reference) | 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](https://docs.lacunasoftware.com/articles/signer/quick-reference) | 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 |

```html
<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>
```

```bash
npm install web-pki --save
```

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

```javascript
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](https://docs.lacunasoftware.com/articles/web-pki/browser-support) e, para redes Windows, a [distribuição via GPO](https://docs.lacunasoftware.com/articles/web-pki/installation-webpki-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. 

```javascript
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](https://docs.lacunasoftware.com/articles/web-pki/licensing). 
- Para obter uma licença, [fale com a Lacuna](https://www.lacunasoftware.com/en/home/purchase); 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](https://docs.lacunasoftware.com/articles/web-pki/get-started) |
| `license` | A licença, quando não foi passada ao construtor | [Licenciamento](https://docs.lacunasoftware.com/articles/web-pki/licensing) |
| `defaultFail` | Callback de falha para toda chamada que não tenha o seu | [Callback de erro padrão](https://docs.lacunasoftware.com/articles/web-pki/default-error-callback) |
| `notInstalled` | Substitui o redirecionamento para a página de instalação | [Componente não instalado](https://docs.lacunasoftware.com/articles/web-pki/customizing-not-installed) |
| `restPkiUrl` | Sua instância do Rest PKI, quando não é a padrão https://pki.rest | [URL do Rest PKI](https://docs.lacunasoftware.com/articles/web-pki/customizing-restpki-url) |
| `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](https://docs.lacunasoftware.com/articles/web-pki/api-reference/versions) |
| `brand` | Página de instalação personalizada | [Página de instalação personalizada](https://docs.lacunasoftware.com/articles/web-pki/brand) |
| `angularScope`, `ngZone` | Executa os callbacks dentro dos ciclos do AngularJS ou do Angular | [Callbacks e AngularJS](https://docs.lacunasoftware.com/articles/web-pki/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](https://docs.lacunasoftware.com/articles/web-pki/async)). A [referência da API](https://docs.lacunasoftware.com/articles/web-pki/api-reference) traz todos os métodos, inclusive os que não aparecem aqui, como `sendAuthenticatedRequest()` para [requisições autenticadas](https://docs.lacunasoftware.com/articles/web-pki/auth-request) 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](https://docs.lacunasoftware.com/articles/web-pki/get-started). 

```javascript
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](https://docs.lacunasoftware.com/articles/web-pki/cert-select) e [Propriedades dos certificados](https://docs.lacunasoftware.com/articles/web-pki/cert-properties). 
Mostre todos os certificados e [pré-valide o escolhido](https://docs.lacunasoftware.com/articles/web-pki/cert-validation) em vez de usar [filtros](https://docs.lacunasoftware.com/articles/web-pki/filters), que a documentação desaconselha. 

```javascript
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](https://docs.lacunasoftware.com/articles/web-pki/get-started). 
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. 

```javascript
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](https://docs.lacunasoftware.com/articles/web-pki/faq/sign-data-vs-hash). 

```javascript
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](https://docs.lacunasoftware.com/articles/pki-guide/web-signatures/remote). 

```javascript
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](https://docs.lacunasoftware.com/articles/rest-pki/quick-reference). 

```javascript
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](https://www.lacunasoftware.com/en/home/purchase)) e só funcionam no Windows. Veja [Assinaturas web locais](https://docs.lacunasoftware.com/articles/pki-guide/web-signatures/local). 

```javascript
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](https://docs.lacunasoftware.com/articles/web-pki/default-error-callback). 

- **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](https://docs.lacunasoftware.com/articles/web-pki/customizing-not-installed). 
- **Códigos de erro**: `code` indica qual erro ocorreu, e [Callback de erro padrão](https://docs.lacunasoftware.com/articles/web-pki/default-error-callback#códigos-de-erro) 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](https://docs.lacunasoftware.com/articles/web-pki/licensing); 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](https://docs.lacunasoftware.com/articles/rest-pki/troubleshoot/could-not-get-pending-sig). 

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](https://docs.lacunasoftware.com/articles/pki-guide/test-certs#web-pki); 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](https://try.lacunasoftware.com/pt/web-pki/certificates-in-the-browser)
- Demonstração: [Sign a file with your certificate](https://try.lacunasoftware.com/pt/pki-suite/sign-a-file)
- Sign a local PDF in the browser with Web PKI: [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/mvc/PkiSuiteAspNetMvcSample/Controllers/PadesSignatureWebController.cs)
- Sign a local file with CAdES in the browser using Web PKI: [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/mvc/PkiSuiteAspNetMvcSample/Controllers/CadesSignatureWebController.cs)
- List the user's certificates with Web PKI: [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/mvc/PkiSuiteAspNetMvcSample/Controllers/ListCertJQueryController.cs) · [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/ListCertJQueryController.java) · [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/list-cert-jquery.js) · [Python](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/python/flask/sample/views/list_cert_jquery.py) · [Ruby](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/ruby/rails/app/controllers/list_cert_jquery_controller.rb)
- Read a certificate's details with Web PKI: [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/mvc/PkiSuiteAspNetMvcSample/Controllers/ReadCertJQueryController.cs) · [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/ReadCertJQueryController.java) · [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/read-cert-jquery.js) · [Python](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/python/flask/sample/views/read_cert_jquery.py) · [Ruby](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/ruby/rails/app/controllers/read_cert_jquery_controller.rb)
- Sign data with RSA in the browser using Web PKI: [.NET](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/dotnet/mvc/PkiSuiteAspNetMvcSample/Controllers/RSAWebController.cs) · [Java](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/java/springmvc/src/main/java/com/lacunasoftware/pkisuite/controller/RSAWebController.java) · [Node.js](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/nodejs/expressmvc/routes/rsa-web.js) · [Python](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/python/flask/sample/views/rsa_web.py) · [Ruby](https://github.com/LacunaSoftware/PkiSuiteSamples/blob/master/ruby/rails/app/controllers/rsa_web_controller.rb)