TrustArbitrator

The TrustArbitrator defines which digital certificates Signer accepts. When Signer signs or validates a digital signature, it builds the certificate chain. The chain is the list of certificates that links the signer's certificate to a root CA (the highest-level certificate authority). Then Signer asks the TrustArbitrator if this root is trusted. If the TrustArbitrator does not accept the root, Signer rejects the signature.

By default, Signer accepts only ICP-Brasil certificates. This page explains how to change this setting. For example, you can accept your own root CA, e-Notariado or certificates from other countries.

Where the TrustArbitrator is used

Signer has a default TrustArbitrator for the instance and one TrustArbitrator for each signature type:

Where	Setting	Default
Instance default	`TrustArbitrator` section	ICP-Brasil
Simple signature type	`SignatureTypes:Simple:TrustArbitrator` section	ICP-Brasil
Qualified signature type	`SignatureTypes:Qualified:TrustArbitrator` section	ICP-Brasil
Advanced signature type	Security context, in the administration area	Set in each context

If the section does not exist, or if Type is empty, the TrustArbitrator accepts only ICP-Brasil.

Signer uses the default TrustArbitrator in these cases:

To sign and validate digital signatures, if SignatureTypes is disabled or if the operation does not specify a signature type.
To authenticate with a digital certificate on CSC cloud signature services.
In the simplified manifest, to decide if the text about ICP-Brasil is shown.

The SignatureTypes:Simple:TrustArbitrator and SignatureTypes:Qualified:TrustArbitrator sections apply only if SignatureTypes:Enabled is true. The Signature Types settings describe the SignatureTypes parameters.

Advanced signature

The Advanced type does not use the settings file. A security context groups the rules of Advanced signatures, and each context has its own TrustArbitrator. The instance administrator sets this TrustArbitrator in the administration area. The administrator selects the standard PKIs and uploads the trusted roots of the context.

TrustArbitrator JSON format

A JSON describes the TrustArbitrator. The two configuration methods on this page use the same JSON:

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

Property	Required	Description
`Version`	Yes	Format version: `2019-05-09` or `2022-07-21`. Any other value causes an error.
`StandardPkis`	No	List of accepted standard PKIs. See the values in `StandardPkis` values.
`TrustedRoots`	No	List of accepted root CA certificates, in addition to the standard PKIs. Each item is a certificate in Base64 (DER) or PEM format.
`IntermediateCAs`	No	List of intermediate CA certificates, in the same format as `TrustedRoots`. Only available in version `2022-07-21`.

Intermediate CAs

An intermediate CA is between the root CA and the signer's certificate. Use IntermediateCAs if the signers' certificates do not include the data that Signer needs to download these CAs. The certificates in IntermediateCAs are not trusted by themselves. The chain must still end in an accepted root.

`StandardPkis` values

A PKI (public key infrastructure) is the set of CAs of a country or sector. The StandardPkis property accepts these values:

Value	Accepted certificates
`Brazil`	ICP-Brasil
`Italy`	Italian PKI
`Peru`	Peruvian PKI
`System`	Trusted roots of the server operating system
`ENotariado`	e-Notariado (Colégio Notarial do Brasil)
`RegistroCivil`	Registro Civil do Brasil (IdRC)

If the TrustArbitrator has more than one PKI or root, one of them must accept the certificate root.

Where to store the JSON

The Type property defines where Signer gets the TrustArbitrator JSON. Select the method from the JSON content:

`Type`	JSON location	Use if
`AppSetting`	In the `Content` property, as text	You use only standard PKIs.
`BlobStorage`	In a file in the Blob Storage	The TrustArbitrator has its own roots or intermediate CAs.

With your own roots, the Content text becomes long and difficult to maintain. Thus, use BlobStorage in this case.

Environment variables

In Docker or Azure App Services installations, you can set the settings with environment variables. Separate each level with __ (two underscores). The examples on this page show the two methods. After you change appsettings.json or the environment variables, restart the application.

