Pular para o conteúdo principal

Referência rápida do Rest PKI (legado)

O essencial do Rest PKI numa só página, com links para os artigos completos.

Produto legado

O Rest PKI, o serviço em nuvem em pki.rest, é um produto legado: continua recebendo correções de bugs e de segurança, mas, para uma nova integração em nuvem, use o Rest PKI Core. O Rest PKI Core também atende à maior parte das APIs do Rest PKI clássico (assinaturas PAdES, CAdES e XML, autenticação com certificado e marcas em PDF), o que facilita a migração de uma aplicação.

TODO(docs): não há guia para migrar uma aplicação do Rest PKI para o Rest PKI Core. O Rest PKI continua recebendo versões (1.33.9 em 2026-09-08).

Para que serve​

O Rest PKI é um serviço em nuvem para operações de certificação digital, como assinaturas digitais e autenticação com certificado, usado a partir de praticamente qualquer linguagem de programação por meio de bibliotecas cliente; também é possível hospedar uma instância própria em Windows Server ou Azure App Service. Numa aplicação web, ele trabalha com o Web PKI: o seu backend inicia a operação e recebe um token de uso único, o signWithRestPki() do Web PKI assina no navegador e o seu backend conclui a operação com esse token.

Prefira outro produtoQuando ele atende melhor
Rest PKI CoreVocê vai começar uma nova integração em nuvem: assinaturas, validação, carimbos de tempo e verificação biométrica por uma API REST, em core.pki.rest ou numa instância própria, com páginas de assinatura hospedadas por ele.
PKI ExpressVocê assina nos seus próprios servidores Windows ou Linux, a partir de praticamente qualquer linguagem. Para Linux, o artigo do Rest PKI on-premises recomenda o PKI Express.
PKI SDKO seu backend é .NET: o guia de certificação digital recomenda o PKI SDK para assinaturas no servidor em .NET, e ele pode fazer a parte do servidor das assinaturas web com o Web PKI.
Web PKIVocê precisa só da parte do navegador: listar os certificados do usuário, lê-los e assinar com eles em JavaScript. O Rest PKI o usa nessa etapa.

Instalação​

