Skip to content

Public CA Issued Server TLS Certificates with Directory Allowlist

This document defines the requirements and verification process for TLS server certificates used by Members of the Trust Framework when those certificates are issued by a public Certificate Authority (CA).

The Trust Framework uses a centrally managed allowlist of DNS names to restrict access to Member servers. This list is published and maintained by the Directory.

Server Certificates

Servers operated by Members must present an X.509 certificate issued by a publicly trusted CA.

The certificate must:

  • Include the DNS name of the server in the Subject Alternative Name (SAN).
  • Match exactly one DNS name (wildcard certificates are prohibited).
  • Be valid according to the current system time.
  • Have a certificate chain that terminates in a root CA trusted by major public trust stores.

The server operator is responsible for acquiring and renewing their certificate from a publicly trusted CA of their choice.

Allowlist

To enable clients to restrict connections to servers operated by Members of the Trust Framework, the Directory maintains an authoritative allowlist of DNS names.

The allowlist is available at a stable, Directory-hosted URL. This URL:

  • Is discovered by logging into the Directory’s user interface. The user can generate URLs for the entire Trust Framework or for a specific Scheme.
  • Does not change, and may be hard coded in service implementations.

The allowlist is a JSON object with the properties:

ib1:allowlist (string)
Allowlist version, currently "1.0"
allowlistFor (string)
The identifier (URL) of the Trust Framework or Scheme.
lastUpdated (ISO 8601 UTC timestamp as a string)
The time and date of the last update to the allowlist.
allowed (array of strings)
A list of fully-qualified DNS names that are permitted for trusted connections.

Example allowlist

{
  "ib1:allowlist": "1.0",
  "allowlistFor": "https://registry.core.trust.ib1.org/trust-framework",
  "lastUpdated": "2024-09-16T15:32:56Z",
  "allowed": [
      "server1.member.org",
      "api.member2.org",
      "service.member3.net"
  ]
}

Cache Control

The allowlist response includes HTTP cache control headers that must be strictly respected by clients:

  • Clients must not refresh the allowlist more frequently than allowed by the Cache-Control: max-age directive.
  • Clients must refresh the allowlist after the max-age period expires.
  • Clients must support ETag and If-None-Match to optimize revalidation and minimize unnecessary downloads.

Example response headers:

Cache-Control: max-age=3600
ETag: "abc123"

Error Handling on Fetch Failure

If a client attempts to fetch the allowlist and encounters an error (e.g., network failure, HTTP 5xx error, invalid response):

  • The client must continue using the last successfully fetched version of the resource, even if it has exceeded the max-age period.
  • The client must retry fetching the resource periodically, with a reasonable retry schedule, until a valid, fresh copy is obtained.
  • If no valid version of the resource has ever been fetched (e.g., first-time fetch fails), the client must reject connections to servers.

Validation by clients

Clients must:

  • Attempt to fetch the allowlist for each transaction (in most cases, this fetch will be served from a locally cached copy in accordance with HTTP caching rules without connecting to the Directory.)
  • Validate that the SAN DNS name in the certificate exactly matches a DNS name in the allowlist (case-insensitive comparison as specified in RFC 6125, Section 6.4.1 and 6.4.2).
    • Subdomains of allowed DNS names are not implicitly trusted. Each DNS name must be explicitly listed in the allowlist to be valid for connection.
  • Reject wildcard certificates.
  • Support both Certificate Revocation List (CRL) and Online Certificate Status Protocol (OCSP) checking. For each certificate in the chain, the client must perform revocation checking using one of the methods indicated in the certificate's extensions. Revocation checking is mandatory for all certificates in the chain.
  • Only allow HTTP redirects to the same hostname and URL scheme.
  • Log an event whenever a server's hostname is not present in the allowlist and the connection is rejected as a result.