MRSP 3.1: Issue #s 282 and 295: CP/CPS Documentation

[Ben Wilson]

All,

This thread begins discussion of proposed updates to the Mozilla Root Store Policy (MRSP) dealing with Certificate Policy/Certification Practice Statement (CP/CPS) Documentation. Throughout the MRSP, the term, “CP/CPS Documentation,” will replace the phrase “CP, CPS, or combined CP/CPS”.

Over time, CP/CPS documentation has increasingly relied on incorporation by reference to the Baseline Requirements, which seems to reduce visibility into CA-specific implementation details. Also, concerns have been expressed in community discussions (e.g. the 2025 Roundtable, dev-security-policy, and CCADB Public) regarding the level of detail provided in CP/CPS documentation. The proposed changes are intended to improve the extent to which CP/CPS documentation can be used to understand and evaluate a CA operator’s actual practices, rather than serve as a high-level, referential document.

The proposed changes primarily address the following GitHub issues:

• #295 – Revisions to MRSP 3.3
• #282 – Require Markdown/AsciiDoc for CP/CPS documentation

Here is comparison of proposed MRSP 3.1 (as of today) vs. current MRSP v. 3.0: https://github.com/mozilla/pkipolicy/compare/3b7d84f5c9708cf6be9655319825d60ea338eca4...ad8e1766be6e0e9a93a64b0b71506ae923086ec5.

Here is the working branch for MRSP v. 3.1 (working draft, subject to change):  https://github.com/BenWilson-Mozilla/pkipolicy/blob/3.1/rootstore/policy.md.

 

Overview of Proposed Changes

1. Sufficiency and Clarity of Disclosure -  #295

The current MRSP requires that CP/CPS documentation provide sufficient information to determine compliance. In practice, however, many CP/CPS documents have relied heavily on incorporation by reference (e.g., citing Baseline Requirements sections) without clearly describing how those requirements are satisfied with implementation.

The proposed changes clarify that CP/CPS documentation must describe the CA operator’s implementation of applicable requirements, not merely identify them.

Under this approach:

• 3.3.1  CP/CPS documentation is expected to provide CA-specific detail sufficient for a technically competent reviewer to understand how validation, issuance, revocation, and related processes are actually performed.
• 3.3.2  Incorporation by reference remains permissible for normative obligations and shared definitions, but it cannot substitute for disclosure of CA-specific practices.
• 3.3.3  Documentation must be explicit, bounded, and testable where feasible, enabling meaningful audit, review, and comparison across CA operators.
• 3.3.4  Reviewers should not be required to reconstruct operational practices by correlating multiple external documents.
• 3.3.5  CP/CPS documentation must contain or clearly reference certificate, CRL, and OCSP profiles (separate, versioned companion documents are allowed where appropriate).
• 3.3.6  CP/CPS documentation must reflect current operations with substantive changes traceable through version history and changelogs.

The intent is to make CP/CPS documentation a reliable and self-contained description of how a CA operates in practice, particularly in areas where the Baseline Requirements or other standards allow discretion.

2. Documentation Format and Versioning - #282

Also proposed (in Item 2 of MRSP 3.3) are requirements to maintain publicly accessible CP/CPS documentation in a structured, text-based format (e.g., Markdown, AsciiDoc, or similar), with version history.  It is proposed that the requirement to publish CP/CPS documentation on the CA operator’s website be removed, to allow for alternative publication models (e.g., version-controlled public repositories). CA operators may continue to publish PDF versions on their websites if they choose.

These edits are intended to promote CA operator consistency in how such documentation is maintained and published and to support more efficient review, comparison, and automation. Rather than prescribing a single tool or platform, the requirement focuses on characteristics: structured text, version control, and publicly accessible history.

Feedback on the proposed direction and draft language is welcome.

Thanks,
Ben Wilson
Mozilla Root Program

[Wayne]

Having read the comparison of proposed changes nothing jumps out as a stepback. Overall the changes seem to improve clarity, transparency, and are overall a step forward for the industry.

Thanks everyone for your hard work in getting us this far.

- Wayne

[Aaron Gable]

I concur, the changes related to CPS content seem good and don't seem onerous.

I have one minor concern: Section 3.3(2) says that CAs must keep their CP/CPS Documentation in markdown in a public repo, but doesn't say how the CA shall disclose the location of such. Linked from our website (as the current version of the requirements says)? Linked from our Repository? Disclosed in CCADB? Paragraph (7) of the same section does say that CAs shall "maintain links to all historical versions", but it doesn't say where, and my interpretation of that paragraph is that it is about preventing bit-rot (i.e. old links have to continue working).

Thanks,

Aaron

--
You received this message because you are subscribed to the Google Groups "dev-secur...@mozilla.org" group.
To unsubscribe from this group and stop receiving emails from it, send an email to dev-security-po...@mozilla.org.
To view this discussion visit https://groups.google.com/a/mozilla.org/d/msgid/dev-security-policy/d0ce4550-b3a1-4ec6-9bb1-6984ba7da030n%40mozilla.org.

