Contextos de segurança - Rest PKI Core

Um contexto de segurança diz ao Rest PKI Core em quais certificados confiar quando ele valida o certificado de um signatário: em assinaturas, sessões de assinatura, autenticação com certificado e inspeção de assinaturas. Um certificado só é aceito se a cadeia dele terminar numa raiz em que o contexto de segurança confia.

Toda instância tem contextos de segurança padrão, como o da ICP-Brasil e o da ICP de testes da Lacuna. Quando nenhum deles serve, por exemplo porque os seus usuários têm certificados emitidos por uma AC privada, crie um contexto de segurança próprio no dashboard.

Contextos de segurança padrão

O Rest PKI Core cria estes contextos de segurança em toda instância, com os mesmos IDs em todas. Eles aparecem para todas as organizações e não podem ser alterados:

Contexto de segurança	ID	Confia em
PkiBrazil	201856ce-273c-4058-a872-8937bd547d36	ICP-Brasil
PkiBrazilExtended	3ce63ec8-2c71-4181-b4cd-33c3ba6d614f	Entidades de estado oficiais brasileiras: ICP-Brasil e gov.br
GovBR	5d323217-c031-4eed-9001-1cd82d86a8b5	gov.br
PkiBrazilWithENotariado	f963e2dd-1606-4937-b903-01926785dcf0	ICP-Brasil e a hierarquia do e-Notariado (Colégio Notarial do Brasil)
PkiBrazilWithGovBrAndENotariado	4bf4409f-db45-4aab-91bf-2c73930ca556	ICP-Brasil, gov.br e a hierarquia do e-Notariado
PkiItaly	c438b17e-4862-446b-86ad-6f85734f0bfe	As ACs confiáveis da ICP italiana
WindowsServer	3881384c-a54d-45c5-bbe9-976b674f5ec7	As raízes que a Microsoft considera confiáveis
LacunaTest	803517ad-3bbc-4169-b085-60053a8f6dbf	ICP-Brasil, as raízes que a Microsoft considera confiáveis e a ICP de testes da Lacuna. Apenas para desenvolvimento (veja Certificados de teste)

Em .NET, a classe StandardSecurityContexts (namespace Lacuna.RestPki.Api) tem todos eles, como StandardSecurityContexts.PkiBrazil; em Java, a classe SecurityContext tem todos menos os dois do e-Notariado, como SecurityContext.pkiBrazil. Os quatro que o Rest PKI também tem, PkiBrazil, PkiItaly, WindowsServer e LacunaTest, têm os mesmos IDs lá.

Escolhendo o contexto de segurança de uma chamada

Passe o ID do contexto de segurança no campo securityContextId da requisição. Estas APIs o recebem:

API	Rota
Sessões de assinatura	POST api/signature-sessions
Assinaturas em duas etapas	POST api/signature
Autenticação com certificado	POST api/v2/authentication
Inspeção de assinaturas	PUT api/signature-inspection
Extensão de arquivamento de uma assinatura	POST api/signature/archival-extension
As APIs do Rest PKI que o Rest PKI Core atende	O início de uma assinatura (Api/PadesSignatures, Api/CadesSignatures, Api/XmlSignatures/...), as rotas Open e Api/Authentications

Em .NET, por exemplo:

var response = await restPkiService.CreateSignatureSessionAsync(new CreateSignatureSessionRequest() {
	ReturnUrl = "https://localhost:5001/signature-callback",
	SecurityContextId = StandardSecurityContexts.PkiBrazil,
});

Quando uma chamada não informa o securityContextId, o Rest PKI Core usa o contexto de segurança padrão da organização ou, se a organização não tiver um, o padrão da instância, que é o PkiBrazil, a menos que a instância tenha sido configurada de outra forma. As rotas de assinatura do Rest PKI são uma exceção: sem contexto de segurança, elas confiam no que a política de assinatura define, e falham com SecurityContextRequired quando a política não define nada, como a StandardPadesSignaturePolicies.Basic. A rota de autenticação com certificado do Rest PKI, Api/Authentications, sempre exige o ID.

dica

Cite o contexto de segurança em todas as chamadas em vez de depender de um padrão. Assim, o seu código confia nos mesmos certificados qualquer que seja a organização ou a instância em que ele roda.

Gerenciando os contextos de segurança no dashboard

Os contextos de segurança são gerenciados no dashboard da instância, por usuários com o papel Gerente ou Administrador (veja Escolhendo os papéis). No menu lateral, clique em Contextos de segurança. A lista mostra os contextos de segurança padrão e os da organização, com o Tipo deles: Standard para os padrão, Custom para os criados na organização e System para os criados na área de administração do sistema da instância, que todas as organizações podem usar.

