Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

(Draft Ballot) EV Guidelines Agency Disclosure #11

Closed
wants to merge 7 commits into from

Conversation

sleevi
Copy link
Owner

@sleevi sleevi commented Apr 1, 2020

Formal Ballot now at cabforum#194

docs/EVG.md Outdated Show resolved Hide resolved
docs/EVG.md Outdated Show resolved Hide resolved
docs/EVG.md Outdated Show resolved Hide resolved
docs/EVG.md Outdated Show resolved Hide resolved
docs/EVG.md Outdated Show resolved Hide resolved
docs/EVG.md Outdated Show resolved Hide resolved
docs/EVG.md Outdated Show resolved Hide resolved
docs/EVG.md Outdated Show resolved Hide resolved
docs/EVG.md Outdated Show resolved Hide resolved
@BenWilson-Mozilla
Copy link

Mozilla will endorse a ballot for these proposed changes to the EV Guidelines.

@sleevi sleevi force-pushed the 2020-03-02-EVG-Jurisdiction branch from 0e941ef to 0383db7 Compare June 9, 2020 17:15
sleevi and others added 7 commits June 16, 2020 18:33
Based on discussions on the 2020-02-27 Validation Subcommittee call,
this attempts to put in a basic requirement that the CA document
publicly what sources they use as a Registration Agency or
Incorporating Agency.

It is meant to be lightweight, while providing suitable transparency,
by merely requiring public documentation be made available what
source(s) will be used and what the allowed value(s) are for those
sources. The CA is not required to place this information in their
CP/CPS, but is required to place a pointer to this information so that
it can be discovered. Further, the CA is required to provide a basic
changelog that MUST minimally include a version and date, to avoid any
ambiguities when referencing this data.
Address a few concerns raised with the draft:

* Section 8.2 is more related to Certificate Policy OIDs. While disclosure requirements within the CP/CPS are captured here, instead move the disclosure of information sources closer to the verification process, since disclosure is required prior to use within verification
* There was concern that '24x7 availability' is at odds with a light touch approach that would permit disclosure via source control repositories (e.g. GitHub, GitLab) or online document services (e.g. Microsoft Office 365, Google G Suite). "readily accessible" is sufficient to indicate it must have more uptime than downtime
* Shift from 1 September to 1 October. This ensures "at least" three months, factoring in discussion, voting, and IP review, while avoiding any holiday freezes.
* Clarify that CAs only need to declare the sources they use, rather than any source they evaluate. CAs still need to disclose prior to use, and thus benefit from disclosing more early, but this does not require disclosure of every source evaluated, including those that are never used.
* Address default-deny concerns by making it clear that it's a minimum, not a maximum, for disclosure
Only require disclosure of form/syntax if the CA actually restricts.
Since this is only about disclosure, make it clear it is OK to disclose multiple values for the jurisdiction fields, if there really is a qualifying Agency which is authoritative for multiple distinct jurisdictions.
This addresses feedback from Tim and Doug regarding ambiguous
language:

1. "consistent with" in 9.2.4 has been replaced by instead clarifying
that, at time of issuance, the value must have been disclosed, and
must have been disclosed for the relevant Agency