[Ben Wilson]

Hi Aaron,

Thanks for these comments.  

You’re right that the draft hasn't explicitly addressed location of documentation disclosure and archiving.

One idea is to leverage the CCADB field “Document Repository” or to create an adjacent field to specify archival locations.

I am considering adding the following requirement to MRSP Section 3.3:

“CA operators MUST ensure that the location (URL) of their CP/CPS Documentation is disclosed and maintained in the CCADB 'Document Repository' field.”

However, that alone will be inadequate. We'll need to amend the CCADB Policy and/or provide guidance for use of the “Document Repository” field (and possibly add another field for archival locations) to clarify the use of the(se) field(s) and ensure uniformity and consistent implementation. For example:

“The ‘Document Repository’ field MUST contain one or more URLs that provide access to the CA Owner’s current CP/CPS Documentation. Where CP/CPS Documentation is maintained in a version-controlled repository, the URL MUST reference the repository or a stable landing page that clearly identifies the current version and provides access to prior versions or version history. CA Owners MUST ensure that this field is kept accurate and up to date.”

What are everyone's thoughts on this, and Is another CCADB field needed to point to the archival repository (even if they are both in the same location)?

Ben

[Ben Wilson]

What about this formulation of Item 2 under MRSP section 3.3?

2. CA operators MUST maintain CP/CPS Documentation in a structured, text-based format suitable for version control (e.g., Markdown, AsciiDoc, or equivalent), host such documentation in a publicly accessible repository or equivalent system that provides publicly accessible version history, and ensure that the current, publicly accessible locations (URLs) of that CP/CPS documentation are disclosed in, and kept up to date within, the CCADB “Document Repository” field.

Thanks,

Ben

[Aaron Gable]

I think that's much better. One potential issue: if a CA maintains a separate CP and CPS (I believe still acceptable in v3.1), they could be in different GitHub repositories. This would make disclosing a single URL in the "Document Repository" field difficult, as it could only point to one or the other.

[Roman Fischer]

I'm a bit confused: Does this mean that the disclosed location should be the repository (typically a webpage or github repo) where the current and the archived versions are listed or the URL of the current CP/CPS document (typically a Markdown file hosted somewhere) or an array of URLs of the current and previous versions of the CP/CPS document?

 

Thx
Roman

To view this discussion visit https://groups.google.com/a/mozilla.org/d/msgid/dev-security-policy/18857592-1c83-480d-a0b5-6e071c03969cn%40mozilla.org.

[Ben Wilson]

Hi Aaron and Roman,

Thanks for your feedback and questions. The CCADB has two fields implicated here:

• the “CA Document Repository” field, which identifies repository locations and may contain multiple URLs as a semicolon-separated list; and
• the “Document Link” field(s), which identify the specific URLs for the actual CP/CPS documents themselves.

Because the CCADB separately tracks the specific document URLs, I am considering emphasizing those specific document links over the "repository” concept. In other words, the CCADB still collects the repository location, which is a useful reference when browsing a CA operator’s website to locate related CP/CPS documentation, but I think it's less important from a filing/compliance perspective now that the CCADB stores direct document links separately.

I am currently considering abbreviating the language to something like:

“CA operators MUST ensure that CP/CPS Documentation is made publicly available in a structured, text-based format (e.g. Markdown, AsciiDoc, or equivalent) and in a manner that preserves publicly accessible version history. CA operators MUST ensure that the current location (URL) of each CP/CPS document is accurately disclosed and maintained within the CCADB.”

I’ve tried to avoid being overly prescriptive in order to preserve flexibility.   

What are your thoughts?  Will this approach adequately addresses your concerns, or should we take a different one? 

Also, are your concerns related to subsection 7 (document archiving)? Should that paragraph be edited too?

Thanks again,
Ben

To view this discussion visit https://groups.google.com/a/mozilla.org/d/msgid/dev-security-policy/ZR0P278MB0170793B0492FDC89EF045EDFA3D2%40ZR0P278MB0170.CHEP278.PROD.OUTLOOK.COM.

[Roman Fischer]

Hi Ben,

 

Your suggested wording makes the intention clear to me. And section 7 is also IMHO very clear and useful to ensure traceability over past versions of the documents.

 

Rgds
Roman

[Trevoli Ponds-White]

I like the updates Ben. I have a few comments

1) 3.3.3 Implementation Commitments" should probably have a further future date. This policy provides more clarity and people may want to edit their CP/CPS.

2) "multiple external documents." This could use some examples or additional clarity. For example Mozilla has a few places where CAs are required to "communicate to subscribers" this is generally done with the Subscriber Agreement not the CP/CPS. Is this saying we need to duplicate the text that is also in the Subscriber Agreement into the CP/CPS with some language like "we comply this with this by putting the following in the Subscriber Agreement..." or is that not considered an external document and instead some extension of the CP/CPS?

Thanks!

[Ben Wilson]

Hi Trev,

Thanks for your comments.  I have revised section 3.3 of the working draft to add an effective date of October 15, 2026, and also made other changes.

