Extension:PageProtectionPlus/Installation Guide

Getting
The whole code with installation guide is now available for download from the following locations:
 * http://entropy.echelon.pl/people/siefca/software/PageProtectionPlus-2.3b.tar.gz
 * ftp://ep09.pld-linux.org/people/siefca/software/PageProtectionPlus-2.3b.tar.gz
 * ftp://ftp.pld-linux.org/people/siefca/software/PageProtectionPlus-2.3b.tar.gz

Requirements
Required parts have 3 different types:


 * PHP's packages – these you should install into your MediWiki tree
 * PHP's extensions – to enable these you should install extension and/or recompile your PHP
 * system libraries – these are wanted by some PHP's functionalities to work and should be installed from tarball or system package if there is a way (rpm, deb)

Always required
You always need PEAR and PEAR/Crypt_RSA.


 * Crypt_RSA package for PHP – http://pear.php.net/package/Crypt_RSA
 * Pear-Base package for PHP – http://pear.php.net/package/PEAR

Additionaly, you'll need one of these:


 * GMP system library – http://www.swox.com/gmp/ -> new: http://gmplib.org/
 * bin_int PHP's package/extension – http://pecl.php.net/package/big_int
 * bcmath PHP's extension – (PHP compiled using --with-bcmath or bcmath module enabled in php.ini)

My favorite is GMP. You may also want to use big_int - easy to install and you may set it up in 3 ways: as a package, as an extension module, or as built-in when recompiling PHP. Try to avoid bcmath.

Extension functions (optional)
Some (older) MediaWiki installations  need the  additional file called ExtensionFunctions.php for the special pages to be properly registered. If you are experiencing troubles just:


 * 1. go to http://svn.wikimedia.org/viewvc/mediawiki/trunk/extensions/ExtensionFunctions.php?revision=15706
 * 2. save the contents as extensions/ExtensionFunctions.php
 * 3. add to your LocalSettings.php:

Symmetric engines
You can   choose  between   symmetric  engines. At least one engine  should  be  installed  For  now,  you  can  use Crypt_Blowfish and mcrypt.


 * mcrypt system library – http://mcrypt.sourceforge.net/
 * Crypt_Blowfish – http://pear.php.net/package/Crypt_Blowfish (version 1.1.0RC1 or higher!)

You can install both.

The most  powerful  for   now  is  mcrypt,  which  provides many popular  symmetric  encryption  algorithms. It needs libmcrypt to be  installed in  system and  needs PHP  to be compiled  using  --with-mcrypt (or  if  it  is possible  the mcrypt  PHP  extenstion  to  be  activated  in  php.ini  and extension module to be installed). If you'll decide to build libmcrypt from sources, make sure you do it with the option --disable-posix-threads

Blowfish is easy to  install on non  package-based systems, because you won't have to recompile anything. All you have to do  is  to  unpack Crypt_Blowfish  into  your  MediaWiki directory tree. Bad news is that it provides -  as the name says - only one algorithm.

Example preinstallation
Assuming that MediaWiki resides on /usr/share/mediawiki and you are not  installing  anything from  system package  but compiling.


 * PEAR package downloaded and unpacked to /usr/share/mediawiki
 * Crypt_RSA package downloaded and unpacked to /usr/share/mediawiki
 * Crypt_Blowfish package downloaded and unpacked to /usr/share/mediawiki
 * libgmp downloaded and installed in /usr/local using make install
 * libmcrypt downloaded and installed in /usr/local using ./configure --disable-posix-threads and make install
 * PHP 5 compiled using ./configure --with-mysql --with-gmp --with-mcrypt

Assuming that MediaWiki resides on /usr/share/mediawiki and you are installing everything from system packages.


 * PEAR package downloaded and unpacked to /usr/share/mediawiki
 * Crypt_RSA package downloaded and unpacked to /usr/share/mediawiki
 * Crypt_Blowfish package downloaded and unpacked to /usr/share/mediawiki
 * libgmp system package downloaded and installed using package manager (rpm or deb)
 * libmcrypt system package downloaded and installed using package manager (rpm or deb)
 * PHP 5 installed from package
 * gmp PHP's extension installed from package and activated in php.ini
 * mcrypt PHP's extension installed from package and activated in php.ini
 * mysql PHP's extension installed from package and activated in php.ini

Installation

 * make sure that all required libraries and PHP's extensions are installed
 * copy all files and directories from this package to extensions/PPP directory inside of your MediaWiki tree
 * unpack all PEAR-packages (including PEAR itself) into your MediaWiki directory tree


 * add the following to your LocalSettings.php:

Variables are setting the following parameters:


 * $wgPEMsize sets the size for the default RSA key
 * $wgPEMlite_size sets the size for the RSA key used in Pure-RSA mode
 * $wgPEMdir sets the directory for storing RSA keys
 * $wgPEMfile is the filename for the default key (used for encryption)
 * $wgPEMlite_file is the filename for the 'lite' key (used for encryption in Pure-RSA mode)
 * $wgPEMold is an optional pathname of a file containing the key used in PageProtection

When started for the first time, the extension will create a new PEM-file in the $wgPEMdir directory. You should set the correct path to it in LocalSettings.php and make sure, that the webserver has the write access to  the directory, where the files will reside. Alternatively, you can create your own PEM-file  and save  it  there  under  the name  set  in $wgPEMfile.

If  you  have   been  using   PageProtection  before,   the PageProtectionPlus will   try  to   import  your   old  key ($wgPEMold) by  copying  it into  the  directory  mentioned above.

Fixing the bug in Crypt_RSA
If you would like to use RSA keys that are bigger than 512bits (this is the default in the example) and your version of Crypt_RSA is less or equal than  1.2.0b you have to do a little hack according to Bug #7252).

Go to the line 235 of the file RSA/KeyPair.php present in your MediaWiki directory and replace:

with the:



If you have sed on hand, just do this (as root or via sudo): sed -i -e '235s/\$in/\$str/' /usr/share/pear/Crypt/RSA/KeyPair.php

Key generation
PageProtectionPlus needs at least one RSA-key. Here are the ways to create RSA keys.


 * Remember: Always create a directory (or let the server do it) for storing keys before you'll use the extension!

One approach is to  let the web  server write  the default key  in  the  specified directory  ($wgPEMdir),  and  leave $wgPEMfile to be set to 'default.pem'. The directory should be placed outside the MediaWiki tree, or better, somewhere outside the  default scope  of the Web  server. If this is impossible try to give it some unpredictible name.

Second approach is  to create  directory and  generate the default file by hand Make sure the web server has access to that file.

There is also another approach, combining these two, use it especially when  you  are  uprading  from  PageProtection. Create the  directory  for  keys,  give  the  Web  service permission to  write there, edit  one page and  encrypt it, and then take the write  permission for directory and files away. Example (assuming your web-server runs  under GID of the group called 'http'):

su - mkdir /var/run/PPP-keys chown root:http /var/run/PPP-keys chmod 0770 /var/run/PPP-keys

[edit one page using the browser]

chmod 0750 /var/run/PPP-keys chmod 0640 /var/run/PPP-keys/*

If your PHP  is not  allowed  to read  files outside  some directories change the pathname according to your needs. If you don't have root-access  to the host  you have  to make sure that there is no way to read keys using the HTTP.

Directory Structure
/mw |- index.php |- PEAR.php |- PEAR/ |   | ...  |- Crypt |   | ...  |    |- RSA |   |- Blowfish | |- extensions |   |-  PPP |   |     |- PageProtectionPlus.php |  ... ...