Bug #6568

Mention Seahorse in documentation

Added by sajolida 2014-01-05 04:21:51 . Updated 2019-03-08 16:03:08 .

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

50%

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

Starter:
Affected tool:
Deliverable for:

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.

Subtasks

Related issues

Related to Tails - Bug #9404: Document how to generate strong OpenPGP keys with Seahorse instead of Claws Mail Resolved 2015-05-14
Related to Tails - Feature #9407: Mention OpenPGP best practices Confirmed 2015-05-15
Related to Tails - Feature #15174: Mention Enigmail in documentation Rejected 2018-01-16
Related to Tails - Bug #16221: Stop using DocBook-style CSS classes In Progress 2018-12-13
Related to Tails - Bug #17183: Seahorse fails to import PGP public key Confirmed

History

#1 Updated by BitingBird 2014-03-05 17:00:43

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 2014-03-05 17:23:23

  • Description updated

#3 Updated by BitingBird 2014-03-05 18:52:08

  • Description updated

#4 Updated by sajolida 2014-03-06 10:40:32

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/

#5 Updated by BitingBird 2014-03-24 16:46:38

Written to seahorse developers list https://mailman.boum.org/pipermail/tails-dev/2014-March/005262.html

#6 Updated by BitingBird 2014-04-10 23:35:38

Got answers!

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

#7 Updated by intrigeri 2014-06-21 15:26:29

#8 Updated by sajolida 2015-01-08 13:57:09

  • Description updated

#9 Updated by BitingBird 2015-01-28 14:54:01

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

#10 Updated by BitingBird 2015-01-30 06:18:44

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

#11 Updated by BitingBird 2015-01-30 06:19:04

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

#12 Updated by intrigeri 2015-01-30 14:18:51

  • 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 2015-01-30 19:14:55

Thank you !

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

#14 Updated by BitingBird 2015-01-31 11:36:14

  • 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 2015-02-01 08:48:17

> 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 2015-02-21 17:46:56

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

#17 Updated by BitingBird 2015-03-03 13:26:48

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

#18 Updated by BitingBird 2015-03-12 22:37:40

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 2015-03-15 18:31:06

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

#20 Updated by BitingBird 2015-03-15 18:31:21

#21 Updated by BitingBird 2015-04-07 01:59:36

  • % 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 Feature #5316.

#22 Updated by BitingBird 2015-05-04 20:55:01

  • 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 Feature #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 2015-05-11 18:44:18

  • 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 2015-05-11 18:48:58

  • 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 2015-07-05 04:47:56

  • Target version set to Tails_1.5

#26 Updated by BitingBird 2015-07-06 10:32:20

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

#27 Updated by BitingBird 2015-07-24 03:54:39

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

#28 Updated by BitingBird 2015-07-24 03:56:02

#29 Updated by BitingBird 2015-08-03 09:29:54

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

#30 Updated by BitingBird 2015-08-05 08:09:44

Finally pushed :)

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

#31 Updated by BitingBird 2015-08-12 06:03:13

  • 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 2015-08-18 09:17:50

  • 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 2015-09-22 15:00:33

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

#34 Updated by BitingBird 2015-11-17 09:58:05

  • Target version changed from Tails_1.7 to 246

#35 Updated by sajolida 2015-11-27 04:47:28

  • Target version changed from 246 to Tails_2.0

#36 Updated by BitingBird 2016-01-27 16:35:54

  • Target version deleted (Tails_2.0)

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

#37 Updated by Anonymous 2017-06-30 14:05:25

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 Anonymous 2017-06-30 14:05:58

  • Assignee deleted (BitingBird)

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

#39 Updated by Anonymous 2018-01-15 11:55:56

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 Anonymous 2018-01-15 11:56:17

  • Assignee set to sajolida

See my previous comment.

#41 Updated by Anonymous 2018-01-15 11:56:29

  • Starter deleted (Yes)

#42 Updated by Anonymous 2018-01-16 16:49:29

#43 Updated by Anonymous 2018-08-16 12:46:13

Is this still something we want to do?

#44 Updated by sajolida 2018-08-16 19:06:08

  • 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 Anonymous 2019-03-08 16:03:08

  • Status changed from In Progress to Confirmed

#46 Updated by sajolida 2020-03-18 16:59:21

  • related to Bug #16221: Stop using DocBook-style CSS classes added

#47 Updated by sajolida 2020-03-18 17:07:26

  • related to Bug #17183: Seahorse fails to import PGP public key added