892060 - Remove Help page for Validation preference pane and update sections mentioning CRL management

Status: RESOLVED FIXED

(SeaMonkey :: Help Documentation, defect)

Description

[rsx11m]

+++ This bug was initially created as a clone of Bug #886099 +++

Bug 867465 removed the window that the button opens.

As there is only one thing left in that pane, we should probably move it to another pane.

Help will also need to be updated.

And there are string changes too, which is annoying 1 day before uplift...

Comment 1

[rsx11m]

Looks like the following actions need to be done for this change:

 - move validation_help.xhtml#ocsp to certs_prefs_help.xhtml
 - remove everything else of validation_help.xhtml
 - remove validation_help.xhtml from jar.mn
 - update using_certs_help.xhtml#how_validation_works
 - remove using_certs_help.xhtml#managing_crls section
 - update help-index1.rdf and suite-toc.rdf for links

Comment 2

[rsx11m]

Bug 886099 just checked in, thus tentatively taking this bug.

Comment 3

[rsx11m]

In the current Help text, the OCSP section includes settings "Validate a certificate if it specifies a OCSP server" and "Validate all certificates using the following OSCP server" which are not in the old Validation preference pane. I can't find those strings anywhere else either, thus I assume that the descriptions of those options can be removed.

Comment 4

[[e-mail]]

Ah yes, that was bug 810672, so those descriptions can go too, thanks.

Comment 5

[rsx11m]

And the reasoning for their removal is in bug 802302. Current help text says in the introduction "This process involves checking the certificate against a certificate revocation list (CRL) maintained at a specified server." So, which server is that? The one specified by the CA on the certificate (as suggested by the removed UI) or an OCPS server at some central service? I don't see any security.OCPS.* preferences specifying that.

Comment 6

[rsx11m]

Maybe I'll just replace "specified server" with "dedicated server" or "trusted server" to avoid the need to say which server is talked about (it is my understanding that this can be either the CA's server or a server trusted by the client application, thus picked "somehow" by Mozilla).

Comment 7

[[e-mail]]

