MPI-Bremen / IT-Dept

Celsiusstr. 1 Bremen 28359 Germany mdoehle@mpi-bremen.de

This document defines the "company-certs" well-known URI in accordance with Request for Comments (RFC) 8615. The URI provides a JSON metadata document that allows an organization to publish application-specific trust anchors and related revocation information for use by consuming applications. The mechanism is intended for scoped trust bootstrapping, such as S/MIME, mutual TLS, or other application-local trust decisions, without modifying the global operating system trust store. Authority to publish such metadata is derived from successful validation of the HTTPS endpoint for the associated DNS domain. This specification does not provide an independent assessment of the trustworthiness of the published trust anchors beyond that domain control.

Introduction Organizations frequently operate private or application-specific Certification Authorities (CAs) for specialized purposes, including enterprise S/MIME, mutual TLS for APIs, device authentication, or internal service authentication. Distributing the corresponding trust anchors to external partners or isolated applications is often operationally complex. This document specifies a discovery mechanism that allows an organization to publish trust anchor metadata at a well-known HTTPS endpoint. The mechanism is intended to support application-scoped trust decisions and does not require installation of the discovered trust anchors into a system-wide trust store. This specification defines:

• a well-known URI suffix, "company-certs";
• a JSON metadata format;
• retrieval and validation rules for consuming clients; and
• security and privacy considerations for such trust bootstrapping.

This specification does not define:

• a mechanism for proving that a published private CA is globally trustworthy;
• a replacement for the Web PKI;
• a mechanism for modifying a client's operating system trust store; or
• a general-purpose certificate enrollment protocol.

Conventions and Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. The term "metadata document" refers to the JSON object retrieved from the "company-certs" well-known URI. The term "trust anchor" refers to a CA certificate or certification path material published for use by a consuming application under local policy. The term "usage context" refers to the intended application context for which a published trust anchor is applicable, such as "email_protection" or "client_authentication".

Protocol Overview An organization publishes a metadata document at its "company-certs" well-known URI. The metadata document identifies one or more trust anchors, the usage contexts in which they are intended to be used, optional constraints on their scope, and optional revocation endpoints. A consuming client retrieves the metadata document over HTTPS, validates the HTTPS connection according to local policy and this specification, processes the metadata, and may then retrieve the referenced certificate chain resources. Control over the DNS domain hosting the metadata document constitutes authority to publish trust anchor metadata for that domain under this specification. This authority is based on validated control of the HTTPS endpoint and does not constitute an independent attestation of the quality, security, or operational trustworthiness of the published CA infrastructure.

Well-Known URI The well-known URI suffix defined by this specification is "company-certs", in accordance with . For an origin whose authority is "example.org", the metadata document URI is:

The metadata document MUST be retrieved via HTTPS. Retrieval over HTTP MUST NOT be used.

Metadata Document

General Requirements The metadata document MUST be a JSON object encoded in UTF-8. The media type used to serve the document SHOULD be "application/json". The top-level object MUST contain the following members:

• "version"
• "authority_information"
• "trust_anchors"

The "version" member identifies the metadata format version and processing rules. This specification defines version 1.

Top-Level Members

version:

REQUIRED. Integer. For this specification, the value MUST be 1.

authority_information:

REQUIRED. Object. Contains descriptive information about the publishing authority.

trust_anchors:

REQUIRED. Array of one or more trust anchor objects.

authority_information Object The "authority_information" object contains the following members:

ca_name:

REQUIRED. String. A human-readable name for the publishing CA or trust authority. The value MUST be between 1 and 200 characters in length.

contacts:

OPTIONAL. Array of one or more contact strings. Each value SHOULD identify an operational or security contact, such as an email address. Duplicate values MUST NOT appear in the array.

trust_anchor Object Each element of the "trust_anchors" array is an object containing the following members:

usage_context:

REQUIRED. String. Identifies the application context for the published trust material. The value MUST match the token syntax defined in . Clients MUST ignore trust anchor objects whose "usage_context" value is not recognized.

certificate_chains:

REQUIRED. Array of one or more certificate chain objects as defined in .

constraints:

OPTIONAL. Object. Contains scoping constraints that limit the intended use of the published trust anchor. If present, the object MUST contain at least one member.

certificate_chain Object Each "certificate_chain" object contains the following members:

valid_from:

