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