1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/README.txt Sun Oct 21 00:43:40 2012 +0200
1.3 @@ -0,0 +1,156 @@
1.4 +Introduction
1.5 +------------
1.6 +
1.7 +MoinMessage provides a library for creating, signing, encrypting, decrypting,
1.8 +verifying PGP/GPG content in Python along with mechanisms for updating
1.9 +MoinMoin Wiki instances with such content such that contributors can be
1.10 +identified from their PGP signatures and such details used to authenticate
1.11 +their contributions.
1.12 +
1.13 +Configuring GPG for a Wiki
1.14 +--------------------------
1.15 +
1.16 +Initialise a homedir for GPG and configure it using ACL (access control list)
1.17 +properties:
1.18 +
1.19 +./scripts/init_wiki_keyring.sh
1.20 +
1.21 +To be in any way useful, signing keys must be made available within this
1.22 +homedir so that incoming messages can have their senders verified.
1.23 +
1.24 +To see the keys available to you in your own environment:
1.25 +
1.26 +gpg --list-keys --with-fingerprint
1.27 +
1.28 +The full fingerprints are used when defining a user mapping in the Wiki, and
1.29 +the --with-fingerprint option is used to show them. Otherwise, only the last
1.30 +eight characters of the fingerprints are shown.
1.31 +
1.32 +Export the public key used when signing messages from your own environment:
1.33 +
1.34 +gpg --armor --output 1C1AAF83.asc --export 1C1AAF83
1.35 +
1.36 +Import the key into the Wiki's GPG homedir:
1.37 +
1.38 +gpg --homedir wiki/gnupg --import 1C1AAF83.asc
1.39 +
1.40 +For the Wiki to receive encrypted data, a key for the Wiki must be created:
1.41 +
1.42 +gpg --homedir wiki/gnupg --gen-key
1.43 +
1.44 +Export the Wiki's key for encrypting messages sent to the Wiki:
1.45 +
1.46 +gpg --homedir wiki/gnupg --armor --output 0891463A.asc --export 0891463A
1.47 +
1.48 +This exported key can now be imported into your own environment:
1.49 +
1.50 +gpg --import 0891463A.asc
1.51 +
1.52 +Configuring the Wiki
1.53 +--------------------
1.54 +
1.55 +In the Wiki configuration, define the following settings:
1.56 +
1.57 + moinmessage_gpg_homedir
1.58 + This sets the path to the homedir initialised above.
1.59 +
1.60 + moinmessage_gpg_users_page (optional, default is MoinMessageUserDict)
1.61 + This provides a mapping from key fingerprints to Moin usernames.
1.62 +
1.63 +The Fingerprint-to-Username Mapping
1.64 +-----------------------------------
1.65 +
1.66 +The mapping from fingerprints to usernames is a WikiDict page having the
1.67 +following general format:
1.68 +
1.69 + fingerprint:: username
1.70 +
1.71 +Each fingerprint must exclude space characters and correspond to the
1.72 +fingerprint shown for a key in the available key listing generated above.
1.73 +
1.74 +Each username must correspond to a registered user in the Wiki.
1.75 +
1.76 +Quick Start: Signing, Encrypting and Sending Messages
1.77 +-----------------------------------------------------
1.78 +
1.79 +To send a message signed and encrypted to a resource on localhost:
1.80 +
1.81 +python tests/test_send.py 1C1AAF83 0891463A localhost /wiki/ShareTest \
1.82 + 'An update to the Wiki.' 'Another update.'
1.83 +
1.84 +Here, the first identifier is a reference to the signing key (over which you
1.85 +have complete control), and the second identifier is a reference to the
1.86 +encryption key (which is a public key published for the Wiki).
1.87 +
1.88 +This needs password protection to be removed from the secret key in the Web
1.89 +server environment, and so uses a modified trust model when invoking gpg.
1.90 +
1.91 +Below, the mechanisms employed are illustrated through the use of the other
1.92 +test programs.
1.93 +
1.94 +Signing
1.95 +-------
1.96 +
1.97 +Prepare a message signed with a "detached signature" (note that this does not
1.98 +seem to be what gpg calls a detached signature with the --detach-sig option):
1.99 +
1.100 + python tests/test_message.py 'An update to the Wiki.' 'Another update.' \
1.101 +| python tests/test_sign.py 1C1AAF83
1.102 +
1.103 +The complicated recipe based on the individual operations is as follows:
1.104 +
1.105 + python tests/test_message.py 'An update to the Wiki.' 'Another update.' \
1.106 +> test.txt \
1.107 +&& cat test.txt \
1.108 +| gpg --armor -u 1C1AAF83 --detach-sig \
1.109 +| python tests/test_sign_wrap.py test.txt
1.110 +
1.111 +Encryption
1.112 +----------
1.113 +
1.114 +Prepare a message with an encrypted payload using the above key:
1.115 +
1.116 + python tests/test_message.py 'An update to the Wiki.' 'Another update.' \
1.117 +| python tests/test_encrypt.py 0891463A
1.118 +
1.119 +The complicated recipe based on the individual operations is as follows:
1.120 +
1.121 + python tests/test_message.py 'An update to the Wiki.' 'Another update.' \
1.122 +> test.txt \
1.123 +&& cat test.txt \
1.124 +| gpg --armor -r 0891463A --encrypt --trust-model always \
1.125 +| python tests/test_encrypt_wrap.py
1.126 +
1.127 +Note that "--trust-model always" is used only to avoid prompting issues.
1.128 +
1.129 +Signing and Encrypting
1.130 +----------------------
1.131 +
1.132 +Send a message signed and encrypted:
1.133 +
1.134 +python tests/test_send.py 1C1AAF83 0891463A localhost /wiki/ShareTest
1.135 +
1.136 + python tests/test_message.py 'An update to the Wiki.' 'Another update.' \
1.137 +| python tests/test_sign.py 1C1AAF83 \
1.138 +| python tests/test_encrypt.py 0891463A
1.139 +
1.140 +The complicated recipe based on the individual operations is as follows:
1.141 +
1.142 + python tests/test_message.py 'An update to the Wiki.' 'Another update.' \
1.143 +> test.txt \
1.144 +&& cat test.txt \
1.145 +| gpg --armor -u 1C1AAF83 --detach-sig \
1.146 +| python tests/test_sign_wrap.py test.txt \
1.147 +| gpg --armor -r 0891463A --encrypt --trust-model always \
1.148 +| python tests/test_encrypt_wrap.py
1.149 +
1.150 +Posting a Message
1.151 +-----------------
1.152 +
1.153 +To post a signed and/or encrypted message, output from the above activities
1.154 +can be piped into the following command:
1.155 +
1.156 +python tests/test_post.py localhost /wiki/ShareTest
1.157 +
1.158 +Here, the resource "/wiki/ShareTest" on localhost is presented with the
1.159 +message.