Project

General

Profile

Bug #6568

Feature #5316: Improve OpenPGP documentation

Mention Seahorse in documentation

Added by sajolida almost 6 years ago. Updated 8 months ago.

Status:
Confirmed
Priority:
Low
Assignee:
-
Category:
-
Target version:
-
Start date:
01/05/2014
Due date:
% Done:

50%

Feature Branch:
bitingbird:doc/6568-seahorse
Type of work:
End-user documentation
Blueprint:
Starter:
Affected tool:

Description

At the moment, Seahorse doesn't have a page in the documentation. We have received reports from users who were thinking that the gpgApplet was the recommended key manager in Tails, which is not the case.

This task implies:

  • Linking upstream documentation.
  • Identifying what is specific to Tails regarding Seahorse.
  • Create a page and linking it from the Encryption & Privacy section, and at least gpgApplet documentation.

Related issues

Related to Tails - Bug #9404: Document how to generate strong OpenPGP keys with Seahorse instead of Claws Mail Resolved 05/14/2015
Related to Tails - Feature #9407: Mention OpenPGP best practices Confirmed 05/15/2015
Related to Tails - Feature #15174: Mention Enigmail in documentation Rejected 01/16/2018

History

#1 Updated by BitingBird over 5 years ago

There is some documentation there: https://help.gnome.org/users/seahorse/stable/seahorse-getting-started.html.en but they are planning on moving it at some point.

#2 Updated by BitingBird over 5 years ago

  • Description updated (diff)

#3 Updated by BitingBird over 5 years ago

  • Description updated (diff)

#4 Updated by sajolida over 5 years ago

This online documentation is apparently for a quite much older version of Seahorse. I went through it pretty quickly and found several differences. For example, the OpenPGP key types changed, they recommend DSA ElGamal while the current best practice is to do RSA (I think).

Note that when we will change to GNOME 3, this interface would changed totally and linking to the GNOME 2 documentation will be out of question.

So I would first check whether there is also an online doc for Seahorse in GNOME 3. Then it would be ok to link to this outdated GNOME 2 documentation until Tails Wheezy (1.1), and then switch the link to the GNOME 3 documentation.

For an example of how we link to external documentation for a given program, the most recent page doing that is the Pidgin one:

https://tails.boum.org/doc/anonymous_internet/pidgin/

#6 Updated by BitingBird over 5 years ago

Got answers!

https://help.gnome.org/users/seahorse/ is where we'll find documentation, version by version.

#7 Updated by intrigeri over 5 years ago

#8 Updated by sajolida almost 5 years ago

  • Description updated (diff)

#9 Updated by BitingBird almost 5 years ago

  • Assignee set to BitingBird
  • Target version set to Tails_1.3.2

#10 Updated by BitingBird almost 5 years ago

What version of Seahorse is in Tails ? I don't know where to find the information...

#11 Updated by BitingBird almost 5 years ago

  • Assignee changed from BitingBird to intrigeri
  • QA Check set to Info Needed

#12 Updated by intrigeri almost 5 years ago

  • Assignee changed from intrigeri to BitingBird
  • QA Check deleted (Info Needed)

BitingBird wrote:

What version of Seahorse is in Tails ? I don't know where to find the information...

https://tails.boum.org/torrents/files/tails-i386-1.2.3.packages :)

#13 Updated by BitingBird almost 5 years ago

Thank you !

So, the correct link for documentation is https://help.gnome.org/users/seahorse/3.4/

#14 Updated by BitingBird almost 5 years ago

  • Status changed from Confirmed to In Progress
  • Assignee changed from BitingBird to sajolida
  • QA Check set to Info Needed

https://fedoraproject.org/wiki/Creating_GPG_Keys has a short, efficient documentation (the part with Gnome uses Seahorse).

Do we want to only link to upstream documentation, or re-document things? In the first case, I can submit my page, in the second, I'll probably steal a lot from the Fedora page.

#15 Updated by intrigeri almost 5 years ago

Do we want to only link to upstream documentation, or re-document things?

Link to upstream if it's good enough. Otherwise, improve upstream doc :)

#16 Updated by BitingBird over 4 years ago

  • Assignee changed from sajolida to BitingBird
  • QA Check deleted (Info Needed)
  • Feature Branch set to bitingbird:doc/6568-seahorse

#17 Updated by BitingBird over 4 years ago

  • Target version changed from Tails_1.3.2 to Tails_1.4

#18 Updated by BitingBird over 4 years ago

When this is done, a link should be added from persistence/configure and doc/first_steps/introduction_to_gnome_and_the_tails_desktop section "desktop shortcuts"

#19 Updated by BitingBird over 4 years ago

  • Related to deleted (Feature #5316: Improve OpenPGP documentation)

#20 Updated by BitingBird over 4 years ago

  • Parent task set to #5316

#21 Updated by BitingBird over 4 years ago

  • % Done changed from 0 to 20

So, I have a page about Seahorse that looks good. I'll look during the next days at how to integrate it with #5316.

#22 Updated by BitingBird over 4 years ago

  • Assignee changed from BitingBird to sajolida
  • % Done changed from 20 to 50
  • QA Check set to Ready for QA

Well, let's merge this page, and we'll see about #5316 probably in 1.4.1. It would already be an improvement, since lots of users ask questions about managing their PGP keys (at least on irc).

Built, looks good - please review :)

#23 Updated by sajolida over 4 years ago

  • Target version changed from Tails_1.4 to Tails_1.4.1

Thanks for working on this.

