1 Introduction
2 ------------
3
4 MoinMessage provides a library for creating, signing, encrypting, decrypting,
5 and verifying PGP/GPG content in Python along with mechanisms for updating
6 MoinMoin wiki instances with such content such that contributors can be
7 identified from their PGP signatures and such details used to authenticate
8 their contributions. It also permits PGP/GPG content to be stored in dedicated
9 message stores when received, enabling further processing of received content
10 and other means of perusal of such content.
11
12 Configuring GPG for a Wiki
13 --------------------------
14
15 Initialise a homedir for GPG and configure it using filesystem ACL (access
16 control list) properties:
17
18 ./scripts/init_wiki_keyring.sh WIKI WEBUSER
19
20 Here, WIKI should be replaced by the top-level wiki instance directory, and
21 WEBUSER should be the name of the user under which the Web server operates.
22
23 Note that this script may need re-running after the homedir has been changed
24 by gpg operations as gpg likes to remove permissions from various files.
25
26 Configuring GPG: Signing Keys
27 -----------------------------
28
29 To be in any way useful, signing keys must be made available within this
30 homedir so that incoming messages can have their senders verified.
31
32 To see the keys available to you in your own environment:
33
34 gpg --list-keys --with-fingerprint
35
36 The full fingerprints are used when defining a user mapping in the wiki, and
37 the --with-fingerprint option is used to show them. Otherwise, only the last
38 eight characters of the fingerprints are shown.
39
40 Export the public key used when signing messages from your own environment:
41
42 gpg --armor --output 1C1AAF83.asc --export 1C1AAF83
43
44 Import the key into the wiki's GPG homedir:
45
46 gpg --homedir WIKI/gnupg --import 1C1AAF83.asc
47
48 Configuring GPG: Encryption Keys
49 --------------------------------
50
51 For the wiki to receive and decrypt encrypted data, a key for the wiki must be
52 created:
53
54 gpg --homedir WIKI/gnupg --gen-key
55
56 For the wiki environment to be able to use the key, password access must be
57 disabled. This can be done by either not specifying a password or by removing
58 it later using the --edit-key option:
59
60 gpg --homedir WIKI/gnupg --edit-key 0891463A
61 passwd
62
63 Export the wiki's key for encrypting messages sent to the wiki:
64
65 gpg --homedir WIKI/gnupg --armor --output 0891463A.asc --export 0891463A
66
67 This exported key can now be imported into your own environment:
68
69 gpg --import 0891463A.asc
70
71 This key can also be used to sign relayed messages, and this is described in
72 more detail below.
73
74 Configuring the Wiki
75 --------------------
76
77 In the wiki configuration, define the following settings:
78
79 moinmessage_gpg_homedir
80 This sets the path to the homedir initialised above.
81
82 moinmessage_gpg_users_page (optional, default is MoinMessageUserDict)
83 This provides a mapping from key fingerprints to Moin usernames.
84
85 moinmessage_gpg_signing_users_page (optional, default is MoinMessageSigningUserDict)
86 This provides a mapping from Moin usernames to key fingerprints.
87
88 moinmessage_gpg_relaying_user (optional)
89 This specifies the username of a special user who will sign relayed
90 messages. Partner wikis will need to record the details of this user in
91 their fingerprint-to-user mapping (see moinmessage_gpg_users_page) to be
92 able to receive messages from this wiki.
93
94 moinmessage_gpg_recipients_page (optional, default is MoinMessageRecipientsDict)
95 This provides a mapping from recipients to remote URLs and key fingerprints.
96 Each user can define the named page as a subpage of their own home page.
97 If no such personal mapping exists, a common mapping exists relative to the
98 site root.
99
100 moinmessage_reject_messages_without_dates (optional, default is True)
101 This causes messages sent to a wiki using the PostMessage action to be
102 rejected if date information is missing.
103
104 moinmessage_static_files (optional, may refer to the built-in htdocs directory)
105 This explicitly defines the path to static resources used by Moin, enabling
106 such resources to be attached to messages. When set, the path must refer to
107 the htdocs directory (possibly renamed) containing the different theme
108 resource directories, together with the robots.txt and favicon.ico files.
109
110 For signature verification to function, the following needs to be added:
111
112 from MoinMoin.auth.pgp import PGPAuth
113
114 This should import an authentication handler installed when the MoinMessage
115 software is installed as an extension package.
116
117 Within the configuration class itself, the auth setting needs to be updated to
118 include PGPAuth in the list of registered handlers. For example:
119
120 auth = [MoinAuth(), PGPAuth()]
121
122 This would permit the traditional Moin authentication and add signature-based
123 authentication so that messages can be accepted by the wiki.
124
125 Fingerprints and Keys
126 ---------------------
127
128 All fingerprints mentioned in the various configuration pages must exclude
129 space characters - that is, the letters and digits must appear together in a
130 continuous block of text - and refer to keys available in the wiki homedir.
131
132 The Fingerprint-to-Username Mapping
133 -----------------------------------
134
135 The mapping from fingerprints to usernames typically defined by the
136 MoinMessageUserDict page is a WikiDict having the following general format:
137
138 fingerprint:: username
139
140 Each fingerprint corresponds to a key used by a person wanting to send
141 messages to the wiki to sign such messages.
142
143 Each username must correspond to a registered user in the wiki.
144
145 If a wiki is to perform message relaying, receiving messages from partner
146 wikis and sending them on, a user is required for this purpose. You could
147 create such a user as follows:
148
149 moin --config-dir=WIKI account create --name=RelayingUser --email=messagerelay
150
151 (You may need to run this command as the Web server user to be able to change
152 the wiki installation, as well as indicating the full path to the moin program
153 either as the program name or by setting the PATH.)
154
155 After doing this, you could define an entry for the relaying user as follows:
156
157 fingerprint:: RelayingUser
158
159 Here, "fingerprint" should be substituted for a key fingerprint used by a
160 partner wiki to sign messages that it then sends to this wiki. See the next
161 section for more information on signing keys and identities.
162
163 It may very well be the case that more than one partner wiki will be sending
164 messages to this wiki: the signing key fingerprint of each partner wiki can be
165 added to this mapping and specify the same relaying user; there is no
166 restriction on each fingerprint needing to map to a different user.
167
168 The Username-to-Signing Key Mapping
169 -----------------------------------
170
171 The mapping from usernames to fingerprints typically defined by the
172 MoinMessageSigningUserDict page is a WikiDict having the following general
173 format:
174
175 username:: fingerprint
176
177 Each fingerprint corresponds to a key available in the wiki's GPG homedir
178 generated for the purpose of signing the specified user's messages. Such a key
179 is not the same as one used by a person to send messages to the wiki since
180 only the public key is available to the wiki when verifying such messages,
181 whereas the signing of messages requires access to a private key. Thus, the
182 signing process employs a special private key known to the wiki for a user.
183
184 If a wiki is to perform message relaying, the special relaying user must be
185 defined in this mapping together with an appropriate key fingerprint. You can
186 use the key generated during the wiki's configuration (see "Configuring GPG
187 for a Wiki" above) for this purpose. This fingerprint can then be used by
188 partner wikis in their fingerprint-to-user mapping in order to verify incoming
189 messages and to process them as relayed messages.
190
191 The Recipients Mapping
192 ----------------------
193
194 The mapping from recipients to remote URLs and fingerprints typically defined
195 by the MoinMessageRecipientsDict page is a WikiDict having the following
196 general format:
197
198 recipient:: type location [ fingerprint ]
199
200 Where the type is "page", the accompanying location must be a page name
201 indicating a page that provides a message store that will accept messages.
202 The affected page resides on the same wiki and is thus a bare page name, not
203 the URL of a page on the same or another wiki.
204
205 Where the type is "url", the accompanying location must be a URL that must
206 itself refer to a resource that can accept MoinMessage content.
207
208 Where a type of "url" has been given, a fingerprint must accompany this
209 information in order to encrypt messages sent to the specified resource.
210
211 Each fingerprint corresponds to a key used by the wiki to encrypt messages and
212 by the remote site (as identified by the URL) to decrypt messages.
213
214 Each wiki user can have their own recipients mapping by making a page, called
215 MoinMessageRecipientsDict unless overridden by the configuration, as a subpage
216 of their own home page.
217
218 Quick Start: Signing, Encrypting and Sending Messages
219 -----------------------------------------------------
220
221 To send a message signed and encrypted to a resource on localhost:
222
223 python tests/test_send.py 1C1AAF83 0891463A http://localhost/wiki/ShareTest \
224 collection update 'An update to the wiki.' 'Another update.'
225
226 Here, the first identifier is a reference to the signing key (over which you
227 have complete control), and the second identifier is a reference to the
228 encryption key (which is a public key published for the wiki).
229
230 This needs password protection to be removed from the secret key in the Web
231 server environment. It also uses a modified trust model when invoking gpg in
232 order to avoid complaints about the identity of the sender during encryption.
233
234 To sign the encrypted message for forwarding, the above command is modified:
235
236 python tests/test_send.py 1C1AAF83 0891463A --forward 1C1AAF83 \
237 http://localhost/wiki/ShareTest \
238 collection update 'An update to the wiki.' 'Another update.'
239
240 Below, the mechanisms employed are illustrated through the use of the other
241 test programs.
242
243 Signing
244 -------
245
246 Prepare a message signed with a "detached signature" (note that this does not
247 seem to be what gpg calls a detached signature with the --detach-sig option):
248
249 python tests/test_message.py collection update 'An update to the wiki.' \
250 'Another update.' \
251 | python tests/test_sign.py 1C1AAF83
252
253 The complicated recipe based on the individual operations is as follows:
254
255 python tests/test_message.py collection update 'An update to the wiki.' \
256 'Another update.' \
257 > test.txt \
258 && cat test.txt \
259 | gpg --armor -u 1C1AAF83 --detach-sig \
260 | python tests/test_sign_wrap.py test.txt
261
262 Encryption
263 ----------
264
265 Prepare a message with an encrypted payload using the above key:
266
267 python tests/test_message.py collection update 'An update to the wiki.' \
268 'Another update.' \
269 | python tests/test_encrypt.py 0891463A
270
271 The complicated recipe based on the individual operations is as follows:
272
273 python tests/test_message.py collection update 'An update to the wiki.' \
274 'Another update.' \
275 > test.txt \
276 && cat test.txt \
277 | gpg --armor -r 0891463A --encrypt --trust-model always \
278 | python tests/test_encrypt_wrap.py
279
280 Note that "--trust-model always" is used only to avoid prompting issues.
281
282 Signing and Encrypting
283 ----------------------
284
285 Sign and encrypt a message:
286
287 python tests/test_message.py collection update 'An update to the wiki.' \
288 'Another update.' \
289 | python tests/test_sign.py 1C1AAF83 \
290 | python tests/test_encrypt.py 0891463A
291
292 The complicated recipe based on the individual operations is as follows:
293
294 python tests/test_message.py collection update 'An update to the wiki.' \
295 'Another update.' \
296 > test.txt \
297 && cat test.txt \
298 | gpg --armor -u 1C1AAF83 --detach-sig \
299 | python tests/test_sign_wrap.py test.txt \
300 | gpg --armor -r 0891463A --encrypt --trust-model always \
301 | python tests/test_encrypt_wrap.py
302
303 Signing and Encrypting then Signing
304 -----------------------------------
305
306 Where a message is to be forwarded and not decrypted, it will be signed by the
307 author, encrypted, but then signed by the forwarder (perhaps initially the
308 author):
309
310 python tests/test_message.py collection update 'An update to the wiki.' \
311 'Another update.' \
312 | python tests/test_sign.py 1C1AAF83 \
313 | python tests/test_encrypt.py 0891463A \
314 | python tests/test_sign.py 1C1AAF83
315
316 The complicated recipe based on the individual operations is as follows:
317
318 python tests/test_message.py collection update 'An update to the wiki.' \
319 'Another update.' \
320 > test.txt \
321 && cat test.txt \
322 | gpg --armor -u 1C1AAF83 --detach-sig \
323 | python tests/test_sign_wrap.py test.txt \
324 | gpg --armor -r 0891463A --encrypt --trust-model always \
325 | python tests/test_encrypt_wrap.py \
326 > test2.txt \
327 && cat test2.txt \
328 | gpg --armor -u 1C1AAF83 --detach-sig \
329 | python tests/test_sign_wrap.py test2.txt
330
331 Posting a Message
332 -----------------
333
334 To post a signed and/or encrypted message, output from the above activities
335 can be piped into the following command:
336
337 python tests/test_post.py http://localhost/wiki/ShareTest
338
339 Here, the resource "/wiki/ShareTest" on localhost is presented with the
340 message.
341
342 Fetching Messages
343 -----------------
344
345 To fetch messages from a message store associated with a page, the following
346 command can be used:
347
348 python tests/test_fetch.py 1C1AAF83 0891463A http://localhost/wiki/ShareTest \
349 RETR
350
351 This should retrieve all messages from the store associated with the
352 "/wiki/ShareTest" resource on localhost.
353
354 The Message Format
355 ------------------
356
357 Messages are MIME-encoded and consist of one or more update fragments. Where
358 the "Update-Type" header is present and set to a value of "collection", a
359 multipart message describes as many updates as there are parts. Otherwise,
360 only a single update is described by the message.
361
362 For each update, the "Update-Action" header indicates the action to be taken
363 with the update content. Where it is absent, the content is inserted into the
364 wiki page specified in the request; where it is present and set to "replace",
365 the content replaces all content on the wiki page; where it is set to "store",
366 the content is stored in a message store associated with the wiki page.
367
368 Each update may describe multiple representations of some content by employing
369 a multipart/alternative section containing parts for each of the
370 representations. Alternatively, a single message part may describe a single
371 representation.
372
373 HTTP Methods
374 ------------
375
376 Since MoinMoin seems to reserve POST methods for request/entity bodies that
377 contain HTML form data, it is necessary to use alternative methods to post
378 messages to a site served by MoinMoin and to fetch messages from such a site.
379 Consequently, MoinMessage uses PUT to post and fetch messages. Unfortunately,
380 MoinMoin 1.9 prevents the use of GET with request/entity bodies, and so the
381 natural usage of GET to fetch messages cannot be employed.
382
383 Contact, Copyright and Licence Information
384 ------------------------------------------
385
386 See the following Web page for more information about this work:
387
388 http://moinmo.in/ActionMarket/MoinMessage
389
390 The author can be contacted at the following e-mail address:
391
392 paul@boddie.org.uk
393
394 Copyright and licence information can be found in the docs directory - see
395 docs/COPYING.txt and docs/LICENCE.txt for more information.
396
397 Dependencies
398 ------------
399
400 MoinMessage has the following basic dependencies:
401
402 Packages Release Information
403 -------- -------------------
404
405 MoinSupport Tested with 0.4
406 Source: http://hgweb.boddie.org.uk/MoinSupport