LinguagemPacoteMajor atualRegistry
.NET (C#, VB.NET, C++.NET)Lacuna.RestPki.Client5 (mais recente: 5.0.0); 1.24.1 para .NET Framework 3.5 a 4.6NuGet
Java 7+com.lacunasoftware.restpki:restpki-client1 (mais recente: 1.15.11, para Java 8+; em Java 7, 1.15.7)Maven Central
Java 6com.lacunasoftware.restpki:restpki-client-java61 (mais recente: 1.9.0)Maven Central
PHP 5.5+lacuna/restpki-client2 (mais recente: 2.9.10)Packagist
PHP 5.3 e 5.4lacuna/restpki-client-legacy1 (mais recente: 1.1.0)Packagist
Node.jsrestpki-client2 (mais recente: 2.3.8)npm
Pythonrestpki-client1 (mais recente: 1.3.1)PyPI
Rubyrest_pki1 (mais recente: 1.1.0)RubyGems
  • O .NET tem duas linhas de versões: a 1.24.1, a última 1.x, atende ao .NET Framework 3.5 a 4.6 e ao .NET Standard 1.3 e 2.0; a 2.2.0 e as seguintes atendem só ao .NET Standard 2.0, são publicadas com o Rest PKI Core e têm os mesmos números de versão do cliente dele, o Lacuna.RestPkiCore.Client. As duas linhas funcionam com o pki.rest; escolha pelo framework de destino. Veja .NET.
  • Java: as versões 1.15.9 e seguintes do restpki-client são compiladas para Java 8; em Java 7, use a 1.15.7. Veja Java.
  • O PHP 5.2 não tem pacote: use o arquivo RestPkiLegacy52.php com o pacote do Composer educoder/pest. Veja PHP.
  • As APIs REST não são feitas para chamadas diretas: use uma biblioteca cliente. Referências da API: .NET, Java e a cópia do OpenAPI.

Configuração e autenticação​

  • Token de acesso: crie uma conta em pki.rest, autentique-se e, no Painel de Controle, clique em Gerar novo token de acesso.
  • Cliente: um RestPkiClient recebe o endpoint e o token de acesso, e todo starter, finisher e explorer recebe o cliente. Nas chamadas HTTP diretas, envie o token no header Authorization: Bearer <token>.
  • Endpoint: https://pki.rest/ na nuvem; por padrão, o Web PKI chama o endereço alternativo https://restpki.lacunasoftware.com/, que tem menos chance de ser bloqueado por firewalls. On-premises, o endpoint é o endereço da sua instância, terminado em /, e a página o passa ao init() do Web PKI como restPkiUrl.
  • Contexto de segurança: cada operação indica um contexto de segurança, que define as ACs raiz confiáveis; em produção, os exemplos usam StandardSecurityContexts.PkiBrazil (ICP-Brasil).
  • Licenças: o serviço em nuvem não usa arquivo de licença, e o Web PKI não precisa de licença com ele, inclusive em produção. Uma instância on-premises exige uma licença do PKI SDK e, nesse caso, o Web PKI precisa da própria licença. Veja Licenciamento.
  • Datas nas assinaturas de PDF: cultura, fuso horário e formato de data vêm de Região e Data na sua conta. Veja Configuração de data e hora. 
var accessToken = ConfigurationManager.AppSettings["RestPkiAccessToken"];
var endpoint = ConfigurationManager.AppSettings["RestPkiEndpoint"];
if (string.IsNullOrEmpty(endpoint)) {
	endpoint = "https://pki.rest/";
}
return new RestPkiClient(endpoint, accessToken);

Operações principais​

O código é C#, do projeto de exemplos em ASP.NET MVC; as demais linguagens seguem o mesmo fluxo, veja Disponibilidade de exemplos.

Assinar um PDF​

Assinatura PAdES com o certificado do usuário: PadesSignatureStarter.StartWithWebPkiAsync() devolve o token, a página chama o signWithRestPki({ token, thumbprint }) do Web PKI e PadesSignatureFinisher2.FinishAsync() devolve o PDF assinado e o certificado do signatário. O token não é o token de acesso e só vale uma vez; por isso, o exemplo envia headers que desativam o cache. Para a representação visual, veja Tags PAdES. Veja Assinatura PAdES. 

// GET action
var signatureStarter = new PadesSignatureStarter(Util.GetRestPkiClient()) {
	SignaturePolicyId = StandardPadesSignaturePolicies.Basic,
	SecurityContextId = Util.GetSecurityContextId()
};
signatureStarter.SetPdfToSign(userfilePath);
var token = await signatureStarter.StartWithWebPkiAsync();

// POST action, after signWithRestPki() in the browser
var signatureFinisher = new PadesSignatureFinisher2(Util.GetRestPkiClient()) {
	Token = model.Token
};
var result = await signatureFinisher.FinishAsync();
var signerCert = result.Certificate;

Assinar qualquer arquivo com CAdES​

Assinatura CMS/CAdES de qualquer arquivo, gravada como .p7s: CadesSignatureStarter e depois CadesSignatureFinisher2, como no fluxo do PDF. Para fazer uma assinatura conjunta, chame SetCmsToCoSign() com o CMS existente em vez de SetFileToSign(). Veja Assinatura CAdES. 

var signatureStarter = new CadesSignatureStarter(Util.GetRestPkiClient()) {
	SignaturePolicyId = StandardCadesSignaturePolicies.PkiBrazil.AdrBasica,
	SecurityContextId = Util.GetSecurityContextId(),
	EncapsulateContent = true
};
signatureStarter.SetFileToSign(userfilePath);
var token = await signatureStarter.StartWithWebPkiAsync();

Assinar um documento XML​

O FullXmlSignatureStarter assina o documento inteiro; o XmlElementSignatureStarter, com SetToSignElementId(), assina um elemento, como no exemplo de NF-e. Os dois concluem com o XmlSignatureFinisher. Veja Assinatura XML. 

var signatureStarter = new FullXmlSignatureStarter(Util.GetRestPkiClient());
signatureStarter.SetXml(StorageMock.GetSampleXmlDocumentPath());
signatureStarter.SetSignaturePolicy(StandardXmlSignaturePolicies.XadesBes);
signatureStarter.SetSecurityContext(Util.GetSecurityContextId());
var token = await signatureStarter.StartWithWebPkiAsync();

Validar uma assinatura​

Abra um arquivo assinado e valide as assinaturas dele: PadesSignatureExplorer com Validate = true e depois OpenAsync(). Para CAdES, use o CadesSignatureExplorer; para XML, o XmlSignatureExplorer. Veja Abrir uma assinatura PAdES. 

var sigExplorer = new PadesSignatureExplorer(Util.GetRestPkiClient()) {
	Validate = true,
	DefaultSignaturePolicyId = StandardPadesSignaturePolicies.Basic,
	SecurityContextId = Util.GetSecurityContextId()
};
sigExplorer.SetSignatureFile(userfilePath);
var signature = await sigExplorer.OpenAsync();

Gerar uma versão para impressão​

Um PDF marcado com os signatários e um código de verificação: faça upload do arquivo com UploadFile(), valide-o com o PadesSignatureExplorer como acima e adicione as marcas com o PdfMarker, montadas com o PdfHelper da API fluente; o AlphaCode gera o código. Veja Versão para impressão. 

var client = Util.GetRestPkiClient();
var blob = client.UploadFile(pdfContent);
var pdfMarker = new PdfMarker(client);
pdfMarker.SetFile(blob);
pdfMarker.Marks.Add(manifestMark);
var result = pdfMarker.Apply();

Autenticar com certificado​

Login com certificado: GetAuthentication() e depois StartWithWebPkiAsync() com o contexto de segurança; depois que o Web PKI assina o token, CompleteWithWebPkiAsync() devolve os resultados da validação. Veja Autenticação. 

// GET action
var auth = Util.GetRestPkiClient().GetAuthentication();
var token = await auth.StartWithWebPkiAsync(Util.GetSecurityContextId());

// POST action, after signWithRestPki() in the browser
var auth = Util.GetRestPkiClient().GetAuthentication();
var validationResults = await auth.CompleteWithWebPkiAsync(model.Token);
if (!validationResults.IsValid) {
	return View("Failed", validationResults);
}

Solicitar um carimbo de tempo​

Carimbos de tempo ICP-Brasil, com o token de acesso como Bearer: por TSP (RFC 3161) em POST https://pki.rest/tsp/a402df41-8559-47b2-a05c-be555bf66310 ou por REST em POST https://pki.rest/Api/TimestampPlans/a402df41-8559-47b2-a05c-be555bf66310/Issue, que devolve encodedValue (o carimbo de tempo, em Base64) e info. Algoritmos: SHA-1 e SHA-256. Veja Solicitando carimbos de tempo. 

{
	"algorithm": "SHA256",
	"value": "L80RIvFw2jwpiObzFQN+tuEQQ4E9qnGeYYYd+4DrM8M="
}

Erros​

O Rest PKI responde com um código de status HTTP: 401 quando o token de acesso não é válido, 422 com um código de retorno quando uma operação falha e 500 para um erro inesperado. Veja Códigos de retorno. O cliente .NET lança ValidationException para o código de erro ValidationError, cujos ValidationResults dizem o que falhou, e RestPkiException para os demais códigos, com o código em ErrorCode. Para HTTP 401 e outros códigos de status de erro, ele lança RestErrorException, com o status em StatusCode, e, quando nenhuma resposta chega (falha de rede ou timeout), RestUnreachableException. Todas derivam de RestException. Veja Erros no artigo de .NET. O cliente Java também tem RestErrorException e RestUnreachableException.

ErroO que significa
HTTP 401O token de acesso não é válido.
ValidationErrorO certificado do signatário não estava válido na assinatura ou na autenticação; os erros de validação dizem o motivo, como CertificateChainRootNotTrusted.
SecurityContextRequiredNenhum contexto de segurança foi informado.
"Could not get pending signature" (no navegador)O Web PKI não conseguiu acessar o Rest PKI. Verifique se o computador do usuário abre /Api/System/Info na instância e, on-premises, o restPkiUrl. Veja o artigo.

Certificados de teste e credenciais​

  • Certificados de teste: arquivos PKCS #12 com senha 1234, da ICP de testes da Lacuna, que nunca deve ser confiada em produção.
  • Para aceitá-los, use o contexto de segurança da ICP de testes da Lacuna, 803517ad-3bbc-4169-b085-60053a8f6dbf. Os exemplos em .NET usam StandardSecurityContexts.LacunaTest só em builds de debug e avisam que uma instalação on-premises pode não tê-lo; os demais exemplos o usam quando trustLacunaTestRoot (TRUST_LACUNA_TEST_ROOT em Python) está ligado na configuração.
  • Token de acesso: os projetos do PkiSuiteSamples vêm com um token de acesso de avaliação para o pki.rest, com a data de expiração num comentário ao lado (no exemplo em ASP.NET MVC, RestPkiAccessToken no Web.config). Para a sua aplicação, gere um token como em Configuração e autenticação.

TODO(docs): nenhum ambiente de testes separado está documentado para o pki.rest.

Experimente​

Demonstrações e os exemplos do Rest PKI em cada linguagem:

Ver em Markdown