Extension:Secure HTML

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
Secure HTML

Release status: stable

Implementation Tag, User rights
Description Lets you include arbitrary HTML in an authorized and secure way
Author(s) Ryan Finnie (Fo0bartalk)
Latest version 2.4.1 (2014-04-14)
MediaWiki 1.18+
License GPL
Download Download latest stable release (2.4.1), or:
Example <shtml> tag (PayPal forms), Special:SecureHTML
Parameters

$wgSecureHTMLSecrets, $shtml_keys (deprecated)

Tags
<shtml>

Translate the Secure HTML extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

Occasionally you need to display HTML within a wiki, but allowing it site-wide opens you up to various XSS attacks. This extension solves that problem by letting you specify arbitrary HTML, but only if the HTML includes a corresponding hash that is created by combining the HTML input, along with a secret that only authorized people know.

The extension uses a special page, Special:SecureHTML which helps you build a tag, <shtml>, which acts as a wrapper around raw HTML. An example looks like (linefeeds added for readability):

<shtml version="2" keyname="fo0bar"
  hash="7fa503206cb1de131dd6acdca576e92262dd6d176cc3466073a343863743b8ed"
><strong>Hello world!</strong></shtml>

If the user uses a valid shared secret to build the hashed <shtml> snippet and includes it in a wiki page, the snippet is rendered as the raw HTML contained within the tag. If the shared secret is invalid, the snippet is rendered as an error message (but not containing the HTML, obviously).

Installation[edit | edit source]

Secure HTML has been tested with MediaWiki 1.18 and later (the earliest supported version at the time of this writing). It may work with earlier MediaWiki versions, however.

You can download the extension directly from the MediaWiki source code repository (browse code). You can get:

One of the extension's tags

Not all extensions have tags. Some extensions have tags for each release, in which case those tags have the same stability as the release. To download a tag

  • Go to the tags list
  • Click the name of the tag you want to download
  • Click "snapshot"
The latest version of one of the extension's branches

Each extension has a master branch containing the latest code (might be unstable). Extensions may have further branches as well.

  • Go to the branches list
  • Click the branch name
  • Click "snapshot"
A snapshot made during the release of a MediaWiki version.

This might be unstable and is not guaranteed to work with the associated MediaWiki version.

After you've got the code, save it into the extensions/SecureHTML directory of your wiki.

If you are familiar with git and have shell access to your server, you can obtain the extension, with all its tags and branches, as follows:

cd extensions
git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/SecureHTML.git
  • Edit LocalSettings.php in the root of your MediaWiki installation, and add the following lines near the bottom:
require_once( "$IP/extensions/SecureHTML/SecureHTML.php" );
 
$wgSecureHTMLSecrets = array(
  'keyname' => 'keysecret',
);
  • Modify $wgSecureHTMLSecrets as per below.
  • Go to Special:SecureHTML and use the page to create a hashed snippet of raw HTML using the key secrets defined.
  • Add the hashed snippet to your desired wiki page.

Configuration[edit | edit source]

Secure HTML uses HMAC digests to sign a piece of raw HTML in a <shtml> tag, using a shared secret key. The $wgSecureHTMLSecrets configuration array may have multiple shared secrets, and is in the format:

$wgSecureHTMLSecrets = array(
  'Wiki admin' => 'foo',
  'developers' => 'bar',
  'Support department' => 'baz',
);

The first part of each pair is the key name, and the second part is the key secret. This way, you can logically segment shared secrets among several groups. If a keyname= parameter is not given to the <shtml> tag, the first entry in $wgSecureHTMLSecrets is assumed. So, for example:

<!-- Use the default key ("Wiki admin" in the above example), signed with "foo" -->
<shtml version="2" hash="ab...cd">HTML</shtml>

<!-- Or specify the key name explicitly -->
<shtml version="2" keyname="Wiki admin" hash="ab...cd">HTML</shtml>

<!-- Use the "developers" key, signed with "bar" -->
<shtml version="2" keyname="developers" hash="ab...cd">HTML</shtml>

Special:SecureHTML[edit | edit source]

The special page Special:SecureHTML is used to build the snippet, specifying the raw HTML, the key secret, and (optionally) the key name. If a key name is not specified, the first entry in $wgSecureHTMLSecrets is assumed. When the form is submitted, the signed snipped is displayed, and an attempt to render the snippet is made. If the key secret is incorrect, this will show you the results immediately, before you try to add the snippet to a page.

As of version 2.1, the special page is restricted to users who have the 'edit' right; the rationale being the user needs to be able to edit pages anyway to make use of this extension. If you would like to change this right, set $wgSecureHTMLSpecialRight to another right, or set to '' to allow anyone to use the special page.

Note that this restriction does not provide much extra security. If your MediaWiki installation requires users to be logged in to edit, it does provide superficial protection against anonymous dictionary attacks (checking the preview result) against a key. However, if a user already knows a key secret, he/she can build the signed snippet manually; the special page is not strictly needed.

Internationalization[edit | edit source]

Translation of the extension strings is managed by Translatewiki.net (direct extension link). Please contribute translations there.

Hash versions[edit | edit source]

Version 1 (deprecated)[edit | edit source]

The original version of this extension stored its keys in the global $shtml_keys, and used a simple MD5 concatenation of the key secret and the raw HTML to form the hash. This is potentialy less secure than HMAC, and has been deprecated. If a version= parameter is not given to the <shtml> tag, version 1 is assumed, and keys will be taken from $shtml_keys.

This interface is retained for backwards compatibility with the original version. If you have upgraded from the original version, please convert your snippets as soon as possible, as this interface will be removed at a future date.

Version 2[edit | edit source]

Version 2 is signified by <shtml version="2" ...>, and uses a HMAC_SHA256 digest of the raw HTML and key secret. It is the current, default (when using Special:SecureHTML to generate the snippet) and preferred interface.

See also[edit | edit source]