[cabf_validation] Cert Profile spec: question about the outline/ToC

Mon Aug 2 17:37:47 UTC 2021

In the screenshot below you have 2 sections numbered 7.1.2.4 and 7.1.2.5.

From: Ryan Sleevi <sleevi at google.com> 
Sent: Monday, August 2, 2021 1:30 PM
To: Doug Beattie <doug.beattie at globalsign.com>
Cc: CA/Browser Forum Validation SC List <validation at cabforum.org>
Subject: Re: [cabf_validation] Cert Profile spec: question about the outline/ToC

Also, I'm still not sure I follow you on what you mean by the numbering bug. Could you try to rephrase what you see as the numbering issue (re: Common CA fields & Common Certificate Fields)?

On Mon, Aug 2, 2021 at 1:29 PM Ryan Sleevi <sleevi at google.com <mailto:sleevi at google.com> > wrote:

Sorry, we (infrastructure) still haven't wired up automation to make this even more discoverable for folks not using GitHub daily :)

On https://github.com/sleevi/cabforum-docs/pull/36 , you can click the "Checks" tab ( https://github.com/sleevi/cabforum-docs/pull/36/checks ) to see the actions, and then click either of the "Build Guidelines Actions" runs to download the artifacts (at the bottom of the page)

You can also click the green checkmark next to any commit in a branch (e.g. on https://github.com/sleevi/cabforum-docs/tree/profiles or https://github.com/sleevi/cabforum-docs/commits/profiles ) to access the artifacts for that commit (or batch of commits).

That will have the generated word and PDF files. The word file, due to the Word bug/quirk I mentioned ( https://github.com/jgm/pandoc/issues/458 ) requires you click the refresh button on the ToC to regenerate it once you open, but it should generate the right ToC.

On Mon, Aug 2, 2021 at 12:48 PM Doug Beattie <doug.beattie at globalsign.com <mailto:doug.beattie at globalsign.com> > wrote:

I viewed the file in GitHub and copied into word to generate the ToC, but for the life if me could not find the link to the PDF, so I’ll poke around a bit more.

Now that has one more level than the current BRs, those headings are present and will make (my) navigation to the applicable section much easier.  And of course being compliant with RFC 3647 which I wasn’t thinking of when I sent my comments, so no issues with that. Sorry!

I’m not a huge fan of the “Common CA fields” where it is vs. with the CA profiles, same with “common Certificate fields”, but I can cope with that.  A small bug in the numbering of those last 2 items in your screenshot.

Doug

From: Ryan Sleevi <sleevi at google.com <mailto:sleevi at google.com> > 
Sent: Monday, August 2, 2021 11:54 AM
To: Ryan Sleevi <sleevi at google.com <mailto:sleevi at google.com> >; CA/Browser Forum Validation SC List <validation at cabforum.org <mailto:validation at cabforum.org> >
Cc: Doug Beattie <doug.beattie at globalsign.com <mailto:doug.beattie at globalsign.com> >
Subject: Re: [cabf_validation] Cert Profile spec: question about the outline/ToC

And for completeness: This is what the PDF produced looks like from the canonical markdown:

That said, I haven't really paid attention to the Word file, as I don't use it, but could you confirm the process you're using to generate the table of contents? It should be generated with four levels of depth, like above - the Word default is 3 levels, so if you're manually doing the generation, this may explain. It looks like there's a slight bug in Word that we don't have a way to work around <https://github.com/jgm/pandoc/issues/458>  related to how it generates the TOC, but if you're manually replacing the ToC, that may explain why you don't have a matching experience.

On Mon, Aug 2, 2021 at 11:48 AM Ryan Sleevi via Validation <validation at cabforum.org <mailto:validation at cabforum.org> > wrote:

Hey Doug,

Thanks for the suggestion!

I think you may recall that we had at least two calls where we discussed this outline, early on, in order to gather feedback early on, so that it wouldn't require major restructuring. That's not to say no, but that this isn't exactly a light request.

There's a clear problem with your proposal, which is that it relies on breaking from RFC 3647 format. Considering multiple root programs, and the BRs itself, require CAs to adhere to RFC 3647, that's a somewhat big divergence here, and I want to call attention to it.

I'll certainly give it some thought, but I'm hoping as well you can better explain your concern: Is your primary concern simply the Table of Contents on the main PDF? I'm not sure I understand "avoid long numbered headings" in and of itself as a goal, especially since we have other places (and within the NCSSRs, but especially the EVGs), so it does seem you're proposing a more substantial requirement that is inconsistent with our existing work. That doesn't mean it's bad, but it seems we should try to aim to be self-consistent to a degree, shouldn't we?

_______________________________________________
Validation mailing list
Validation at cabforum.org <mailto:Validation at cabforum.org> 
https://lists.cabforum.org/mailman/listinfo/validation

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.cabforum.org/pipermail/validation/attachments/20210802/4afdcd3e/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image001.png
Type: image/png
Size: 283040 bytes
Desc: not available
URL: <http://lists.cabforum.org/pipermail/validation/attachments/20210802/4afdcd3e/attachment-0001.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 8424 bytes
Desc: not available
URL: <http://lists.cabforum.org/pipermail/validation/attachments/20210802/4afdcd3e/attachment-0001.p7s>