Criando um contexto de segurança

1. Em Contextos de segurança, clique em Adicionar. Se o dashboard estiver mostrando todas as organizações, selecione uma organização antes: o contexto de segurança pertence à organização em que for criado.
2. Preencha um Nome, único na organização (até 100 caracteres).
3. Em Raízes confiáveis, faça upload dos certificados raiz das ACs em que confiar. Cada um precisa ser um certificado raiz, isto é, autoassinado.
4. Em Arbitradores de confiança padrão adicionais, marque os conjuntos padrão de raízes em que também confiar: ICP-Brasil, Gov.BR, Entidades de estado brasileiras (inclui ICP-Brasil e gov.br), PKI Itália, Windows Server, Lacuna Test e e-Notariado.
5. Se quiser, escolha um Plano de fornecimento de carimbo de tempo e marque a opção em Outras opções (veja Configurações de um contexto de segurança abaixo).
6. Clique em Salvar.

O novo contexto de segurança recebe um ID, mostrado como Id quando você o abre pela lista: use-o como o securityContextId das suas chamadas.

Um contexto de segurança confia na união das raízes confiáveis dele e dos arbitradores de confiança padrão marcados. Um contexto de segurança que não confia em nada pode ser salvo, mas toda chamada que o usar falha.

Se o dashboard não conseguir salvar o contexto de segurança, ele informa o motivo:

Mensagem	O que fazer
Já existe um contexto de segurança com o mesmo nome	Escolha outro Nome
O certificado de uma ou mais raízes adicionadas é inválido	Verifique se o arquivo enviado é um certificado
Uma ou mais das raízes confiáveis dadas não é um certificado raiz	Envie a raiz da cadeia, não uma AC intermediária nem um certificado de usuário final
Uma ou mais das raízes confiáveis sendo adicionadas já existe no contexto de segurança	Ao editar, não envie uma raiz que o contexto de segurança já tem

Configurações de um contexto de segurança

Configuração	Efeito
Plano de fornecimento de carimbo de tempo	O plano de carimbo de tempo usado quando uma política de assinatura exige carimbo de tempo. Com Nenhum, o Rest PKI Core escolhe o plano pelas raízes confiáveis (o da ICP-Brasil ou o da Lacuna Test) ou então o plano padrão, e a assinatura falha com SecurityContextNotConfiguredForTimestamping quando não há nenhum
Ignorar falhas de validação de "estado de revogação desconhecido"	Aceita certificados cujo estado de revogação não pode ser determinado, em assinaturas, sessões de assinatura e nas rotas de assinatura e Open do Rest PKI. A autenticação com certificado e a inspeção de assinaturas não a usam: elas recebem o próprio parâmetro ignoreRevocationStatusUnknown, e a autenticação com certificado, quando o parâmetro é omitido, segue Ignorar status de revogação desconhecido por padrão em Configurações > Configurações gerais

Editando e excluindo

Clique no nome de um contexto de segurança da organização para alterá-lo e depois em Salvar, ou para Excluir o contexto. Os contextos de segurança padrão abrem apenas para leitura.

aviso

O Rest PKI Core não verifica se um contexto de segurança está em uso antes de excluí-lo. Depois da exclusão, as chamadas que o citam falham com SecurityContextNotFound, e as sessões de assinatura, assinaturas em duas etapas e autenticações com certificado iniciadas com ele falham ao serem concluídas. Se ele era o padrão da organização, as chamadas que não citam nenhum contexto de segurança também falham. Antes de excluir, verifique se nenhuma aplicação o usa e, se preciso, escolha outro padrão.

O contexto de segurança padrão

Para escolher o contexto de segurança usado pelas chamadas que não citam nenhum, vá a Configurações > Configurações gerais > Contexto de segurança padrão no dashboard. Isso exige o papel Gerente ou Administrador. Sem um padrão, o Rest PKI Core usa o da instância.

Pela API

O dashboard gerencia os contextos de segurança por meio de api/security-contexts, que não faz parte da referência da API, e as bibliotecas cliente não têm métodos para isso. Uma aplicação cuja chave tem o papel Operador, como na maioria das integrações, pode usar qualquer contexto de segurança pelo ID, mas não pode listá-los, criá-los nem alterá-los.

Migrando do Rest PKI

Os contextos de segurança padrão que o Rest PKI tem mantêm os IDs no Rest PKI Core, então o código que os cita funciona sem mudanças. Um contexto de segurança que você criou no Rest PKI não é levado: crie-o de novo no Rest PKI Core e use o novo ID. Veja Migração do Rest PKI.

Veja também

• Escolhendo os papéis
• Certificados de teste
• Inspeção de assinaturas