WikiShCrypt

Summary: Provide encryption/decryption for WikiSh commands and in other contexts
Version: 2015-06-06
Prerequisites: WikiSh, MCRYPT extension to PHP
Status: Alpha
Maintainer: Peter Bowers

Questions answered by this recipe

This section is optional; use it to indicate the types of questions (if any) this recipe is intended to answer.

  • How can I achieve a greater level of privacy/data security with information in pmwiki? How can I encrypt pages?

Description

Provide encryption/decryption for WikiSh commands and elsewhere.

Installation

There is an extension to PHP called MCRYPT which provides excellent encryption capabilities. WikiShCrypt depends on this extension. However, it is not installed by default on many servers. Here are BRIEF instructions on how to install (it is beyond the scope of this document to describe in greater detail):

  • To enable mcrypt extension under Windows you need to:
    1. uncomment line "extension=php_mcrypt.dll" in php.ini
    2. download libmcrypt.dll from [(approve links) edit diff] and put it to System32 directory (for example C:\Windows\System32).
    (Copied from Ivan Fredericks comment on http://www.php.net/mcrypt)
  • To enable mcrypt extension under Linux you need to:
    1. SOMEONE PLEASE FILL IN THIS BLANK OR SEND ME INSTRUCTIONS SO I CAN FILL IT IN

The PHP script WikiShCrypt.phpΔ must be placed in your cookbook directory and the appropriate line included in your config.php after including WikiSh.php:

include_once('$FarmD/cookbook/WikiShCrypt.php');
$WikiShVars['CRYPT_IV_FILE'] = 'TEXTFILE--CryptIV.txt';

You must make sure that you have read/write privileges to the page or file specified for CRYPT_IV_FILE the first time you attempt to encrypt or decrypt something. Thereafter you will need only read privileges. Please note the necessity of passing all 4 levels of security in order to obtain read or write privilege for a given page or file. If encryption is all you are working on then this configuration should suffice:

include_once('cookbook/WikiSh.php');
include_once('cookbook/WikiShCrypt.php');
$WikiShVars['CRYPT_IV_FILE'] = 'TEXTFILE--CryptIV.txt';
$EnableWikiShTextRead = true;
$WikiShTextReadList = array('CryptIV.txt');
$EnableWikiShTextWrite = true;
$WikiShTextWriteList = array('CryptIV.txt');

You can specify any filename or a pagename for the CRYPT_IV_FILE value, but be aware that you do NOT want to lose this file. It will be automatically created the first time you do any encryption or decryption. Thereafter that file/page will be read and the value used each time any encryption or decryption is done. If you lose that file then all encrypted files, well, not to be overly dramatic, but they will remain encrypted forever. Be forewarned - BACK IT UP! Also if you change from one algorithm or mode of encryption to another you should decrypt all encrypted files and then delete the CRYPT_IV_FILE file (or rename it or respecify a different value in your config.php), then change the algorithm/mode, and then encrypt some other piece of data in order to recreate the IV for the new encryption type.

There are also 4 configuration variables used in setting the encryption algorithm and mode. They correspond to the 4 arguments to mcrypt_generic_init(). They are (in order):

  • ${CRYPT_ALGORITHM} (default MCRYPT_DES)
  • ${CRYPT_ALGORITHM_DIR} (default blank)
  • ${CRYPT_MODE} (default MCRYPT_MODE_ECB)
  • ${CRYPT_MODE_DIR} (default blank)

These variables (with the others) can be set in config.php via $WikiShVars[] or in the profile/rc pages to give page-level administrative control.

Usage

Here is how you use the encryption/decryption capabilities:

  • Each WikiSh MX which allows input from a file will honor the --decrypt option and the --passwd:PASSWD option to specify the password. This will read encrypted data from a page or file and decrypt it for use in that command.
  • Each WikiSh MX which allows output to a file will honor the --encrypt option and the --passwd:PASSWD option to specify the password. Whatever would have been output by this command will now be output in an encrypted form. If output was going to a page or file then the data in that page/file will be encrypted.
  • If you are looking for an MX to encrypt/decrypt text as a filter in a pipeline, simply use "cat --encrypt" or "cat --decrypt"
  • A default password can be specified in the ${CRYPT_PASSWD} variable. The --passwd:PASSWD option overrides this default.

If I wanted to take a page I had created in Session.MyPrivatePage and place this virtual page in a "real" page MyGroup.MyPrivatePage but I wanted it to be encrypted here is what I would do:

{(cp --encrypt --passwd:secret123 Session.MyPrivatePage MyGroup.MyPrivatePage)}

Obviously putting a command like this with the password in cleartext on a page is not ideal. So normally this would be accomplished by creating a form for the user to enter the password, placing that password in a variable, and then specifying the password by means of that variable:

{(cp --encrypt --passwd:${passwdfromform} Session.MyPrivatePage MyGroup.MyPrivatePage)}

As a convenient side effect of the implementation method of all reading/writing within WikiSh, you can easily encrypt or decrypt a page or a file by simply copying it overtop of itself:

Encrypting:

{(cp --encrypt --passwd:${passwdfromform} MyGroup.MyPrivatePage MyGroup.MyPrivatePage)}

Decrypting:

{(cp --decrypt --passwd:${passwdfromform} MyGroup.MyPrivatePage MyGroup.MyPrivatePage)}

Release Notes

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

ReleaseChange Log
2015-06-06Implemented Markup_e() for PHP 5.5 compatibility
2008-05-05Fixed a problem with IV file creation. Changed the wording on the encryption-viewing to specify what happens if you use the wrong password.
2008-05-04BGot rid of an unsightly debug trace statement I missed on the first release.
2008-05-04Changed the format of the encrypted text with a cleartext prefix/suffix and did a base64 encoding to make it easier to handle (text rather than binary). NOTE THAT ANYTHING ENCRYPTED BY THE PREVIOUS VERSION MUST BE DECRYPTED BY THAT PREVIOUS VERSION AND THEN RE-ENCRYPTED BY THIS VERSION. WikiShCrypt is now separated from WikiSh to be a separate (but still dependent) recipe. Capabilities built in for EditCrypt. Added capability of viewing an encrypted page by markup and immediate entry of password. Moved away from the use of MCRYPT_DEV_RAND entirely since it was causing problems even on linux boxes (?!?).
2008-04-29Initial Release

See Also

Known problems

  • If you are reading from a mixture of some encrypted pages and some decrypted pages there is no way to specify this.
  • If you are writing to an encrypted page via append/prepend/midpend then you must specify --decrypt as well as --encrypt. If you are reading an unencrypted file (or a file encrypted with a different password) elsewhere in the same command there is no way to specify which one to decrypt and which one not to decrypt. (Same situation if you are reading from an encrypted file and writing via append/prepend/midpend -- it will try to decrypt the target page as well.)

Contributors

Comments

User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.