# Documentação da Lacuna Software > Documentação para desenvolvedores dos produtos de certificação digital, assinatura digital e PKI da Lacuna Software: Web PKI, Rest PKI Core, PKI SDK, PKI Express, Signer, Amplia e serviços relacionados. Index: https://docs.lacunasoftware.com/pt-br/llms.txt # [Bem-vindo ao Lacuna Docs](https://docs.lacunasoftware.com/articles/welcome) Seja bem-vindo ao novo portal de documentação da [Lacuna Software](https://www.lacunasoftware.com/). Utilizando a mesma tecnologia do portal [Microsoft Docs](https://docs.microsoft.com/), este site combina toda a informação técnica que você pode precisar sobre cada um de nossos produtos em uma experiência unificada e interconectada de documentação. > **Dica** > > Este site é destinado a desenvolvedores de software. Se você é um usuário final tendo problemas para utilizar algum > de nossos produtos, como o plugin Web PKI, por favor visite a nossa [Central de Suporte](http://lacuna.help/) Se você encontrar algum erro ou alguma documentação faltando, por favor [crie uma issue](https://github.com/LacunaSoftware/docs/issues) reportando o problema. Um bom lugar para começar é o artigo [Soluções para certificação digital](https://docs.lacunasoftware.com/articles/pki-guide). ## Por onde começar - [Como escolher um produto](https://docs.lacunasoftware.com/articles/welcome/choosing-a-product): qual produto atende à sua integração, com link para a referência rápida de cada um. - [Como usar esta documentação com agentes de IA](https://docs.lacunasoftware.com/articles/welcome/using-with-ai-agents): llms.txt, a versão em Markdown de cada página, as especificações OpenAPI e um parágrafo para o seu agente de programação. # [Como escolher um produto](https://docs.lacunasoftware.com/articles/welcome/choosing-a-product) Comece pelo que a sua aplicação precisa fazer. Cada produto aponta para a sua referência rápida: instalação, configuração, operações principais, erros e exemplos numa só página. ## Produtos principais | Se a sua aplicação precisa… | Use | |---|---| | Trabalhar com os certificados do usuário no navegador: listá-los, lê-los, assinar com eles numa página web | [Web PKI](https://docs.lacunasoftware.com/articles/web-pki/quick-reference) | | Assinar, validar e aplicar carimbo de tempo em documentos por uma API REST, como serviço em nuvem ou em instância própria | [Rest PKI Core](https://docs.lacunasoftware.com/articles/rest-pki/core/quick-reference) | | Assinar nos próprios servidores Windows ou Linux, numa linguagem que não seja .NET (Java, PHP, Python, Node.js, Ruby…) | [PKI Express](https://docs.lacunasoftware.com/articles/pki-express/quick-reference) | | Assinar, validar e tratar certificados dentro de uma aplicação .NET | [PKI SDK](https://docs.lacunasoftware.com/articles/pki-sdk/quick-reference) | | Enviar documentos para pessoas e colher as assinaturas delas, com um fluxo | [Signer](https://docs.lacunasoftware.com/articles/signer/quick-reference) | | Emitir certificados: operar as próprias autoridades certificadoras ou uma PKI inteira | [Amplia](https://docs.lacunasoftware.com/articles/amplia/quick-reference) | Já integra o **Rest PKI** em pki.rest? Ele é um produto legado que continua recebendo correções de bugs e de segurança; veja a [referência rápida dele (legado)](https://docs.lacunasoftware.com/articles/rest-pki/quick-reference). Para uma nova integração em nuvem, use o Rest PKI Core. ## Combinações comuns - **Assinatura numa página web com o certificado do usuário**: o Web PKI faz a parte que precisa rodar no navegador, e um produto no servidor (Rest PKI Core, PKI SDK ou PKI Express) faz o restante. O artigo [assinaturas web](https://docs.lacunasoftware.com/articles/pki-guide/web-signatures) do guia de certificação digital explica as abordagens. - **Assinatura com chave guardada no servidor**: sem etapa no navegador. Em .NET, o guia recomenda o PKI SDK; veja [assinaturas no servidor](https://docs.lacunasoftware.com/articles/pki-guide/server-signatures). - **Login com certificado**: o Web PKI no navegador e um produto no servidor para verificar o certificado; veja [login com certificado digital](https://docs.lacunasoftware.com/articles/pki-guide/cert-auth). ## Outros produtos | Produto | O que faz | |---|---| | [Amplia Reg](https://docs.lacunasoftware.com/articles/amplia-reg) | Autoridade de Registro do Amplia: confirma quem é o titular antes da emissão do certificado | | [PSC](https://docs.lacunasoftware.com/articles/psc) | Armazena e gerencia certificados em nuvem, junto com o Amplia | | [TSA](https://docs.lacunasoftware.com/articles/tsa) | Servidor de carimbo de tempo (RFC 3161) | | [GrantID](https://docs.lacunasoftware.com/articles/grant-id) | Single Sign On e múltiplos fatores de autenticação para os seus aplicativos | | [Bulk Signer](https://docs.lacunasoftware.com/articles/bulk-signer) | Serviço on-premises que assina arquivos em lote | | [Scanner](https://docs.lacunasoftware.com/articles/scanner) | Adiciona digitalização de documentos a uma aplicação web | | [Digiploma](https://docs.lacunasoftware.com/articles/digiploma) | Emite, registra e publica diplomas digitais conforme a Portaria MEC 554/2019 | | [TrustBridge](https://docs.lacunasoftware.com/articles/trustbridge) | Assinatura remota com certificados ICP-Brasil de pessoas, em smart card ou token USB | Para entregar esta documentação a um agente de IA de programação, veja [Como usar esta documentação com agentes de IA](https://docs.lacunasoftware.com/articles/welcome/using-with-ai-agents). # [Como usar esta documentação com agentes de IA](https://docs.lacunasoftware.com/articles/welcome/using-with-ai-agents) Quando um agente de IA de programação (Claude Code, Cursor, GitHub Copilot, Codex…) escreve a sua integração, indique a ele os recursos abaixo. Eles têm o mesmo conteúdo das páginas que você lê, em formatos que um agente baixa e interpreta com facilidade. A [última seção](https://docs.lacunasoftware.com/articles/welcome/using-with-ai-agents#um-parágrafo-para-o-seu-agente) traz um parágrafo pronto para colar nas instruções do seu agente. ## Comece pelo llms.txt | Arquivo | O que contém | |---|---| | [llms.txt](https://docs.lacunasoftware.com/llms.txt) | Índice das páginas em inglês, agrupadas por produto, cada uma com a URL em Markdown e uma descrição de uma linha. A referência rápida de cada produto vem primeiro. As páginas que ainda não existem em inglês apontam para a versão em português, marcadas com (pt-br). Termina com as especificações OpenAPI. | | [llms-full.txt](https://docs.lacunasoftware.com/llms-full.txt) | As mesmas páginas na íntegra, num só arquivo, cada uma sob um título com a sua URL. | | [pt-br/llms.txt](https://docs.lacunasoftware.com/pt-br/llms.txt), [pt-br/llms-full.txt](https://docs.lacunasoftware.com/pt-br/llms-full.txt) | O mesmo para as páginas em português. | Os dois seguem o formato [llms.txt](https://llmstxt.org/). ## Cada página em Markdown Acrescente `.md` à URL de qualquer página para obtê-la em Markdown puro. Por exemplo, https://docs.lacunasoftware.com/articles/signer/get-started.md é a versão em Markdown de https://docs.lacunasoftware.com/articles/signer/get-started. - O front matter traz o título, a descrição, a URL canônica, o idioma, o produto e a data da última alteração. - As abas viram um bloco de código por aba, cada um com um rótulo em negrito; observações e avisos viram citações; links e imagens são URLs absolutas. - Cada página aponta para a sua versão em Markdown no head do HTML (``) e abaixo do conteúdo (**Ver em Markdown**, **Copiar página em Markdown**). - A referência da API .NET do PKI SDK funciona do mesmo jeito: https://docs.lacunasoftware.com/api/Lacuna.Pki/PKCertificate.md. ## Referências rápidas Uma página por produto com o que uma integração precisa primeiro: instalação, configuração e autenticação, operações principais com código, erros, certificados de teste, demonstrações e exemplos. O que a documentação ainda não cobre fica marcado como `TODO(docs)` em vez de ser deduzido. - [Web PKI](https://docs.lacunasoftware.com/articles/web-pki/quick-reference) - [Rest PKI Core](https://docs.lacunasoftware.com/articles/rest-pki/core/quick-reference) - [PKI Express](https://docs.lacunasoftware.com/articles/pki-express/quick-reference) - [PKI SDK](https://docs.lacunasoftware.com/articles/pki-sdk/quick-reference) - [Signer](https://docs.lacunasoftware.com/articles/signer/quick-reference) - [Amplia](https://docs.lacunasoftware.com/articles/amplia/quick-reference) - [Rest PKI (legado)](https://docs.lacunasoftware.com/articles/rest-pki/quick-reference) Em dúvida sobre qual produto usar? Veja [Como escolher um produto](https://docs.lacunasoftware.com/articles/welcome/choosing-a-product). ## Especificações das APIs A especificação OpenAPI de cada API em nuvem é copiada para uma URL estável neste site. As instâncias on-premises servem a sua própria em `/swagger`. | API | Especificação | Especificação ao vivo | |---|---|---| | Rest PKI Core | [openapi/rest-pki-core.json](https://docs.lacunasoftware.com/openapi/rest-pki-core.json) | https://core.pki.rest/swagger/api/swagger.json | | Signer | [openapi/signer.json](https://docs.lacunasoftware.com/openapi/signer.json) | https://www.dropsigner.com/swagger/api/swagger.json | | Amplia | [openapi/amplia.json](https://docs.lacunasoftware.com/openapi/amplia.json) | https://amplia.lacunasoftware.com/swagger/api/swagger.json | | Amplia Reg | [openapi/amplia-reg.json](https://docs.lacunasoftware.com/openapi/amplia-reg.json) | https://ar.lacunasoftware.com/swagger/api/swagger.json | | CloudHub | [openapi/cloudhub.json](https://docs.lacunasoftware.com/openapi/cloudhub.json) | https://cloudhub.lacunasoftware.com/swagger/v1/swagger.json | | Digiploma | [openapi/digiploma.json](https://docs.lacunasoftware.com/openapi/digiploma.json) | https://www.digiploma.com.br/swagger/api/swagger.json | | Scanner | [openapi/scanner.json](https://docs.lacunasoftware.com/openapi/scanner.json) | https://scn.lacunasoftware.com/swagger/api/swagger.json | | Rest PKI (legado) | [openapi/rest-pki.json](https://docs.lacunasoftware.com/openapi/rest-pki.json) | https://pki.rest/swagger/docs/v1 | ## Demonstrações e exemplos - **Demonstrações**: https://try.lacunasoftware.com/demos.json lista as demonstrações de [try.lacunasoftware.com](https://try.lacunasoftware.com/pt), com o produto, a página da documentação e os exemplos de cada uma. - **Exemplos**: os repositórios [PkiSuiteSamples](https://github.com/LacunaSoftware/PkiSuiteSamples) e [SignerSamples](https://github.com/LacunaSoftware/SignerSamples) mantêm cada um um catálogo `samples.json`: uma entrada por tarefa e linguagem, com o arquivo a ler, como executá-lo, a página da documentação e a demonstração. - As páginas que tratam de uma tarefa terminam com um quadro **Demonstrações e exemplos** que aponta para a demonstração e para o exemplo em cada linguagem. ## Um parágrafo para o seu agente Cole isto nas instruções do seu agente (por exemplo `CLAUDE.md`, `AGENTS.md` ou `.cursor/rules`) e diga qual produto você usa. O texto fica em inglês, o idioma mais completo da documentação: ```text This project integrates Lacuna Software products (digital certificates, digital signatures, PKI). Use the official docs at https://docs.lacunasoftware.com and read them as Markdown: - Start with https://docs.lacunasoftware.com/llms.txt, the index of all pages by product. - Add ".md" to any docs page URL to get its Markdown version. - Read the product's quick reference first (listed first under the product in llms.txt): packages, configuration, core operations, errors and samples. - For REST APIs, use the OpenAPI specs at https://docs.lacunasoftware.com/openapi/ (listed at the end of llms.txt). - For working code, follow the samples linked from the docs pages (PkiSuiteSamples and SignerSamples on GitHub) in this project's language. Do not guess package names, versions, endpoints or headers: take them from the quick reference, the OpenAPI spec or a sample. When developing, use the test certificates from https://docs.lacunasoftware.com/en-us/articles/pki-guide/test-certs, never production certificates. ``` # [Licenciamento dos produtos Lacuna](https://docs.lacunasoftware.com/articles/welcome/licensing) Esta página reúne, em um só lugar, o que é preciso para **adquirir, ativar, atualizar e usar** as licenças dos produtos da Lacuna Software. O conteúdo foi compilado a partir da documentação de cada produto, que continua sendo a referência detalhada: a seção de cada produto termina com os links para os artigos de origem. > **Dica: Você é usuário final?** > > Se você apenas usa um site ou sistema que pede o Web PKI para assinar documentos ou fazer login com certificado > digital, **não precisa comprar nem configurar nenhuma licença**. A licença é de quem desenvolve e mantém o site. > Veja [Para usuários finais](https://docs.lacunasoftware.com/articles/welcome/licensing#usuario-final). ## Resumo por produto | Produto e cenário | Precisa de licença? | O que é usado | |---|---|---| | [Web PKI](https://docs.lacunasoftware.com/articles/welcome/licensing#web-pki) em aplicação no *localhost* (desenvolvimento) | Não | — | | [Web PKI](https://docs.lacunasoftware.com/articles/welcome/licensing#web-pki) com o Rest PKI em nuvem (`https://pki.rest`) | Não, inclusive em produção | — | | [Web PKI](https://docs.lacunasoftware.com/articles/welcome/licensing#web-pki) nos demais casos, fora do *localhost* | Sim | Licença do Web PKI, informada no JavaScript da página | | [Rest PKI](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki) em nuvem | Não usa arquivo de licença | Conta em `pki.rest` e token de acesso | | [Rest PKI](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki) *on-premises* | Sim | Licença do PKI SDK (arquivo `LacunaPkiLicense.txt`) | | [Rest PKI Core](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-core) em nuvem (`core.pki.rest`) | Não usa arquivo de licença | Endpoint e chave de API, fornecidos pelo suporte | | [Rest PKI Core](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-core) *on-premises* | Sim | Licença do PKI SDK (obrigatória) e licença do Web PKI (para assinatura no navegador) | | [PKI SDK](https://docs.lacunasoftware.com/articles/welcome/licensing#pki-sdk) | Sim | Licença do PKI SDK (arquivo `LacunaPKILicense.config` ou texto em Base64) | | [PKI Express](https://docs.lacunasoftware.com/articles/welcome/licensing#pki-express) | Sim | Arquivo `LacunaPkiLicense.config`, usado para ativar o PKI Express na máquina | | [Signer](https://docs.lacunasoftware.com/articles/welcome/licensing#signer) *on-premises* | Sim | Licença do PKI SDK e licença do Web PKI | | [Bulk Signer](https://docs.lacunasoftware.com/articles/welcome/licensing#bulk-signer) | Sim | Licença do PKI SDK (texto em Base64) | | [Usuário final](https://docs.lacunasoftware.com/articles/welcome/licensing#usuario-final) de um site ou sistema | Não | — | ## Entendendo as licenças Os produtos desta página usam uma ou mais destas licenças: - **Licença do PKI SDK**: licença da biblioteca .NET da Lacuna. Ela é usada diretamente pelas aplicações que usam o [PKI SDK](https://docs.lacunasoftware.com/articles/welcome/licensing#pki-sdk) e também é exigida na instalação *on-premises* do [Rest PKI](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki), do [Rest PKI Core](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-core), do [Signer](https://docs.lacunasoftware.com/articles/welcome/licensing#signer) e do [Bulk Signer](https://docs.lacunasoftware.com/articles/welcome/licensing#bulk-signer). É entregue como arquivo (`LacunaPKILicense.config` ou, no Rest PKI *on-premises*, `LacunaPkiLicense.txt`) ou como texto em Base64. Uma licença do PKI SDK pode ter uso restrito ao Rest PKI. - **Licença do Web PKI**: autoriza o uso do componente de navegador nos domínios de um site. É informada pelo desenvolvedor no código JavaScript da página e, nas instalações *on-premises* do Rest PKI Core e do Signer, também na configuração do servidor. - **Licença do PKI Express**: arquivo `LacunaPkiLicense.config`, usado para ativar o PKI Express na máquina onde ele está instalado. Os serviços em nuvem não usam arquivo de licença: o acesso é feito com credenciais da sua conta, como o **token de acesso** do Rest PKI e a **chave de API** do Rest PKI Core. Essas credenciais não substituem a licença do Web PKI nos cenários em que ela é necessária (veja [Quando a licença do Web PKI é necessária](https://docs.lacunasoftware.com/articles/welcome/licensing#web-pki-quando)). > **Info: O que significa "atualizar a versão da licença"** > > Na prática, é uma destas situações: > > 1. **A licença venceu, vai vencer ou precisa cobrir algo novo**, como um novo domínio no Web PKI. Você recebe uma > nova licença e troca o valor configurado. > 2. **Você vai atualizar a versão de um produto *on-premises*.** A licença do PKI SDK aceita apenas versões do SDK > lançadas até uma certa data. Por isso, antes de atualizar o Signer ou o Rest PKI Core, confira no histórico de > versões se a sua licença cobre a versão de destino. Se não cobrir, peça uma licença atualizada antes de atualizar. > > O [passo a passo para atualizar uma licença](https://docs.lacunasoftware.com/articles/welcome/licensing#atualizar) vale para os dois casos. ## Como adquirir uma licença | Produto | Como solicitar | |---|---| | PKI SDK | Licença de *trial* gratuita pelo site pki.lacunasoftware.com | | Web PKI | Pelo [Fale conosco](https://www.lacunasoftware.com/pt/home/purchase) ou pelo e-mail [suporte@lacunasoftware.com](mailto:suporte@lacunasoftware.com), informando os *hostnames* ou URLs onde o componente será usado. As licenças do PKI SDK geralmente já vêm acompanhadas de uma licença do Web PKI | | PKI Express | Licença para testes pelo [Fale conosco](https://www.lacunasoftware.com/pt/home/purchase) | | Rest PKI *on-premises* | Licença de teste pelo [Fale conosco](https://www.lacunasoftware.com/pt/home/purchase) | | Rest PKI Core e Signer *on-premises* | Usam as licenças do PKI SDK e do Web PKI (linhas acima) | | Bulk Signer | A Lacuna fornece a licença (texto em Base64) junto com as credenciais de acesso ao produto | | Rest PKI em nuvem | Crie uma conta em [pki.rest](https://pki.rest/) e gere um token de acesso no **Painel de Controle**. Veja os [preços](https://www.lacunasoftware.com/pt-br/pricing/#cloud-simulator) | | Rest PKI Core em nuvem | Peça o endpoint e a chave de API ao [suporte ao desenvolvedor](mailto:suporte@lacunasoftware.com) | Ao solicitar, recomendamos informar: - o produto e o ambiente em que a licença será usada (produção, homologação ou testes); - no caso do **Web PKI**, os *hostnames* ou URLs de produção e de homologação. As faixas de IP privado já vêm liberadas para homologação (veja [Uso em IPs internos](https://docs.lacunasoftware.com/articles/web-pki/licensing#uso-em-ips-internos)); - se a licença é para **atualizar a versão** de um produto *on-premises*, a versão que você pretende instalar. ## Passo a passo para atualizar uma licença 1. **Identifique a licença e onde ela está configurada**, usando a tabela abaixo. Um mesmo produto pode usar mais de uma licença: o Signer, por exemplo, usa a do PKI SDK e a do Web PKI. 2. **Se a troca acompanha uma atualização de versão**, consulte o histórico de versões (*changelog*) do produto entre a versão atual e a de destino. Procure avisos como *"garanta que sua licença suporta versões do PKI SDK lançadas até AAAA-MM-DD"*. 3. **Obtenha a nova licença** pelos canais de [Como adquirir uma licença](https://docs.lacunasoftware.com/articles/welcome/licensing#adquirir). 4. **Substitua o valor inteiro**, no mesmo lugar onde a licença antiga está configurada. Licenças em Base64 devem ser coladas completas, em uma única linha. A licença JSON do Web PKI deve ser usada inteira. 5. **Reinicie a aplicação ou o serviço** nos produtos que leem a licença na inicialização (PKI SDK, Rest PKI Core, Signer e Bulk Signer). No Rest PKI *on-premises*, a troca é feita pela tela de administração. 6. **Confirme que a nova licença foi carregada**, com a verificação indicada para o produto. | Produto | Onde a licença fica | Como confirmar | |---|---|---| | [Web PKI](https://docs.lacunasoftware.com/articles/welcome/licensing#web-pki-atualizar) | JavaScript da página: `new LacunaWebPKI(licença)` ou parâmetro `license` do `init()` | Nenhum erro de licença no componente. No formato JSON, confira `expiration` e os domínios | | [Rest PKI *on-premises*](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-trocar) | **Administração** > **Status do sistema** > **SDK license loaded** | A mesma tela mostra o licenciado e a data de expiração | | [Rest PKI Core *on-premises*](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-core-trocar) | Arquivo de configuração ou variáveis de ambiente (no Azure, `PkiSuite__SdkLicense` e `PkiSuite__WebLicense`) | O serviço volta a responder em `/api/system/info` (que mostra só a versão, não os dados da licença); teste uma assinatura | | [PKI SDK](https://docs.lacunasoftware.com/articles/welcome/licensing#pki-sdk-atualizar) | `LacunaPKILicense.config`, `Web.config`/`App.config` ou `PkiConfig.LoadLicense` | `PkiInfo.License` (licenciado e expiração) | | [PKI Express](https://docs.lacunasoftware.com/articles/welcome/licensing#pki-express-atualizar) | Ativação da máquina (`pkie activate` ou `pkiemgr.exe`) | Comandos executados sem os códigos de erro de ativação e licença (17 a 21) | | [Signer *on-premises*](https://docs.lacunasoftware.com/articles/welcome/licensing#signer-trocar) | Seção `PkiSuite` (`SdkLicense` e `WebLicense`) | A partir da 2.2.0, licença do PKI SDK inválida impede a inicialização: confira `/api/system/info`. Para a do Web PKI, teste uma assinatura no navegador | | [Bulk Signer](https://docs.lacunasoftware.com/articles/welcome/licensing#bulk-signer-trocar) | `Signing__PkiSdkLicense` (ou `Signing:PkiSdkLicense`) | Impressão digital da licença no *banner* de inicialização e no painel | ## Web PKI O [Web PKI](https://docs.lacunasoftware.com/articles/web-pki) é o componente que permite a um site usar os certificados digitais do computador do usuário. A licença do Web PKI é **do site**: ela vale para os domínios da aplicação e é configurada pelo desenvolvedor, no código da página. ### Quando a licença é necessária A licença **não** é necessária: - para testar em uma aplicação rodando no *localhost* (qualquer porta); - quando o Web PKI é usado com o **Rest PKI em nuvem** (`https://pki.rest`), inclusive em produção. Nos demais casos fora do *localhost*, a licença é necessária. Isso inclui: - aplicações que usam o Web PKI com o [PKI SDK](https://docs.lacunasoftware.com/articles/welcome/licensing#pki-sdk), o [PKI Express](https://docs.lacunasoftware.com/articles/welcome/licensing#pki-express) ou qualquer outro *backend* (as licenças do PKI SDK geralmente já vêm acompanhadas de uma licença do Web PKI); - aplicações que usam uma [instância *on-premises* do Rest PKI](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-on-premises), ou seja, um Rest PKI diferente de `https://pki.rest`. Nesse caso, informe também a URL da instância em `restPkiUrl`; - aplicações que usam o [Rest PKI Core](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-core), inclusive em nuvem (`core.pki.rest`): a dispensa vale apenas para o Rest PKI em nuvem (`https://pki.rest`). A licença do Web PKI também entra na configuração do servidor de produtos *on-premises*: no [Signer](https://docs.lacunasoftware.com/articles/welcome/licensing#signer-licencas), ela consta como obrigatória nas instalações em Linux e Azure; no [Rest PKI Core](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-core-licencas), ela é necessária quando os usuários assinam no navegador via Web PKI. **Homologação:** as licenças são emitidas permitindo uso em caráter de homologação em qualquer IP privado (`10.x.x.x`, `127.x.x.x`, `172.16.0.0` a `172.31.255.255` e `192.168.x.x`). Domínios de homologação, como `staging.patorum.com`, ficam no campo `homologDomains` da licença. ### Formatos da licença Você recebe a licença em dois formatos equivalentes: ```javascript // Licença binária var webPkiLicense = 'ASYAanNma...Q=='; // Licença JSON var webPkiLicense = { "format": 1, "allowedDomains": [ "www.patorum.com" ], "homologDomains": [ "staging.patorum.com", "ip4:10.0.0.0/8", "ip4:127.0.0.0/8", "ip4:172.16.0.0/12", "ip4:192.168.0.0/16" ], "productLevel": "Standard", "expiration": null, "signature": "LzdT1cgp...w==" }; ``` - O formato **binário** esconde os detalhes da licença. Eles não ficam cifrados, apenas codificados em Base64. - O formato **JSON** deixa os detalhes legíveis, o que facilita o diagnóstico de problemas como uma licença expirada. - Nas configurações de servidor do Rest PKI Core e do Signer, use a licença **binária**. > **Aviso** > > O campo `signature` da licença JSON não funciona sozinho como licença. Use a licença binária inteira ou a licença > JSON inteira: qualquer tentativa de usar só uma parte da licença faz o componente rejeitá-la. ### Como configurar Passe a licença no construtor da classe `LacunaWebPKI`: ```javascript var pki = new LacunaWebPKI('ASYAanNma...Q=='); // ou o objeto JSON completo pki.init({ ready: onWebPkiReady }); ``` A licença também pode ser informada no parâmetro `license` do método `init()`, caso não tenha sido passada no construtor. Com um Rest PKI diferente de `https://pki.rest`, informe também a URL da instância: ```javascript var pki = new LacunaWebPKI('ASYAanNma...Q=='); pki.init({ restPkiUrl: 'https://YourRestPKI.com/', ready: onWebPkiReady }); ``` ### Como atualizar a licença 1. Solicite a nova licença pelo e-mail [suporte@lacunasoftware.com](mailto:suporte@lacunasoftware.com) ou pelo [Fale conosco](https://www.lacunasoftware.com/pt/home/purchase) (por vencimento ou para incluir um domínio, por exemplo), informando os *hostnames* ou URLs de produção e de homologação. 2. Substitua a licença antiga pela nova **no mesmo lugar** em que ela é informada: no construtor `new LacunaWebPKI(...)`, no parâmetro `license` do `init()` ou, na [substituição do ICPBravoAccess](https://docs.lacunasoftware.com/articles/web-pki/icpbravo-replacement), em `window.lacunaWebPkiLicense`. Troque a licença inteira. 3. Publique a página e teste nos domínios de homologação e de produção. 4. Se a licença do Web PKI também estiver configurada em um produto *on-premises*, troque-a lá: [Rest PKI Core](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-core-trocar) e [Signer](https://docs.lacunasoftware.com/articles/welcome/licensing#signer-trocar). > **Observação** > > Não confunda a licença com a versão do componente. O Web PKI é atualizado automaticamente nos computadores dos > usuários, e a biblioteca JavaScript (`lacuna-web-pki-{version}.js`) deve ser atualizada pelo desenvolvedor. Veja > [Atualizações do Web PKI](https://docs.lacunasoftware.com/articles/web-pki/update). ### Erros de licença Quando há um problema com a licença, o componente retorna um destes códigos de erro ([`LacunaWebPKI.ErrorCodes`](https://docs.lacunasoftware.com/content/typedocs/web-pki/enums/_lacuna_web_pki_d_.lacunawebpki.errorcodes.html)): | Código | Significado | |---|---| | `license_not_set` | A licença é necessária e não foi configurada | | `license_invalid` | A licença informada não é válida | | `license_restricted` | A licença não permite o comando solicitado | | `license_expired` | A licença expirou | | `license_domain_not_allowed` | A licença não permite o domínio em uso | **Artigos de origem:** [Licenciamento do Web PKI](https://docs.lacunasoftware.com/articles/web-pki/licensing) · [Primeiros passos](https://docs.lacunasoftware.com/articles/web-pki/get-started) · [Especificando a URL do Rest PKI](https://docs.lacunasoftware.com/articles/web-pki/customizing-restpki-url) · [Atualizações](https://docs.lacunasoftware.com/articles/web-pki/update) ## Rest PKI > **Observação: Rest PKI e Rest PKI Core são produtos diferentes** > > Cada um tem a sua documentação, a sua nuvem (`pki.rest` e `core.pki.rest`) e a sua forma de acesso. Esta seção trata > do [Rest PKI](https://docs.lacunasoftware.com/articles/rest-pki). O Rest PKI Core tem [seção própria](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-core). ### Rest PKI em nuvem O Rest PKI em nuvem não usa arquivo de licença. O acesso é feito com um **token de acesso** da sua conta: 1. Autentique-se no site do Rest PKI ([pki.rest](https://pki.rest/)). 2. No **Painel de Controle**, clique em **Gerar novo token de acesso** e copie o valor gerado. 3. Configure o token na sua aplicação (nos projetos de exemplo, no arquivo de configuração, como o `web.config`). Nas chamadas HTTP diretas, como as de carimbo de tempo, envie-o no header `Authorization: Bearer `. A resposta **401 Unauthorized** indica que o token informado não é válido. Com o Rest PKI em nuvem, o Web PKI não precisa de licença, inclusive em produção. ### Rest PKI *on-premises* Uma instância *on-premises* do Rest PKI, em Windows Server ou Azure App Service, exige uma **licença do Lacuna PKI SDK**, solicitada durante a instalação. Desde a versão 1.5.0, o Rest PKI também aceita licenças do PKI SDK de uso restrito ao Rest PKI. Para instalar, você precisa de: - o pacote de binários do Rest PKI; - a licença binária do PKI SDK (arquivo `LacunaPkiLicense.txt`). Se ainda não tiver uma, [solicite uma licença de teste](https://www.lacunasoftware.com/pt/home/purchase). No Windows Server, a instalação segue o capítulo 2 do [Manual de instalação](https://cdn.lacunasoftware.com/restpki/restpki-admin-guide-pt.pdf). No Azure App Service, com o pacote e a licença em mãos, [entre em contato](https://www.lacunasoftware.com/pt/home/purchase) para obter as instruções de instalação. Se a sua aplicação usa o Web PKI com a instância *on-premises*, configure também a **licença do Web PKI** e a URL da instância (veja [Como configurar o Web PKI](https://docs.lacunasoftware.com/articles/welcome/licensing#web-pki-configurar)). A partir da versão 1.14.0, o painel do Rest PKI exibe um aviso quando a licença do PKI SDK está próxima do vencimento. A versão 1.12.0 corrigiu um erro que ocorria ao alterar a licença do PKI SDK; em instâncias mais antigas, considere atualizar antes de trocar a licença. ### Como trocar a licença 1. Autentique-se como administrador na sua instância do Rest PKI. Se não souber a senha, veja [Recuperação de senha de admin](https://docs.lacunasoftware.com/articles/rest-pki/on-premises/admin-recover). 2. No menu superior, clique em **Administração** > **Status do sistema**. 3. No item **SDK license loaded**, clique no botão **Alterar**. 4. No arquivo `LacunaPkiLicense.txt`, localize a licença binária do PKI SDK, na seção *Binary license content (Base64-encoded)*: ```text Binary license content (Base64-encoded) --------------------------------------- AxAA........................................iw== ``` 5. Copie e cole **a linha inteira** e clique no botão **Configurar licença**. ![Item SDK license loaded na tela de status do sistema do Rest PKI](https://docs.lacunasoftware.com/images/rest-pki/sdk-license.png) A mesma tela mostra o licenciado e a data de expiração da licença carregada. **Artigos de origem:** [Alterando a licença de uso](https://docs.lacunasoftware.com/articles/rest-pki/on-premises/change-license) · [Rest PKI *on premises*](https://docs.lacunasoftware.com/articles/rest-pki/on-premises) · [Instalação em Windows Server](https://docs.lacunasoftware.com/articles/rest-pki/on-premises/windows-setup) · [Instalação em Azure App Service](https://docs.lacunasoftware.com/articles/rest-pki/on-premises/azure-setup) · [Solicitando carimbos de tempo](https://docs.lacunasoftware.com/articles/rest-pki/requesting-timestamps) ## Rest PKI Core O [Rest PKI Core](https://docs.lacunasoftware.com/articles/rest-pki/core) pode ser usado em nuvem (SaaS), no endereço [core.pki.rest](https://core.pki.rest/), ou em uma instância própria (*on-premises*). ### Rest PKI Core em nuvem No SaaS, a aplicação não usa arquivo de licença. São necessários dois parâmetros, que devem ser solicitados ao [suporte ao desenvolvedor](mailto:suporte@lacunasoftware.com): - o **endpoint** da API; - a **chave de API**. Em ASP.NET Core, os dois ficam na seção `RestPki` do `appsettings.json` (chaves `Endpoint` e `ApiKey`). Chamando a API diretamente, a chave de API vai no header `X-Api-Key` (nos endpoints de carimbo de tempo, use `Authorization: ApiKey SUA_CHAVE_DE_API`; veja [Solicitando carimbos de tempo](https://docs.lacunasoftware.com/articles/rest-pki/core/requesting-timestamps)). A resposta **401** indica chave ausente ou inválida, e a **403**, que a aplicação não tem permissão para a operação. Se a sua aplicação usa o Web PKI com o Rest PKI Core, a licença do Web PKI é necessária: a dispensa vale apenas para o Rest PKI em nuvem (`https://pki.rest`). ### Licenças da instância *on-premises* Uma instância *on-premises* precisa de duas licenças: - **licença do PKI SDK**, em Base64; - **licença do Web PKI**, em formato binário (Base64). | Plataforma | Onde as licenças são configuradas | |---|---| | [Windows Server](https://docs.lacunasoftware.com/articles/rest-pki/core/on-premises/windows-server) | Arquivo `appsettings.ini` na pasta `C:\ProgramData\Lacuna Software\Rest PKI Core` (não a cópia em `config-templates`) | | [Linux (Ubuntu)](https://docs.lacunasoftware.com/articles/rest-pki/core/on-premises/linux/install-ubuntu) | Arquivo `/etc/restpkicore/appsettings.conf` | | [Docker](https://docs.lacunasoftware.com/articles/rest-pki/core/on-premises/docker) | Variáveis de ambiente (arquivo de exemplo `restpkicore.env`) | | [Azure App Services](https://docs.lacunasoftware.com/articles/rest-pki/core/on-premises/azure/install) | *Configuration* do App Service: `PkiSuite__SdkLicense` e `PkiSuite__WebLicense` | No Azure, a `PkiSuite__SdkLicense` é obrigatória, e a `PkiSuite__WebLicense` só é obrigatória se os usuários forem assinar documentos com certificados em seus computadores (assinatura no navegador via Web PKI). Nas demais plataformas, as duas licenças constam como pré-requisito da instalação. Para Rocky Linux, veja a [instalação no Rocky Linux](https://docs.lacunasoftware.com/articles/rest-pki/core/on-premises/linux/install-rocky). Nos arquivos de configuração (Windows, Linux e Docker), preencha as licenças seguindo as instruções do próprio arquivo de modelo. Nas variáveis de ambiente, o nome é formado pela seção e pela configuração separadas por `__` (dois *underscores*): a configuração `SdkLicense` da seção `PkiSuite`, por exemplo, vira `PkiSuite__SdkLicense`. ### Como trocar a licença > **Observação** > > A documentação do Rest PKI Core não tem um artigo específico sobre troca de licença. Os passos abaixo seguem os > procedimentos de configuração e de reinício de cada plataforma. - **Linux**: edite `/etc/restpkicore/appsettings.conf`, substitua a licença e reinicie o serviço com `systemctl restart restpkicore`. Acompanhe os logs com `journalctl -u restpkicore -f`. - **Windows Server**: edite o `appsettings.ini`, substitua a licença e reinicie o site no IIS (*Stop* e *Start*). - **Docker**: altere a licença no arquivo de variáveis de ambiente (por exemplo, `restpkicore.env`). Como as variáveis são lidas na criação do contêiner, remova o contêiner atual (`docker rm -f restpkicore`) e crie-o novamente com o mesmo comando `docker run --name restpkicore --env-file restpkicore.env ...` da instalação. Confira os logs com `docker logs -f restpkicore`. - **Azure App Services**: em *Configuration*, altere `PkiSuite__SdkLicense` e/ou `PkiSuite__WebLicense` e clique em **Save**. Depois da troca, confira se a instância responde em `https://endereco-do-seu-restpki-core/api/system/info`. ### Antes de atualizar a versão Algumas versões exigem que a licença do PKI SDK suporte versões lançadas até uma certa data: | Versão do Rest PKI Core | A licença do PKI SDK deve suportar versões lançadas até | |---|---| | [2.0.0 RC 8](https://docs.lacunasoftware.com/articles/rest-pki/core/changelog#v2.0.0-rc08) | 2023-06-27 | | [2.0.0 RC 7](https://docs.lacunasoftware.com/articles/rest-pki/core/changelog#v2.0.0-rc07) | 2022-10-19 | Antes de atualizar, consulte o [histórico de versões](https://docs.lacunasoftware.com/articles/rest-pki/core/changelog) entre a sua versão e a de destino. A versão instalada aparece em `/api/system/info` (veja [Verificando a versão instalada](https://docs.lacunasoftware.com/articles/rest-pki/core/on-premises/check-version)). **Artigos de origem:** [Rest PKI Core](https://docs.lacunasoftware.com/articles/rest-pki/core) · [Primeiros passos para integração](https://docs.lacunasoftware.com/articles/rest-pki/core/integration/get-started) · [Ambientes *on premises*](https://docs.lacunasoftware.com/articles/rest-pki/core/on-premises#platforms) · [Setup em Azure App Services](https://docs.lacunasoftware.com/articles/rest-pki/core/on-premises/azure/install) · [Histórico de versões](https://docs.lacunasoftware.com/articles/rest-pki/core/changelog) ## PKI SDK O [Lacuna PKI SDK](https://docs.lacunasoftware.com/articles/pki-sdk) é uma biblioteca .NET, distribuída pelo NuGet (pacote `Lacuna.Pki`). Para usá-lo, é necessário carregar a licença na inicialização da aplicação. ### Como obter a licença Se você ainda não tem uma licença, entre em contato pelo site pki.lacunasoftware.com para obter uma licença de *trial* gratuita. A licença pode ser usada em dois formatos: - arquivo `LacunaPKILicense.config`; - texto em Base64. Se a sua aplicação faz assinatura no navegador, ela também usa o [Web PKI](https://docs.lacunasoftware.com/articles/welcome/licensing#web-pki), que precisa de licença própria fora do *localhost*. As licenças do PKI SDK geralmente já vêm acompanhadas de uma licença do Web PKI. ### Como carregar a licença Existem três formas. A recomendada depende do tipo de aplicação: | Forma | Recomendada para | |---|---| | Arquivo `LacunaPKILicense.config` no diretório da DLL | Aplicações web | | Chave no `Web.config` ou no `App.config` | — | | Programaticamente, com `PkiConfig.LoadLicense` | Aplicações desktop | **1. Arquivo no diretório da DLL.** O SDK procura automaticamente o arquivo `LacunaPKILicense.config` junto à `Lacuna.Pki.dll`. Uma forma prática é incluir o arquivo no projeto com **Build Action** = **Content** e **Copy to Output Directory** = **Copy Always**. **2. `Web.config` ou `App.config`.** Na seção `appSettings`, informe o caminho do arquivo ou a licença em Base64: ```xml ``` **3. Programaticamente.** No código de inicialização do site ou da aplicação, carregue a licença decodificada: ```csharp byte[] binLicense = Convert.FromBase64String("[licença em Base64]"); PkiConfig.LoadLicense(binLicense); ``` Essa forma deixa a licença embutida no código-fonte, o que dificulta o vazamento para terceiros. Também existe `PkiConfig.LoadLicense(string)`, que recebe o caminho do arquivo `.config`, mas ela não é recomendada para aplicações desktop. ### Como atualizar a licença > **Observação** > > A página de licenciamento do PKI SDK não descreve a troca de licença. Como a licença é carregada na inicialização, o > procedimento é substituí-la onde ela foi configurada e reiniciar a aplicação. 1. Substitua a licença no mesmo lugar em que ela foi configurada: o arquivo `LacunaPKILicense.config`, a chave `LacunaPKI.LicensePath` ou `LacunaPKI.BinaryLicense`, ou o valor passado a `PkiConfig.LoadLicense`. 2. Se a licença está incluída no projeto ou embutida no código, recompile e publique a aplicação. 3. Reinicie a aplicação ou o site. 4. Para conferir a licença carregada, use a propriedade `PkiInfo.License` (classe [`PkiInfo`](https://docs.lacunasoftware.com/api/Lacuna.Pki.Util/PkiInfo)), que informa o licenciado (`Licensee`) e a data de expiração (`Expiration`). Nos produtos *on-premises* que usam a licença do PKI SDK, a troca é feita na configuração de cada produto: veja [Rest PKI](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-trocar), [Rest PKI Core](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-core-trocar), [Signer](https://docs.lacunasoftware.com/articles/welcome/licensing#signer-trocar) e [Bulk Signer](https://docs.lacunasoftware.com/articles/welcome/licensing#bulk-signer-trocar). ### Licença e versões do SDK A licença do PKI SDK pode ter data de expiração (confira em `PkiInfo.License.Expiration`) e aceita apenas versões do SDK lançadas até uma certa data. Por isso, os produtos que usam o PKI SDK avisam, no histórico de versões, qual cobertura a licença precisa ter antes de uma atualização (veja [Signer](https://docs.lacunasoftware.com/articles/welcome/licensing#signer-versao) e [Rest PKI Core](https://docs.lacunasoftware.com/articles/welcome/licensing#rest-pki-core-versao)). **Artigos de origem:** [Licenciamento do PKI SDK](https://docs.lacunasoftware.com/articles/pki-sdk/get-started/licensing) · [Acessando pacotes NuGet](https://docs.lacunasoftware.com/articles/pki-sdk/get-started/nuget) · [Assinatura no browser](https://docs.lacunasoftware.com/articles/pki-sdk/signatures/web-remote) ## PKI Express O [PKI Express](https://docs.lacunasoftware.com/articles/pki-express) é instalado em Windows ou Linux e **precisa de uma licença**: o arquivo `LacunaPkiLicense.config`, usado para ativar o PKI Express na máquina. ### Como obter a licença [Fale conosco](https://www.lacunasoftware.com/pt/home/purchase) para obter uma licença para testes. ### Ativação no Windows 1. Instale o PKI Express com o instalador ou, sem permissões de administrador, com um dos pacotes zip (veja [Instalação em Windows](https://docs.lacunasoftware.com/articles/pki-express/setup/windows)). 2. Abra a pasta de instalação e execute o **PKI Express Configuration Manager** (arquivo `pkiemgr.exe`). Não há atalho no menu Iniciar: é preciso navegar até a pasta. 3. Siga as instruções do aplicativo para ativar o PKI Express. No Windows, tanto a ativação pela rede quanto a manual são feitas por esse aplicativo. ### Ativação no Linux Depois de instalar o pacote e configurar a pasta de logs (veja [Ubuntu ou Mint](https://docs.lacunasoftware.com/articles/pki-express/setup/linux-ubuntu#install), [Red Hat Enterprise Linux](https://docs.lacunasoftware.com/articles/pki-express/setup/linux-rhel#install) ou [CentOS, Oracle Linux ou Fedora](https://docs.lacunasoftware.com/articles/pki-express/setup/linux-centos#install)), ative o PKI Express com o arquivo de licença: ```sh sudo pkie activate LacunaPkiLicense.config ``` Se a ativação automática falhar, faça a [ativação manual](https://docs.lacunasoftware.com/articles/welcome/licensing#pki-express-manual). ### Ativação manual (Linux) 1. Gere o pedido de ativação: ```sh pkie activate LacunaPkiLicense.config --request ``` Um arquivo chamado `pkie-activation-request.pem` é salvo na pasta atual. 2. Envie esse arquivo pela [Central de Suporte](http://lacuna.help). 3. Você receberá de volta o arquivo de ativação `pkie-activation.pem`. Copie-o para a pasta atual e execute: ```sh sudo pkie activate ``` Ou, se preferir, informe o caminho do arquivo: ```sh sudo pkie activate --file /path/to/pkie-activation.pem ``` ### Trocar a licença e atualizar a versão > **Observação** > > A documentação do PKI Express não tem um artigo específico sobre troca de licença. Para aplicar uma nova licença, > refaça a ativação com o novo arquivo `LacunaPkiLicense.config`: no Linux, com > `sudo pkie activate LacunaPkiLicense.config` (ou pela [ativação manual](https://docs.lacunasoftware.com/articles/welcome/licensing#pki-express-manual)); no Windows, pelo > `pkiemgr.exe`. A ativação manual com uma nova licença foi corrigida na versão > [1.6.2](https://docs.lacunasoftware.com/articles/pki-express/changelog#v1-6-2); use essa versão ou superior. Atualizar a **versão** do PKI Express é outro procedimento: - **Windows**: baixe a nova versão e execute o instalador (veja [Atualização](https://docs.lacunasoftware.com/articles/pki-express/setup/windows#update)). - **Linux**: baixe o novo pacote, apague o conteúdo da pasta de destino e extraia o novo pacote nela (veja Atualização em [Ubuntu ou Mint](https://docs.lacunasoftware.com/articles/pki-express/setup/linux-ubuntu#update), [RHEL](https://docs.lacunasoftware.com/articles/pki-express/setup/linux-rhel#update) ou [CentOS, Oracle Linux ou Fedora](https://docs.lacunasoftware.com/articles/pki-express/setup/linux-centos#update)). Se estiver atualizando a partir de uma versão 1.0.x, refaça também a configuração da pasta de logs e a ativação. ### Códigos de retorno | Código | Nome | Significado | |---|---|---| | 17 | `NotActivated` | PKI Express não ativado | | 18 | `ActivationError` | Falha na ativação do PKI Express | | 19 | `BadLicense` | Base64 inválida (da licença de ativação) | | 20 | `LicenseNeeded` | Nenhum arquivo de licença fornecido | | 21 | `InvalidLicense` | Licença inválida | **Artigos de origem:** [PKI Express](https://docs.lacunasoftware.com/articles/pki-express) · [Instalação](https://docs.lacunasoftware.com/articles/pki-express/setup) · [Ativação manual](https://docs.lacunasoftware.com/articles/pki-express/setup/manual-activation) · [Códigos de retorno](https://docs.lacunasoftware.com/articles/pki-express/return-codes) ## Signer Uma instância *on-premises* do [Signer](https://docs.lacunasoftware.com/articles/signer) precisa de duas licenças: - **licença do PKI SDK**, em Base64; - **licença do Web PKI**, em formato binário (Base64). ### Onde as licenças são configuradas | Plataforma | Onde configurar | |---|---| | [Linux (Ubuntu)](https://docs.lacunasoftware.com/articles/signer/on-premises/linux/install-ubuntu) | Arquivo `/etc/lacuna-signer/appsettings.linux.json`, seção `PkiSuite`: `SdkLicense` e `WebLicense` | | [Azure App Services](https://docs.lacunasoftware.com/articles/signer/on-premises/azure) | *Configuration* do App Service: `PKiSuite__SdkLicense` e `PKiSuite__WebLicense` | | [Windows Server](https://docs.lacunasoftware.com/articles/signer/on-premises/windows) | Arquivo `appsettings.iis.json`, seção `PkiSuite`: `SdkLicense` e `WebLicense` | | [Docker](https://docs.lacunasoftware.com/articles/signer/on-premises/docker) | Variáveis de ambiente `PkiSuite__SdkLicense` e `PkiSuite__WebLicense` | Nas páginas de instalação em Linux e em Azure, as duas licenças são obrigatórias. Nos artigos de Windows Server e Docker, apenas a `SdkLicense` consta como obrigatória, e a `WebLicense` aparece como condicional. De qualquer forma, a licença do Web PKI é necessária para a [assinatura embutida](https://docs.lacunasoftware.com/articles/welcome/licensing#signer-embutida). A partir da versão 2.2.0, a licença do PKI SDK é validada na inicialização: se ela não for válida, a inicialização é interrompida. ### Como trocar a licença > **Observação** > > A documentação do Signer não tem um artigo específico sobre troca de licença. Os passos abaixo seguem os > procedimentos de instalação e de atualização de cada plataforma. - **Linux**: edite `/etc/lacuna-signer/appsettings.linux.json`, substitua `SdkLicense` e/ou `WebLicense` na seção `PkiSuite` e reinicie o serviço com `systemctl restart lacuna-signer`. Confira com `systemctl status lacuna-signer` e acompanhe os logs com `journalctl -u lacuna-signer -f`. - **Azure App Services**: em *Configuration*, altere `PKiSuite__SdkLicense` e/ou `PKiSuite__WebLicense` e clique em **Save**. - **Windows Server**: pare o site no IIS, altere a seção `PkiSuite` do `appsettings.iis.json` e inicie o site novamente. - **Docker**: altere as variáveis `PkiSuite__SdkLicense` e/ou `PkiSuite__WebLicense` e recrie o contêiner. Depois da troca, confira se a instância responde em `/api/system/info` (no Linux, por exemplo, `curl http://localhost:5001/api/system/info`). ### Antes de atualizar a versão do Signer Algumas versões exigem que a licença do PKI SDK suporte versões do SDK lançadas até uma certa data. Confira o [histórico de versões](https://docs.lacunasoftware.com/articles/signer/changelog) entre a versão atual e a de destino: | Versão do Signer | A licença deve suportar versões do PKI SDK lançadas | |---|---| | [2.2.0](https://docs.lacunasoftware.com/articles/signer/changelog#v2-2-0) | até 2025-08-01 | | [2.0.0](https://docs.lacunasoftware.com/articles/signer/changelog#v2-0-0) | até 2025-05-20 | | [1.72.0](https://docs.lacunasoftware.com/articles/signer/changelog#v1-72-0) | até 2024-07-03 | | [1.64.0](https://docs.lacunasoftware.com/articles/signer/changelog#v1-64-0) | até 2023-09-27 | | [1.61.0](https://docs.lacunasoftware.com/articles/signer/changelog#v1-61-0) | até 2023-08-01 | | [1.59.0](https://docs.lacunasoftware.com/articles/signer/changelog#v1-59-0) | até 2023-06-28 | | [1.58.0](https://docs.lacunasoftware.com/articles/signer/changelog#v1-58-0) | até 2023-05-25 | | [1.43.0](https://docs.lacunasoftware.com/articles/signer/changelog#v1-43-0) | após 2022-04-29 | Se a sua licença não cobre a data exigida, obtenha uma licença atualizada do PKI SDK antes de atualizar. ### Assinatura embutida Para usar a [assinatura embutida](https://docs.lacunasoftware.com/articles/signer/embedded-signature) (componente `LacunaSignerWidget`) em outra aplicação, o Signer deve estar configurado com uma licença do Web PKI que tenha o domínio no qual o componente será carregado. Para incluir um novo domínio, obtenha uma nova licença do Web PKI e troque-a conforme [Como trocar a licença](https://docs.lacunasoftware.com/articles/welcome/licensing#signer-trocar). **Artigos de origem:** [Instalação em Ubuntu Server](https://docs.lacunasoftware.com/articles/signer/on-premises/linux/install-ubuntu) · [Setup em Azure App Services](https://docs.lacunasoftware.com/articles/signer/on-premises/azure) · [Atualização em Linux](https://docs.lacunasoftware.com/articles/signer/on-premises/linux/update) · [Histórico de versões](https://docs.lacunasoftware.com/articles/signer/changelog) ## Bulk Signer O [Bulk Signer](https://docs.lacunasoftware.com/articles/bulk-signer) usa uma única licença: a **licença do Lacuna PKI SDK**, um texto em Base64 fornecido pela Lacuna Software. Ela é obrigatória: sem ela, o serviço não inicia. ### Como obter A Lacuna entrega três itens, que não são intercambiáveis: - as credenciais do *registry* (usuário e token de acesso), para baixar a imagem de contêiner; - um identificador único, usado nas URLs de download dos binários; - a licença do PKI SDK, que libera o serviço em execução. Como a licença é apenas um texto, e não um download, ela também funciona em servidores isolados da rede. ### Onde configurar A forma preferida é a variável de ambiente `Signing__PkiSdkLicense`. Também é possível usar a chave `Signing:PkiSdkLicense` no `appsettings.Production.json`, desde que o arquivo esteja fora do controle de versão e com acesso restrito à conta de serviço. A variável é preferida porque mantém a licença fora da árvore de arquivos, e ela tem precedência na inicialização. | Alvo | Onde definir `Signing__PkiSdkLicense` | Como aplicar | |---|---|---| | Linux (systemd) | Arquivo `/etc/bulksigner/bulksigner.env` (modo `0640`, dono `bulksigner`) | `sudo systemctl restart bulksigner` | | Windows (serviço) | Variável de ambiente de escopo de máquina | `Restart-Service LacunaBulkSigner` | | Docker / Compose | Arquivo `deploy/docker/.env` | `docker compose up -d` | | Azure App Service | *App settings*, como referência ao Key Vault | Veja [Azure App Service](https://docs.lacunasoftware.com/articles/bulk-signer/azure) | No Windows, defina a variável em um PowerShell com privilégios elevados: ```powershell [Environment]::SetEnvironmentVariable("Signing__PkiSdkLicense", "", "Machine") Restart-Service LacunaBulkSigner ``` > **Aviso: Atualizando a partir da 1.0.x** > > Na versão 1.0.x, a chave se chamava `Signing:License` (`Signing__License`). Ela foi renomeada na 1.1.0 e o nome > antigo não é mais lido: uma instalação atualizada que ainda usa o nome antigo falha na inicialização com > `Signing:PkiSdkLicense is required`. Renomeie a chave durante a atualização. ### Como trocar a licença 1. Anote a impressão digital da licença atual: linha `pki license` do *banner* de inicialização, ou página **Sistema** (`/system`) do painel, campo **Impressão digital da licença**. 2. Substitua o valor de `Signing__PkiSdkLicense` no local indicado para o seu alvo (tabela acima). Se você usa `Signing:PkiSdkLicense` no `appsettings.Production.json`, verifique se não há uma variável de ambiente antiga definida, porque ela tem precedência. 3. Reinicie o serviço. 4. Confira se a impressão digital da licença mudou e se o endpoint `/api/ready` não aponta falha na verificação `license`. ### Diagnóstico - **`Signing:PkiSdkLicense is required`**: nem a variável de ambiente nem a configuração têm valor. Defina a variável no alvo e reinicie o serviço. - **`/api/ready` retorna 503 com falha na verificação `license`**: a licença não foi carregada. Se a impressão digital não aparece no *banner*, a licença foi rejeitada na inicialização. **Artigos de origem:** [Instalação](https://docs.lacunasoftware.com/articles/bulk-signer/installation) · [Configuração](https://docs.lacunasoftware.com/articles/bulk-signer/configuration) · [Segurança](https://docs.lacunasoftware.com/articles/bulk-signer/security) · [Resolução de problemas](https://docs.lacunasoftware.com/articles/bulk-signer/troubleshooting) ## Para usuários finais Esta seção é para quem usa um site ou sistema que pede o **Web PKI**, a extensão de navegador da Lacuna, para assinar documentos ou fazer login com certificado digital. ### Preciso comprar ou configurar uma licença? Não. Quando o Web PKI exige licença, ela é do site: vale para os domínios do site e é configurada por quem o desenvolve, no código da página (sites que usam o Rest PKI em nuvem nem precisam dela). Quem apenas instala a extensão para usar o site não compra nem configura licença. Se o site exibir um erro de licença do Web PKI (por exemplo, licença expirada ou domínio não permitido), o problema está na configuração do site. Informe a empresa responsável por ele. ### Certificado digital: quem emite? O Web PKI não emite certificados digitais. Ele permite que o site use um certificado que você já tem, seja um certificado A1, instalado no computador, seja um A3, em um dispositivo criptográfico como token ou cartão. Certificados ICP-Brasil são adquiridos de uma Autoridade Certificadora (AC) credenciada, que consta na [lista oficial do ITI](https://www.gov.br/iti/pt-br/assuntos/icp-brasil/entidades-icp-brasil). Dúvidas sobre compra, validade ou renovação do certificado devem ser tratadas com a AC que o emitiu. Para conferir, no Windows, se há um certificado com chave privada no computador: 1. **Iniciar** > **Executar...** > **certmgr.msc** 2. Na pasta **Pessoal**, dê um duplo clique no certificado. 3. Deve aparecer a mensagem "Tem uma chave particular correspondente a este certificado." ### Instalação do Web PKI - Se o componente não estiver instalado, estiver desatualizado ou o navegador não for suportado, normalmente o site leva você à página de instalação e, ao final, você volta automaticamente ao site (o site pode exibir antes uma mensagem própria). - A instalação do Web PKI é feita apenas a partir de [get.webpkiplugin.com](https://get.webpkiplugin.com): a extensão vem da loja oficial do navegador, e o aplicativo nativo é baixado desse mesmo domínio. - Depois de instalado, o Web PKI é atualizado automaticamente. - Veja os [navegadores suportados](https://docs.lacunasoftware.com/articles/web-pki/browser-support). ### Onde pedir ajuda - **Erros de licença ou dúvidas sobre o serviço do site**: fale com a empresa responsável pelo site. Pedidos sobre os seus dados pessoais também devem ser feitos a ela, que é a controladora dos dados. - **Problemas para instalar ou usar o Web PKI**: visite a [Central de Suporte](http://lacuna.help/) da Lacuna. - Ao pedir suporte, ajuda ativar os logs detalhados: clique no ícone da extensão e vá em **Configurações** > **Avançadas** > **Logs detalhados** (veja [Logs](https://docs.lacunasoftware.com/articles/web-pki/logs)). ## Contatos | Canal | Para quê | |---|---| | [Fale conosco](https://www.lacunasoftware.com/pt/home/purchase) | Solicitar licenças, licenças de teste e informações comerciais | | [suporte@lacunasoftware.com](mailto:suporte@lacunasoftware.com) | Suporte ao desenvolvedor, pedido de licença do Web PKI e parâmetros do Rest PKI Core em nuvem | | [Central de Suporte](http://lacuna.help/) | Usuários finais e ativação manual do PKI Express | | pki.lacunasoftware.com | Licença de *trial* gratuita do PKI SDK | | +55 61 3030-5700 | Telefone. Endereço: EQN 102/103, Ed. Avenida 102, 2º andar, Asa Norte, Brasília-DF | # [Contribuindo](https://docs.lacunasoftware.com/articles/welcome/contributing) No momento, não estamos aceitando contribuições públicas, mas em breve passaremos a aceitar pull requests. Por enquanto, se você encontrar um erro ou notar que falta algo neste portal de documentação, [abra uma issue](https://github.com/LacunaSoftware/docs/issues) ## Criando um novo artigo Siga estas orientações para criar um novo artigo: 1. Crie o artigo **nos dois projetos, en-us e pt-br**, com codificação UTF-8 com BOM 1. Altere o `toc.md` **dos dois projetos**, incluindo o artigo > **Dica** > > Uma forma fácil de garantir que o novo artigo tenha codificação UTF-8 com BOM é copiar um artigo existente em vez de criar um arquivo novo. Você não precisa escrever as duas versões do artigo de imediato: pode escrever uma das versões e colocar isto na outra: ```md # Article title {/* link to version in Portuguese */}
``` ou ```md # Título do Artigo {/* link to version in English */}
``` ## Escrevendo documentação Estes são os links mais importantes sobre como escrever documentação: * [Mastering Markdown - GitHub Guides](https://guides.github.com/features/mastering-markdown/) * [DocFX Flavored Markdown - site do DocFX](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html) * [Links and Cross References - site do DocFX](https://dotnet.github.io/docfx/tutorial/links_and_cross_references.html) * [Overwrite Files - site do DocFX](https://dotnet.github.io/docfx/tutorial/intro_overwrite_files.html) ## Guia rápido de Markdown Esta é a sintaxe dos elementos mais comuns: * [Títulos](https://docs.lacunasoftware.com/articles/welcome/contributing#títulos) * [Negrito](https://docs.lacunasoftware.com/articles/welcome/contributing#negrito) * [Itálico](https://docs.lacunasoftware.com/articles/welcome/contributing#itálico) * [Código inline](https://docs.lacunasoftware.com/articles/welcome/contributing#código-inline) * [Listas](https://docs.lacunasoftware.com/articles/welcome/contributing#listas) * [Linhas horizontais](https://docs.lacunasoftware.com/articles/welcome/contributing#linhas-horizontais) * [Links](https://docs.lacunasoftware.com/articles/welcome/contributing#links) * [Trechos de código](https://docs.lacunasoftware.com/articles/welcome/contributing#trechos-de-código) * [Includes](https://docs.lacunasoftware.com/articles/welcome/contributing#includes) * [Inclusão de trechos de código](https://docs.lacunasoftware.com/articles/welcome/contributing#inclusão-de-trechos-de-código) * [Imagens](https://docs.lacunasoftware.com/articles/welcome/contributing#imagens) * [Citações, notas e avisos](https://docs.lacunasoftware.com/articles/welcome/contributing#citações-notas-e-avisos) * [Tabelas](https://docs.lacunasoftware.com/articles/welcome/contributing#tabelas) ### Títulos Título de nível superior (H1): ```md # Article title ``` Título de nível 2 (H2): ```md ## Section title ``` Título de nível 3 (H3): ```md ### Subsection title ``` ### Negrito ```md This is a **bold** statement ``` This is a **bold** statement ### Itálico ```md This is a *foreign word*. ``` This is a *foreign word*. ### Código inline ```md Pass the `callback` parameter ``` Pass the `callback` parameter ### Listas Não ordenada: ```md * Item A * Item B * Subitem (prefix spaces to align with parent) * And so on * Item C ``` * Item A * Item B * Subitem (prefix spaces to align with parent) * And so on * Item C Ordenada: ```md 1. Item 1 1. Item 2 1. Subitem (prefix spaces to align with parent) 1. And so on 1. Item 3 ``` 1. Item 1 1. Item 2 1. Subitem (prefix spaces to align with parent) 1. And so on 1. Item 3 > A numeração em si não importa: o DocFX ordena a lista ao renderizar o arquivo. Prefira repetir `1.` em todos os itens em vez de escrever `1.`, `2.`, `3.` etc., porque isso facilita reordenar os itens. ### Linhas horizontais Use `***` para inserir uma linha horizontal: ```md Something *** Some other thing ``` > **Observação** > > **Não** use a sintaxe `---`, pois ela tem um significado especial no DocFX ### Links ```md [text](url) ``` Para artigos na mesma pasta: ```md See the article [Welcome](index.md) ``` See the article [Welcome](https://docs.lacunasoftware.com/articles/welcome) Para artigos em outras pastas: ```md You can use the [Lacuna PKI SDK](../pki-sdk/index.md) for this purpose ``` You can use the [Lacuna PKI SDK](https://docs.lacunasoftware.com/articles/pki-sdk) for this purpose Para classes: ```md See class @Lacuna.RestPki.Client.RestPkiClient ``` See class @Lacuna.RestPki.Client.RestPkiClient Para métodos: ```md See method @Lacuna.RestPki.Client.RestPkiClient.GetPkiBrazilTimestamper ``` See method @Lacuna.RestPki.Client.RestPkiClient.GetPkiBrazilTimestamper > Para descobrir os UIDs exatos de classes e métodos, veja os arquivos .yml da pasta `api` depois de compilar o projeto docfx. Em alguns casos, a sintaxe `@uid` não funciona para referências cruzadas. Nesses casos, use: ```md ``` Se o uid contiver um `#`, codifique-o como `%23`: ```md ``` Links para seções de artigos: Primeiro, você precisa declarar o nome da âncora logo antes do título da seção: ```md ## Section title \{#anchor-name} ``` > **Observação** > > Se o artigo estiver em inglês e o título da seção corresponder ao nome da âncora (convertido para minúsculas e com os espaços substituídos por hifens), você > não precisa declarar a âncora Depois, para criar o link para a seção: ```md See [Default error callback](../web-pki/advanced.md#default-error-callback) ``` See [Default error callback](https://docs.lacunasoftware.com/articles/web-pki/advanced#default-error-callback) ### Trechos de código ```languageid code ``` IDs de linguagem comuns: * csharp ou cs * javascript ou js * html Trechos de código podem ser indentados dentro de listas: 1. Instalação 1. Prepare o ambiente 1. Execute isto: ```bash sudo apt install something ``` 1. Finalize 1. Pronto Veja todos os [nomes e aliases de linguagem](https://github.com/highlightjs/highlight.js#supported-languages) suportados. ### Includes ```md {/* include: url */} ``` Blocos de include comuns aos dois idiomas ficam na pasta [includes/](https://github.com/LacunaSoftware/docs/tree/master/includes). Por exemplo, para incluir o bloco [rest-pki-samples-matrix.md](https://github.com/LacunaSoftware/docs/blob/master/includes/rest-pki-samples-matrix.md) a partir de um local como `docs.en-us/articles/project-name/article.md`: ```md {/* include: ../../../includes/rest-pki-samples-matrix.md */} ``` Exemplo: [Rest PKI](https://docs.lacunasoftware.com/articles/rest-pki) ### Inclusão de trechos de código * [Sintaxe](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#code-snippet) * Exemplo: @Lacuna.Pki.Cades.CadesSignatureCompression \[[código-fonte](https://github.com/LacunaSoftware/docs/blob/master/docs.en-us/apidoc/Lacuna.Pki.Cades.CadesSignatureCompression.md)\] ### Imagens ```md ![Alt Text](url) ``` `url` pode ser uma URL remota, mas normalmente é uma referência relativa a uma imagem da pasta [images/](https://github.com/LacunaSoftware/docs/tree/master/images). Por exemplo, para referenciar a imagem [images/pki-sdk/pades-rectangle.png](https://github.com/LacunaSoftware/docs/blob/master/images/pki-sdk/pades-rectangle.png) a partir dos seguintes locais: A partir de `docs.en-us/articles/project-name/article.md`: ```md ![Image name](/images/pki-sdk/pades-rectangle.png) ``` A partir de `docs.en-us/articles/project-name/subfolder/article.md`: ```md ![Image name](/images/pki-sdk/pades-rectangle.png) ``` Exemplos: * [PKI SDK / Primeiros passos / Adicionando o pacote nuget](https://docs.lacunasoftware.com/articles/pki-sdk/get-started/nuget) * [Web PKI / Browsers suportados](https://docs.lacunasoftware.com/articles/web-pki/browser-support) ### Citações, notas e avisos Citações: ```md As Jeffrey Lebowski once said: > Far out. ``` As Jeffrey Lebowski once said: > Far out. Notas: ```md :::note This is an important notice ::: ``` > **Observação** > > This is an important notice Avisos: ```md :::warning Watch out! ::: ``` > **Aviso** > > Watch out! Também são suportados: > **Dica** > > Isto é uma dica > **Info** > > Isto é importante > **Cuidado** > > Prossiga com cautela ### Tabelas ```md First Header | Second Header --------------------------- | ------------- Content from cell 1 | Content from cell 2 Content in the first column | Content in the second column ``` First Header | Second Header --------------------------- | ------------- Content from cell 1 | Content from cell 2 Content in the first column | Content in the second column Não é realmente necessário alinhar as colunas; isto gera exatamente o mesmo resultado: ```md First Header | Second Header ------------ | ------------- Content from cell 1 | Content from cell 2 Content in the first column | Content in the second column ``` First Header | Second Header ------------ | ------------- Content from cell 1 | Content from cell 2 Content in the first column | Content in the second column Para casos mais complexos, por exemplo com a célula superior esquerda em branco, use esta sintaxe um pouco mais complexa: ```md | | Second Header | | --- | ------------- | | Content from cell 1 | Content from cell 2 | | Content in the first column | Content in the second column | ``` | | Second Header | | --- | ------------- | | Content from cell 1 | Content from cell 2 | | Content in the first column | Content in the second column | > A especificação do Markdown do GitHub (que o DocFX estende) exige pelo menos três hifens (`---`) em cada coluna da linha de cabeçalho (como mostrado acima, na primeira coluna). A linha de cabeçalho é sempre renderizada em negrito. Se você também precisar da primeira coluna em negrito, faça assim: ```md | | Ease of use | Awesomeness | | ------------ | ------------- | ------------ | | **Web PKI** | Very easy | So good | | **Rest PKI** | Super easy | Much awesome | | **PKI SDK** | Easy peasy | Wow | ``` | | Ease of use | Awesomeness | | ------------ | ------------- | ------------ | | **Web PKI** | Very easy | So good | | **Rest PKI** | Super easy | Much awesome | | **PKI SDK** | Easy peasy | Wow | O texto nas células normalmente fica alinhado à esquerda. Para outros alinhamentos: ```md | Left-aligned | Center-aligned | Right-aligned | | :--- | :---: | ---: | | git status | git status | git status | | git diff | git diff | git diff | ``` | Left-aligned | Center-aligned | Right-aligned | | :--- | :---: | ---: | | git status | git status | git status | | git diff | git diff | git diff | Veja também: * [Organizing information with tables - GitHub Help](https://help.github.com/articles/organizing-information-with-tables/) * Exemplos * Tabela com a célula superior esquerda em branco: [Web PKI / Introdução](https://docs.lacunasoftware.com/articles/web-pki) * Tabela com texto centralizado: [Web PKI / Browsers suportados](https://docs.lacunasoftware.com/articles/web-pki/browser-support) # [Política de Privacidade](https://docs.lacunasoftware.com/articles/welcome/privacy-policy) * Última alteração: 16 de junho de 2020 * Data efetiva: 16 de junho de 2020 A Lacuna Software Ltda (coletivamente, "Lacuna", "nós", "nos" ou "nosso") respeita a sua privacidade. Os serviços que oferecemos são ferramentas para que organizações e desenvolvedores façam uso de certificação digital e tecnologias correlatas com segurança. Nossa Política de Privacidade descreve os tipos de Dados Pessoais que coletamos por nossos produtos e serviços (“Serviços”) e por nossa presença online, que inclui nosso site principal, [Lacuna Software](https://lacunasoftware.com/), e serviços e sites que disponibilizamos na Internet, como o [Dropsigner](https://www.dropsigner.com/) (coletivamente, nossos “Sites”). Esta política também descreve como usamos Dados Pessoais, com quem os compartilhamos, quais são seus direitos e opções e como você pode entrar em contato conosco para falar sobre as nossas práticas de privacidade. Esta política não se aplica a sites, produtos ou serviços de terceiros, mesmo que eles estejam vinculados aos nossos Serviços ou Sites, portanto, informe-se com atenção sobre as práticas de privacidade de tais terceiros. De modo a facilitar referenciação, nossa Política de Privacidade está segmentada por produto e serviço, observando as especificidades de cada um. Na lista abaixo é possível encontrar todos os artigos: * [Política de Privacidade do Rest PKI](https://docs.lacunasoftware.com/articles/rest-pki/privacy-policy) * [Política de Privacidade do Web PKI](https://docs.lacunasoftware.com/articles/web-pki/privacy-policy) ## Perguntas / Comentários sobre privacidade Se você tiver questões ou sugestões sobre a Política de Privacidade da Lacuna, por favor entre em contato conosco em [suporte@lacunasoftware.com](mailto:suporte@lacunasoftware.com) ou EQN 102/103, Ed. Avenida 102, 2º Andar - Asa Norte, Brasília-DF, Brasil. Telefone: +55 61 3030-5700. # [Referência rápida do Web PKI](https://docs.lacunasoftware.com/articles/web-pki/quick-reference) 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 ``` ```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) # [Lacuna Web PKI](https://docs.lacunasoftware.com/articles/web-pki) O componente Web PKI possibilita que páginas web interajam com certificados digitais através de código javascript. > **Dica** > > O Web PKI faz parte da nossa linha de soluções para certificação digital. Recomendamos que você leia o artigo > [Certificação Digital](https://docs.lacunasoftware.com/articles/pki-guide) para ter certeza de que esse é o produto mais indicado para o seu caso. As principais funcionalidades são: * Recuperar os certificados disponíveis (A1, A3, etc) * Obter os atributos públicos do certificado (Nome, e-mail, etc) * Ler a codificação binária de um certificado * Assinar dados (ou um hash pré-computado) com um certificado O principal objetivo do Web PKI é realizar o processamento client-side necessário em operações com certificados digitais. Um exemplo de operação seria uma [assinatura digital remota](https://docs.lacunasoftware.com/articles/pki-guide/web-signatures/remote) utilizando um SDK (Software Development Kit) no servidor: | | *Client-side* (Lacuna Web PKI) | *Server-side* (SDK no servidor) | | - | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 1 | Obter o *encoding* do certificado e enviar ao servidor | Preparar a assinatura, produzindo os bytes que devem ser utilizados como entrada para o algoritmo de assinatura ("to-sign-bytes" ou "signed attributes") | | 2 | Assinar os "to-sign-bytes" com a chave de um certificado digital e enviar o resultado ao servidor | Montar o pacote de assinatura -- seja um PDF assinado (PAdES), um envelope CMS (CAdES) um XML assinado (XAdES) -- dependendo do tipo de assinatura utilizada | > **Observação** > > Se você não possui um SDK para realizar o processamento no servidor, você pode usar o [Lacuna PKI SDK](https://docs.lacunasoftware.com/articles/pki-sdk). > [Fale conosco](https://www.lacunasoftware.com/pt/home/purchase) para obter informações de licenciamento. Veja o artigo [Primeiros passos](https://docs.lacunasoftware.com/articles/web-pki/get-started) para começar a utilizar o Web PKI. # [Web PKI - Perguntas frequentes (FAQ)](https://docs.lacunasoftware.com/articles/web-pki/faq) Aqui estão reunidas as repostas para as dúvidas mais frequentes sobre o uso do [Web PKI](https://docs.lacunasoftware.com/articles/web-pki). > **Dica** > > Essa FAQ é destinada a **desenvolvedores de software**. Se você é um usuário final > tendo problemas para utilizar algum de nossos produtos, por favor visite a nossa [Central de Suporte](http://lacuna.help/) Perguntas: * [Qual é a diferença entre as funções signData e signHash?](https://docs.lacunasoftware.com/articles/web-pki/faq/sign-data-vs-hash) * [Qual é o formato da assinatura retornada pelas funções signData e signHash?](https://docs.lacunasoftware.com/articles/web-pki/faq/sign-data-output) * [Como posso realizar uma assinatura digital utilizando o Web PKI?](https://docs.lacunasoftware.com/articles/web-pki/faq/digital-signature) * [O Web PKI suporta conexões SSL usando o certificado do usuário? (ou Como faço para transmitir uma NFe Para a Receita/SEFAZ/prefeitura?)](https://docs.lacunasoftware.com/articles/web-pki/faq/ssl) # [Como posso realizar uma assinatura digital utilizando o Web PKI?](https://docs.lacunasoftware.com/articles/web-pki/faq/digital-signature) Veja o artigo [Assinaturas web](https://docs.lacunasoftware.com/articles/pki-guide/web-signatures). **Demonstrações e exemplos** - 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) # [Qual é o formato da assinatura retornada pelas funções signData e signHash?](https://docs.lacunasoftware.com/articles/web-pki/faq/sign-data-output) As funções `signData` e `signHash` realizam um ***algoritmo*** *de assinatura digital* utilizando a chave privada de um dos certificados do usuário. Sendo assim, o formato retornado é a saída do algoritmo de assinatura codificada em Base64. No caso mais comum, que é do algoritmo RSA com chave de 2048 bits, a saída tem 256 bytes (344 caracteres em Base64). Essa dúvida geralmente ocorre devido à confusão entre uma *assinatura digital*, por exemplo CMS/CAdES, XmlDSig/XAdeS ou PAdES, e um ***algoritmo*** *de assinatura*, como o RSA. Geralmente, o algoritmo de assinatura é uma parte do processo de realizar uma assinatura digital. As funções `signData` e `signHash` realizam apenas o algoritrmo, não a assinatura inteira. Por favor veja a pergunta [Como posso realizar uma assinatura digital utilizando o Web PKI?](https://docs.lacunasoftware.com/articles/web-pki/faq/digital-signature) para informações sobre como utilizar o Web PKI para realizar assinaturas digitais. # [Qual é a diferença entre as funções signData e signHash?](https://docs.lacunasoftware.com/articles/web-pki/faq/sign-data-vs-hash) Ambas funções -- `signData` e `signHash` -- realizam um algoritmo de assinatura digital utilizando a chave privada de um dos certificados presentes na máquina do usuário. Para entender a diferença entre as duas funções, precisamos falar rapidamente sobre os detalhes de um algoritmo de assinatura. > **Observação** > > O termo ***algoritmo*** *de assinatura digital* não deve ser confundido com *assinatura digital*. Leia mais sobre > esse assunto no artigo [Assinaturas digitais](https://docs.lacunasoftware.com/articles/pki-guide/signatures). O algoritmo RSA, em linhas gerais, tem 4 etapas: 1. Cálculo do hash dos bytes a serem assinados 1. Codificação da estrutura [DigestInfo](https://tools.ietf.org/html/rfc2313#section-10.1.2), que contém o hash e o OID do algoritmo de hash usado para produzi-lo 1. *Padding* do DigestInfo codificado 1. Operação matemática sobre DigestInfo codificado e *padded* > **Observação** > > O cálculo de hash realizado na primeira etapa geralmente **não é sobre o documento sendo assinado**. Nos esquemas de > assinatura CMS/CAdES, PAdES e XmlDSig/XAdES, os bytes usados como entrada para o algoritmo de assinatura correspondem > à codificação dos "atributos assinados", uma estrutura que contém diversos dados, entre eles o hash do documento. A função `signData` recebe como entrada o *to-sign-data* e realiza sobre ele todas as etapas, enquanto que a função `signHash` recebe como entrada o *to-sign-hash*, isto é, o hash pré-computado do *to-sign-data*, e realiza sobre ele apenas da segunda etapa em diante. Ambas funções podem ser usadas na implementação de [assinaturas web remotas](https://docs.lacunasoftware.com/articles/pki-guide/web-signatures/remote) independentemente do esquema de assinatura (CAdES, PAdES, etc) sendo utilizado. A escolha da função a ser utilizada depende do *output* fornecido pelo código que executa em backend ao final do "preparo" da assinatura remota. Se for produzido um *to-sign-data*, utilize a função `signData`. Se for produzido um *to-sign-hash*, utilize a função `signHash`. **Demonstrações e exemplos** - 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) # [O Web PKI suporta conexões SSL usando o certificado do usuário?](https://docs.lacunasoftware.com/articles/web-pki/faq/ssl) Sim. Desde a [versão 1.4 da API](https://docs.lacunasoftware.com/articles/web-pki/api-reference/versions#v1-4), o método `sendAuthenticatedRequest()` envia requisições web autenticadas com o certificado do usuário através de SSL/TLS mútuo, a partir do computador do usuário. Veja [Requisição autenticada](https://docs.lacunasoftware.com/articles/web-pki/auth-request). Para transmitir uma NFe, porém, em geral não é preciso usar o certificado do usuário, como explicado abaixo. ## (ou Como faço para transmitir uma NFe Para a Receita/SEFAZ/prefeitura?) Atualmente, é comum utilizar um mesmo certificado para emitir uma nota fiscal eletrônica (NFe) e transmiti-la ao órgão competente (a transmissão é feita via SSL com autenticação mútua). A predominância dessa arquitetura advém do fato de que os primeiros produtos de assinatura de NFe eram, em sua grande maioria, aplicações desktop. Em um sistema web, é preciso lidar com o problema de o certificado do cliente não estar disponível no backend. Para resolver o problema da assinatura da NFe no browser, o componente Web PKI se adequa perfeitamente (veja o [exemplo online](https://www.lacunasoftware.com/en/DemoRestPKI/nfeSignature)). Já no caso da transmissão, não é necessário utilizar o mesmo certificado utilizado para emitir a NFe. O padrão nacional permite que seja utilizado para transmissão um certificado emitido para uma empresa diferente da empresa que emitiu a NFe. Isso possibilita que **a transmissão seja feita no backend utilizando um certificado A1 emitido em nome da empresa que oferece o serviço de assinatura de NFe na web (sua empresa), ao invés de usar o certificado da empresa emissora da NFe (seu cliente)**. Assim, evita-se o problema de transmitir a NFe com um certificado disponível apenas no frontend. # [Web PKI API](https://docs.lacunasoftware.com/articles/web-pki/api-reference) ## Guia da API Para documentação detalhada de cada método, acesse o [Guia da API](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html). ## Veja também [Versões da API](https://docs.lacunasoftware.com/articles/web-pki/api-reference/versions) # [Versões da API](https://docs.lacunasoftware.com/articles/web-pki/api-reference/versions) O Web PKI oferece a possibilidade de o desenvolvedor definir qual a versão da API deseja exigir, baseando-se no conjunto de funcionalidades que deseja utilizar. Para isso, utilize o parâmetro `requiredApiVersion` no método [`init()`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#init): ```js pki.init({ ready: onWebPkiReady, requiredApiVersion: pki.apiVersions.v1_2 }); ``` No exemplo acima, definimos que iremos utilizar funcionalidades introduzidas na [API 1.2](https://docs.lacunasoftware.com/articles/web-pki/api-reference/versions#v1-2). Desta forma, a atualização dos componentes do Web PKI só será exigida aos usuários com versões inferiores às definidas pela [API 1.2](https://docs.lacunasoftware.com/articles/web-pki/api-reference/versions#v1-2). Nenhuma atualização desnecessária será exigida de usuários com versões suficientes, ainda que não sejam a mais recente. Se o parâmetro não for passado, o padrão é exigir a [API 1.3](https://docs.lacunasoftware.com/articles/web-pki/api-reference/versions#v1-3). ## Histórico de versões da API ### 1.8.2 (2023-11-23) Desde lib [2.16.3](https://docs.lacunasoftware.com/articles/web-pki/update) - Melhoria no método [`importCertificate`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#importcertificate) suportando múltiplas chamadas ### 1.8.1 (2022-12-17) - Adiciona métodos [encrypt](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#encrypt) e [decrypt](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#decrypt) - Adiciona Extended Key Usage info ao [CertificateModel](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.certificatemodel.html) - Adiciona o parâmetro `nonExportableKey` ao método [generateSoftwareRsaKeyPair](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#generatesoftwarersakeypair) ### 1.7.2 (2022-07-03) - Adiciona suporte a respostas sem limite de tamanho do App - Adiciona campos de PKI internacionais no [CertificateModel](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.certificatemodel.html): [`PkiArgentinaModel`](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.pkiargentinamodel.html), [`PkiEcuadorModel`](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.pkiecuadormodel.html), [`PkiParaguayModel`](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.pkiparaguaymodel.html), [`PkiPeruModel`](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.pkiperumodel.html) - Adiciona campos no [CertificateModel](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.certificatemodel.html): `certificatePolicies`, `subjectDN`, `issuerDN` ### 1.6.1 (2020-05-23) - Adiciona comando [`downloadToFolder`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#downloadtofolder)* com suporte forçado a TLS 1.2 ### 1.6 (2019-10-13) - Adiciona métodos [`keySignData`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#keysigndata) e [`keySignHash`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#keysignhash) para assinatura com Id de chave privada gerada. - Adiciona o parâmetro `privateKeyId` ao resultado da geração de par de chaves [`GenerateKeyPairResponse`](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.generatekeypairresponse.html). - Corrige bug na resposta do método [`sendAuthenticatedRequest`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#sendauthenticatedrequest) quando o *payload* retornado não possui a propriedade `Content-Length` no *Header*. ### 1.5.2 (2019-07-19) - Adiciona opção de retorno do conteúdo do documento assinado nos comandos de assinatura local sem limite de 1MB: [`returnContent`](https://docs.lacunasoftware.com/content/typedocs/web-pki/enums/_lacuna_web_pki_d_.lacunawebpki.outputmodes.html#returncontent) - Adiciona nível de validação do certificado do assinante nos comandos de assinatura local: [`CertificateValidationLevels`](https://docs.lacunasoftware.com/content/typedocs/web-pki/enums/_lacuna_web_pki_d_.lacunawebpki.certificatevalidationlevels.html) - Adiciona controle de direção vertical e horizontal na representação visual da assinatura PAdES (PDF): [`PadesVisualAutoPositioning`](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.padesvisualautopositioning.html) - Adiciona controle do ciclo de vida da aplicação nativa no método `init`: [`useDomainNativePool`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#init) ### 1.5 (2018-11-27) - Adiciona comando mais eficiente de assinatura de lote: [`signHashBatch`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#signhashbatch) - Adiciona licença v3 - Adiciona integração com _mobile_ ### 1.4.1 (2018-06-15) - Corrige *bug* de *buffer* vazio no comando [`sendAuthenticatedRequest`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#sendauthenticatedrequest)* ### 1.4 (2018-02-23) - Adiciona funcionalidades de assinatura local de XML: - [`signFullXml`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#signfullxml)* - [`signXmlElement`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#signxmlelement)* - [`openXmlSignature`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#openxmlsignature)* - Adiciona funcionalidades de requisição Web autenticada: - [`sendAuthenticatedRequest`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#sendauthenticatedrequest)* - Adiciona mensagem de erro de usuário no objeto de exceção: - [`userMessage`](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.exceptionmodel.html#usermessage) ### 1.3 (2017-11-10) - Adiciona gerenciador de erro com objeto de exceção mais detalhado: - [`fail`](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.promise.html#fail) ### 1.2 (2017-06-19) - Adiciona funcionalidades para emissão de certificado digital em repositório local e via PKCS#11: - [`generateSoftwareRsaKeyPair`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#generatesoftwarersakeypair) - [`importCertificate`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#importcertificate) - [`listTokens`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#listtokens) - [`generateTokenRsaKeyPair`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#generatetokenrsakeypair) - [`importTokenCertificate`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#importtokencertificate) ### 1.1 (2016-08-19) - Adiciona licença v2 - Adiciona funcionalidades para assinatura local: - [`showFileBrowser`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#showfilebrowser)* - [`openFile`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#openfile)* - Adiciona funcionalidades de assinatura local PAdES: - [`signPdf`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#signpdf)* - [`openPades`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#openpades)* - Adiciona funcionalidades de assinatura local CAdES: - [`signCades`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#signcades)* - [`openCades`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#opencades)* ### 1.0 (2015-04-28) - Adiciona funcionalidades básicas: - [`init`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#init) - [`listCertificates`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#listcertificates) - [`readCertificate`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#readcertificate) - [`signHash`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#signhash) - [`signData`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#signdata) - [`redirectToInstallPage`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#redirecttoinstallpage) - Adiciona funcionalidade para assinatura em lote: - [`preauthorizeSignatures`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#preauthorizesignatures) - Adiciona funcionalidade de download e seleção de diretório: - [`showFolderBrowser`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#showfolderbrowser) - [`downloadToFolder`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#downloadtofolder) - [`openFolder`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#openfolder) - Adiciona integração de assinatura com RestPKI: - [`signWithRestPki`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#signwithrestpki) * Métodos suportados apenas em Windows. Para mais informações veja o artigo [Assinaturas web](https://docs.lacunasoftware.com/articles/pki-guide/web-signatures). # [privacy-policy](https://docs.lacunasoftware.com/articles/web-pki/privacy-policy) > **Observação** > > Revisamos nossas políticas para garantir que estamos em conformidade com o Regulamento Geral de Proteção de Dados da União Europeia # Web PKI - Política de Privacidade * Última alteração: 16 de junho de 2020 * Data efetiva: 16 de junho de 2020 Esta Política de Privacidade se aplica à extensão [Web PKI](https://get.webpkiplugin.com/Help?brand=&jslib=&returnUrl=#) (o “Plugin”, a “Extensão”) pertencente e operado pela Lacuna Software Ltda (coletivamente, "Lacuna", "nós", "nos" ou "nosso"). Esta Política de Privacidade descreve como a Lacuna coleta, usa, compartilha e protege as informações pessoais que você fornece, bem como as informações sobre os usuários finais de nossos clientes que processamos em nome de nossos clientes. Também descreve suas opções em relação ao uso, acesso, correção e exclusão de suas informações pessoais. ## Como coletamos informações Coletamos as seguintes informações pessoais: ### Informação que você nos fornece sobre você Quando você se inscreve nos Serviços, solicitamos informações como * Informações de contato, tal como nome, endereço de e-mail, endereço para correspondência ou número de telefone; * Identificadores exclusivos, como nome de usuário, número da conta ou senha; * Endereço IP. Se você não fornecer essas informações, não poderemos fornecer os Serviços a você. ### Informação que você fornece sobre seus usuários e contatos Para que possamos efetivar a prestação de nossos serviços, você nos fornece informações que podem identificar seus usuários finais ou funcionários. Essas informações incluem: * Certificado digital; * Endereço IP; * Hash de documento. Você também pode nos fornecer informações pessoais sobre seus funcionários como Nome e endereço de e-mail onde podemos enviar recibo de suas compras. Quando você nos fornece informações pessoais sobre seus funcionários, essas informações serão usadas apenas pelo motivo específico pelo qual foram fornecidas. Se você acredita que um de seus funcionários nos forneceu suas informações pessoais e gostaria de solicitar que elas sejam removidas de nosso banco de dados, entre em contato conosco pelas informações de contato abaixo. ### Informação coletada automaticamente Quando você utiliza nossos Serviços, nós utilizamos cookies e tecnologias similares para coletar informações sobre sua localização, e suas atividades em nosso Plugin, informações sobre o seu dispositivo e informações de registro. Isso é descrito com mais detalhes abaixo. Estes cookies e tecnologias similares coletam endereço de protocolo de Internet (IP) anonimizado, tipo do browser, serviço de provedor de internet (ISP), páginas de saída/referências, sistema operacional, data/hora, e/ou dados do fluxo de cliques. Lacuna permite que o Google Analytics e o Snowplow Analytics usem essas tecnologias para analisar tendências, administrar o Plugin, rastrear os movimentos dos usuários no Plugin e coletar informações demográficas sobre nossa base de usuários como um todo para fins de análise. Você pode controlar o uso de cookies no nível do navegador individual, mas se você escolher desabilitar cookies, isto pode limitar seu uso de determinados recursos ou funções em nosso Plugin ou serviço. Nós não podemos usar ou permitir o uso de cookies ou tecnologias similares em conexão com os dados de seus clientes. *Google Analytics:* Nós usamos uma tela chamada "Google Analytics" para coletar algumas informações que listamos acima sobre o uso de seus Serviços. Usamos as informações que obtemos do Google Analytics para aprimorar os Serviços prestados. Para coletar essas informações, o Google Analytics pode definir cookies no seu navegador ou dispositivo móvel ou ler cookies que já estão lá. O Google Analytics também pode receber informações sobre aplicativos que você baixou, que são parceiros do Google. Não combinamos as informações coletadas pelo uso do Google Analytics com informações de identificação pessoal. A capacidade do Google de usar e compartilhar informações coletadas pelo Google Analytics sobre suas visitas aos Serviços de outro aplicativo que seja parceiro do Google é restrita pelos Termos de Uso do Google Analytics e pela Política de Privacidade do Google. Por favor revise isto e veja [https://policies.google.com/technologies/partner-sites](https://policies.google.com/technologies/partner-sites) para informações sobre como o Google usa as informações fornecidas pelo Google Analytics e como você pode controlar as informações fornecidas para o Google. Para impedir que seus dados sejam usados pelo Google Analytics, você pode fazer o download do complemento do navegador de desativação do Google Analytics para o Google Analytics, que pode ser encontrado aqui. ## Finalidade e base jurídica do processamento Usamos as informações sobre você para fornecer os serviços e para melhorá-los. Utilizamos informações sobre seus clientes ou usuários finais apenas para fornecer os serviços. Na medida em que a lei de proteção de dados da EU se aplica a esses usos de suas informações, agimos como o "controlador de dados". Na medida em que a lei de proteção de dados da UE se aplica ao processamento de dados de seus clientes ou usuários finais, você atua como "controlador de dados" e nós como "processador de dados". *Para executar os Serviços:* Usamos suas informações para identificá-lo, processar seu pagamento, fornecer suporte e assistência técnica; e comunicar com você sobre os serviços por e-mail. Por exemplo, entraremos em contato para notificá-lo sobre qualquer problema com os Serviços ou sobre qualquer atividade suspeita em sua conta. A base legal para esses usos na execução do contrato com você. *Para otimizar ou melhorar os serviços:* Usamos suas informações para autenticar você, evitar fraudes e abusos de nossos serviços e realizar pesquisas. A base legal para esses usos é nosso interesse legítimo na melhoria e otimização de nossas ofertas de serviços e em garantir a segurança de nossos serviços, e aplicamos safeguards adequadas para proteger suas informações (veja [section Security](https://docs.lacunasoftware.com/articles/web-pki/privacy-policy#security)). ## Como nós compartilhamos sua informação Compartilhamos informações com os provedores de serviços, conforme exigido por lei, e em conexão com a proteção e aplicação de nossos direitos legais e contratuais. *Com provedores de serviços:* Compartilhamos suas informações com terceiros que prestam serviços em nosso nome para ajudar em nossas atividades comerciais. Isto inclui: processamento de pagamento, prestação de serviço ao cliente, enviando comunicação de marketing (este não está incluído informações sobre seu cliente), conduzindo pesquisas e análises e fornecendo infraestrutura de computação em nuvem. A base legal para o compartilhamento dessas informações é o nosso interesse legítimo em fornecer nossos Serviços com eficiência e implementamos medidas para proteger suas informações. *Com autoridades públicas ou autoridades policiais:* Em determinadas situações, a Lacuna pode ser obrigada a divulgar dados pessoais em resposta a solicitações legais de autoridades públicas, inclusive para atender aos requisitos de segurança nacional ou de aplicação da lei. Também podemos divulgar suas informações pessoais conforme exigido por lei, como para cumprir uma intimação ou outro processo legal, quando acreditarmos de boa fé que a divulgação é necessária para proteger nossos direitos, quando acreditarmos que há uma violação de nossos Termos de Serviço. Serviço (consulte os Termos de Serviço Web PKI), proteja sua segurança ou a segurança de outras pessoas, investigue fraudes ou responda a uma solicitação do governo. Se a Lacuna estiver envolvida em uma fusão, aquisição ou venda de todos ou parte de seus ativos, você será notificado por e-mail e / ou um aviso em destaque em nosso site sobre qualquer alteração de propriedade, uso de suas informações pessoais e escolhas que você possa ter em relação às suas informações pessoais. Não vendemos, alugamos ou compartilhamos informações pessoais com terceiros sem o seu consentimento prévio. A base legal para isso é nosso interesse legítimo em proteger nossos direitos legais e os de terceiros, o cumprimento de obrigações legais e nosso interesse legítimo em cumprir obrigações legais impostas por autoridades legais fora da EU. *Prevenir fraudes e abusos dos Serviços:* Compartilharemos informações para prevenir ou detectar fraudes ou solucionar problemas técnicos e, se acharmos necessário investigar, impedir ou tomar medidas em relação a situações que envolvam abuso da infraestrutura dos Serviços. A base legal para isso é o nosso interesse legítimo em manter a segurança de nossos Serviços. Também processamos e compartilhamos informações de maneira agregada e não identificada, onde as informações são compartilhadas como parte de um relatório estatístico e não contêm informações pessoais. ## Segurança A segurança de suas informações pessoais é importante para nós. Implementamos medidas adequadas para proteger as informações pessoais enviadas a nós, durante a transmissão e depois que elas são recebidas. A Lacuna Software Ltda toma medidas para garantir que todo o código-fonte, arquivos e dados permaneçam privados e confidenciais. Devido à natureza sensível do código-fonte, levamos isso muito a sério e o tornamos nossa principal preocupação para todos os clientes. Restringimos o acesso às informações pessoais aos funcionários, contratados e agentes da Lacuna que precisam conhecer essas informações para operar, desenvolver ou melhorar nosso serviço. Esses indivíduos estão sujeitos a obrigações de confidencialidade e podem estar sujeitos a disciplina, incluindo rescisão e processo criminal, se não cumprirem essas obrigações. Se você tiver alguma dúvida sobre a segurança de suas informações pessoais, entre em contato conosco através das informações de contato abaixo. ## Direitos com relação às suas informações Mediante solicitação, a Lacuna fornecerá informações sobre a retenção ou não de suas informações pessoais. Você pode acessar, corrigir, obter uma cópia ou solicitar a exclusão de suas informações pessoais fazendo login em sua conta ou entrando em contato conosco através das informações de contato abaixo. Responderemos à sua solicitação dentro de um prazo razoável. Em certas circunstâncias, podemos ser obrigados por lei a reter suas informações pessoais, ou talvez precisemos retê-las para continuar prestando um serviço. A Lacuna Software Ltda reconhece que você tem o direito de acessar suas informações pessoais. A Lacuna Software Ltda não tem relacionamento direto com seus usuários finais cujos dados pessoais são processados. Um indivíduo que busca acessar ou procura corrigir, alterar ou excluir dados imprecisos deve encaminhar sua consulta ao Cliente da Lacuna Software Ltda (o controlador de dados). Se solicitado remover dados, responderemos em um prazo razoável. Em certas circunstâncias, podemos ser obrigados por lei a reter suas informações pessoais, ou talvez precisemos retê-las para continuar prestando um serviço. ## Suas escolhas com relação à informação Comunicação promocional por email: Você pode se inscrever para receber email, boletim informativo ou outras comunicações nossas. Se você deseja interromper o recebimento dessas informações, atualize suas preferências de email usando o link "Cancelar inscrição" encontrado nos emails que enviamos para você ou entrando em contato conosco pelas informações de contato abaixo. Google Analytics: veja [https://policies.google.com/technologies/partner-sites](https://policies.google.com/technologies/partner-sites) para informações sobre como o Google usa as informações fornecidas pelo Google Analytics e como você pode controlar as informações fornecidas pelo Google. Para impedir que seus dados sejam usados pelo Google Analytics, você pode fazer o download do complemento do navegador de desativação do Google Analytics que pode ser encontrado [aqui](https://tools.google.com/dlpage/gaoptout/). ## Retenção de dados Podemos reter suas informações enquanto sua conta estiver ativa ou conforme necessário para fornecer serviços, cumprir nossas obrigações legais, resolver disputas e fazer cumprir nossos acordos. Em certas circunstâncias, podemos ser obrigados por lei a reter suas informações pessoais, ou talvez precisemos retê-las para continuar prestando um serviço. Mesmo se você excluir sua conta, lembre-se de que a exclusão por nossos fornecedores terceirizados pode não ser imediata e que as informações excluídas podem persistir em cópias de segurança por um período de tempo razoável. ## Política em relação às crianças Os Serviços não são direcionados a crianças menores de 16 anos. Não coletamos intencionalmente Informações Pessoais de crianças menores de 16 anos. Se você tem menos de 16 anos, não use os Serviços e não forneça nenhuma informação pessoal para nós. Se você perceber que uma criança menor de 16 anos nos forneceu informações pessoais sem o seu consentimento, entre em contato conosco em [suporte@lacunasoftware.com](mailto: suporte@lacunasoftware.com). Se você é residente na Califórnia com menos de 18 anos e deseja remover o conteúdo disponível publicamente, entre em contato conosco em [suporte@lacunasoftware.com](mailto: suporte@lacunasoftware.com) com a linha de assunto "Borracha da Califórnia". ## Transferências de informações que não são do EEE Na medida em que informações pessoais são transferidas para os Estados Unidos de outros países da Área Econômica Européia e da Suíça, incluindo informações pessoais que são transferidas do Canadá, empregamos safeguard semelhantes, como selecionar cuidadosamente fornecedores de terceiros, garantindo que as informações pessoais usadas e divulgado apenas conforme estabelecido nesta política de privacidade e protegido por safeguard de segurança apropriadas. No entanto, em conexão com essas transferências de dados, suas informações pessoais podem estar sujeitas a leis de privacidade que podem não fornecer a mesma proteção que seu país de residência. Por exemplo, entidades governamentais em outros países podem ter certos direitos para acessar suas informações pessoais. Ao usar este plugin ou nosso Serviço relacionado a este aviso de privacidade, você concorda com a transferência de suas informações pessoais. ## Navegador Do Not Track Os Serviços honram e aplicam as preferências Do Not Track. Do Not Track (DNT) é uma preferência de privacidade que você pode definir no seu navegador da web para indicar que não deseja que determinadas informações sobre as visitas às suas páginas sejam coletadas nos sites quando você não interagiu com esse serviço na página. Para todos os detalhes, incluindo como ativar o Do Not Track, visite [donottrack.us] (http://donottrack.us/). ## Mudanças para esta Política de Privacidade Podemos atualizar esta Política de Privacidade para refletir alterações em nossas práticas de informações. Se fizermos alguma alteração relevante, notificaremos você por e-mail (enviado para o endereço de e-mail especificado em sua conta) ou por meio de um aviso neste site antes da efetivação da alteração. Recomendamos que você reveja periodicamente esta página para obter as informações mais recentes sobre nossas práticas de privacidade. ## Perguntas / Comentários sobre privacidade Se você tiver questões ou sugestões sobre a Política de Privacidade da Lacuna, por favor entre em contato conosco em [suporte@lacunasoftware.com](mailto:suporte@lacunasoftware.com) ou EQN 102/103, Ed. Avenida 102, 2º Andar - Asa Norte, Brasília-DF, Brasil. Telefone: +55 61 3030-5700. # [Callbacks e AngularJS](https://docs.lacunasoftware.com/articles/web-pki/angularjs) Se a sua página utilizar o framework AngularJS, você deve passar uma referência para o `$scope` do seu controller ou serviço ao chamar o método `init()`: ```javascript pki.init({ ready: onWebPkiReady, angularScope: $scope, ... }); ``` Se você não fizer isso, seus callbacks serão chamados fora dos "ciclos" do AngularJS, o que pode ocasionar que mudanças ao `$scope` não sejam refletidas na view. # Angular2+ Se a sua página utilizar o framework Angular2+, você deve passar uma referência para o `NgZone` do seu componente ou serviço ao chamar o método `init()`: ```javascript pki.init({ ready: onWebPkiReady, ngZone: this.ngZone, ... }); ``` # [Chamadas assíncronas](https://docs.lacunasoftware.com/articles/web-pki/async) Vejamos novamente nosso exemplo para obter os certificados disponíveis: ```javascript pki.listCertificates().success(function (certs) { // fazer alguma coisa com o array "certs" }); ``` O código acima é um exemplo de uma **chamada assíncrona**. O método [`listCertificates()`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#listcertificates) não pode fazer imediatamente todo o procedimento necessário e retornar o resultado. Ele precisa de tempo para realizar essa operação. Nós *poderíamos* bloquear a execução até que a operação fosse concluída, mas isso é uma má-pratica em javascript e poderia causar sérios problemas, como a página web travar e o browser sugerir ao usuário que a página deveria ser fechada. Ao invés disso, o método imediatamente retorna uma **promessa** (uma instância da classe [`Promise`](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.promise.html). Uma promessa é um objeto através do qual você pode registrar callbacks que serão chamados quando a promessa for cumprida, isso é, quando a operação for concluída. Você deve sempre registrar um callback para quando a operação for concluída com sucesso e, opcionalmente, pode registrar um outro callback para quando ocorrer um erro durante a operação. Todos os métodos da classe [`Promise`](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.promise.html) são encadeáveis, ou seja, você pode fazer o seguinte: ```javascript pki.listCertificates().success(function (certs) { // do something with the "certs" array }).fail(function (ex) { alert('An error has occurred while retrieving the certificates: ' + ex.userMessage); }); ``` O callback de sucesso sempre recebe um único argumento contendo o resultado da operação. Entretanto, o tipo (string, array ou objeto) e seu significado dependem do método que retornou a promessa. Você deve verificar a documentação de cada método para obter essas informações. Para mais informações sobre os parâmetros do objeto da exceção, veja a documentação do método [Promise.fail()](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.promise.html#fail) e [ExceptionModel](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.exceptionmodel.html). > **Observação** > > Todos os métodos da classe [`LacunaWebPKI`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html) são assíncronos, com raras exceções. # [Requisição Autenticada](https://docs.lacunasoftware.com/articles/web-pki/auth-request) O Web PKI oferece a funcionalidade de envio de requisições Web autenticadas com o certificado digital do usuário através de SSL/TLS mútuo. Essa operação tem grande utilidade na comunicação com serviços da Receita Federal, SEFAZ ou prefeituras. ## NFe - Nota Fiscal eletrônica Outra área na qual a requisição autenticada se faz necessária é a de serviços envolvendo notas fiscais eletrônicas (NFe). No cenário de transmissão da NFe, o padrão nacional permite que seja utilizado, na autenticação, um certificado de uma empresa diferente da que emitiu a NFe. Isso possibilita que a transmissão seja feita no *backend* utilizando um certificado A1 emitido em nome da empresa que oferece o serviço de assinatura de NFe na web, por exemplo. No entanto, existem outros serviços, e.g. consultas e manifestações, nos quais se faz necessária a autenticação apenas com o certificado da empresa emissora da NFe. Para tais casos, a requisição autenticada com o Web PKI permite a implementação das comunicações à partir do computador do usuário, respeitando ideais de segurança, tanto possibilitando a utilização de certificados em dispositivos criptográficos, A3, tanto evitando a necessidade do envio de certificados A1, deixando-os sob a guarda de terceiros. ## Exemplos No exemplo abaixo, demonstramos uma simples requisição autenticada que verifica o *status* operacional do serviço SEFAZ-RS em homologação. ```js // Definicao dos parametros do request var request = { // URL do servico url: 'https://nfe-homologacao.svrs.rs.gov.br/ws/NfeStatusServico/NfeStatusServico4.asmx', method: 'post', headers: { 'Content-Type': 'application/soap+xml; charset=utf-8' }, // Envelope SOAP da requisicao body: '253STATUS' }; // Define o certificado do usuario para autenticar a requisicao request.certificateThumbprint = $('#certificateSelect').val(); // Envia a requisicao pki.sendAuthenticatedRequest(request).success(function (response) { // Usa a resposta "response" }); ``` ## Veja também * Exemplo funcional no JSFiddle: [Exemplo de envio de requisição autenticada](https://jsfiddle.net/LacunaSoftware/3cv5xjov/) * [Documentação do método `sendAuthenticatedRequest()`](https://docs.lacunasoftware.com/content/typedocs/web-pki/classes/_lacuna_web_pki_d_.lacunawebpki.html#sendauthenticatedrequest) (disponível desde a [versão 1.4 da API](https://docs.lacunasoftware.com/articles/web-pki/api-reference/versions#v1-4)) # [Utilizando uma página de instalação personalizada](https://docs.lacunasoftware.com/articles/web-pki/brand) ```javascript pki.init({ ready: onWebPkiReady, brand: 'YourBrand' }); ``` # [Browsers suportados](https://docs.lacunasoftware.com/articles/web-pki/browser-support) Atualmente, os seguintes browsers são suportados: | ![Chrome](https://docs.lacunasoftware.com/images/web-pki/chrome.gif) | ![Firefox](https://docs.lacunasoftware.com/images/web-pki/firefox.gif) | ![IE](https://docs.lacunasoftware.com/images/web-pki/ie.gif) | ![Edge](https://docs.lacunasoftware.com/images/web-pki/edge.gif) | |:---------------------------------------------:|:------------------------------------------------:|:-------------------------------------:|:-----------------------------------------:| | Chrome Versão 44+ | Firefox Versão 50+ | IE9+ | Microsoft Edge Versão 42+ | | Em Windows, Linux e Mac | Em Windows, Linux e Mac | Em Windows | Em Windows | Versões dos sistemas suportados: * Windows 7 SP2 ou superior\* * Linux (distribuições baseadas em Debian, RedHat e Slackware) * Mac OS X 10.12+ > **Observação** > > \*Windows XP e Vista: **não há suporte oficial, USE POR SUA PRÓPRIA CONTA E RISCO**, uma vez que estes sistemas estão **descontinuados** pela Microsoft. Para funcionamento, o sistema deve estar em sua versão mais atualizada possível. # [Propriedades dos certificados](https://docs.lacunasoftware.com/articles/web-pki/cert-properties) Ao chamar a função `listCertificates()`, o seu callback recebe um array com os certificados disponíveis na máquina do usuário. Cada elemento do array retornado é um objeto do tipo [CertificateModel](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.certificatemodel.html) contendo informações sobre o certificado: ```javascript pki.listCertificates().success(function (certs) { for (var i = 0; i < certs.length; i++) { var cert = certs[i]; console.log(cert.subjectName); console.log(cert.email); console.log(cert.validityEnd); console.log(cert.pkiBrazil.cpf); console.log(cert.pkiItaly.codiceFiscale); } }); ``` Esse mesmo objeto é recebido como argumento para o callback `selectOptionFormatter` que pode ser passado na chamada à função `listCertificates()`: ```javascript pki.listCertificates({ selectId: 'certificateSelect', selectOptionFormatter: function (cert) { var text = cert.subjectName + ' (' + 'emitido por ' + cert.issuerName + ' em ' + cert.validityEnd.toLocaleDateString() + ')'; if (new Date() > cert.validityEnd) { text = '[EXPIRADO] ' + text; } return text; } }); ``` Algumas das propriedades disponíveis são: * `subjectName`: Campo *Common Name* (CN) do nome do titular * `email`: Endereço de e-mail do titular * `validityEnd`: Data de expiração do certificado (tipo `Date` padrão de JavaScript) * `pkiBrazil`: Objeto com campos específicos da ICP-Brasil * `pkiBrazil.cpf`: CPF do titular/responsável * `pkiBrazil.cnpj`: CNPJ da empresa (ou `null`, caso não seja um certificado de pessoa jurídica) * `pkiItaly`: Objeto com campos específicos de certificados italianos * `pkiItaly.codiceFiscale`: *codice fiscale* do titular > **Observação** > > As propriedades `pkiBrazil` e `pkiItaly` estão sempre preenchidas, mesmo que o certificado não seja um certificado brasileiro ou italiano, > de modo que é seguro fazer algo como `if (cert.pkiBrazil.cpf) { ... }` sem risco de erros. Nesse caso, as sub-propriedade (`pkiBrazil.*` / > `pkiItaly.*`) é que estarão com valor `null`. Para obter uma lista completa das propriedades disponíveis em cada elemento do array, veja o guia da API para o tipo [CertificateModel](https://docs.lacunasoftware.com/content/typedocs/web-pki/interfaces/_lacuna_web_pki_d_.certificatemodel.html). # [Personalizando a listagem de certificados](https://docs.lacunasoftware.com/articles/web-pki/cert-select) É possível personalizar o texto mostrado para cada certificado na listagem de certificados utilizando as [Propriedades dos certificados](https://docs.lacunasoftware.com/articles/web-pki/cert-properties) retornadas pelo Web PKI: ```js function onWebPkiReady() { pki.listCertificates({ selectId: 'certificateSelect', selectOptionFormatter: getCertText }); } function getCertText(cert) { return cert.subjectName + ' (issued by ' + cert.issuerName + ')'; } ``` O mesmo se aplica se você estiver processando o array de certificados manualmente: ```js function onWebPkiReady() { pki.listCertificates().success(function (certs) { var select = $('#certificateSelect'); for (var i = 0; i < certs.length; i++) { var cert = certs[i]; select.append( $('