Add a doc page for the GPG plugin.

1 files changed, 100 insertions, 0 deletions

diff --git a/doc/en/plugins/gpg.txt b/doc/en/plugins/gpg.txt
new file mode 100644
index 00000000..31f2b80d
--- /dev/null
+++ b/doc/en/plugins/gpg.txt
@@ -0,0 +1,100 @@
+GPG
+===
+
+This plugin implements the
+link:http://xmpp.org/extensions/xep-0027.html[XEP-0027] “Current Jabber OpenPGP
+Usage”.
+
+This is a plugin used to encrypt one-to-one conversation using the PGP
+encryption method. You can use it if you want really good privacy. Without this
+encryption, your messages are encrypted *at least* from your client (poezio) to
+your server. The message is decrypted by your server and you cannot control the
+encryption method of your messages from your server to your contact’s server
+(unless you are your own server’s administrator), nor from your contact’s
+server to your contact’s client.
+
+This plugin does end-to-end encryption. This means that *only* your contact can
+decrypt your messages, and it is fully encrypted during *all* its travel
+through the internet.
+
+Note that if you are having an encrypted conversation with a contact, you can
+*not* send XHTML-IM messages to him. They will be remove and be replaced by
+plain text messages.
+
+Installation and configuration
+------------------------------
+
+You should autoload this plugin, as it will send your signed presence directly
+on login, making it easier for your contact’s clients that you are supporting
+GPG encryption. To do that, use the _plugins_autoload_ configuration option.
+
+You need to create a plugin configuration file. Create a file named _gpg.cfg_
+into your plugins configuration directory (_~/.config/poezio/plugins_ by
+default), and fill it like this:
+
+[source,python]
+---------------------------------------------------------------------
+[Poezio]
+keyid = 091F9C78
+passphrase = your OPTIONAL passphrase
+
+[keys]
+example@jabber.org = E3CFCDE2
+juliet@xmpp.org = EF27ABCD
+---------------------------------------------------------------------
+
+The *Poezio* section is about your key. You need to specify the keyid, for the
+key you want to use. You can as well provide a passphrase. If you don’t, you
+should use a gpg agent or something like that that will ask your passphrase
+whenever you need it.
+
+The *keys* section contains your contact’s id keys. For each contact you want
+to have encrypted conversations with, add her/his JID associated with the keyid
+of his/her key.
+
+And that’s it, now you need to talk directly to the *full* jid of your
+contacts. Poezio doesn’t let you encrypt messages whom recipients is a bare
+JID.
+
+Additionnal information on GnuPG
+--------------------------------
+
+Create a key
+~~~~~~~~~~~~
+
+To create a personal key, use
+==================
+gpg --gen-key
+==================
+and fill the instructions
+
+
+Keyid
+~~~~~
+The keyid (required in the gpg.cfg configuration file) is a 8 character-long
+key. You can get the ones you created or imported by using the command
+=======================
+gpg --list-keys
+=======================
+You will get something like
+
+---------------------------------------------------------------------
+pub   4096R/01234567 2011-11-11
+uid                  Your Name Here (comment) <email@example.org>
+sub   4096R/AAFFBBCC 2011-11-11
+
+pub   2048R/12345678 2011-11-12 [expire: 2011-11-22]
+uid                  A contact’s name (comment) <fake@fake.fr>
+sub   2048R/FFBBAACC 2011-11-12 [expire: 2011-11-22]
+---------------------------------------------------------------------
+
+In this example, the keyids are *01234567* and  *12345678*.
+
+Share your key
+~~~~~~~~~~~~~~
+Use
+===========================
+gpg --send-keys --keyserver pgp.mit.edu <keyid>
+===========================
+to upload you public key on a public server.
+