REQUIRED. String containing an date-time value. The time from which this chain is intended to be used.

valid_until:

REQUIRED. String containing an date-time value. The time after which this chain is no longer intended to be used. The value of "valid_from" MUST identify a point in time strictly earlier than the value of "valid_until".

ca_chain_url:

REQUIRED. Absolute HTTPS URI. Identifies a resource containing the certificate chain material. The URI MUST be same-origin with the metadata document URI.

chain_format:

REQUIRED. String. Identifies the encoding format of the certificate chain resource. For this specification, the value MUST be "pem_x509_chain".

crl_url:

OPTIONAL. Absolute URI for a Certificate Revocation List resource. Publishers SHOULD use an HTTPS URI.

ocsp_responder_url:

OPTIONAL. Absolute URI for an OCSP responder endpoint. Publishers SHOULD use an HTTPS URI.

sha256_fingerprint:

OPTIONAL. Hex-encoded SHA-256 fingerprint of the primary trust anchor certificate, encoded as a hexadecimal string of exactly 64 characters.

At least one of "crl_url" or "ocsp_responder_url" SHOULD be present. A publisher MAY provide both.

constraints Object The "constraints" object, if present, MUST contain at least one member. This specification defines the following members:

permitted_domains:

OPTIONAL. Array of one or more DNS host names. If present, these identify DNS domains for which the published trust anchor is intended to be used. Each value MUST be identical to, or a subdomain of, at least one DNS identifier present in the validated TLS certificate of the metadata document origin. Duplicate values MUST NOT appear in the array.

isolated_store_required:

OPTIONAL. Boolean. Indicates that the publisher expects the trust anchor to be used only in an application-isolated trust store and not to be installed into a global operating system trust store. This member expresses publisher intent. It does not create a technical enforcement mechanism on its own.

Future specifications may define additional constraint members.

Certificate Chain Resource A "ca_chain_url" resource with "chain_format" equal to "pem_x509_chain" MUST contain one or more PEM-encoded X.509 certificates . The certificates MUST be presented in certification path order, beginning with the most specific CA certificate intended for use by the client. The sequence MAY end with a self-signed root certificate. Consuming clients MUST be able to process a chain resource whether or not the final self-signed root certificate is included.

Example The following example illustrates a version 1 metadata document. Note that long URIs have been wrapped for readability only.

Client Processing Rules

HTTPS Validation A consuming client MUST retrieve the metadata document over HTTPS and MUST perform normal HTTPS server authentication and certificate validation for the origin from which the metadata document is retrieved. If HTTPS validation fails, the metadata document MUST be rejected.

Scope of Publisher Authority This specification derives publisher authority from successful validation of the HTTPS endpoint for the metadata document origin. If the "constraints.permitted_domains" member is present, each listed domain MUST be either identical to, or a subdomain of, at least one DNS identifier present in the validated TLS certificate for the metadata document origin. If this condition is not met, the client MUST reject the affected trust anchor object. This rule intentionally limits the scope that a publisher can assert through the metadata document based on demonstrated control of the endpoint's DNS namespace.

Retrieval of Certificate Chain Resources The value of "ca_chain_url" MUST be an absolute HTTPS URI. To reduce cross-origin trust ambiguity, "ca_chain_url" MUST be same-origin with the metadata document URI; that is, it MUST use the same scheme, host, and port as the metadata document. If a "ca_chain_url" does not satisfy this requirement, the client MUST reject that certificate chain object.

Use of Revocation Information If present, "crl_url" and "ocsp_responder_url" provide revocation information associated with the published chain . Publishers SHOULD use HTTPS for revocation resources when supported by their deployment environment. Clients MAY apply stricter local policy and refuse retrieval of revocation information over insecure transport. This document does not override revocation information embedded in certificates themselves. A client MAY use the metadata-provided revocation endpoints, the certificate-embedded endpoints, or both, according to local policy.

Selection Among Multiple Chains A client MAY encounter multiple "certificate_chain" entries for the same "usage_context". The client MUST ignore any chain whose current time is outside the inclusive interval defined by "valid_from" and "valid_until". If multiple chains remain applicable, the client SHOULD prefer the applicable chain with the most recent "valid_from" value, unless overridden by local policy.

