TrustArbitrator

O TrustArbitrator define quais certificados digitais o Signer aceita. Ao assinar ou validar uma assinatura digital, o Signer monta a cadeia do certificado. A cadeia é a lista de certificados que liga o certificado do signatário a uma AC raiz (autoridade certificadora de nível mais alto). Depois, o Signer pergunta ao TrustArbitrator se essa raiz é confiável. Se o TrustArbitrator não aceita a raiz, o Signer recusa a assinatura.

Por padrão, o Signer aceita apenas certificados da ICP-Brasil. Esta página explica como mudar essa configuração. Por exemplo, você pode aceitar uma AC raiz própria, o e-Notariado ou certificados de outros países.

Onde o TrustArbitrator é usado

O Signer tem um TrustArbitrator padrão da instância e um TrustArbitrator para cada tipo de assinatura:

Onde	Configuração	Padrão
Padrão da instância	Seção TrustArbitrator	ICP-Brasil
Tipo de assinatura Simples	Seção SignatureTypes:Simple:TrustArbitrator	ICP-Brasil
Tipo de assinatura Qualificada	Seção SignatureTypes:Qualified:TrustArbitrator	ICP-Brasil
Tipo de assinatura Avançada	Contexto de segurança, na área de administração	Definido em cada contexto

Se a seção não existir, ou se Type estiver vazio, o TrustArbitrator aceita apenas a ICP-Brasil.

O Signer usa o TrustArbitrator padrão nestes casos:

• Na assinatura e na validação digital, se SignatureTypes está desabilitado ou se a operação não informa o tipo de assinatura.
• Na autenticação por certificado digital nos serviços de assinatura em nuvem CSC.
• No manifesto simplificado, para decidir se o texto sobre a ICP-Brasil aparece.

As seções SignatureTypes:Simple:TrustArbitrator e SignatureTypes:Qualified:TrustArbitrator só têm efeito se SignatureTypes:Enabled é true. A página Configurações do Signer descreve os parâmetros de SignatureTypes.

Assinatura Avançada

O tipo Avançada não usa o arquivo de configuração. Um contexto de segurança agrupa as regras de assinatura Avançada, e cada contexto tem o próprio TrustArbitrator. O administrador da instância define esse TrustArbitrator na área de administração. Ele escolhe as PKIs padrão e envia as raízes confiáveis do contexto.

Formato do JSON do TrustArbitrator

Um JSON descreve o TrustArbitrator. As duas formas de configuração desta página usam o mesmo JSON:

{
  "Version": "2019-05-09",
  "StandardPkis": [ "Brazil" ],
  "TrustedRoots": []
}

Propriedade	Obrigatória	Descrição
Version	Sim	Versão do formato: 2019-05-09 ou 2022-07-21. Qualquer outro valor gera erro.
StandardPkis	Não	Lista de PKIs padrão aceitas. Veja os valores em Valores de StandardPkis.
TrustedRoots	Não	Lista de certificados de AC raiz aceitos, além das PKIs padrão. Cada item é o certificado em Base64 (DER) ou em formato PEM.
IntermediateCAs	Não	Lista de certificados de ACs intermediárias, no mesmo formato de TrustedRoots. Só existe na versão 2022-07-21.

ACs intermediárias

Uma AC intermediária fica entre a AC raiz e o certificado do signatário. Use IntermediateCAs se os certificados dos signatários não trazem as informações para o Signer baixar essas ACs. Os certificados de IntermediateCAs não são confiáveis sozinhos. A cadeia ainda precisa terminar em uma raiz aceita.

Valores de StandardPkis

Uma PKI (infraestrutura de chaves públicas) é o conjunto de ACs de um país ou setor. A propriedade StandardPkis aceita os valores abaixo:

Valor	Certificados aceitos
Brazil	ICP-Brasil
Italy	PKI da Itália
Peru	PKI do Peru
System	Raízes confiáveis do sistema operacional do servidor
ENotariado	e-Notariado (Colégio Notarial do Brasil)
RegistroCivil	Registro Civil do Brasil (IdRC)

Se o TrustArbitrator tem mais de uma PKI ou raiz, basta que uma delas aceite a raiz do certificado.

Onde guardar o JSON

A propriedade Type define onde o Signer busca o JSON do TrustArbitrator. Escolha a forma pelo conteúdo do JSON:

Type	Onde fica o JSON	Use se
AppSetting	Na propriedade Content, como texto	Você usa apenas PKIs padrão.
BlobStorage	Em um arquivo no Blob Storage	O TrustArbitrator tem raízes ou ACs intermediárias próprias.

Com raízes próprias, o texto de Content fica longo e difícil de manter. Por isso, use BlobStorage nesse caso.

Variáveis de ambiente

Em instalações com Docker ou Azure App Services, você pode definir as configurações por variáveis de ambiente. Separe cada nível com __ (dois sublinhados). Os exemplos desta página mostram as duas formas. Depois de alterar appsettings.json ou as variáveis de ambiente, reinicie a aplicação.

Opção 1: JSON nas configurações (AppSetting)

Nesta opção, o JSON do TrustArbitrator fica na propriedade Content, como texto em uma única linha. É a forma mais simples. O exemplo abaixo aceita ICP-Brasil e e-Notariado:

appsettings.json

appsettings.json

{
  "TrustArbitrator": {
    "Type": "AppSetting",
    "Content": "{ \"Version\": \"2019-05-09\", \"StandardPkis\": [ \"Brazil\", \"ENotariado\" ] }"
  }
}