See https://github.com/BenWilson-Mozilla/pkipolicy/commit/c555615430fd188db394503baad6c62981e15aa8.

Thanks again,

Ben

To view this discussion visit https://groups.google.com/a/mozilla.org/d/msgid/dev-security-policy/5162792e-35b4-4d84-90a5-79560c9c3cc5n%40mozilla.org.

[Martijn Katerbarg]

Ben, 

While this is feedback we sent on the recent survey, I’ll repeat it here: For the effective date, is Mozilla willing to consider aligning with Apple’s policy update proposal, targeting July of 2027?

Both programs are making changes which will require extensive reviews across multiple CP/CPSes. As we know, incorrections in a CPS can have a large impact. As such, we worry that a “rush job” on this, is a recipe for disaster. Additionally, several CAs are also still working on making the documentation available in MarkDown format, and splitting our general CP/CPSes into purpose specific CP/CPSes. 

I feel a careful balance of gains verses risk management is warranted here, hence our request to align with the later date proposed by Apple. 

Regards,

Martijn

From: 'Ben Wilson' via dev-secur...@mozilla.org <dev-secur...@mozilla.org>
Date: Tuesday, 12 May 2026 at 22:05
To: Trevoli Ponds-White <trev...@amazon.com>
Cc: dev-secur...@mozilla.org <dev-secur...@mozilla.org>
Subject: Re: MRSP 3.1: Issue #s 282 and 295: CP/CPS Documentation

This Message Is From an External Sender

This message came from outside your organization.

Report Suspicious

 

To view this discussion visit https://groups.google.com/a/mozilla.org/d/msgid/dev-security-policy/CA%2B1gtaYOQAP73bpC6fTzm9n%3Dqa_-x%2BEJdhvG6RzP69bPKgw%3DKQ%40mail.gmail.com.

[Ben Wilson]

That's fine, too. I'll make that change.

[Trevoli Ponds-White]

That's fantastic Ben. Great suggestion Martijn I hadn't made that connection yet but definitely concur. For the documents reference what about adding this sentence:

"This excludes documents defined by or referenced in the Baseline Requirements for the applicable certificate type."

In practice this would mean for TLS certificates all these external references are allowable:

1. Any RFC, IANA, or NIST resource referenced in the applicable BRs.
2. Subscriber Agreement. Which is defined by in the BRs.
3. Relying Party Agreement. Which is referenced in the BRs. (We probably want to fix this in a cleanup ballot because in the BRs we refer to this like a defined term but it’s not defined.)
4. The CA/B Forum website.
5. WebTrust Principles and Critieria.
6. CA/B F recommended Github repos. Such as the Debian weak keys.
7. The links for TorProject, Fermat Attack, and Public Suffix List.

I'm don't know enough about what other types of external docs other CAs are referencing to know how restrictive this should be. In addition to referencing some of those listed above ours also includes a reference to a privacy policy and the policy pages for the root programs. 

[Roman Fischer]

To add to Trev's list, we have references to:

• Our webpage, document repository and the demo webpages
• CCADB
• ETSI

 

Regards
Roman

To view this discussion visit https://groups.google.com/a/mozilla.org/d/msgid/dev-security-policy/206640f0-2e8c-4eb9-ba96-d7031c5f5405n%40mozilla.org.

[Ben Wilson]

Greetings, 

In response to comments from Trev and Roman, I am editing section 3.3.2 (Normative References and Incorporation by Reference), which currently reads as follows:

To avoid duplication, divergence, and staleness, incorporation by reference SHOULD be used for shared definitions and externally defined normative requirements (e.g., CA/Browser Forum Requirements, RFCs, documents incorporated by reference therein, corresponding WebTrust or ETSI audit criteria, and other applicable policies).

However, incorporation by reference MUST NOT be used as a substitute for describing CA-specific implementation practices. CP/CPS Documentation MUST clearly identify incorporated documents.

CP/CPS Documentation MAY reference operational, contractual, informational, repository, or technical materials maintained outside the CP/CPS Documentation by the CA operator, Root Programs, the CCADB, standards bodies, or the CA/Browser Forum (e.g., webpages, Subscriber Agreements, validation procedures, or technical appendices), provided that:

• such materials are clearly identified and publicly accessible where necessary to understand the CA operator’s practices; their scope and applicability are clearly described;
• the CP/CPS Documentation remains sufficiently complete and coherent for a reviewer to understand how the CA operator complies with applicable requirements; and
• such references do not alter or supersede applicable requirements.

See https://github.com/BenWilson-Mozilla/pkipolicy/commit/03f638b283d71a0b163056c2998e50b5cb8c6658  (lines 255-364).

I'm open to further suggestions and refinements.

Ben

To view this discussion visit https://groups.google.com/a/mozilla.org/d/msgid/dev-security-policy/ZR0P278MB017085FF55FEECDB2C0795DBFA062%40ZR0P278MB0170.CHEP278.PROD.OUTLOOK.COM.

[Trevoli Ponds-White]

These changes are great Ben. Ship it!