--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/OpenPGP.mdwn	Sun May 14 20:58:00 2017 +0300
@@ -0,0 +1,77 @@
+[[!meta title="MCabber OpenPGP support"]]
+
+[[!toc]]
+
+MCabber supports OpenPGP by implementing the [[!xep 0027]] protocol. When used,
+status messages (presence) are signed and message bodies can be encrypted.
+
+When a client supports OpenPGP, it signs presences (status messages). This is
+the only way for a client to advertise its support of PGP. Messages are
+encrypted when sent to such clients.
+
+There is currently no indication of whether the message being sent will be
+encrypted (or is there?) It is also unknown what happens when a message is
+sent to a client with multiple active resources, when not all of them support
+encryption or if they use different keys (please document).
+
+MCabber supports OpenPGP since version 0.9.0. This page explains how to set it
+up.
+
+# Building mcabber with OpenPGP support
+
+Note: You need `libgpgme` > 1.0.0 (for example, `libgpgme11` & `libgpgme11-dev`
+in Debian) to build mcabber with OpenPGP support.
+
+# Enabling OpenPGP
+
+Once mcabber is built with PGP support, you will have to set it up.
+
+In the configuration file, enable `pgp` and set `pgp_private_key` to your key
+id.  Your key id can be found with the following command:
+
+    gpg --list-keys --keyid-format long your_name
+
+Example (in `$HOME/.mcabber/mcabberrc`):
+
+    set pgp = 1
+    set pgp_private_key = "E3E6A9C1A6A013D3"
+
+# Encrypting messages
+
+Now when you start mcabber, it should ask for your passphrase (unless you put
+it in your configuration file or you use `gpg-agent`).
+
+If you want to know if a contact is using PGP, select the contact and use
+`/info`. If (s)he is, it should display something like
+
+    PGP key id: E2C4C9A1601A5A4
+    Last PGP signature: unknown
+
+The signature is "unknown", because we don't have the contact's key. We could
+get it with `gpg`, for example.
+
+    gpg --recv-keys E2C4C9A1601A5A4
+
+Then, wait for the next presence message.
+
+If the contact has your key and you have their key, you should have
+bidirectional encrypted messages.
+
+# Per-contact settings
+
+You can provide a PGP key to be used for a given Jabber user or disable PGP on
+a per-account basis, using the command `/pgp`. If you provide a KeyId for a
+contact, it will be compared to the key the contact uses to sign their
+presence/messages and it will be used for all outgoing encrypted messages (by
+default, mcabber will use the contact signature's key).
+
+    /pgp disable foo@bar.org
+    /pgp setkey bar@foo.net C9940A9BB0B92210
+
+The command `/pgp` can be used in the configuration file (without the leading /).
+
+Example (in `$HOME/.mcabber/mcabberrc`): 
+
+    pgp disable foo@bar.org
+    pgp setkey bar@foo.net C9940A9BB0B92210
+