Internet-Draft Company-Certs Discovery July 2026
Doehle Expires 23 January 2027 [Page]
Workgroup:
Network Working Group
Internet-Draft:
draft-doehle-company-certs-discovery-00
Published:
Intended Status:
Standards Track
Expires:
Author:
M. Doehle
MPI-Bremen / IT-Dept

A Well-Known URI for Discovery of Application-Specific Trust Anchors

Abstract

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.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 23 January 2027.

▲

Table of Contents

1. 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:

This specification does not define:

2. 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 [RFC2119] [RFC8174] 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".

3. 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.

4. Well-Known URI

The well-known URI suffix defined by this specification is "company-certs", in accordance with [RFC8615].

For an origin whose authority is "example.org", the metadata document URI is:

https://example.org/.well-known/company-certs

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

5. Metadata Document

5.1. General Requirements

The metadata document MUST be a JSON object [RFC8259] 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.

5.2. 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.

5.3. 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.

5.4. 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 Section 7. 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 Section 5.5.
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.

5.5. certificate_chain Object

Each "certificate_chain" object contains the following members:

valid_from:
REQUIRED. String containing an [RFC3339] date-time value. The time from which this chain is intended to be used.
valid_until:
REQUIRED. String containing an [RFC3339] 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.

5.6. 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.

5.7. 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 [RFC5280].

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.

5.8. Example

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

{
  "version": 1,
  "authority_information": {
    "ca_name": "Example Company Root CA",
    "contacts": ["security@example.org"]
  },
  "trust_anchors": [
    {
      "usage_context": "email_protection",
      "certificate_chains": [
        {
          "valid_from": "2026-01-01T00:00:00Z",
          "valid_until": "2031-01-01T00:00:00Z",
          "ca_chain_url": "https://example.org/.well-known/\
company-certs/certs/smime-chain-v2.pem",
          "chain_format": "pem_x509_chain",
          "crl_url": "https://example.org/.well-known/\
company-certs/certs/smime-v2.crl",
          "ocsp_responder_url": "https://example.org/ocsp/smime"
        },
        {
          "valid_from": "2021-01-01T00:00:00Z",
          "valid_until": "2026-06-01T00:00:00Z",
          "ca_chain_url": "https://example.org/.well-known/\
company-certs/certs/smime-chain-v1.pem",
          "chain_format": "pem_x509_chain",
          "crl_url": "https://example.org/.well-known/\
company-certs/certs/smime-v1.crl"
        }
      ],
      "constraints": {
        "permitted_domains": ["example.org", "sub.example.org"],
        "isolated_store_required": true
      }
    }
  ]
}

6. Client Processing Rules

6.1. 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.

6.2. 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.

6.3. 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.

6.4. Use of Revocation Information

If present, "crl_url" and "ocsp_responder_url" provide revocation information associated with the published chain [RFC6960].

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.

6.5. 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.

6.6. 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.

7. Initial Usage Context Values

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

^[a-z][a-z0-9_-]{0,63}$
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 Section 10.2.

8. 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.

9. 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.

10. IANA Considerations

10.1. 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 [RFC8615].

URI suffix:

company-certs

Change controller:

IETF

Specification document:

[this document]

10.2. 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:

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

11. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC3339]
Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, , <https://www.rfc-editor.org/info/rfc3339>.
[RFC5280]
Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, , <https://www.rfc-editor.org/info/rfc5280>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC8259]
Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, , <https://www.rfc-editor.org/info/rfc8259>.
[RFC8615]
Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, , <https://www.rfc-editor.org/info/rfc8615>.

12. Informative References

[I-D.bhutton-json-schema]
Wright, A., Andrews, H., Hutton, B., and G. Dennis, "JSON Schema: A Media Type for Describing JSON Documents", Work in Progress, Internet-Draft, draft-bhutton-json-schema-01, , <https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-01>.
[RFC6960]
Santesson, S., Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. Adams, "X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSP", RFC 6960, DOI 10.17487/RFC6960, , <https://www.rfc-editor.org/info/rfc6960>.

Appendix A. JSON Schema for Version 1 Metadata Documents

