1 Introduction
2 ------------
3
4 MoinMessage provides a library for creating, signing, encrypting, decrypting,
5 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.
9
10 Configuring GPG for a Wiki
11 --------------------------
12
13 Initialise a homedir for GPG and configure it using ACL (access control list)
14 properties:
15
16 ./scripts/init_wiki_keyring.sh
17
18 To be in any way useful, signing keys must be made available within this
19 homedir so that incoming messages can have their senders verified.
20
21 To see the keys available to you in your own environment:
22
23 gpg --list-keys --with-fingerprint
24
25 The full fingerprints are used when defining a user mapping in the Wiki, and
26 the --with-fingerprint option is used to show them. Otherwise, only the last
27 eight characters of the fingerprints are shown.
28
29 Export the public key used when signing messages from your own environment:
30
31 gpg --armor --output 1C1AAF83.asc --export 1C1AAF83
32
33 Import the key into the Wiki's GPG homedir:
34
35 gpg --homedir wiki/gnupg --import 1C1AAF83.asc
36
37 For the Wiki to receive encrypted data, a key for the Wiki must be created:
38
39 gpg --homedir wiki/gnupg --gen-key
40
41 Export the Wiki's key for encrypting messages sent to the Wiki:
42
43 gpg --homedir wiki/gnupg --armor --output 0891463A.asc --export 0891463A
44
45 This exported key can now be imported into your own environment:
46
47 gpg --import 0891463A.asc
48
49 Configuring the Wiki
50 --------------------
51
52 In the Wiki configuration, define the following settings:
53
54 moinmessage_gpg_homedir
55 This sets the path to the homedir initialised above.
56
57 moinmessage_gpg_users_page (optional, default is MoinMessageUserDict)
58 This provides a mapping from key fingerprints to Moin usernames.
59
60 The Fingerprint-to-Username Mapping
61 -----------------------------------
62
63 The mapping from fingerprints to usernames is a WikiDict page having the
64 following general format:
65
66 fingerprint:: username
67
68 Each fingerprint must exclude space characters and correspond to the
69 fingerprint shown for a key in the available key listing generated above.
70
71 Each username must correspond to a registered user in the Wiki.
72
73 Quick Start: Signing, Encrypting and Sending Messages
74 -----------------------------------------------------
75
76 To send a message signed and encrypted to a resource on localhost:
77
78 python tests/test_send.py 1C1AAF83 0891463A localhost /wiki/ShareTest \
79 'An update to the Wiki.' 'Another update.'
80
81 Here, the first identifier is a reference to the signing key (over which you
82 have complete control), and the second identifier is a reference to the
83 encryption key (which is a public key published for the Wiki).
84
85 This needs password protection to be removed from the secret key in the Web
86 server environment, and so uses a modified trust model when invoking gpg.
87
88 Below, the mechanisms employed are illustrated through the use of the other
89 test programs.
90
91 Signing
92 -------
93
94 Prepare a message signed with a "detached signature" (note that this does not
95 seem to be what gpg calls a detached signature with the --detach-sig option):
96
97 python tests/test_message.py 'An update to the Wiki.' 'Another update.' \
98 | python tests/test_sign.py 1C1AAF83
99
100 The complicated recipe based on the individual operations is as follows:
101
102 python tests/test_message.py 'An update to the Wiki.' 'Another update.' \
103 > test.txt \
104 && cat test.txt \
105 | gpg --armor -u 1C1AAF83 --detach-sig \
106 | python tests/test_sign_wrap.py test.txt
107
108 Encryption
109 ----------
110
111 Prepare a message with an encrypted payload using the above key:
112
113 python tests/test_message.py 'An update to the Wiki.' 'Another update.' \
114 | python tests/test_encrypt.py 0891463A
115
116 The complicated recipe based on the individual operations is as follows:
117
118 python tests/test_message.py 'An update to the Wiki.' 'Another update.' \
119 > test.txt \
120 && cat test.txt \
121 | gpg --armor -r 0891463A --encrypt --trust-model always \
122 | python tests/test_encrypt_wrap.py
123
124 Note that "--trust-model always" is used only to avoid prompting issues.
125
126 Signing and Encrypting
127 ----------------------
128
129 Send a message signed and encrypted:
130
131 python tests/test_send.py 1C1AAF83 0891463A localhost /wiki/ShareTest
132
133 python tests/test_message.py 'An update to the Wiki.' 'Another update.' \
134 | python tests/test_sign.py 1C1AAF83 \
135 | python tests/test_encrypt.py 0891463A
136
137 The complicated recipe based on the individual operations is as follows:
138
139 python tests/test_message.py 'An update to the Wiki.' 'Another update.' \
140 > test.txt \
141 && cat test.txt \
142 | gpg --armor -u 1C1AAF83 --detach-sig \
143 | python tests/test_sign_wrap.py test.txt \
144 | gpg --armor -r 0891463A --encrypt --trust-model always \
145 | python tests/test_encrypt_wrap.py
146
147 Posting a Message
148 -----------------
149
150 To post a signed and/or encrypted message, output from the above activities
151 can be piped into the following command:
152
153 python tests/test_post.py localhost /wiki/ShareTest
154
155 Here, the resource "/wiki/ShareTest" on localhost is presented with the
156 message.