Migração do Rest PKI para o Rest PKI Core
O Rest PKI, serviço em nuvem em pki.rest, é um produto legado: continua recebendo correções de bugs e de segurança, mas novas integrações em nuvem devem usar o Rest PKI Core. Este guia é para uma aplicação já integrada ao Rest PKI que passa a usar o Rest PKI Core, na instância SaaS em core.pki.rest ou numa instância própria.
O Rest PKI Core atende à maioria das APIs do Rest PKI, por isso a migração pode acontecer em duas etapas:
- Aponte a aplicação para o Rest PKI Core. As APIs do Rest PKI que ele atende mantêm as mesmas rotas e os mesmos modelos: o seu código muda onde obtém o endpoint e a credencial, onde as suas páginas inicializam o Web PKI e, se você criou contextos de segurança próprios, onde os cita. Veja Usando o seu código como está.
- Adote as APIs mais novas, no seu ritmo. As sessões de assinatura, as assinaturas em duas etapas e a autenticação com certificado substituem os fluxos de assinatura e de autenticação do Rest PKI, com páginas de assinatura hospedadas, webhooks e bibliotecas cliente mais novas. Veja Migrando para as APIs mais novas.
Algumas APIs do Rest PKI não têm equivalente no Rest PKI Core: confira O que o Rest PKI Core não atende antes de começar.
Antes de começar
- Obtenha acesso a uma instância. Na instância SaaS, peça acesso ao suporte ao desenvolvedor se a sua organização ainda não o tiver; para uma instância própria, veja Rest PKI Core on-premises.
- Crie uma aplicação e uma chave de API no dashboard da instância, com o papel Operador. O Operador cobre todas as APIs do Rest PKI que o Rest PKI Core atende: assinaturas, autenticação com certificado, carimbos de tempo, marcas em PDF e inspeção de assinaturas. Veja Crie uma chave de API.
- Preveja a licença do Web PKI. Com o Rest PKI em pki.rest, o Web PKI não precisa de licença, nem em produção. Com o Rest PKI Core, precisa, tanto na instância SaaS quanto numa instância própria. Veja Licenciamento.
Usando o seu código como está
O que o Rest PKI Core atende
O Rest PKI Core responde a estas rotas do Rest PKI com os modelos de requisição e de resposta do Rest PKI:
| Funcionalidade do Rest PKI | Rotas |
|---|---|
| Assinatura PAdES | POST Api/PadesSignatures, Api/v2/PadesSignatures, Api/PadesSignatures/{token}/SignedBytes, Api/PadesSignatures/{token}/Finalize, Api/v2/PadesSignatures/{token}/SignedBytes |
| Assinatura CAdES, inclusive a coassinatura | POST Api/CadesSignatures, Api/v2/CadesSignatures, Api/v3/CadesSignatures, Api/CadesSignatures/{token}/SignedBytes, Api/CadesSignatures/{token}/Finalize, Api/v2/CadesSignatures/{token}/SignedBytes, Api/CadesSignatures/RequiredHashes |
| Assinatura XML do documento inteiro ou de um elemento | POST Api/XmlSignatures/FullXmlSignature, Api/XmlSignatures/XmlElementSignature, Api/XmlSignatures/{token}/SignedBytes, Api/XmlSignatures/{token}/Finalize |
| Abertura e validação de assinaturas | POST Api/PadesSignatures/Open, Api/CadesSignatures/Open, Api/XmlSignatures/Open, Api/v2/XmlSignatures/Open |
| Autenticação com certificado | POST Api/Authentications, Api/Authentications/{token}/Finalize, Api/Authentications/{token}/SignedBytes; GET e POST Api/Authentication |
| Abertura de um certificado | POST Api/Certificates/Open |
| Marcas em PDF (versões para impressão) | POST Api/Pdf/AddMarks |
| Posicionamentos predefinidos da representação visual | GET Api/PadesVisualPositioningPresets/Footnote, .../FootnoteBottomUp, .../NewPage |
| Upload de arquivos grandes | POST Api/MultipartUploads, Api/MultipartUploads/{token}/{partNumber}, Api/MultipartUploads/{token} |
| Carimbos de tempo | POST tsp/{id} (protocolo TSP) e POST Api/TimestampPlans/{id}/Issue |
Assinatura no navegador com o signWithRestPki() do Web PKI | GET e POST Api/PendingSignatures/{token}, POST Api/PendingSignatures/{token}/Certificate (chamadas pelo Web PKI, não pelo seu código) |
As mesmas políticas de assinatura padrão estão disponíveis, com os mesmos IDs, como StandardPadesSignaturePolicies.PkiBrazil.AdrBasica e
StandardCadesSignaturePolicies.PkiBrazil.AdrArquivamento, assim como as tags da representação visual do PDF, como {{name}} e
{{br_cpf_formatted}} (veja Tags PAdES). O callbackArgument de uma assinatura também volta quando ela é
concluída.
O que muda
| Rest PKI | Rest PKI Core | |
|---|---|---|
| Endpoint | https://pki.rest/ ou a sua instância on-premises | https://core.pki.rest/ na instância SaaS ou o endereço do dashboard da sua instância |
| Credencial | Um token de acesso, gerado no Painel de Controle em pki.rest | Uma chave de API de uma aplicação com o papel Operador, criada no dashboard da instância |
| Header | Authorization: Bearer <token de acesso> | X-Api-Key: <chave de API>; Authorization: Bearer <chave de API> também é aceito, por isso uma biblioteca cliente que envia o token de acesso como token de portador funciona quando recebe a chave de API no lugar dele |
| Web PKI | Chama https://restpki.lacunasoftware.com/ por padrão | Passe o endpoint do Rest PKI Core ao init() como restPkiUrl (veja abaixo) |
| Licença do Web PKI | Não é necessária com o pki.rest | Necessária |
| Datas nas assinaturas de PDF | Região e Data na sua conta | Configurações > Região e Data no dashboard |
Se as suas páginas assinam com o signWithRestPki() do Web PKI, como os exemplos do Rest PKI, o Web PKI obtém a assinatura pendente na própria
instância do Rest PKI. Informe a ele onde está o Rest PKI Core:
pki.init({
restPkiUrl: 'https://core.pki.rest/', // o endpoint da sua instância do Rest PKI Core
ready: onWebPkiReady,
});
Bibliotecas cliente
As bibliotecas cliente do Rest PKI enviam o token de acesso como Authorization: Bearer, e o Rest PKI Core aceita uma chave de API enviada
dessa forma; por isso, a aplicação pode manter de início a biblioteca do Rest PKI e só passar a ela o novo endpoint e a chave de API. As
bibliotecas do Rest PKI Core variam de linguagem para linguagem:
| Linguagem | Rest PKI | Rest PKI Core | O que a biblioteca do Rest PKI Core traz |
|---|---|---|---|
| .NET | Lacuna.RestPki.Client | Lacuna.RestPkiCore.Client 5.0.0 | Depende do Lacuna.RestPki.Client 5.0.0 e usa o mesmo namespace, Lacuna.RestPki.Client: ao adicioná-la, você mantém o RestPkiClient, os starters, finishers e explorers, o Authentication e o PdfMarker, ao lado do IRestPkiService para as APIs mais novas. As duas têm como alvo o .NET Standard 2.0 |
| Java | com.lacunasoftware.restpki:restpki-client | com.lacunasoftware.restpki:restpkicore-client 1.4.0 | Um pacote novo, com.lacunasoftware.restpkicore, sem as classes do Rest PKI. O RestPkiService dele tem métodos para as rotas do Rest PKI, como startPadesSignature(), completePadesSignature(), startCadesSignature(), startFullXmlSignature() e addPdfMarks(), além das APIs mais novas. As duas exigem o Java 8 |
| PHP | lacuna/restpki-client | lacuna/restpkicore-client 1.2.1 | Exige o lacuna/restpki-client ^2.7.0 e usa o mesmo namespace, Lacuna\RestPki, por isso as classes do Rest PKI continuam disponíveis. O RestPkiService dela cobre as sessões de assinatura e os documentos; o exemplo em PHP chama as rotas da assinatura em duas etapas pelo getRestClient()->post(), já que a biblioteca não tem método para elas |
| Node.js | restpki-client | restpki-core-client 1.0.2 | Classes geradas a partir da API para cada grupo de rotas, inclusive as do Rest PKI (PadesSignatureApi, CadesSignatureApi, XmlSignatureApi, PdfApi, TimestampApi, AuthenticationApi) e as mais novas (SignatureApi, SignatureSessionsApi, DocumentsApi, SignatureInspectionApi), por trás de um RestPkiCoreClient criado com baseUrl e apiKey. Não tem starters nem finishers |
| Python | restpki-client | restpki-ng-python-client, usado pelo exemplo em Python (0.9.1.1) | — |
| Ruby | rest_pki | Nenhuma: o exemplo em Ruby chama a API REST diretamente | — |
Em .NET, o cliente do Rest PKI a partir da 2.2.0 compartilha os números de versão com o Lacuna.RestPkiCore.Client e tem como alvo apenas o
.NET Standard 2.0; uma aplicação na 1.24.1 (.NET Framework 3.5 a 4.6) precisa atualizar antes. Veja
.NET na documentação do Rest PKI. Para configurar a biblioteca do Rest PKI Core
para as APIs mais novas, veja Primeiros passos.
TODO(docs): nenhuma página diz se as bibliotecas cliente do Rest PKI para Java, PHP, Node.js, Python e Ruby têm suporte com o Rest PKI Core, e a
biblioteca Python restpki-ng-python-client não está documentada em nenhum lugar.
Contextos de segurança
O Rest PKI Core cria os contextos de segurança padrão em toda instância, com os mesmos IDs do Rest PKI; por isso, o código que passa
StandardSecurityContexts.PkiBrazil ou StandardSecurityContexts.LacunaTest funciona sem mudanças:
| Contexto de segurança | ID |
|---|---|
PkiBrazil (ICP-Brasil) | 201856ce-273c-4058-a872-8937bd547d36 |
PkiItaly | c438b17e-4862-446b-86ad-6f85734f0bfe |
WindowsServer | 3881384c-a54d-45c5-bbe9-976b674f5ec7 |
LacunaTest (ICP de testes da Lacuna, só para desenvolvimento) | 803517ad-3bbc-4169-b085-60053a8f6dbf |
O Rest PKI Core acrescenta PkiBrazilExtended, GovBR, PkiBrazilWithENotariado e PkiBrazilWithGovBrAndENotariado.
Um contexto de segurança que você mesmo criou no Rest PKI não é levado: crie-o de novo no Rest PKI Core, onde os usuários com o papel Gerente ou Administrador gerenciam os contextos de segurança da organização, e use o novo ID. Você também pode escolher um Contexto de segurança padrão para a organização, em Configurações > Configurações gerais, que o Rest PKI Core usa quando uma chamada não cita nenhum.
TODO(docs): nenhuma página descreve como gerenciar os contextos de segurança no dashboard do Rest PKI Core.
Testes com a ICP de testes da Lacuna
Os certificados de teste funcionam como no Rest PKI: cite o contexto de segurança LacunaTest nas chamadas,
apenas em desenvolvimento. Ao contrário de uma instância on-premises do Rest PKI, em que talvez seja preciso criá-lo antes, toda instância do
Rest PKI Core o cria ao iniciar. Veja Rest PKI Core na página de certificados de teste.
TODO(docs): nenhuma página descreve uma sandbox ou um ambiente de testes da instância SaaS, nem chaves de API de teste para ela.
Carimbos de tempo
No Rest PKI Core, os carimbos de tempo vêm de tiers (níveis) em vez de planos. O tier PkiBrazil (ICP-Brasil) tem o ID do plano do Rest PKI,
a402df41-8559-47b2-a05c-be555bf66310 (StandardTimestampPlans.PkiBrazil); por isso, tsp/a402df41-8559-47b2-a05c-be555bf66310 e
Api/TimestampPlans/a402df41-8559-47b2-a05c-be555bf66310/Issue continuam funcionando numa instância em que esse tier está habilitado, como a
instância SaaS. Essas rotas também aceitam o nome do tier em vez do ID, como tsp/PkiBrazil, e o Rest PKI Core acrescenta api/tsp/{tier}, em
que o header documentado é Authorization: ApiKey <chave de API>. Veja Requisitando carimbos de tempo.
O que o Rest PKI Core não atende
- Assinaturas XML de recursos destacados ou online:
Api/XmlSignatures/DetachedResourceXmlSignatureeApi/XmlSignatures/OnlineResourceXmlSignature(em .NET,DetachedResourceXmlSignatureStartereOnlineResourceXmlSignatureStarter) não foram portadas. O código-fonte pede a quem precisar delas que avise a Lacuna: escreva ao suporte ao desenvolvedor. - APIs de conta e de gerenciamento: gerar tokens de acesso, gerenciar contextos de segurança, listar políticas de assinatura, planos de
carimbo de tempo e transações pelas rotas do Rest PKI (
Api/Account,Api/SecurityContexts,Api/SignaturePolicies,Api/TimestampPlans,Api/Transactions,Api/Userse outras). O Rest PKI Core tem dashboard e APIs próprios para isso. - Rotas de informações do sistema além de
api/system/info, comoApi/System/Cultures,Api/System/TimeZoneseApi/System/Date.
As observações da API de assinatura XML no código-fonte também citam Api/XmlSignatures/Open como não portada, mas o Rest PKI Core 5.0.5 a
atende, junto com Api/v2/XmlSignatures/Open.
Migrando para as APIs mais novas
Quando a aplicação estiver rodando no Rest PKI Core, substitua cada fluxo do Rest PKI pelo equivalente mais novo quando for conveniente:
| Com o Rest PKI | Com o Rest PKI Core | Veja |
|---|---|---|
Iniciar uma assinatura PAdES, CAdES ou XML, assinar com o signWithRestPki() do Web PKI na sua página e concluí-la | Criar uma sessão de assinatura e redirecionar o usuário à página de assinatura hospedada pelo Rest PKI Core, que usa o Web PKI ou certificados em nuvem; obter os documentos assinados pela API ou por um webhook | Sessões de assinatura |
| O mesmo, mantendo a página de assinatura na sua aplicação | Preparar a assinatura, assinar o hash com o signHash() do Web PKI na sua página e concluí-la | Assinaturas em duas etapas |
| Assinar com uma chave guardada no servidor (os exemplos server key) | Preparar a assinatura, assinar o hash no servidor e concluí-la | Assinaturas em duas etapas |
Authentication: StartWithWebPkiAsync(), signWithRestPki(), CompleteWithWebPkiAsync() | Preparar a autenticação, assinar o hash com o signHash() do Web PKI e concluí-la; o estado fica na sua página, e nonces reutilizados são rejeitados | Autenticação com certificado |
Abrir e validar assinaturas (PadesSignatureExplorer, CadesSignatureExplorer, XmlSignatureExplorer) | Inspeção de assinaturas, PUT api/signature-inspection, com validate = true para validar | Referência da API |
Adicionar marcas a um PDF (PdfMarker) | POST api/pdf/stamp | Referência da API |
| Requisitar um carimbo de tempo | POST api/tsp/{tier} | Requisitando carimbos de tempo |
TODO(docs): nenhuma página descreve a API de inspeção de assinaturas (api/signature-inspection) nem a API de carimbo em PDF (api/pdf/stamp) do
Rest PKI Core, nem como um carimbo se compara às marcas em PDF do Rest PKI.
As APIs mais novas também trazem o que o Rest PKI não tem: webhooks, requisitos de certificado, conversão para PDF/A, processamento em segundo plano e códigos de verificação nos documentos assinados.
Comparando os exemplos
Os projetos PkiSuiteSamples têm versões para o Rest PKI e para o Rest PKI Core de alguns exemplos, lado a lado, que mostram a mesma funcionalidade antes e depois da migração:
| Funcionalidade | Exemplo do Rest PKI | Exemplo do Rest PKI Core |
|---|---|---|
| Assinatura PAdES na sua página com o Web PKI | PadesSignatureRestController (.NET, Java), pades-signature-rest (PHP), pades-signature-restpki.js (Node.js) | PadesSignatureRestCoreController (.NET), PadesSignatureCoreController (Java), pades-signature-rest-core (PHP), pades-signature-core.js (Node.js), pades_signature_rest_core.py (Python, Flask), pades_signature_rest_core_controller.rb (Ruby) |
| Lote de assinaturas PAdES | batch-pades-signature-restpki.js (Node.js) | batch-pades-signature-core.js (Node.js) |
| Autenticação com certificado | AuthenticationRestController (.NET, Java) | AuthenticationRestPkiCoreController (Java) |
| Assinatura PAdES com uma chave no servidor | pades-server-key-rest (PHP) | PadesServerKeyRestCoreController (.NET) |
| Página de assinatura hospedada | — | SignatureSessionRestCoreController e SignatureSessionPreDefRestCoreController (.NET, Java), signature-session-rest-core (PHP), com WebhookRestCoreController (.NET, Java) e webhook-rest-core (PHP) |
Nas páginas, os exemplos do Rest PKI chamam o signWithRestPki() do Web PKI com o token; os exemplos do Rest PKI Core leem o certificado com o
readCertificate(), enviam-no ao servidor, que prepara a assinatura, e depois assinam o hash com o signHash(). Em .NET, os exemplos usam um
único método para o contexto de segurança, Util.GetSecurityContextId(), nos dois produtos, e os exemplos em Node.js, PHP, Python e Ruby passam
ao Rest PKI Core os IDs de StandardSecurityContexts do Rest PKI, já que os IDs padrão são os mesmos.
Ainda não há exemplo do Rest PKI Core para assinaturas CAdES, assinaturas XML (inclusive NF-e), abertura e validação de assinaturas nem versões para impressão; para elas, a aplicação pode continuar usando as APIs do Rest PKI que o Rest PKI Core atende como estão.