diff --git a/.github/ISSUE_TEMPLATE/audit-submission.md b/.github/ISSUE_TEMPLATE/audit-submission.md new file mode 100644 index 0000000..090680d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/audit-submission.md @@ -0,0 +1,54 @@ +--- +name: Audit submission +about: Use this template to notify the Program team of an audit update, provide attestation wording and CCADB actions, and link the related PR. +title: "[Audit] {CA name} - Audit submission - {YYYY-MM-DD}" +labels: audit, triage +assignees: msroot@microsoft.com +--- + +## Summary +- Short summary of the audit update and the certificates/roots affected (e.g., "Annual WebTrust update for Root CA X"). + +## Affected sections / files +- Which `Requirements.md` section(s) or other files are affected (e.g., `Requirements.md` Section 4.1). + +## Audit type +- [ ] WebTrust +- [ ] ETSI +- [ ] Equivalent (describe) + +## Attestation wording (required) +- Provide exact wording for the attestation or the attestation letter text you expect auditors to provide. Example: + > "This change updates the Audit Requirements in Section 4.1 to require [X]. Rationale: aligns with EN 319 411-2 updates. Reference: https://aka.ms/auditreqs." + +## Attachments / Public URLs +- Attach or link to a **searchable PDF** attestation letter hosted on a public site (do NOT upload private audit PDFs into this repo). Provide the URL(s) and the auditor's published page if available. + +## CCADB actions required +- Describe required CCADB updates (audit upload, attestation metadata, which fields to set) and who will perform them. + +## Auditor contact +- Auditor name, organization, and email (for Microsoft verification contact). + +## Changelog entry (proposed) +- Proposed `Changelog.md` line (version | YYYY-MM-DD | Short summary): + | 1.x | YYYY-MM-DD | Short summary: "Updated Audit Requirements in Section 4.1" | + +## Timelines +- Expected dates for auditor confirmation, CCADB upload, and Program sign-off. + +## Related PR / Issue +- Link the PR that implements the text change and any related issues here (include PR number once created). + +## Checklist +- [ ] Exact attestation wording is provided +- [ ] Searchable attestation PDF is publicly accessible and linked above +- [ ] CCADB actions are documented and an owner is named +- [ ] Program team (`msroot@microsoft.com`) is requested for sign-off +- [ ] A PR is opened and linked to this issue and includes the proposed changelog line + +## Additional notes +- Any other context, roll-forward plans, or follow-up tasks. + +--- +*Note: This template collects public attestation metadata only. For private correspondence or files, contact the Program team via email (msroot@microsoft.com).* \ No newline at end of file diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..1b9da50 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,98 @@ +# Copilot instructions for Microsoft Root Program requirements repository + +Purpose +- This repository is the single source-of-truth for the Microsoft Trusted Root Program requirements. The authoritative policy text lives in `Requirements.md`; `README.md` explains the repo structure and `Changelog.md` tracks published versions. + +Quick orientation (what to read first) +1. Read `README.md` to understand the project intent and update process. +2. Read `Requirements.md` top-to-bottom to understand the policy language, sectioning, and normative statements. +3. Inspect `Changelog.md` for how versions are recorded and sample entries. + +Primary workflows an agent should follow +- Changes are made via GitHub pull requests. Create a single PR that updates the policy text and any supporting artifacts (changelog, templates). +- Every normative change must include: the exact text change, a short rationale, relevant external references (links to CAB Forum, WebTrust/ETSI, CCADB pages, or aka.ms docs), and a changelog entry. +- For policy changes that affect audit or program behavior, add the Program contact in the PR description and include a request for explicit Program-team sign-off: msroot@microsoft.com. + +Repository conventions and style (concrete, discoverable rules) +- Maintain the existing numbered section style (e.g., 3.1.1, 3.1.2). Insert new clauses by appending the next number in the same subsection. +- Preserve the `[TOC]` placeholder at the top of `Requirements.md` and keep the main headings (Introduction, Program Participation, Program Technical Requirements, Audit requirements). +- Use Markdown tables for enumerations (e.g., OID lists, key size tables). When adding a new row, match the existing header and column alignment. +- Write normative statements succinctly and in active voice. Avoid speculative or aspirational wording; the repo contains discoverable, enforceable rules. + +Examples (copy/paste-ready) +- Add a new OID row to the OID table in `Requirements.md`: + + | Policy | OID | + | --- | --- | + | New Policy Example | 1.2.3.4.5.6 | + +- Changelog entry example (append to `Changelog.md`): + | 1.1 | YYYY-MM-DD | Short summary: "Added requirement X to Section 3.1" | + +PR checklist (what must be present before merging) +- [ ] Updated `Requirements.md` with the final wording and section number(s) +- [ ] Added or updated `Changelog.md` with version, date, and short summary +- [ ] Provided a short rationale and authoritative reference link(s) in the PR body +- [ ] Marked Program-team reviewers and, for program-affecting changes, requested msroot@microsoft.com sign-off +- [ ] Verified Markdown renders correctly locally (preview links and tables) + +Integration points and external systems to be aware of +- CCADB: audit attestations and PKI disclosures live outside this repo. Changes that affect CCADB-related processes should include instructions / links pointing to CCADB guidance (https://ccadb.org). +- Audit references (WebTrust / ETSI) and `aka.ms` link targets should be kept current; update links when authoritative URLs change. + +Compliance & Audit (mandatory steps for audit-related changes) +- If a change affects Audit Requirements, include a clear summary of the **audit impact** in the PR body and the proposed text change in `Requirements.md`. +- Required attachments and checks for audit-affecting PRs: + - State whether the change requires a new or updated Qualifying Audit and which standard applies (WebTrust, ETSI, or Equivalent Audit). + - If CCADB actions are required, describe the exact CCADB updates (audit upload, attestation entries) and the responsible party. + - Provide exact attestation wording examples (e.g., "This change updates the Audit Requirements in Section 4.1 to require [X]. Rationale: aligns with EN 319 411-2 updates. Reference: https://aka.ms/auditreqs.") + - Add explicit next steps and timelines (who will contact CCADB/auditor and expected timing). +- Program-team sign-off: **msroot@microsoft.com** must be included as a reviewer for all audit-affecting PRs. +- Use the **Audit submission** issue template (`.github/ISSUE_TEMPLATE/audit-submission.md`) to notify the Program team, capture attestation wording and CCADB actions, and link the resulting issue number in your PR. See example workflow in `.github/examples/example-audit-issue.md` and `.github/examples/example-audit-pr.md` for a filled sample of the issue + PR flow. + +What NOT to do (discovered constraints) +- Do not add operational or private audit artifacts (PDFs, attestations) into this repo — audit artifacts are managed externally via CCADB or the CA/auditor workflows. +- Do not change contact email addresses or contract-level language without Program-team approval. + +When in doubt +- If a change could materially affect how CAs operate or how Microsoft products trust certificates, flag the PR as requiring Program-team sign-off and include msroot@microsoft.com in the request. + +Feedback +- If anything here is unclear or missing, leave a comment on this PR or open an issue and tag the repository owners so we can iterate on these instructions. + +PR templates & examples +- **Sample PR titles**: + - `REQ: Update Section 3.1.6 Key Usage wording — rationale: clarify OCSP signing` + - `ADD: New OID 1.2.3.4.5.6 — Section 3.1.15` + - `CHG: Relax RSA key-size wording in Section 3.1.20 (audit: WebTrust change)` + +- **PR body template (copy/paste)**: + ``` + Summary: + - Short summary of change and the exact section(s) modified (e.g., 3.1.20). + + Rationale: + - One or two sentences explaining why this change is required. + + References: + - Links to authoritative sources (CABForum, WebTrust, ETSI, CCADB, aka.ms links). + + Changelog: + - Proposed Changelog.md entry line (version | YYYY-MM-DD | Short summary). + + Program reviewers: + - List Program-team contacts (e.g., msroot@microsoft.com) if the change affects audit, trust, or operations. + ``` + +- **Audit-update wording example**: + - `This change updates the Audit Requirements in Section 4.1 to require [X]. Rationale: aligns with EN 319 411-2 updates. Reference: https://aka.ms/auditreqs.` + +- **Changelog example (append exactly as a table row)**: + | 1.1 | YYYY-MM-DD | Short summary: "Added requirement X to Section 3.1" | + +Notes & verification +- Always preview Markdown locally (GitHub rendering) and verify table alignment. +- If the change affects external systems (CCADB, WebTrust filings), include explicit next-steps in PR (who will contact CCADB/auditor, expected timing). + +--- +(Generated: guidance to help AI agents be productive in this docs-first repository) \ No newline at end of file diff --git a/.github/examples/example-audit-issue.md b/.github/examples/example-audit-issue.md new file mode 100644 index 0000000..bc8adb7 --- /dev/null +++ b/.github/examples/example-audit-issue.md @@ -0,0 +1,45 @@ +# Example: Audit submission (filled) + +Title: [Audit] Contoso CA - Audit submission - 2025-12-22 + +## Summary +- Annual WebTrust audit update for Contoso Root CA (SHA256: ABCDEF...) + +## Affected sections / files +- `Requirements.md`: Section 4.1 (Audit Requirements) + +## Audit type +- [x] WebTrust + +## Attestation wording (required) +- "This change updates the Audit Requirements in Section 4.1 to require explicit WebTrust attestations for server authentication EKUs. Rationale: aligns with EN 319 411-2 updates. Reference: https://aka.ms/auditreqs." + +## Attachments / Public URLs +- Public attestation: https://auditor.example.org/contoso-audit-2025.pdf + +## CCADB actions required +- Upload attestation to CCADB under Contoso CA entry; add SHA256 thumbprint and date. Owner: Contoso PKI team (pki@contoso.com). + +## Auditor contact +- Jane Doe, AuditorOrg, jane.doe@auditor.example.org + +## Changelog entry (proposed) +| 1.1 | 2025-12-22 | Updated Audit Requirements in Section 4.1 to require WebTrust attestation for server authentication EKU | + +## Timelines +- Auditor confirmation: 2025-12-24 +- CCADB upload: 2025-12-26 +- Program sign-off requested: 2026-01-02 + +## Related PR / Issue +- PR: #123 (link once PR is created) + +## Checklist +- [x] Exact attestation wording is provided +- [x] Searchable attestation PDF is publicly accessible and linked above +- [x] CCADB actions are documented and an owner is named +- [x] Program team (`msroot@microsoft.com`) is requested for sign-off +- [ ] A PR is opened and linked to this issue and includes the proposed changelog line + +--- +*This is a sample to illustrate required fields; do not upload private documents to the repo.* \ No newline at end of file diff --git a/.github/examples/example-audit-pr.md b/.github/examples/example-audit-pr.md new file mode 100644 index 0000000..ccd4643 --- /dev/null +++ b/.github/examples/example-audit-pr.md @@ -0,0 +1,40 @@ +# Example PR: Update Audit Requirements (filled) + +**Title:** REQ: Update Section 4.1 Audit Requirements — require explicit WebTrust attestation for server authentication EKU + +## Summary +- Updated `Requirements.md` Section 4.1 to require explicit WebTrust attestation language for server authentication EKU. + +## Rationale +- Aligns Microsoft Audit Requirements with recent clarifications in EN 319 411-2 and ensures consistency with CCADB automation parsing requirements. + +## Changes +- `Requirements.md`: Section 4.1 — added clause that specifies the required attestation wording and upload process. +- `Changelog.md`: appended a row proposing the change. + +## References +- EN 319 411-2: https://www.etsi.org +- https://aka.ms/auditreqs + +## Changelog entry +| 1.1 | 2025-12-22 | Updated Audit Requirements in Section 4.1 to require WebTrust attestation for server authentication EKU | + +## Program reviewers & sign-off +- Added `msroot@microsoft.com` as a reviewer and requested explicit sign-off. + +## Compliance checklist +- [x] This change affects Audit Requirements; WebTrust selected +- [x] Proposed attestation wording included in the PR body +- [x] CCADB actions documented in related issue #456 (example) +- [x] Timelines added and owner named +- [x] Audit submission issue opened: #456 + +## Checklist +- [x] Updated `Requirements.md` with the final wording and section number(s) +- [x] Added or updated `Changelog.md` with version, date, and short summary +- [x] Provided a short rationale and authoritative reference link(s) in the PR body +- [x] Marked Program-team reviewers and requested `msroot@microsoft.com` sign-off +- [x] Verified Markdown renders correctly (preview) and tables align + +--- +*This PR is an example to demonstrate the expected fields and approach for audit-related changes.* \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..cd67410 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,36 @@ +## Summary +- Short summary of the change and the exact section(s) modified (e.g., “Updated Section 3.1.6: Key Usage wording”). + +## Rationale +- One or two sentences explaining why the change is required (policy update, audit alignment, editorial fix, etc.). + +## Changes +- Bullet list of files modified (e.g., `Requirements.md`: Section 3.1.6 updated). + +## References +- Links to authoritative sources (CABForum, WebTrust/ETSI, CCADB, aka.ms links). + +## Changelog entry +- Proposed `Changelog.md` line (version | YYYY-MM-DD | Short summary): + | 1.x | YYYY-MM-DD | Short summary: "..." | + +## Program reviewers & sign-off +- If this change affects audit, trust, or program behavior, **@msroot@microsoft.com** must be added as a reviewer and explicit sign-off requested. + +## Compliance checklist (audit-related PRs) +- [ ] Does this change affect Audit Requirements? If yes, indicate which standard applies: WebTrust / ETSI / Equivalent. +- [ ] Have you included proposed attestation wording or the text required for auditors? +- [ ] Have you documented any CCADB actions required (upload, attestation metadata) and who will perform them? +- [ ] Have you added timelines for auditor/CCADB contact and expected completion dates? +- [ ] Did you add `msroot@microsoft.com` as a reviewer and request explicit Program sign-off? +- [ ] Opened an Audit submission issue using `.github/ISSUE_TEMPLATE/audit-submission.md` and linked it here (issue #...) + +## Checklist +- [ ] Updated `Requirements.md` with the final wording and section number(s) +- [ ] Added or updated `Changelog.md` with version, date, and short summary +- [ ] Provided a short rationale and authoritative reference link(s) in the PR body +- [ ] Marked Program-team reviewers and requested `msroot@microsoft.com` sign-off if policy- or audit-affecting +- [ ] Verified Markdown renders correctly (preview) and tables align + +--- +*Tip: Use PR titles following the pattern `REQ:`, `ADD:`, or `CHG:` (e.g., `REQ: Update Section 3.1.6 Key Usage wording`).* \ No newline at end of file diff --git a/Changelog.md b/Changelog.md index 331f031..7545b6b 100644 --- a/Changelog.md +++ b/Changelog.md @@ -1,4 +1,4 @@ | Version | Date Effective | Notes | |--------|-----|-----------| | 1.0 | October 13, 2025 | First update on TRP Github. No changes to current program requirements, but this version supercedes current requirements on learn.microsoft.com. | -| 1.1 | November 21, 2025 | Updates include changes to require compliance with CA/B Forum Guidelines and CCADB Guidelines, clarification on Microsoft issuing exceptions to the BRs and required prior notice on CP/CPS changes | +| 1.1 | November 21, 2025 | Updates include changes to require compliance with CA/B Forum Guidelines and CCADB Guidelines, clarification on Microsoft issuing exceptions to the BRs and required prior notice on CP/CPS changes || 1.2 | 2025-12-22 | Added contributor guidance, PR & issue templates, and audit submission examples. | \ No newline at end of file diff --git a/Requirements.md b/Requirements.md index b69f90b..6cc0781 100644 --- a/Requirements.md +++ b/Requirements.md @@ -222,6 +222,8 @@ To submit annual audits, refer to the CCADB instructions on how to create an aud If the CA is applying into the Root Store and isn't in the CCADB, they should email their audit attestation to msroot\@microsoft.com. +Note: For changes that affect Server Authentication EKU or other audit-sensitive clauses, include exact attestation wording in the PR (see `.github/ISSUE_TEMPLATE/audit-submission.md`), describe required CCADB actions, and link the related Audit submission issue in the PR body. Program-team sign-off (msroot@microsoft.com) is required for audit-affecting changes. + ## 4.2 Acceptable Audit Standards The Program accepts two types of audit standards: WebTrust and ETSI. For each of the EKUs on the left, Microsoft requires an audit that conforms to the standard marked.