Re: [Tails-dev] Please review the documentation of gpgApplet

Delete this message

Reply to this message
Author: intrigeri
Date:  
To: The Tails public development discussion list
Subject: Re: [Tails-dev] Please review the documentation of gpgApplet
Hi,

sajolida@??? wrote (06 Oct 2012 23:00:57 GMT) :
> Today I worked on the documentation of the new Tails gpgApplet. (I
> wondered whether giving it a name without camel case.)


Great work!

> You can find most of the work in commits 1c3c5bc..94e4fb4, but those are
> a bit hardcore so you might rather look directly at the result on those
> four pages:


> I have a couple of questions and bug reports, though.


Bellow, I'll (implicitly or explicitly) ignore anything that is about
symmetric encryption/decryption, since they probably are no
regressions caused by that branch, and I'd rather focus on the
devel..feature/assymetric_gpgApplet diff given the short delay from
now to the freeze.

sajolida, do you want to take care to come back later (e.g. post-0.14)
with these bug reports, or should $someone (you?) create tickets
right now so that they're not forgotten?

I'm also ignoring most reports for bugs introduced by this branch,
since I won't have time to fix them myself in time for the freeze.
I may still provide the occasional opinion inline, though.

Let's start with my remarks, and then I'll reply some of your questions.

> - [[Encrypt and sign text with a public key|encryption_and_privacy/gpgapplet/public-key_encryption]]


I'm worried to read "sign text with a public key".
I'm not sure what phrasing could be better, not too complicated,
while less wrong.

s/Javascript/JavaScript

> "you can decrypt text that is encrypted using OpenPGP or verify text
> that is signed using OpenPGP."


I wonder whether s/is/was/ would be better to clarify what was done
already, and what can be done *now*.

> "Select with the mouse the encrypted text that you want to decrypt
> or the signed text that you want to verify. To copy it into the
> clipboard, right-click on the selected text and choose Copy from
> the menu."


Is explicit "Copy" really needed? IIRC the applet gets input from the
X selection buffer if available, but I don't remember the exact
semantics and priorities. Ditto on gpgapplet/public-key_encryption.

This is followed by a screenshot. I'm not sure this one is necessary.
I expect most users who will be able to understand and follow the rest
of this piece of documentation to be able to right-click / copy if
instructed by text only.

> "Click on Tails gpgApplet and select"


Previously, only "the icon of Tails gpgApplet" was told about on the
current page ("Tails gpgApplet" is mentioned on the
encryption_and_privacy/gpgapplet page, though). Given it's the only
visible part, I suggest using either always "Tails gpgApplet", or
always "the icon of Tails gpgApplet" when talking of that widget.
Else, one may wonder, arriving at this step, what to click on.

There are some inconsistencies, too, between "click $WIDGET" and
"click on $WIDGET". I'm not sure this is on purpose.

> "If the text that you selected is encrypted using public-key
> encryption, two different dialog boxes can appear."


What appears if the corresponding private-key is not available at all?
Do we care mentioning it?

> "Click on the Authorize to use"


"Authorize button", perhaps?

> "If the text that you selected is only signed, the window described
> in step 5 appears directly."


I'm in doubt, when reading step 5. Shouldn't that be "step 5 or 6"?

Even then, the flow is unclear to me here:

  * steps 5 and 6 assume a passphrase was entered at step 4, which is
    not the case when only verifying a signature
  * step 6 assumes that the text is signed ("if the signature of the
    text is valid") and encrypted ("The decrypted text appears")


> "[...] your messages using a passphrase with OpenPGP passphrase
> encryption. See the corresponding documentation."


A link on "corresponding documentation" would be much welcome :)
Same on gpgapplet/passphrase_encryption.

On gpgapplet/public-key_encryption:

> "This technique requires you to use public-key encryption and to
> have the secret key for which the message was encrypted."


... sounds wrong: which message was encrypted?
Additionally, it requires having the recipient's public-key.

> "If you receive the error message “The clipboard does not contain
> valid input data”, try to select your text again, starting from
> step 2."


Given step 2 uses Copy, and not mere selection,
I suggest s/to select/to copy/.

> "Otherwise anyone who sees the encrypted text can see who the
> recipients are."


I suggest s/can see/can know/.

> "To paste the encrypted or signed text in another application"


paste ... *into*?

> First, I was wondering about the warning "message was not integrity
> protected" when using passphrase encryption. Does it always appears?
> Is there no way of providing integrity when using a passphrase?


Yes, there is a way, with --symmetric --sign, according to gpg(1).

> See what I'm saying about it on line 73 of
> /doc/encryption_and_privacy/gpgapplet/decrypt_verify.mdwn


... so this is untrue, and should be adapted.

> Then, I'm still sticking to documenting Tails gpgApplet and not
> documenting more generally OpenPGP or GnuPG in Tails (Seahorse, Claws
> mail, etc.) so for example I'm not mentioning the “Manage keys” feature.
> Tell me if I should and I will.


I think it would be great to give a pointer to Seahorse's "Manage
keys" feature somewhere, sometime, but this is not critical to have
this merged => TODO++

> And now the bug reports:


> 1. When decrypting a text encrypted using passphrase encryption, if you
> enter a bad passphrase you have to select the text again to try another
> passphrase. The encrypted text should be kept in the clipboard even if
> the given passphrase is bad, no?


Agreed. Is this a regression?

> 2. When encrypting using several public keys that are not trusted, the
> warning message only mentions one. It should either mention each key in
> a separate dialog box, or all of them in a single dialog box.


Blocking for the merge IMHO.

> On the same topic, shall I explain that this message appears when keys
> are not signed by the user, and how they can sign them? I would say this
> is off-topic for now.


Agreed.

> 3. I found two phrases of the GUI that need to be rephrased.


> “Here is the GnuPG output:” → “Output of GnuPG:”


> See GDP [5]: 4.3 How to Write for Translation, Topic 13
> « Replace the genitive construction with an of structure. »


> “While it were at it, GnuPG also mentionned in passing:” → “Other
> messages provided by GnuPG:”


> See GDP [5]: 1.3 Tone
> « Avoid colloquial language. Colloquial language is difficult to
> translate and usually culture-specific. Stay neutral. »


I guess this is no regression, and I'd be glad to see this fixed for
0.14, but no blocker IMHO.

Cheers!