(In reply to rsx11m from comment #5)
> And the reasoning for their removal is in bug 802302. Current help text says
> in the introduction "This process involves checking the certificate against
> a certificate revocation list (CRL) maintained at a specified server." So,
> which server is that? The one specified by the CA on the certificate (as
> suggested by the removed UI) or an OCPS server at some central service? I
> don't see any security.OCPS.* preferences specifying that.

My reading of bug 802302 is that they're removing the option of using a central service, which must mean that it uses the OSCP server provided on the certificate itself.

Comment 8

[rsx11m]

I see. I'll try to come up with some useful but not too specific rewording of that part which hopefully sufficiently matches reality.

Comment 9

[rsx11m]

(Note to myself) More files that require modifications for links and/or references to the Validation prefpane or general CRL description:

 - cert_dialog_help.xhtml
 - mailnews_security.xhtml
 - privsec_help.xhtml

Comment 10

[rsx11m]

Attachment: Proposed patch

Following changes: (comments welcome from anyone)

 - cert_dialog_help.xhtml:
   * changed Validation Settings > Certificates Settings in link

 - certs_prefs_help.xhtml:
   * added direct links to Managing Certificates and Security Devices sections
   * added OCSP section, partially copy-pasted from old validation_help.xhtml
   * kept some details what CRLs are given that OCSP uses them for responses
   * kept part of "use CA's OCSP server named in certificate" per bug 802302

 - help_index1.xhtml:
   * removed all entries linking to CRL management
   * removed bogus entry for "OSCP" (intentional misspelling of OCPS?)
   * removed most entries related to validation (some redundant), kept
     "OCPS" pointing to OCPS section in Certificates Settings now
     "validation settings" pointing to main Certificates Settings

 - mailnews_security.xhtml:
   * changed Validation Settings > Certificates Settings in link

 - privsec_help.xhtml:
   * removed link to Validation Settings below Certificates Settings 

 - suite-toc.rdf:
   * removed "Validation" from "Privacy & Security Preferences"
   * removed "Managing CRLs" from "Controlling Validation"
   * removed "Validation Settings" from "Controlling Validation"

 - using_certs_help.xhtml:
   * removed "Managing CRLs" sections
   * removed link to "Validation Settings"
   * partially rewrote two paragraphs related to CRL and OCPS
   * changed link and text for OCPS settings in "Configuring OCPS"

 - validation_help.xhtml:
   * removed entirely along with respective jar.mn changes

Comment 11

[[e-mail]]

(In reply to rsx11m from comment #10)
>    * added OCSP section, partially copy-pasted from old validation_help.xhtml
>    * kept some details what CRLs are given that OCSP uses them for responses
>    * kept part of "use CA's OCSP server named in certificate" per bug 802302
>    * removed bogus entry for "OSCP" (intentional misspelling of OCPS?)
>    * removed most entries related to validation (some redundant), kept
>      "OCPS" pointing to OCPS section in Certificates Settings now
>      "validation settings" pointing to main Certificates Settings
So which is it, OCSP, OSCP or OCPS?

Comment 12

[rsx11m]

OCSP is correct - http://tools.ietf.org/html/rfc6960
= "Online Certificate Status Protocol"

Comment 13

[rsx11m]

>    * removed bogus entry for "OSCP" (intentional misspelling of OCPS?)
>    * removed most entries related to validation (some redundant), kept
>      "OCPS" pointing to OCPS section in Certificates Settings now

Oh, sorry - that's a typo in my comment only. I've double-checked that there is no other spelling "OCPS" or "OSCP" left in Help files.

Comment 14

[Ian Neal]

Comment on attachment 775144 [details] [diff] [review]
Proposed patch

>+++ b/suite/locales/en-US/chrome/common/help/certs_prefs_help.xhtml

>+  <li><strong>Use the Online Certificate Status Protocol (OCSP) to confirm the
>+    current validity of certificates</strong>: Select this setting if you want
Not sure you need to include the word "setting", so "Select this if you want..."

>+  </li>
>+  <li><strong>When an OCSP server connection fails, treat the certificate as
>+    invalid</strong>: Select this if you want the validation to fail if a
>+    connection to the OCSP server can&apos;t be established, thus to enforce
maybe "thus enforcing" rather than "thus to enforce"

>+    that a certificate always must be positively validated for each use.</li>

>+++ b/suite/locales/en-US/chrome/common/help/using_certs_help.xhtml

>+<p>One way to combat this threat would be for Certificate Manager to check a
>+  previously downloaded certificate revocation list (CRL) as part of the
>+  verification process. However, those lists may be large and require to be
maybe "need" instead of "require"
>+  updated frequently in order to remain current and thus useful.</p>

r=me with those fixed/addressed

Comment 15

[rsx11m]

Attachment: Patch for checkin

Thanks for the review, all changes made as requested.

Comment 16

[rsx11m]

Push for comm-central, please.

Comment 17

[rsx11m]

Callek, can this patch land on c-c? This affects Help contents only and documents changes that were made already with the last cycle (effective for 2.21).

Comment 18

[Ian Neal]

Help changes, in theory, are not usually considered to be the same as string changes, so can land given the correct approvals (though probably a bit too close to final for beta).

Comment 19

[rsx11m]

Ian, you want this on the branches as well? Only 2.21 is affected, thus no need for comm-beta, but I can request approval for comm-aurora.

Comment 20

[rsx11m]

Comment on attachment 782219 [details] [diff] [review]
Patch for checkin

[Approval Request Comment]
Regression caused by (bug #): bug 867465, bug 886099.
User impact if declined: description of a non-existent feature, inconsistencies with actual prefpane content.
Testing completed (on m-c, etc.): works fine on c-c.
Risk to taking this patch (and alternatives if risky): none, Help only.
String changes made by this patch: none per comment #18.

Comment 21

[rsx11m]

Thanks, redirecting needinfo? to RyanVM for checkin on closed tree (can land with DONTBUILD).

Comment 22

[Ryan VanderMeulen [:RyanVM]]

https://hg.mozilla.org/comm-central/rev/76255a2060f0
https://hg.mozilla.org/releases/comm-aurora/rev/df187a1d7ebd

Comment 23

[rsx11m]

(In reply to Ian Neal from comment #18)
> Help changes, in theory, are not usually considered to be the same as string changes,

I've posted a note to the l10n list anyway, can't hurt.