Extension:PageProtectionPlus/Installation Guide

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
OOjs UI icon advanced.svg
PageProtectionPlus
Release status: beta
Implementation Tag, Special
Description Protect areas and sections from access
Latest version 2.3b (2007-12-18)
MediaWiki 1.8.0 - 1.9.1
License No license specified
Download No link
Translate the PageProtectionPlus extension if it is available at translatewiki.net

Getting[edit]

The whole code with installation guide is now available for download from the following locations:

Requirements[edit]

Required parts have 3 different types:

  • PHP's packages – these you should install into your MediaWiki 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[edit]

You always need PEAR and PEAR/Crypt_RSA.

Additionaly, you'll need one of these:

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)[edit]

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:
include_once('extensions/ExtensionFunctions.php');

Symmetric engines[edit]

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

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[edit]

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[edit]

  • 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
################################################################
# PageProtection extension

$wgCachePages   = false;
$wgCacheEpoch   = 'date +%Y%m%d%H%M%S';
$wgPEMsize      = 1024;                 //default key size
$wgPEMlite_size = 512;                  //lite key size
$wgPEMdir       = '/var/run/PPP-keys';  //storage for keys
$wgPEMfile      = 'default.pem';        //default key's filename
$wgPEMlite_file = 'lite.pem';           //lite key's filename

$wgPEMold       = 'private.pem';        //old key's pathname (optional)
                                        //if you've been using PageProtection
# activate PageProtection extension
require_once('extensions/PPP/PageProtectionPlus.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[edit]

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:

$len |= ord($in[$pos++]);           /* BAD */

with the:

$len |= ord($str[$pos++]);          /* OK */

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[edit]

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[edit]

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

See also[edit]