Security contexts - Rest PKI Core

A security context tells Rest PKI Core which certificates to trust when it validates a signer's certificate: in signatures, signature sessions, certificate authentication and signature inspection. A certificate is accepted only if its chain ends at a root that the security context trusts.

Every instance has standard security contexts, such as ICP-Brasil and the Lacuna Test PKI. When none of them fits, for instance because your users have certificates issued by a private CA, create a security context of your own on the dashboard.

Standard security contexts

Rest PKI Core creates these security contexts on every instance, with the same IDs everywhere. They are visible to every subscription and can't be changed:

Security context	ID	Trusts
PkiBrazil	201856ce-273c-4058-a872-8937bd547d36	ICP-Brasil
PkiBrazilExtended	3ce63ec8-2c71-4181-b4cd-33c3ba6d614f	Official Brazilian state entities: ICP-Brasil and gov.br
GovBR	5d323217-c031-4eed-9001-1cd82d86a8b5	gov.br
PkiBrazilWithENotariado	f963e2dd-1606-4937-b903-01926785dcf0	ICP-Brasil and the e-Notariado hierarchy (Colégio Notarial do Brasil)
PkiBrazilWithGovBrAndENotariado	4bf4409f-db45-4aab-91bf-2c73930ca556	ICP-Brasil, gov.br and the e-Notariado hierarchy
PkiItaly	c438b17e-4862-446b-86ad-6f85734f0bfe	The trusted CAs of the Italian PKI
WindowsServer	3881384c-a54d-45c5-bbe9-976b674f5ec7	The root certificates that Microsoft deems trustworthy
LacunaTest	803517ad-3bbc-4169-b085-60053a8f6dbf	ICP-Brasil, the root certificates that Microsoft deems trustworthy and the Lacuna Test PKI. For development only (see Test certificates)

In .NET, the class StandardSecurityContexts (namespace Lacuna.RestPki.Api) has all of them, such as StandardSecurityContexts.PkiBrazil; in Java, the class SecurityContext has all but the two e-Notariado ones, such as SecurityContext.pkiBrazil. The four that Rest PKI also has, PkiBrazil, PkiItaly, WindowsServer and LacunaTest, have the same IDs there.

Choosing the security context of a call

Pass the ID of the security context in the securityContextId field of the request. These APIs take it:

API	Route
Signature sessions	POST api/signature-sessions
Two-step signatures	POST api/signature
Certificate authentication	POST api/v2/authentication
Signature inspection	PUT api/signature-inspection
Archival extension of a signature	POST api/signature/archival-extension
The Rest PKI APIs that Rest PKI Core serves	Starting a signature (Api/PadesSignatures, Api/CadesSignatures, Api/XmlSignatures/...), the Open routes and Api/Authentications

On .NET, for instance:

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

When a call gives no securityContextId, Rest PKI Core uses the subscription's default security context or, if the subscription has none, the instance's default, which is PkiBrazil unless the instance was configured otherwise. The Rest PKI signature routes are an exception: without a security context, they trust what the signature policy defines, and fail with SecurityContextRequired when the policy defines nothing, as StandardPadesSignaturePolicies.Basic does. The Rest PKI certificate authentication route, Api/Authentications, always needs the ID.

tip

Name the security context in every call instead of relying on a default. Your code then trusts the same certificates whichever subscription or instance it runs against.

Managing security contexts on the dashboard

Security contexts are managed on the dashboard of the instance, by users with the Manager or Admin role (see Choosing roles). On the left menu, click Security contexts. The list shows the standard security contexts and those of the subscription, with their Type: Standard for the standard ones, Custom for those created in the subscription and System for those created in the instance's system administration area, which every subscription can use.

Creating a security context

1. On Security contexts, click Add. If the dashboard is showing all subscriptions, select a subscription first: the security context belongs to the subscription it is created in.
2. Fill in a Name, unique in the subscription (up to 100 characters).
3. Under Trusted roots, upload the root certificates of the CAs to trust. Each one must be a root certificate, that is, self-signed.
4. Under Additional standard trust arbitrators, check the standard sets of roots to trust as well: PKI Brazil, Gov.BR, Brazilian state entities (includes PKI Brazil and gov.br), PKI Italy, Windows Server, Lacuna Test and e-Notariado.
5. Optionally, choose a Timestamp tier and check the option under Other options (see Settings below).
6. Click Save.

The new security context gets an ID, shown as Id when you open it from the list: use it as the securityContextId of your calls.

A security context trusts the union of its trusted roots and of the standard trust arbitrators you checked. A security context that trusts nothing can be saved, but every call that uses it fails.

If the dashboard can't save the security context, it tells you why:

Message	What to do
There is already a security context with the same given name	Choose another Name
The certificate of one or more trusted roots being added is invalid	Check that the file you uploaded is a certificate
One or more of the given trusted roots are not root certificates	Upload the root of the chain, not an intermediate CA or end-user certificate
One or more of the trusted roots being added already exists on the security context	When editing, don't upload a root the security context already has

Settings of a security context

Setting	Effect
Timestamp tier	The timestamp tier used when a signature policy needs a timestamp. With None, Rest PKI Core picks the tier from the trusted roots (the ICP-Brasil or Lacuna Test tier) or else the default tier, and the signature fails with SecurityContextNotConfiguredForTimestamping when there is none
Ignore "revocation status unknown" validation failures	Accepts certificates whose revocation status can't be determined, in signatures, signature sessions and the Rest PKI signature and Open routes. Certificate authentication and signature inspection don't use it: they take their own ignoreRevocationStatusUnknown parameter, and certificate authentication, when the parameter is omitted, follows Ignore unknown revocation status by default in Settings > General settings

Editing and deleting

Click the name of a security context of the subscription to change it, then Save, or to Delete it. The standard security contexts open read-only.

warning

Rest PKI Core doesn't check whether a security context is in use before deleting it. After the deletion, calls that name it fail with SecurityContextNotFound, and signature sessions, two-step signatures and certificate authentications started with it fail when they complete. If it was the subscription's default, calls that name no security context fail too. Before deleting, make sure no application uses it, and choose another default if needed.

The default security context

To choose the security context used by calls that name none, go to Settings > General settings > Default security context on the dashboard. This needs the Manager or Admin role. Without a default, Rest PKI Core uses the instance's.

Through the API

The dashboard manages security contexts through api/security-contexts, which is not part of the API reference, and the client libraries have no methods for it. An application whose key has the Worker role, as most integrations do, can use any security context by its ID, but can't list, create or change them.

Moving from Rest PKI

The standard security contexts that Rest PKI has keep their IDs on Rest PKI Core, so code that names them works unchanged. A security context you created on Rest PKI is not carried over: create it again on Rest PKI Core and use its new ID. See Moving from Rest PKI.

See also

• Choosing roles
• Test certificates
• Signature inspection