search

thunderbird / knowledgebase-issues

for tracking Thunderbird Desktop SUMO Knowledge Base issues
Mozilla Public License 2.0
4 stars 1 forks source link

Please review/approve SUMO new article about S/MIME CSR (needed for TB 128) #51

Open kaie opened 4 months ago

kaie commented 4 months ago

Could you please review/approve the following SUMO article: https://support.mozilla.org/en-US/kb/instructions-smime-certificate-using-csr/history

The intention is to have a new feature in TB ESR 128 ( see https://bugzilla.mozilla.org/show_bug.cgi?id=1581796 ) which will show a help button, and the help button will open the above SUMO article.

To Dos

rtanglao commented 4 months ago

(EDIT: pinged kai in the Matrix smime room about this)

rtanglao commented 4 months ago
kaie commented 4 months ago

I don't have permission to view Roland's revisions. On page https://support.mozilla.org/en-US/kb/instructions-smime-certificate-using-csr/history the only revision I can look at is the first one, the one that I had created.

rtanglao commented 4 months ago
rtanglao commented 4 months ago

From email Ben Wilson (thanks!):

In the instructions, under "Import the certificate into Thunderbird" I would change them to say something like, "Certificate Manager has five tabs at the top. Click on the tab “Your Certificates”." (instead of "People"). (I didn't try it under "People", so I don't know if that works.)

Then I would modify the drop-down under "Import" to display other file types as options for importing (e.g. "All Files" or .crt, .p7b, etc.") because when I tested this, the file I received from the CA (based on the submission of the CSR) was just a .crt file. Alternatively, the instructions could be changed to alert the user to the fact that only PKCS12 are shown by default. (Otherwise, they will get confused about where their certificate file is.)

Also, for instruction purposes, testing ought to be done with different CA procedures. For example, some CAs "help" users by generating keys and having them import the PKCS12 into the OS. (I saw the Note: "If the CA is delivering the certificate to you in a file with a filename extension .p12 or .pfx, it may indicate that the CA didn't use the key that you had submitted, but rather generated a secret key on their systems. This may not be what you want.") Such instructions could be written adjacent to that warning, but in any event there should be instructions somewhere on how to copy the PKCS12 from disk into the Certificate Manager (I recall seeing instructions out there on the Internet on how to do this).

Then, in the Instructions, it might be good to rename the title of "Import the certificate into Thunderbird" to "Import the certificate into Certificate Manager" (because after Step 4, the certificate isn't usable by Thunderbird until the user has clicked on "Select"). Then after Step 4 in the instructions say something like "Before you exit Certificate Manager, it is crucial to save your key and certificate to a different disk for secure backup." With that approach, the user will be directed to create a backup, which they might otherwise skip doing if the "Backup your Certificate" step isn't at that location in the instructions.

Another approach would be to combine the two sections and move Backup your Certificate below them. (I found it useful to know that I still had to click on "Select" to complete the process, but I had to read further down in the instructions to learn this.)

Finally, there were a few typos. They are shown with the Firefox LanguageTool writing assistant. But for example, "set up" should be two words and "which asks to you submit the CSR" should be "which asks you to submit the CSR". And, "offered" is misspelled as "ofered"

rtanglao commented 4 months ago
rtanglao commented 3 months ago

(Thanks to Ben for the great feedback!)

  1. In the instructions, under "Import the certificate into Thunderbird" I would change them to say something like, "Certificate Manager has five tabs at the top. Click on the tab “Your Certificates”." (instead of "People"). (I didn't try it under "People", so I don't know if that works.) ^-- @kaie should it be changed to Your Certificates instead of People? I left it as People for now

  2. Then, in the Instructions, it might be good to rename the title of "Import the certificate into Thunderbird" to "Import the certificate into Certificate Manager" (because after Step 4, the certificate isn't usable by Thunderbird until the user has clicked on "Select"). Then after Step 4 in the instructions say something like "Before you exit Certificate Manager, it is crucial to save your key and certificate to a different disk for secure backup." With that approach, the user will be directed to create a backup, which they might otherwise skip doing if the "Backup your Certificate" step isn't at that location in the instructions. ^--@kaie Ben's edits seem appropriate to me, so I made them

  3. Finally, there were a few typos. They are shown with the Firefox LanguageTool writing assistant.
    ^-- thanks for spotting them! I believe I fixed them. @ Ben What do you mean by Firefox LanguageTool writing assistant ? Do you mean the add-on at: https://languagetool.org/firefox Willing to try any new tool to improve my writing!

  4. @kaie When I am back from PTO, I'd like to test this myself, is there some sort of test certificate or do i need to buy one? Or can you screenshot every step of the entire process so I can see the flow myself?
kaie commented 3 months ago

In the instructions, under "Import the certificate into Thunderbird" I would change them to say something like, "Certificate Manager has five tabs at the top. Click on the tab “Your Certificates”." (instead of "People"). (I didn't try it under "People", so I don't know if that works.)

This suggestion from @BenWilson-Mozilla has the following additional complication:

When clicking the import button inside the "Your Certificates" tab, the file selection dialog will show only files with file extensions that refer to the pkcs12 (p12) file format.

But the file you are importing isn't in this format. It's in a plain certificate file format.

That means, the file selection dialog will not show that type of file by default. As an additional step, the user would have to switch the dropdown to select the type of files that are shown list.

If the user clicks the Import button from inside the People tab, then the file dialog is already set to the file extension we expect.

So logically, the user wants to import their own certificate. So it seems more plausible to go to the Your Certificates, I agree with that. If you are ok to add the additional explanation that the type of file needs to be chosen, we can use Ben's suggestion.

kaie commented 3 months ago 
2. > Then, in the Instructions, it might be good to rename the title of "Import the certificate into Thunderbird" to "Import the certificate into Certificate Manager" (because after Step 4, the certificate isn't usable by Thunderbird until the user has clicked on "Select"). Then after Step 4 in the instructions say something like "Before you exit Certificate Manager, it is crucial to save your key and certificate to a different disk for secure backup." With that approach, the user will be directed to create a backup, which they might otherwise skip doing if the "Backup your Certificate" step isn't at that location in the instructions.
   > ^--@kaie Ben's edits seem appropriate to me, so I made them

I don't mind changing the title.

But I think it doesn't really make much of a difference. If the file is imported into the Certificate Manager, it's also already inside Thunderbird. There is no separate storage for Certificate Manager. The certificates and keys are stored inside Thunderbird's profile directory.

The certificate is already usable by Thunderbird. It's just that we must configure Thunderbird to actively use it with an email account (by selecting it in account settings).

I agree it is useful to immediately recommend that the user creates a backup. (It isn't crucial for using the certificates, but people will deeply regret it, if there is a system failure and they didn't create a backup.)

kaie commented 3 months ago 
4. @kaie When I am back from PTO, I'd like to test this myself, is there some sort of test certificate or do i need to buy one? Or can you screenshot every step of the entire process so I can see the flow myself?

I'm not aware of any public and free service that takes a CSR and gives you a certificate for free.

You can create a CSR, and send the file to me. I can create a test certificate based on your CSR, and send you a test certificate by email, which will allow you to test the remaining steps.

kaie commented 3 months ago 
* [ ]  @kaie please review https://support.mozilla.org/en-US/kb/instructions-smime-certificate-using-csr/revision/281129 i am sure there are mistakes, please don't hesitate to correct them; I believe you have permissions to review and approve your edits now on SUMO

Ok, I will review and edit and submit a new revision.

kaie commented 3 months ago

We must change the order of steps in the last section "configure thunderbird to use..."

It might be necessary to import the intermediate CA certificates, before Thunderbird is able to offer them for selection and use them.

I'll change the document.

kaie commented 3 months ago

Also, the import of intermediate CA certificates should be done before creating a backup.

The reason is, the certificate will be unusable without the intermediates. If they have already been imported, they will automatically be included in the backup.

kaie commented 3 months ago

done, I was able to approve my own revision. Would you like to do a final pass on reviewing my changes? Afterwards it should be fine to allow translation.