Quite often, I find that you are copying and pasting stuff too much without editing or being critical enough about what you're pasting and whether it needs improvement in the context. This time it's too big for me not to mention it.

Here are a few remarks to help you start improving on that, but please don't limit yourself to them:

  • What do you mean by "security tokens"?
  • Do we want to call this app "Seahorse" or "Passwords and Keys"? Then do this consistently.
  • Do we want to recommend Seahorse for password management?
  • Do we want to recommend Seahorse for managing SSH keys? Then do this consistently.

Also you're not addressing "Create a page and linking it from the Encryption & Privacy section, and at least gpgApplet documentation".

So I'm postponing...

#24 Updated by sajolida over 4 years ago

  • Assignee changed from sajolida to BitingBird
  • Target version deleted (Tails_1.4.1)
  • QA Check changed from Ready for QA to Dev Needed

#25 Updated by BitingBird over 4 years ago

  • Target version set to Tails_1.5

#26 Updated by BitingBird over 4 years ago

Worked on that, but I have to wait until git cooperates to push :)

#27 Updated by BitingBird over 4 years ago

  • Related to Bug #9404: Document how to generate strong OpenPGP keys with Seahorse instead of Claws Mail added

#28 Updated by BitingBird over 4 years ago

#29 Updated by BitingBird over 4 years ago

  • Target version changed from Tails_1.5 to Tails_1.6

#30 Updated by BitingBird over 4 years ago

Finally pushed :)

I'll review my work before setting as ready for QA.

#31 Updated by BitingBird over 4 years ago

  • Assignee changed from BitingBird to sajolida
  • QA Check changed from Dev Needed to Ready for QA

So, I improved some things you mentionned, but I'm still at a lost regarding others.

The "security tokens" things comes from the Seahorse documentation. I don't like or even understand the formulation, but it feels weird to ignore completely their doc, even though it's bad. Shall we remove the first paragraph completely?

I guess it still won't be merged directly, but I think it's better. Please review :)

#32 Updated by sajolida about 4 years ago

  • Assignee changed from sajolida to BitingBird
  • QA Check changed from Ready for QA to Dev Needed

Thanks for following up on this. I appreciate the small commits and the better integration with the rest of the doc. I think you're doing right by naming everything "Password and Keys" though I'm not use to that kind of stuff :)

Here a few more proposals:

  • Did you consider saying "Manage OpenPGP and SSH keys" instead of "Manage OpenPGP keys and SSH keys"?
  • Forget about the "security tokens", and sorry for the rethorical question last time. I think this means "piece of cryptographic data" in this context. But it's blurry and jargony and nothing we're mentioning elsewhere. So I would simply drop that notion.
  • I think the section "helping to keep your information secure on your
    +computer, and secure when you send information over a network" is gibberish in the context of Tails: "secure on the computer" is not relevant as the only way you can store are encrypted in persistence (and not "on the computer" as such), and "secure when you send information over a network", I'm not sure what this refers to but I don't think they provide additional security on top of what we do already and in the worse case this sentence can create a false sense of alarm ("Is it not secure otherwise?").
  • I would not mention explicitely that Seahorse can be used as a password manager as we have KeePassX for that. Still, as you did already, we have to mention passwords somewhere as that's in the name of the software now. But I would maybe say that people should use KeePassX instead (and not also) for password management. Taking this outside of the list of features of Seahorse, maybe as a single paragraph or a note.
  • I'm not sure listing specific pages of the Seahorse documentation is worth it. The index of https://help.gnome.org/users/seahorse/3.4/ is pretty short and complete. Then I would change your introductory sentence from "See the [official documentation]" to "Refer to the [official documentation] to learn how to create, import, and export OpenPGP and SSH keys".

#33 Updated by BitingBird about 4 years ago

  • Target version changed from Tails_1.6 to Tails_1.7

#34 Updated by BitingBird almost 4 years ago

  • Target version changed from Tails_1.7 to 246

#35 Updated by sajolida almost 4 years ago

  • Target version changed from 246 to Tails_2.0

#36 Updated by BitingBird almost 4 years ago

  • Target version deleted (Tails_2.0)

No date. If somebody wants to steal it, be welcome :)

#37 Updated by u over 2 years ago

Ok, so here apparently the review failed to motivate anybody to bring this to an end :(
There is a branch, probably very outdated, but it would be nice to import what was done.

Also add a link to https://tails.boum.org/doc/encryption_and_privacy/gpgapplet/ to the new page.

#38 Updated by u over 2 years ago

  • Assignee deleted (BitingBird)

Unassigning BitingBird who said she would not work on this a year ago.

#39 Updated by u almost 2 years ago

Assigning this to @sajolida. IMO we should make a decision on:

- what default GPG key manager do we want to advertise? (Seahorse, Enigmail)
- Polish and merge the branch proposed by BitingBird

-> Please reassign to another of our tech writers if you wish!

#40 Updated by u almost 2 years ago

  • Assignee set to sajolida

See my previous comment.

#41 Updated by u almost 2 years ago

  • Starter deleted (Yes)

#42 Updated by u almost 2 years ago

#43 Updated by u about 1 year ago

Is this still something we want to do?

#44 Updated by sajolida about 1 year ago

  • Assignee deleted (sajolida)
  • Priority changed from Normal to Low

Why not... But I don't think we'll be able to work on this as part of our core budget any time soon as our plate is already quite full with things that impact way more people that OpenPGP users.

So yeah, let's at least put this in Priority: Low.

#45 Updated by u 8 months ago

  • Status changed from In Progress to Confirmed

Also available in: Atom PDF