# HG changeset patch # User Paul Boddie # Date 1373754753 -7200 # Node ID a75ee917ed0231b7d649e923bfcb9c8622270b28 # Parent 3a244796f64ddd1d0807fa9172f3abc3a7e8362a Switched "Wiki" to "wiki"; improved the message-signing WikiDict description. diff -r 3a244796f64d -r a75ee917ed02 README.txt --- a/README.txt Wed Jul 10 18:46:28 2013 +0200 +++ b/README.txt Sun Jul 14 00:32:33 2013 +0200 @@ -3,7 +3,7 @@ MoinMessage provides a library for creating, signing, encrypting, decrypting, and verifying PGP/GPG content in Python along with mechanisms for updating -MoinMoin Wiki instances with such content such that contributors can be +MoinMoin wiki instances with such content such that contributors can be identified from their PGP signatures and such details used to authenticate their contributions. @@ -15,7 +15,7 @@ ./scripts/init_wiki_keyring.sh WIKI WEBUSER -Here, WIKI should be replaced by the top-level Wiki instance directory, and +Here, WIKI should be replaced by the top-level wiki instance directory, and WEBUSER should be the name of the user under which the Web server operates. Note that this script may need re-running after the homedir has been changed @@ -28,7 +28,7 @@ gpg --list-keys --with-fingerprint -The full fingerprints are used when defining a user mapping in the Wiki, and +The full fingerprints are used when defining a user mapping in the wiki, and the --with-fingerprint option is used to show them. Otherwise, only the last eight characters of the fingerprints are shown. @@ -36,19 +36,19 @@ gpg --armor --output 1C1AAF83.asc --export 1C1AAF83 -Import the key into the Wiki's GPG homedir: +Import the key into the wiki's GPG homedir: gpg --homedir wiki/gnupg --import 1C1AAF83.asc -For the Wiki to receive encrypted data, a key for the Wiki must be created: +For the wiki to receive encrypted data, a key for the wiki must be created: gpg --homedir wiki/gnupg --gen-key -For the Wiki environment to be able to use the key, password access must be +For the wiki environment to be able to use the key, password access must be disabled. This can be done by either not specifying a password or by removing it later using the --edit-key option. -Export the Wiki's key for encrypting messages sent to the Wiki: +Export the wiki's key for encrypting messages sent to the wiki: gpg --homedir wiki/gnupg --armor --output 0891463A.asc --export 0891463A @@ -59,7 +59,7 @@ Configuring the Wiki -------------------- -In the Wiki configuration, define the following settings: +In the wiki configuration, define the following settings: moinmessage_gpg_homedir This sets the path to the homedir initialised above. @@ -77,7 +77,7 @@ site root. moinmessage_reject_messages_without_dates (optional, default is True) - This causes messages sent to a Wiki using the PostMessage action to be + This causes messages sent to a wiki using the PostMessage action to be rejected if date information is missing. moinmessage_static_files (optional, may refer to the built-in htdocs directory) @@ -99,14 +99,14 @@ auth = [MoinAuth(), PGPAuth()] This would permit the traditional Moin authentication and add signature-based -authentication so that messages can be accepted by the Wiki. +authentication so that messages can be accepted by the wiki. Fingerprints and Keys --------------------- All fingerprints mentioned in the various configuration pages must exclude space characters - that is, the letters and digits must appear together in a -continuous block of text - and refer to keys available in the Wiki homedir. +continuous block of text - and refer to keys available in the wiki homedir. The Fingerprint-to-Username Mapping ----------------------------------- @@ -117,9 +117,9 @@ fingerprint:: username Each fingerprint corresponds to a key used by a person wanting to send -messages to the Wiki to sign such messages. +messages to the wiki to sign such messages. -Each username must correspond to a registered user in the Wiki. +Each username must correspond to a registered user in the wiki. The Username-to-Signing Key Mapping ----------------------------------- @@ -130,10 +130,12 @@ username:: fingerprint -Each fingerprint corresponds to a key available in the Wiki's GPG homedir +Each fingerprint corresponds to a key available in the wiki's GPG homedir generated for the purpose of signing the specified user's messages. Such a key -is not the same as one used by a person to send messages to the Wiki since -only the public key used to verify such messages should be known to the Wiki. +is not the same as one used by a person to send messages to the wiki since +only the public key is available to the wiki when verifying such messages, +whereas the signing of messages requires access to a private key. Thus, the +signing process employs a special private key known to the wiki for a user. The Recipients Mapping ---------------------- @@ -153,7 +155,7 @@ Where a type of "url" has been given, a fingerprint must accompany this information in order to encrypt messages sent to the specified resource. -Each fingerprint corresponds to a key used by the Wiki to encrypt messages and +Each fingerprint corresponds to a key used by the wiki to encrypt messages and by the remote site (as identified by the URL) to decrypt messages. Quick Start: Signing, Encrypting and Sending Messages @@ -162,11 +164,11 @@ To send a message signed and encrypted to a resource on localhost: python tests/test_send.py 1C1AAF83 0891463A http://localhost/wiki/ShareTest \ - collection update 'An update to the Wiki.' 'Another update.' + collection update 'An update to the wiki.' 'Another update.' Here, the first identifier is a reference to the signing key (over which you have complete control), and the second identifier is a reference to the -encryption key (which is a public key published for the Wiki). +encryption key (which is a public key published for the wiki). This needs password protection to be removed from the secret key in the Web server environment. It also uses a modified trust model when invoking gpg in @@ -176,7 +178,7 @@ python tests/test_send.py 1C1AAF83 0891463A --forward 1C1AAF83 \ http://localhost/wiki/ShareTest \ - collection update 'An update to the Wiki.' 'Another update.' + collection update 'An update to the wiki.' 'Another update.' Below, the mechanisms employed are illustrated through the use of the other test programs. @@ -187,13 +189,13 @@ Prepare a message signed with a "detached signature" (note that this does not seem to be what gpg calls a detached signature with the --detach-sig option): - python tests/test_message.py collection update 'An update to the Wiki.' \ + python tests/test_message.py collection update 'An update to the wiki.' \ 'Another update.' \ | python tests/test_sign.py 1C1AAF83 The complicated recipe based on the individual operations is as follows: - python tests/test_message.py collection update 'An update to the Wiki.' \ + python tests/test_message.py collection update 'An update to the wiki.' \ 'Another update.' \ > test.txt \ && cat test.txt \ @@ -205,13 +207,13 @@ Prepare a message with an encrypted payload using the above key: - python tests/test_message.py collection update 'An update to the Wiki.' \ + python tests/test_message.py collection update 'An update to the wiki.' \ 'Another update.' \ | python tests/test_encrypt.py 0891463A The complicated recipe based on the individual operations is as follows: - python tests/test_message.py collection update 'An update to the Wiki.' \ + python tests/test_message.py collection update 'An update to the wiki.' \ 'Another update.' \ > test.txt \ && cat test.txt \ @@ -225,14 +227,14 @@ Sign and encrypt a message: - python tests/test_message.py collection update 'An update to the Wiki.' \ + python tests/test_message.py collection update 'An update to the wiki.' \ 'Another update.' \ | python tests/test_sign.py 1C1AAF83 \ | python tests/test_encrypt.py 0891463A The complicated recipe based on the individual operations is as follows: - python tests/test_message.py collection update 'An update to the Wiki.' \ + python tests/test_message.py collection update 'An update to the wiki.' \ 'Another update.' \ > test.txt \ && cat test.txt \ @@ -248,7 +250,7 @@ author, encrypted, but then signed by the forwarder (perhaps initially the author): - python tests/test_message.py collection update 'An update to the Wiki.' \ + python tests/test_message.py collection update 'An update to the wiki.' \ 'Another update.' \ | python tests/test_sign.py 1C1AAF83 \ | python tests/test_encrypt.py 0891463A \ @@ -256,7 +258,7 @@ The complicated recipe based on the individual operations is as follows: - python tests/test_message.py collection update 'An update to the Wiki.' \ + python tests/test_message.py collection update 'An update to the wiki.' \ 'Another update.' \ > test.txt \ && cat test.txt \ @@ -302,9 +304,9 @@ For each update, the "Update-Action" header indicates the action to be taken with the update content. Where it is absent, the content is inserted into the -Wiki page specified in the request; where it is present and set to "replace", -the content replaces all content on the Wiki page; where it is set to "store", -the content is stored in a message store associated with the Wiki page. +wiki page specified in the request; where it is present and set to "replace", +the content replaces all content on the wiki page; where it is set to "store", +the content is stored in a message store associated with the wiki page. Each update may describe multiple representations of some content by employing a multipart/alternative section containing parts for each of the