1.1 --- a/README.txt Sun Oct 21 00:43:40 2012 +0200
1.2 +++ b/README.txt Sun Oct 21 18:41:38 2012 +0200
1.3 @@ -2,7 +2,7 @@
1.4 ------------
1.5
1.6 MoinMessage provides a library for creating, signing, encrypting, decrypting,
1.7 -verifying PGP/GPG content in Python along with mechanisms for updating
1.8 +and 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 @@ -13,7 +13,13 @@
1.13 Initialise a homedir for GPG and configure it using ACL (access control list)
1.14 properties:
1.15
1.16 -./scripts/init_wiki_keyring.sh
1.17 +./scripts/init_wiki_keyring.sh WIKI WEBUSER
1.18 +
1.19 +Here, WIKI should be replaced by the top-level Wiki instance directory, and
1.20 +WEBUSER should be the name of the user under which the Web server operates.
1.21 +
1.22 +Note that this script may need re-running after the homedir has been changed
1.23 +by gpg operations as gpg likes to remove permissions from various files.
1.24
1.25 To be in any way useful, signing keys must be made available within this
1.26 homedir so that incoming messages can have their senders verified.
1.27 @@ -38,6 +44,10 @@
1.28
1.29 gpg --homedir wiki/gnupg --gen-key
1.30
1.31 +For the Wiki environment to be able to use the key, password access must be
1.32 +disabled. This can be done by either not specifying a password or by removing
1.33 +it later using the --edit-key option.
1.34 +
1.35 Export the Wiki's key for encrypting messages sent to the Wiki:
1.36
1.37 gpg --homedir wiki/gnupg --armor --output 0891463A.asc --export 0891463A
1.38 @@ -57,25 +67,66 @@
1.39 moinmessage_gpg_users_page (optional, default is MoinMessageUserDict)
1.40 This provides a mapping from key fingerprints to Moin usernames.
1.41
1.42 + moinmessage_gpg_signing_users_page (optional, default is MoinMessageSigningUserDict)
1.43 + This provides a mapping from Moin usernames to key fingerprints.
1.44 +
1.45 + moinmessage_gpg_recipients_page (optional, default is MoinMessageRecipientsDict)
1.46 + This provides a mapping from recipients to remote URLs and key fingerprints.
1.47 +
1.48 +Fingerprints and Keys
1.49 +---------------------
1.50 +
1.51 +All fingerprints mentioned in the various configuration pages must exclude
1.52 +space characters - that is, the letters and digits must appear together in a
1.53 +continuous block of text - and refer to keys available in the Wiki homedir.
1.54 +
1.55 The Fingerprint-to-Username Mapping
1.56 -----------------------------------
1.57
1.58 -The mapping from fingerprints to usernames is a WikiDict page having the
1.59 -following general format:
1.60 +The mapping from fingerprints to usernames typically defined by the
1.61 +MoinMessageUserDict page is a WikiDict having the following general format:
1.62
1.63 fingerprint:: username
1.64
1.65 -Each fingerprint must exclude space characters and correspond to the
1.66 -fingerprint shown for a key in the available key listing generated above.
1.67 +Each fingerprint corresponds to a key used by a person wanting to send
1.68 +messages to the Wiki to sign such messages.
1.69
1.70 Each username must correspond to a registered user in the Wiki.
1.71
1.72 +The Username-to-Signing Key Mapping
1.73 +-----------------------------------
1.74 +
1.75 +The mapping from usernames to fingerprints typically defined by the
1.76 +MoinMessageSigningUserDict page is a WikiDict having the following general
1.77 +format:
1.78 +
1.79 + username:: fingerprint
1.80 +
1.81 +Each fingerprint corresponds to a key available in the Wiki's GPG homedir
1.82 +generated for the purpose of signing the specified user's messages. Such a key
1.83 +is not the same as one used by a person to send messages to the Wiki since
1.84 +only the public key used to verify such messages should be known to the Wiki.
1.85 +
1.86 +The Recipients Mapping
1.87 +----------------------
1.88 +
1.89 +The mapping from recipients to remote URLs and fingerprints typically defined
1.90 +by the MoinMessageRecipientsDict page is a WikiDict having the following
1.91 +general format:
1.92 +
1.93 + recipient:: URL fingerprint
1.94 +
1.95 +Each URL must refer to a resource that can accept MoinMessage content.
1.96 +
1.97 +Each fingerprint corresponds to a key used by the remote site (as identified
1.98 +by the URL) for the decryption of messages.
1.99 +
1.100 Quick Start: Signing, Encrypting and Sending Messages
1.101 -----------------------------------------------------
1.102
1.103 To send a message signed and encrypted to a resource on localhost:
1.104
1.105 -python tests/test_send.py 1C1AAF83 0891463A localhost /wiki/ShareTest \
1.106 +python tests/test_send.py 1C1AAF83 0891463A http://localhost/wiki/ShareTest \
1.107 'An update to the Wiki.' 'Another update.'
1.108
1.109 Here, the first identifier is a reference to the signing key (over which you
1.110 @@ -83,7 +134,8 @@
1.111 encryption key (which is a public key published for the Wiki).
1.112
1.113 This needs password protection to be removed from the secret key in the Web
1.114 -server environment, and so uses a modified trust model when invoking gpg.
1.115 +server environment. It also uses a modified trust model when invoking gpg in
1.116 +order to avoid complaints about the identity of the sender during encryption.
1.117
1.118 Below, the mechanisms employed are illustrated through the use of the other
1.119 test programs.
1.120 @@ -126,9 +178,7 @@
1.121 Signing and Encrypting
1.122 ----------------------
1.123
1.124 -Send a message signed and encrypted:
1.125 -
1.126 -python tests/test_send.py 1C1AAF83 0891463A localhost /wiki/ShareTest
1.127 +Sign and encrypt a message:
1.128
1.129 python tests/test_message.py 'An update to the Wiki.' 'Another update.' \
1.130 | python tests/test_sign.py 1C1AAF83 \
1.131 @@ -150,7 +200,7 @@
1.132 To post a signed and/or encrypted message, output from the above activities
1.133 can be piped into the following command:
1.134
1.135 -python tests/test_post.py localhost /wiki/ShareTest
1.136 +python tests/test_post.py http://localhost/wiki/ShareTest
1.137
1.138 Here, the resource "/wiki/ShareTest" on localhost is presented with the
1.139 message.