Option 1: JSON in the settings (`AppSetting`)

With this option, the TrustArbitrator JSON is in the Content property, as text on a single line. This is the simplest method. The example below accepts ICP-Brasil and e-Notariado:

appsettings.json
Environment variables

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

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

Property	Required	Description
`Type`	Yes	`AppSetting`
`Content`	Yes	The TrustArbitrator JSON, as text

warning

In appsettings.json, escape all double quotes in Content with \". Content is text inside another JSON. If Content is empty or has an invalid JSON, the operations that use the TrustArbitrator fail.

Option 2: file in the Blob Storage (`BlobStorage`)

With this option, the TrustArbitrator JSON is in a file in the instance Blob Storage. Before you start, make sure that the Blob Storage is configured. See Blob Storage settings.

Create a .json file with the TrustArbitrator content. For example:

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

Upload the file to the trustarbitrators folder of the Blob Storage. The location depends on the Blob Storage type:

Blob Storage type File location
File system <Blob Storage folder>/trustarbitrators/my-trustarbitrator.json
Azure Configured container, with the trustarbitrators/ prefix
Point Signer to the file with the settings below.

Blob Storage type	File location
File system	`<Blob Storage folder>/trustarbitrators/my-trustarbitrator.json`
Azure	Configured container, with the `trustarbitrators/` prefix

appsettings.json
Environment variables

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

TrustArbitrator__Type=BlobStorage
TrustArbitrator__BlobName=my-trustarbitrator.json

Property	Required	Description
`Type`	Yes	`BlobStorage`
`BlobName`	Yes	File name in the Blob Storage
`BlobFolderName`	No	File folder in the Blob Storage. The default is `trustarbitrators`. Change it only if the file is in a different folder.

warning

Do not use a GUID as the name of the default TrustArbitrator file. The trustarbitrators folder also keeps the TrustArbitrators of the security contexts. Signer uses GUIDs as the names of these files and deletes them when the context changes or is deleted.

Signer reads the file at each operation. Thus, a change to the file applies to the next signatures and validations. You do not need to restart the application.

TrustArbitrators of the Simple and Qualified types

The SignatureTypes:Simple:TrustArbitrator and SignatureTypes:Qualified:TrustArbitrator sections accept the same properties as the TrustArbitrator section: Type, Content, BlobName and BlobFolderName. If the section does not exist, the signature type accepts only ICP-Brasil.

In the example below, the Qualified type accepts ICP-Brasil and e-Notariado. The Simple type uses the TrustArbitrator from a file in the Blob Storage:

appsettings.json
Environment variables

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

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

Troubleshooting

If the TrustArbitrator settings have an error, Signer writes these messages to the log:

Log message	Probable cause
`Invalid trust arbitrator JSON`	The JSON is malformed. Make sure that the quotes in `Content` are escaped and that the file content is a valid JSON.
`'version' property not found`	The JSON does not have the `Version` property.
`Unrecognized version`	`Version` has a value other than `2019-05-09` and `2022-07-21`.
`The content for the trust arbitrator JSON must be set...`	`Type` is `AppSetting`, but `Content` is empty.
`The blobName for the trust arbitrator JSON must be configured`	`Type` is `BlobStorage`, but `BlobName` is empty.

If Signer rejects a signature because the certificate root is not trusted, do these checks:

Find which TrustArbitrator the operation uses in Where the TrustArbitrator is used.
Make sure that the certificate PKI is in the StandardPkis of this TrustArbitrator.
If the PKI is not in the list, make sure that the certificate root is in TrustedRoots.

Where the TrustArbitrator is used​

TrustArbitrator JSON format​

StandardPkis values​

Where to store the JSON​

Option 1: JSON in the settings (AppSetting)​

Option 2: file in the Blob Storage (BlobStorage)​

TrustArbitrators of the Simple and Qualified types​

Troubleshooting​

See also​