Variáveis de ambiente

TrustArbitrator__Type=AppSetting
TrustArbitrator__Content={ "Version": "2019-05-09", "StandardPkis": [ "Brazil", "ENotariado" ] }

Propriedade	Obrigatória	Descrição
Type	Sim	AppSetting
Content	Sim	O JSON do TrustArbitrator, como texto

aviso

No appsettings.json, escape todas as aspas duplas de Content com \". Content é um texto dentro de outro JSON. Se Content estiver vazio ou tiver um JSON inválido, as operações que usam o TrustArbitrator falham.

Opção 2: arquivo no Blob Storage (BlobStorage)

Nesta opção, o JSON do TrustArbitrator fica em um arquivo no Blob Storage da instância. Antes de começar, verifique se o Blob Storage está configurado. Veja Configuração do Blob Storage.

1. Crie um arquivo .json com o conteúdo do TrustArbitrator. Por exemplo:

   meu-trustarbitrator.json

   {
     "Version": "2019-05-09",
     "StandardPkis": [ "Brazil" ],
     "TrustedRoots": [
       "MIIGBjCCA+6gAwIBAgIBATANBgkqhkiG9w0BAQ0FADCBkzELMAkGA1UEBhMCQlIx..."
     ]
   }

2. Envie o arquivo para a pasta trustarbitrators do Blob Storage. O local depende do tipo de Blob Storage:

   Tipo de Blob Storage	Local do arquivo
   Sistema de arquivos	<pasta do Blob Storage>/trustarbitrators/meu-trustarbitrator.json
   Azure	Contêiner configurado, com o prefixo trustarbitrators/

3. Aponte o Signer para o arquivo com a configuração abaixo.

appsettings.json

appsettings.json

{
  "TrustArbitrator": {
    "Type": "BlobStorage",
    "BlobName": "meu-trustarbitrator.json"
  }
}

Variáveis de ambiente

TrustArbitrator__Type=BlobStorage
TrustArbitrator__BlobName=meu-trustarbitrator.json

Propriedade	Obrigatória	Descrição
Type	Sim	BlobStorage
BlobName	Sim	Nome do arquivo no Blob Storage
BlobFolderName	Não	Pasta do arquivo no Blob Storage. O padrão é trustarbitrators. Mude só se o arquivo estiver em outra pasta.

aviso

Não nomeie o arquivo do TrustArbitrator padrão com um GUID. A pasta trustarbitrators também guarda os TrustArbitrators dos contextos de segurança. O Signer nomeia esses arquivos com GUIDs e os apaga quando o contexto muda ou é excluído.

O Signer lê o arquivo a cada operação. Por isso, uma alteração no arquivo vale para as próximas assinaturas e validações. Você não precisa reiniciar a aplicação.

TrustArbitrators dos tipos Simples e Qualificada

As seções SignatureTypes:Simple:TrustArbitrator e SignatureTypes:Qualified:TrustArbitrator aceitam as mesmas propriedades da seção TrustArbitrator: Type, Content, BlobName e BlobFolderName. Se a seção não existir, o tipo de assinatura aceita apenas a ICP-Brasil.

No exemplo abaixo, o tipo Qualificada aceita ICP-Brasil e e-Notariado. O tipo Simples usa o TrustArbitrator de um arquivo no Blob Storage:

appsettings.json

appsettings.json

{
  "SignatureTypes": {
    "Enabled": true,
    "Simple": {
      "TrustArbitrator": {
        "Type": "BlobStorage",
        "BlobName": "simples.json"
      }
    },
    "Qualified": {
      "TrustArbitrator": {
        "Type": "AppSetting",
        "Content": "{ \"Version\": \"2019-05-09\", \"StandardPkis\": [ \"Brazil\", \"ENotariado\" ] }"
      }
    }
  }
}

Variáveis de ambiente

SignatureTypes__Enabled=true
SignatureTypes__Simple__TrustArbitrator__Type=BlobStorage
SignatureTypes__Simple__TrustArbitrator__BlobName=simples.json
SignatureTypes__Qualified__TrustArbitrator__Type=AppSetting
SignatureTypes__Qualified__TrustArbitrator__Content={ "Version": "2019-05-09", "StandardPkis": [ "Brazil", "ENotariado" ] }

Solução de problemas

O Signer registra no log as mensagens abaixo quando a configuração do TrustArbitrator tem erro:

Mensagem no log	Causa provável
Invalid trust arbitrator JSON	O JSON está malformado. Verifique se as aspas de Content têm escape e se o conteúdo do arquivo é um JSON válido.
'version' property not found	O JSON não tem a propriedade Version.
Unrecognized version	Version tem um valor diferente de 2019-05-09 e 2022-07-21.
The content for the trust arbitrator JSON must be set...	Type é AppSetting, mas Content está vazio.
The blobName for the trust arbitrator JSON must be configured	Type é BlobStorage, mas BlobName está vazio.

Se o Signer recusar uma assinatura porque a raiz do certificado não é confiável, faça estas verificações:

1. Veja em Onde o TrustArbitrator é usado qual TrustArbitrator a operação usa.
2. Verifique se a PKI do certificado está em StandardPkis desse TrustArbitrator.
3. Se a PKI não está na lista, verifique se a raiz do certificado está em TrustedRoots.

Veja também

• Configurações do Signer
• Configuração do Blob Storage