384997 - rewrite the documentation on 'When a web site requires a certificate' and 'Validation'

Status: RESOLVED FIXED

(Firefox Graveyard :: Help Documentation, defect)

Description

[Steffen Wilberg]

Bug 382810 relabeled the "Verification" button in Options->Advanced->Encryption to "Validation".

Comment 1

[Steffen Wilberg]

Bug 110161 enabled OCSP by default and reworked the Validation options dialog.

Comment 2

[Steffen Wilberg]

Attachment: patch

Replaced the "When a web site requires a certificate" and "Verification" paragraphs. The former was completely bogus; I learned from bug 395399 that that's really about personal certificates. A few (very few) sites use that instead of username/password to identify their users. That has nothing to do with secure (https) sites in general.
See http://mxr.mozilla.org/seamonkey/source/suite/locales/en-US/chrome/common/help/certs_prefs_help.xhtml#51 for Seamonkey's explanation.

Comment 3

[Jeff Walden (gone starting June 8)]

Comment on attachment 282887 [details] [diff] [review]
patch

>Index: mozilla/browser/locales/en-US/chrome/help/prefs.xhtml

>+      encryption and decryption of connections to <a href=
>+      "glossary.xhtml#secure_site">secure sites</a>.</p>

Nit: move the href= to the second line.


>+      certificate. In order to do so, they generate one for you and ask
>+      &brandShortName; to store it. When you visit the site in the future,

This is slightly incorrect; the following should be more correct:

  In order to do so, they ask &brandShortName; to generate one for you.

The cert is generated client-side, and then Firefox sends the corresponding public key (the cert's the private key) to the server, but I don't think we really need that level of detail.  Just saying the site tells Firefox to generate the cert is accurate and informative enough here.


>-      &brandShortName; verify the validity of your certificates using OCSP

Ugh, we had a grammar problem here?  I wonder how long that's been there; I bet it's pre-1.0.  :-\


>+      OCSP server. Alternately, you can choose an OCSP server to validate all
>+      certificates against. Click the <em>Validation</em> button to manage

"OCSP server against which to validate all certificates"


As it happens, MIT's infrastructure is one of those few sites that relies on certificates; I claim inexperience with the system causing the errors when I (?) originally wrote or reviewed this.  ;-)

Comment 4

[Steffen Wilberg]

Attachment: patch with comment 3 addressed

> >+      encryption and decryption of connections to <a href=
> >+      "glossary.xhtml#secure_site">secure sites</a>.</p>
> Nit: move the href= to the second line.
Done. 

> >+      certificate. In order to do so, they generate one for you and ask
> >+      &brandShortName; to store it. When you visit the site in the future,
> 
> This is slightly incorrect; the following should be more correct:
> 
>   In order to do so, they ask &brandShortName; to generate one for you.
Done.

> The cert is generated client-side, and then Firefox sends the corresponding
> public key (the cert's the private key) to the server
No, the certificate is the public key: http://en.wikipedia.org/wiki/Public_key_certificate.
But you're right, I've seen that little dialog displaying "generating a private key". However, that's not always the case: My email provider let me choose a password and then export my certificate to disk, from where I could import it into Firefox and Thunderbird. So they generated both the public and the private key.
But I guess the more common case is the client-side key generation; the provider really shouldn't know my private key...

Because of bug 398203 comment 4, I also changed the previous sentence to:
"Some servers ask you to identify yourself with a personal certificate."
("servers" instead of "web sites" and "ask" instead of "requires")

> >-      &brandShortName; verify the validity of your certificates using OCSP
> Ugh, we had a grammar problem here?  I wonder how long that's been there; I bet
> it's pre-1.0.  :-\
No, that sentence has been rewritten in bug 341899 for 2.0...

> >+      OCSP server. Alternately, you can choose an OCSP server to validate all
> >+      certificates against. Click the <em>Validation</em> button to manage
> "OCSP server against which to validate all certificates"
Done.

Comment 5

[Steffen Wilberg]

Checked in.

Comment 6

[Ton [:Tonnes]]

> Created an attachment (id=298960) [details]
> Patch (v1.1)
> 
> -<!ENTITY certselect.description          "When a web site requires a certificate:">
> +<!ENTITY certSelection.description       "When a server requests my personal certificate:">

I noticed this line hasn’t changed in the Help doc yet. Wouldn’t it need to?

Comment 7

[Steffen Wilberg]

That's another bug. But we're switching to online help anyway, and that has already been updated:
http://support.mozilla.com/en-US/kb/Options+window#Encryption_tab