2. "consistent with" in 9.2.5 is reworded to make it clear that the
disclosure of format is optional (addressing Doug's concern), but
if it is disclosed, the Registration Number must match (one of)
the formats disclosed for that Agency (addressing Tim's concerns)
Make it clear that you don't have to version for each individual line item change, but that you can batch changes. It's still necessary to publish prior to issuance.
@sleevi sleevi force-pushed the 2020-03-02-EVG-Jurisdiction branch from 0383db7 to 33de720 Compare June 16, 2020 22:34
@sleevi sleevi closed this Jun 16, 2020
sleevi added a commit that referenced this pull request Jan 11, 2021
As of
https://github.com/cabforum/build-guidelines-action/releases/tag/v2.0.0-rc3
section links now include the section number (e.g. "1.1 Section One"
becomes "#11-section-one"). This makes it easier to review and maintain
links, as any re-organizations will cause the links to break, which the
continuous integration will warn on.

This change rewrites all of the internal links to use the new style, and
bumps the dependency to rc3 (which will hopefully be the last release).
sleevi added a commit that referenced this pull request Mar 23, 2021
* Address formatting issues with the BRs

There are three typographical/formatting issues in the current
generated documents:

- Sections 3.2.2.4.18 / 3.2.2.4.19 don't properly appear as numbered
  lists.

- Section 4.10.1 is missing a trailing period.

- Section 6.1.6 makes use of <sup> for superscript, which is valid
  for GitHub flavored markdown, but not in general Markdown.

  Although Pandoc supports superscripts via the `superscript`
  extension, that just leans more into Pandoc-flavored markdown.
  Rather than do that, keep it vanilla markdown by adding a carat
  and whitespace to indicate the superscripting.

Closes cabforum#230
Closes cabforum#231

* Convert the EVGs to Pandoc-flavored Markdown

This enables GitHub Actions-based integration for the production of
the EV Guidelines.

* Fixup NSRs

* Fix lists

* Fix tabs/spaces that were messing up lists

* Add internal cross-references

Update all occurrences of "Section(s) X.Y.Z" to actually link to
the appropriate section within the document. This internal
cross-reference is only relevant for HTML and PDF forms (that is,
it does not affect the Word doc).

This also fixes several bad cross-references:

  - Section 9.6.1 contains a reference to a pre-BRs 1.3.0 structure

    Closes cabforum#237

  - Section 8.1 does not contain the audit schemes (another bad
    conversion in BRs 1.3.0); they are listed in Section 8.4

    Closes cabforum#216

* Harmonize section references of the EV Guidelines

References to sections within the EVGs are inconsistent, as
represented in the form of
"(th[e|is])? Section X (herein|of these Guidelines)?". This
aligns the EVGs to the BRGs by consistently referring to
"Section X" to represent the Section within the current
document.

* Renumber level 2 and 3 lists of the NSRs

This aligns the NSRs to an internally consistent numbering format,
which goes Section (always a number), lower-case alphabet, Arabic
numeral, Roman numeral.

* Update to v2.0.0 action

* Fix a bug: name should be id for the step

* Update to v2.0.0-rc2 action

* Cleanup whitespace and lists

This addresses two sets of issues pointed out by aarongable: An
inconsistent use of tabs vs spaces and inconsistent breakouts of
lists (I'd missed several). This aligns on a common spacing (spaces,
the only true spaces) and breaks out the (i) items.

* Fix some format issues with lists and whitespace

* Update section links

As of
https://github.com/cabforum/build-guidelines-action/releases/tag/v2.0.0-rc3
section links now include the section number (e.g. "1.1 Section One"
becomes "#11-section-one"). This makes it easier to review and maintain
links, as any re-organizations will cause the links to break, which the
continuous integration will warn on.

This change rewrites all of the internal links to use the new style, and
bumps the dependency to rc3 (which will hopefully be the last release).

* Further style cleanups

This linkifies the Appendix sections in both the BRs and the EVGs,
and fixes some markdownlint errors for the EVGs, to go along with
#34 for the BRs.

* Additional cleanups and markdownlint compliance (#34)

* Additional cleanups and markdownlint compliance

This commit updates the BR.md doc with the following changes:
* Removes all instances of two adjacent spaces, except when used
  for indentation
* Removes all instances of two adjacent blank lines
* Fixes all markdownlints, including spaces around lists, spaces
  around headings, and tags on fenced blocks.

It also fixes a few other pieces of miscellany, such as paragraphs
which were not sufficiently indented to semantically fall inside the
list in which they are intended to fall, and fencing code blocks which
should have been fenced.

It does not address two markdownlints: There are still multiple H1
headings, and there are a few places where markdown believes that
unordered list bullets should be unindented (but doing so would
change the semantics of the document).

* Harmonize styles further

This is a series of small list formatting cleanups to ensure proper
display. However, it does renumber Section 8.5.5 of the EVGs to use
Arabic numerals for the requirements, aligning with the other
requirements in Section 8.5, instead of using capitalized letters for
the list. There are no internal references to those requirements, and
so this should be safe.

* Remove stray footnote

During the SC26 cleanup work, there was a stray footnote that got
left in which rendered incorrectly, relating to Section 3.2.2.6 and
wildcards. This correctly removes it.

Although we do support footnotes in the PDF and Docx writers, and
we do use them, Section 3.2.2.6 was modified during SC26 to make the
normative requirement clearer and part of the text, rather than as
a footnote.

* More cleanups

This aligns the NCSSRs with the style of the EVGs and BRs, which is
that lists use single spacing, not double. It aligns the definitions
of the NCSSRs with that of the EVGs and BRs, of keeping the colon
of a definition as non-emphasized text.

* Fix a few stragglers from section references in the BRs

We had a few BR Section X or Section X of these Baseline Requirements
that I'd missed.

* Update artifact name to include SHA-1

This hopefully will make it easier for people to review this PR
as it progresses, by being able to determine which commit a converted
document was associated with.

* More consistency fixes

This further aligns the documents to consistently:

- Use one space after colons or other punctuation (other than period)
- Code-escape ASN.1 field names and values

* [WIP] Attempt to enable redline generation

* Fix indent in section 8.4 (B) of the EVGs

* Update build-draft-docs.yml

Update to v2 of the action, and set draft mode for everything but that landed to the SCWG main repository.

* Switch to explicit v2.0.0 rather than v2

In hindsight, this avoids any potential breakage in the future if there's an uprev of build-guidelines-action that subtly breaks things.

Given that we don't currently regression test the generated files, this seems more likely (such as a break in the template or updated Pandoc minor version), so until we have that in place, I'll use an explicit full version.

* Add languages to fenced codeblocks

No functional change, but ensures that the fenced blocks have an
appropriate syntax/language set. The set of names is adopted from
the GitHub/Linguist supported languages.

* Incoporate changes from SC39v3 and align other links

Co-authored-by: Aaron Gable <aaron@aarongable.com>
sleevi added a commit that referenced this pull request Apr 5, 2021
* SC39v3: CVSS Critical Vulnerability Definition (cabforum#246)

* CVSS Critical Vulnerability Definition

Updates to URL and threshold for CVSS Critical Vulnerability

* Update NSR.md

Change CVSS 3.0 >= 9.0 to CVSS 2.0 >= 7.0 to maintain editorial nature of change

* Update version number in NSR

* Update revision history table

* Ballot SC41: Reformat the BRs/EVGs/NCSSRs (cabforum#235)

* Address formatting issues with the BRs

There are three typographical/formatting issues in the current
generated documents:

- Sections 3.2.2.4.18 / 3.2.2.4.19 don't properly appear as numbered
  lists.

- Section 4.10.1 is missing a trailing period.

- Section 6.1.6 makes use of <sup> for superscript, which is valid
  for GitHub flavored markdown, but not in general Markdown.

  Although Pandoc supports superscripts via the `superscript`
  extension, that just leans more into Pandoc-flavored markdown.
  Rather than do that, keep it vanilla markdown by adding a carat
  and whitespace to indicate the superscripting.

Closes cabforum#230
Closes cabforum#231

* Convert the EVGs to Pandoc-flavored Markdown

This enables GitHub Actions-based integration for the production of
the EV Guidelines.

* Fixup NSRs

* Fix lists

* Fix tabs/spaces that were messing up lists

* Add internal cross-references

Update all occurrences of "Section(s) X.Y.Z" to actually link to
the appropriate section within the document. This internal
cross-reference is only relevant for HTML and PDF forms (that is,
it does not affect the Word doc).

This also fixes several bad cross-references:

  - Section 9.6.1 contains a reference to a pre-BRs 1.3.0 structure

    Closes cabforum#237

  - Section 8.1 does not contain the audit schemes (another bad
    conversion in BRs 1.3.0); they are listed in Section 8.4

    Closes cabforum#216

* Harmonize section references of the EV Guidelines

References to sections within the EVGs are inconsistent, as
represented in the form of
"(th[e|is])? Section X (herein|of these Guidelines)?". This
aligns the EVGs to the BRGs by consistently referring to
"Section X" to represent the Section within the current
document.

* Renumber level 2 and 3 lists of the NSRs

This aligns the NSRs to an internally consistent numbering format,
which goes Section (always a number), lower-case alphabet, Arabic
numeral, Roman numeral.

* Update to v2.0.0 action

* Fix a bug: name should be id for the step

* Update to v2.0.0-rc2 action

* Cleanup whitespace and lists

This addresses two sets of issues pointed out by aarongable: An
inconsistent use of tabs vs spaces and inconsistent breakouts of
lists (I'd missed several). This aligns on a common spacing (spaces,
the only true spaces) and breaks out the (i) items.

* Fix some format issues with lists and whitespace

* Update section links

As of
https://github.com/cabforum/build-guidelines-action/releases/tag/v2.0.0-rc3
section links now include the section number (e.g. "1.1 Section One"
becomes "#11-section-one"). This makes it easier to review and maintain
links, as any re-organizations will cause the links to break, which the
continuous integration will warn on.

This change rewrites all of the internal links to use the new style, and
bumps the dependency to rc3 (which will hopefully be the last release).

* Further style cleanups

This linkifies the Appendix sections in both the BRs and the EVGs,
and fixes some markdownlint errors for the EVGs, to go along with
#34 for the BRs.

* Additional cleanups and markdownlint compliance (#34)

* Additional cleanups and markdownlint compliance

This commit updates the BR.md doc with the following changes:
* Removes all instances of two adjacent spaces, except when used
  for indentation
* Removes all instances of two adjacent blank lines
* Fixes all markdownlints, including spaces around lists, spaces
  around headings, and tags on fenced blocks.

It also fixes a few other pieces of miscellany, such as paragraphs
which were not sufficiently indented to semantically fall inside the
list in which they are intended to fall, and fencing code blocks which
should have been fenced.

It does not address two markdownlints: There are still multiple H1
headings, and there are a few places where markdown believes that
unordered list bullets should be unindented (but doing so would
change the semantics of the document).

* Harmonize styles further

This is a series of small list formatting cleanups to ensure proper
display. However, it does renumber Section 8.5.5 of the EVGs to use
Arabic numerals for the requirements, aligning with the other
requirements in Section 8.5, instead of using capitalized letters for
the list. There are no internal references to those requirements, and
so this should be safe.

* Remove stray footnote

During the SC26 cleanup work, there was a stray footnote that got
left in which rendered incorrectly, relating to Section 3.2.2.6 and
wildcards. This correctly removes it.

Although we do support footnotes in the PDF and Docx writers, and
we do use them, Section 3.2.2.6 was modified during SC26 to make the
normative requirement clearer and part of the text, rather than as
a footnote.

* More cleanups

This aligns the NCSSRs with the style of the EVGs and BRs, which is
that lists use single spacing, not double. It aligns the definitions
of the NCSSRs with that of the EVGs and BRs, of keeping the colon
of a definition as non-emphasized text.

* Fix a few stragglers from section references in the BRs

We had a few BR Section X or Section X of these Baseline Requirements
that I'd missed.

* Update artifact name to include SHA-1

This hopefully will make it easier for people to review this PR
as it progresses, by being able to determine which commit a converted
document was associated with.

* More consistency fixes

This further aligns the documents to consistently:

- Use one space after colons or other punctuation (other than period)
- Code-escape ASN.1 field names and values

* [WIP] Attempt to enable redline generation

* Fix indent in section 8.4 (B) of the EVGs

* Update build-draft-docs.yml

Update to v2 of the action, and set draft mode for everything but that landed to the SCWG main repository.

* Switch to explicit v2.0.0 rather than v2

In hindsight, this avoids any potential breakage in the future if there's an uprev of build-guidelines-action that subtly breaks things.

Given that we don't currently regression test the generated files, this seems more likely (such as a break in the template or updated Pandoc minor version), so until we have that in place, I'll use an explicit full version.

* Add languages to fenced codeblocks

No functional change, but ensures that the fenced blocks have an
appropriate syntax/language set. The set of names is adopted from
the GitHub/Linguist supported languages.

* Incoporate changes from SC39v3 and align other links

Co-authored-by: Aaron Gable <aaron@aarongable.com>

* Version number update to BRs

Version number update to EVGs

Version number update to NCSSRs

* Update effective dates to reflect end of IPR period

* Update date changes for NSRs

* Bump version of build-draft-docs.yml

Co-authored-by: sleevi <ryan.sleevi@gmail.com>

* Update effective dates for IPR period end

* Update cover page dates

Co-authored-by: neildunbar <neil.dunbar@pobox.com>
Co-authored-by: Jos Purvis <jopurvis@cisco.com>
Co-authored-by: sleevi <ryan.sleevi@gmail.com>
Co-authored-by: Aaron Gable <aaron@aarongable.com>
Co-authored-by: Wayne Thayer <wthayer@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
4 participants