Unknown or Unsupported Values If a client encounters a "usage_context" value that it does not support, it MUST ignore the corresponding trust anchor object. If the metadata "version" value is not understood by the client, the client MUST reject the metadata document.

Initial Usage Context Values This specification defines the following initial "usage_context" values. Each value MUST match the token syntax pattern:

email_protection:

Trust anchor intended for S/MIME or comparable email protection use cases.

client_authentication:

Trust anchor intended for validating client certificates, such as mutual TLS client authentication.

server_authentication:

Trust anchor intended for validating server certificates in a scoped application-specific context.

Additional values may be registered in the IANA registry defined in .

Security Considerations The security of this mechanism depends primarily on correct HTTPS validation for the metadata document endpoint and on the consuming application's correct enforcement of scope and isolation rules. Control over the publishing DNS domain is sufficient to publish trust anchor metadata for that domain under this specification. Therefore, compromise of the domain, DNS resolution path, hosting environment, content delivery path, or HTTPS private key may allow an attacker to publish malicious trust anchors. This specification does not provide an independent trust assessment of the published CA hierarchy beyond demonstrated control of the publishing domain. Clients MUST treat discovered trust anchors as application-scoped trust material and MUST NOT automatically install them into a global system trust store solely on the basis of this metadata document. If "isolated_store_required" is present and set to true, clients that cannot honor such isolation SHOULD reject the corresponding trust anchor object. Implementations SHOULD protect against replay and stale metadata. Clients SHOULD apply ordinary HTTP caching controls conservatively and SHOULD revalidate metadata periodically. Clients MAY impose maximum metadata freshness intervals by local policy. Publishers SHOULD avoid weak signature algorithms and weak key sizes in published trust anchor material. Clients MAY reject certificates or chains that do not satisfy local cryptographic policy. The first successful retrieval of metadata remains a trust bootstrap event. Implementers should recognize that this event is sensitive to endpoint compromise and other active attacks against the publishing origin.

Privacy Considerations Retrieval of the metadata document may reveal that a client is interested in a particular organization's trust infrastructure or application relationship. Retrieval of usage-specific chain or revocation resources may further reveal intended application behavior, such as email protection or client authentication. Publishers and consumers SHOULD minimize unnecessary identifying information in requests and responses. Consumers SHOULD avoid excessive polling and SHOULD apply data minimization principles where possible.

IANA Considerations

Well-Known URI Registration IANA is requested to register the "company-certs" well-known URI in the "Well-Known URIs" registry in accordance with RFC 8615 .

URI suffix:

company-certs

Change controller:

IETF

Specification document:

[this document]

Company-Certs Usage Contexts Registry IANA is requested to create a new registry titled "Company-Certs Usage Contexts".

Registration policy:

Specification Required

Initial registry contents:

Value	Description
email_protection	Application-specific email trust
client_authentication	Application-specific client cert trust
server_authentication	Application-specific server cert trust

Normative References Informative References Postman

JSON Schema for Version 1 Metadata Documents This appendix provides a normative JSON Schema for version 1 metadata documents as defined in Section 5 of this specification. A metadata document that validates successfully against this schema satisfies the structural requirements of this specification. Successful schema validation does not, however, imply that all processing rules defined in are satisfied. The schema is expressed using JSON Schema Draft 2020-12 .

Schema Limitations The following requirements defined in this specification cannot be expressed within the JSON Schema above and MUST be enforced by consuming applications independently:

a)

Temporal ordering: "valid_from" MUST identify a point in time strictly earlier than "valid_until". A schema validator will accept any two syntactically valid date-time strings regardless of their relative order.

b)

Same-origin enforcement: "ca_chain_url" MUST be same-origin with the metadata document URI. JSON Schema cannot evaluate the retrieval context of a document.

c)

TLS SAN coverage: If "constraints.permitted_domains" is present, each listed domain MUST be identical to, or a subdomain of, at least one DNS identifier present in the validated TLS certificate of the metadata document origin. This requires access to the TLS session context, which is outside the scope of JSON Schema validation.

d)

Version rejection: If the "version" value is not understood, the metadata document MUST be rejected. A schema validator using "const": 1 will reject documents with other version values, but consuming applications MUST NOT rely solely on schema validation for this check.

e)

Chain selection: When multiple "certificate_chain" entries are present for the same "usage_context", the selection rules defined in MUST be applied by the consuming application.