Lacuna CloudHub

O Lacuna CloudHub conecta a sua aplicação aos provedores de certificado em nuvem da ICP-Brasil por meio de uma única API REST. Um certificado em nuvem guarda a chave privada no HSM do provedor; o titular autoriza cada uso no aplicativo ou na página do próprio provedor, com PIN, notificação push ou QR code. Com o CloudHub, a sua aplicação descobre quais provedores têm um certificado para um CPF ou CNPJ, envia o usuário para autorizar e, depois, lê o certificado e assina hashes com ele.

Os provedores são os Prestadores de Serviço de Confiança (PSCs) credenciados pelo ITI, como BirdID, SafeID e VIDaaS. No CloudHub e nesta documentação, eles são chamados de provedores.

Por que usar o CloudHub

Cada provedor é um servidor de autorização OAuth 2.0, com endpoint próprio, cadastro de cliente próprio e variações próprias em relação à especificação comum. Integrar provedor por provedor significa ter um client ID e um client secret em cada um, cadastrar uma URI de redirecionamento em cada um e escrever código para as particularidades de cada um.

O CloudHub mantém esses cadastros e absorve essas diferenças. A sua aplicação precisa de:

• Uma chave de API, enviada no header X-Api-Key.
• Uma integração: as mesmas chamadas, qualquer que seja o provedor escolhido pelo usuário.
• Nenhuma mudança quando a Lacuna adiciona um provedor: ele aparece na lista que o CloudHub devolve.

O que o CloudHub faz e o que fica com você

O CloudHub faz três coisas: descobre os provedores que têm um certificado para o signatário, intermedia a autorização no provedor e assina um hash com o certificado autorizado.

Ele não monta documentos assinados. A sua biblioteca de assinatura calcula o hash a assinar e, depois, monta o PDF, o CMS ou o XML assinado. Qualquer produto de assinatura da Lacuna funciona com o CloudHub: PKI SDK, Rest PKI, Rest PKI Core ou PKI Express. O CloudHub nunca recebe o documento, só o hash dele, e a chave privada nunca sai do provedor.

O CloudHub também não valida o certificado. Valide-o com a sua biblioteca de assinatura, que faz isso ao concluir a assinatura ou a autenticação.

Provedores suportados

Os provedores disponíveis para a sua aplicação são os que o CloudHub devolve quando você cria uma sessão; a lista abaixo é a que a página inicial do CloudHub mostra hoje.

Provedor	Operado por
BirdID	SOLUTI
DSCloud	DigitalSign
NeoID	SERPRO
RemoteID	Certisign
SafeID	Safeweb
Syngular	Syngular
VIDaaS	VALID

Como uma assinatura acontece

1. O seu backend cria uma sessão com o CPF do signatário e a URL para onde o CloudHub deve devolver o usuário. O CloudHub responde com uma URL de autorização para cada provedor que tem um certificado para esse CPF.
2. O usuário escolhe um provedor, é redirecionado para ele e autoriza. O provedor devolve o usuário ao CloudHub, e o CloudHub o devolve à sua aplicação com um parâmetro session.
3. O seu backend usa essa sessão para ler o certificado, pede à biblioteca de assinatura que calcule o hash a assinar, pede ao CloudHub que assine o hash e finaliza o documento assinado.

Como funciona detalha cada passo, os tipos de sessão e as regras para URIs de redirecionamento.

O que você precisa

• Uma chave de API do CloudHub. Peça uma ao suporte da Lacuna Software (suporte@lacunasoftware.com) e informe as URIs de redirecionamento que a sua aplicação vai usar; o CloudHub só devolve usuários a URIs cadastradas para a sua chave (veja URIs de redirecionamento).
• Uma biblioteca de assinatura para calcular o hash a assinar e finalizar a assinatura: PKI SDK, Rest PKI, Rest PKI Core ou PKI Express.
• O endereço do CloudHub: https://cloudhub.lacunasoftware.com.

Mantenha a chave de API no seu servidor. Ela autoriza todas as chamadas, inclusive a assinatura, e por isso nunca deve chegar a um navegador ou a um aplicativo móvel.

Bibliotecas cliente

Linguagem	Pacote	Instalação
.NET	Lacuna.Cloudhub.Client (NuGet)	dotnet add package Lacuna.Cloudhub.Client
PHP	lacuna/cloudhub-client (Packagist)	composer require lacuna/cloudhub-client
Node.js	cloudhub-client (npm)	npm install cloudhub-client
Java	com.lacunasoftware.cloudhub:cloudhub-client (Maven Central)	implementation 'com.lacunasoftware.cloudhub:cloudhub-client:1.0.5'
Python	nenhuma é necessária	pip install requests; os exemplos chamam a API REST diretamente

A API tem oito operações e um header, então qualquer cliente HTTP serve. A referência da API REST documenta o formato das mensagens.

Exemplos

O repositório PKI Suite Samples tem aplicações completas que assinam com o CloudHub:

Linguagem	Exemplo
.NET (PKI SDK)	PadesCloudHubSdkController.cs, AuthenticationCloudHubSdkController.cs
PHP (Rest PKI)	pades-signature-cloudhub-rest, xml-signature-cloudhub-rest
Node.js (Rest PKI)	pades-signature-cloudhub-restpki.js, authentication-cloudhub.js
Java (Rest PKI)	PadesSignatureCloudhubRestController.java

Nesta documentação

• Como funciona: sessões, tipos de sessão, descoberta, URIs de redirecionamento e segurança.
• Primeiros passos: instale um cliente, crie uma sessão e assine um hash.
• Assinando um PDF: uma assinatura PAdES completa em C#, PHP, Python, Node.js e Java.
• Autenticação: permita que os usuários entrem com o certificado em nuvem.
• API REST: todas as operações, modelos e códigos de erro.