On 08/10/12 14:01, intrigeri wrote:
> 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?
The first one has already been reported, the second was not a bug, and
the third is fixed already.
> 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.
All the changes are it commit e41bea4.
> 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.
Yes. That's no good, indeed. I'm changing it to "Encrypt and sign text
using public-key encryption".
> s/Javascript/JavaScript
Thanks.
>> "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*.
I thought about that and decided for present tense. First because, the
manual of styles I've read, all recommend using the present tense over
past tenses and actually the text is (still) encrypted and is (still)
signed. We're not only talking about an action in the past but about
present charatesitics of the text. But I'm not 100 % sure and if that
ends up being confusing I would not be against using “was” instead.
>> "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.
Explicit “Copy” is not needed and selecting the text is enough. But I
decided add this step because from my experience, people new to Linux
are confused about the fact that only selecting text copies it to the
clipboard. I felt it would be more clear, as a workflow, to explain an
explicit action to copy to the clipboard. People knowing that selecting
is enough in this context would probably be able to figure it out by
themselves, and otherwise they won't be hurt by doing an explicit copy.
> 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.
Right. I'm removing it. I put it in part because I wanted to show what a
PGP message looked like and explicity that the selection had to include
the lines -----BEGIN PGP MESSAGE-----. But that should not be done only
in the screenshot actually, so I'm adding a line to explain that and
removing the screenshot.
>> "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.
I'm changing everything to Tails gpgApplet.
> There are some inconsistencies, too, between "click $WIDGET" and
> "click on $WIDGET". I'm not sure this is on purpose.
I'm fixing this. GDP A.4 says:
- Click on: Use this verb when you refer to most interactive elements in
the GNOME Desktop
- Click: Use this verb when you refer to frequently-used command
buttons, for example: OK, Cancel
>> "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?
Right, I'm adding:
« c. If no secret key for which the text was encrypted is available in
your keyring, a GnuPG error message appears that mentions <span
class="guilabel">decryption failed: secret key not available</span>. »
>> "Click on the Authorize to use"
>
> "Authorize button", perhaps?
Sure.
>> "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"?
Yes, it should be step 6. I had a markdown formatting issue that made
two steps 1 in the rendered page.
> 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")
Ok, I'm changing many things in this section that should solve all those
issues.
>> "[...] 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.
Broken links. Fixed.
> 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.
Sure, I remove the second part of the sentence that doesn't make sense
now that the “Decrypt and Verify” page is separate.
>> "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/.
Sure.
>> "Otherwise anyone who sees the encrypted text can see who the
>> recipients are."
>
> I suggest s/can see/can know/.
Sure.
>> "To paste the encrypted or signed text in another application"
>
> paste ... *into*?
Ok.
>> 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.
Remove for the moment. See anonym's email.
>> 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++
I'm creating a ticket on improving OpenPGP documentation in general.
>> 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?
Apparently not.
>> 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.
There's no bug indeed: one of the public key was from a key pair I had,
so it was trusted automatically ;)
>> 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.
Cool.
>> 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.
Fixed already by anonym.
