From d676c2ee7b6207ff0b2a7b384052ab07c08bf43a Mon Sep 17 00:00:00 2001 From: mathieui Date: Sat, 13 Apr 2013 22:33:06 +0200 Subject: Move the plugins documentation (use automodule directive & docstrings) --- plugins/gpg/__init__.py | 104 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) (limited to 'plugins/gpg') diff --git a/plugins/gpg/__init__.py b/plugins/gpg/__init__.py index 9fa8ee13..c6945e18 100644 --- a/plugins/gpg/__init__.py +++ b/plugins/gpg/__init__.py @@ -1,3 +1,107 @@ +""" +This plugin implements the `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 removed 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 to know that you are +supporting GPG encryption. To do that, use the :term:`plugins_autoload` configuration +option. + +You need to create a plugin configuration file. Create a file named :file:`gpg.cfg` +into your plugins configuration directory (:file:`~/.config/poezio/plugins` by +default), and fill it like this: + +.. code-block:: ini + + [gpg] + keyid = 091F9C78 + passphrase = your OPTIONAL passphrase + + [keys] + example@jabber.org = E3CFCDE2 + juliet@xmpp.org = EF27ABCD + +The ``gpg`` 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 + +.. code-block:: bash + + gpg --gen-key + +and follow 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 + +.. code-block:: bash + + gpg --list-keys + +You will get something like + +.. code-block:: none + + pub 4096R/01234567 2011-11-11 + uid Your Name Here (comment) + sub 4096R/AAFFBBCC 2011-11-11 + + pub 2048R/12345678 2011-11-12 [expire: 2011-11-22] + uid A contact’s name (comment) + sub 2048R/FFBBAACC 2011-11-12 [expire: 2011-11-22] + +In this example, the keyids are ``01234567`` and ``12345678``. + +Share your key +~~~~~~~~~~~~~~ +Use: + +.. code-block:: bash + + gpg --send-keys --keyserver pgp.mit.edu + +to upload you public key on a public server. + +.. _XEP-0027: http://xmpp.org/extensions/xep-0027.html + +""" from gpg import gnupg from sleekxmpp.xmlstream.stanzabase import JID -- cgit v1.2.3