This appendix provides a normative JSON Schema [I-D.bhutton-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 Section 6 are satisfied. The schema is expressed using JSON Schema Draft 2020-12 [I-D.bhutton-json-schema].

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:ietf:params:json-schema:company-certs-metadata",
  "title": "Company-Certs Metadata Schema",
  "type": "object",
  "required": [
    "version",
    "authority_information",
    "trust_anchors"
  ],
  "additionalProperties": false,
  "properties": {
    "version": {
      "type": "integer",
      "const": 1,
      "description":
        "Metadata format version. This specification defines"
        " version 1."
    },
    "authority_information": {
      "$ref": "#/$defs/authority_information"
    },
    "trust_anchors": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/trust_anchor"
      }
    }
  },
  "$defs": {
    "authority_information": {
      "type": "object",
      "required": [
        "ca_name"
      ],
      "additionalProperties": false,
      "properties": {
        "ca_name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description":
            "Human-readable name of the publishing CA or trust"
            " authority."
        },
        "contacts": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "format": "email"
          },
          "description":
            "Optional operational or security contacts. Each"
            " value SHOULD identify an email address."
        }
      }
    },
    "trust_anchor": {
      "type": "object",
      "required": [
        "usage_context",
        "certificate_chains"
      ],
      "additionalProperties": false,
      "properties": {
        "usage_context": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_\\-]{0,63}$",
          "description":
            "Application context token. Values are registered in"
            " the IANA Company-Certs Usage Contexts registry"
            " defined in Section 10.2. Unrecognized values MUST"
            " be ignored by the consuming client."
        },
        "certificate_chains": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/certificate_chain"
          }
        },
        "constraints": {
          "$ref": "#/$defs/constraints"
        }
      }
    },
    "certificate_chain": {
      "type": "object",
      "required": [
        "valid_from",
        "valid_until",
        "ca_chain_url",
        "chain_format"
      ],
      "additionalProperties": false,
      "properties": {
        "valid_from": {
          "type": "string",
          "format": "date-time",
          "description":
            "RFC 3339 date-time value indicating start of window"
            " for this chain. MUST be earlier than valid_until."
        },
        "valid_until": {
          "type": "string",
          "format": "date-time",
          "description":
            "RFC 3339 date-time value indicating end of intended"
            " window for this chain. MUST be later than valid_from."
        },
        "ca_chain_url": {
          "type": "string",
          "format": "uri",
          "pattern": "^https://",
          "description":
            "Absolute HTTPS URI for certificate chain resource."
            " MUST be same-origin with metadata document URI."
        },
        "chain_format": {
          "type": "string",
          "enum": [
            "pem_x509_chain"
          ],
          "description":
            "Encoding format of certificate chain resource. Value"
            " 'pem_x509_chain' denotes PEM-encoded X.509 certs in"
            " path order, starting with specific CA cert."
        },
        "crl_url": {
          "type": "string",
          "format": "uri",
          "description":
            "Optional URI for CRL resource. Publishers SHOULD"
            " use HTTPS URI."
        },
        "ocsp_responder_url": {
          "type": "string",
          "format": "uri",
          "description":
            "Optional URI for OCSP responder endpoint. Publishers"
            " SHOULD use HTTPS URI."
        },
        "sha256_fingerprint": {
          "type": "string",
          "pattern": "^[A-Fa-f0-9]{64}$",
          "description":
            "Optional SHA-256 fingerprint of primary trust anchor"
            " certificate, encoded as hex string of 64 chars."
        }
      }
    },
    "constraints": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": false,
      "properties": {
        "permitted_domains": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "format": "hostname"
          },
          "description":
            "DNS domains for which trust anchor is intended to be"
            " used. Each value MUST be identical to or subdomain of"
            " origin TLS SANs."
        },
        "isolated_store_required": {
          "type": "boolean",
          "description":
            "Publisher intent that trust anchor be used only in"
            " application-isolated store and not installed into"
            " global OS trust store."
        }
      }
    }
  }
}

A.1. 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 Section 6.5 MUST be applied by the consuming application.

Author's Address

M. Doehle
MPI-Bremen / IT-Dept
Celsiusstr. 1
28359 Bremen
Germany